BaseNcodingPascal

[Xor-el]

BaseNcodingPascal

There are well-known algorithms for binary data to string encoding, such as algorithms with radix of power of 2 (base32, base64) and algorithms without power of 2 (base85, base91).

This library implements algorithm for general case, that is, custom alphabet can be used (alphabet with custom length).

Idea of developed algorithm is based on base85 encoding, except that block size is not constant, but is calculated depending on alphabet length.
Steps of algorithm

    Calculation of block size in bits and chars.
    Conversion of input string to byte array (using UTF8 Encoding).
    Splitting byte array on n-bit groups.
    Conversation of every group to radix n.
    Tail bits processing.

For bits block to chars block, the BigInteger Implementation in my BigNumber Library, DelphiBigNumberXLib with some slight modifications was used.

Porting guidelines:

1. All file names (units) are the same, but with a "u" prefix.
2. Some variables were closely named.
3. Some functions were written by me because I could not find a Delphi/
   FreePascal Equivalent of the C# function used, in the RTL or for Backwards
   Compatibility with older Unicode versions of Delphi or FreePascal.

Hints about the code:

1.  Multi-condition "for" loops and loops where iterator gets changed inside
  the loop were converted to while loops.

2.  Log method (Delphi/FreePascal Equivalent "LogN"), two arguments (a, newBase) needed to be
    swapped in Delphi/FreePascal.   

3.  This Library was written with (Delphi 10 Seattle Update 1) but will
    work fine with anything from Delphi 2009 and FreePascal 3.0.0 Upwards.

4.  "Parallel version" was implemented using PPL (Parallel Programming Library)
     but will only work in Delphi XE7 Upwards.

5.  This Library was written with the Object Oriented Paradigm (Class-Based) but
    implements memory management through reference counting with the help of
    Interfaces (that is, created objects or class instances are "freed" once they
    go out of scope).

6. If you are working with FreePascal in which the String and Char types are Mapped
   to "AnsiString" and "AnsiChar" by Default, you could "remap" them to "WideString"
   and "WideChar" by declaring "{$mode delphiunicode}" at the top of your unit
   excluding the ("") symbols.

Common pitfalls during porting:

1. Calling Log methods without swapping arguments places.
2. Writing for .. to .. do loop instead of for .. downto .. do in rare cases.
3. Differences in Order of Operator Precedence between C# and Pascal.

Code Examples

   

Code: Pascal  [Select][+][-]

1.  // Here is a Little Snippet showing Usage for Base32 Operations.  
2.     uses
3.       SysUtils, uBase32;
4.  
5.       procedure TForm1.Button1Click(Sender: TObject);
6.     var
7.       B32: IBase32;
8.       EncodedString, DecodedString, BaseAlphabet: {$IFDEF FPC} UnicodeString {$ELSE} String {$ENDIF};
9.       DecodedArray: TBytes;
10.       BaseSpecial: {$IFDEF FPC} UnicodeChar {$ELSE} Char {$ENDIF};
11.     begin
12.       // Creates a Base32 Instance with Default Values. You can Specify your Desired
13.       // Parameters During Creation of the Instance.
14.       B32 := TBase32.Create();
15.       // Accepts a String and Encodes it Internally using UTF8 as the Default Encoding
16.       EncodedString := B32.EncodeString('TestValue');
17.       // Accepts an Encoded String and Decodes it Internally using UTF8 as the Default Encoding
18.       DecodedString := B32.DecodeToString(EncodedString);
19.       // Accepts a Byte Array and Encodes it.
20.       EncodedString := B32.Encode(TEncoding.ANSI.GetBytes('TestValue'));
21.       // Accepts an Encoded String and Decodes it. (Returns a Byte Array)
22.       DecodedArray := B32.Decode(EncodedString);
23.       // Property that allows you to modifies The Encoding of the Created Instance.
24.       B32.Encoding := TEncoding.Unicode;
25.       // Property that allows you to get The Base Alphabets used to perform the Encoding.
26.       BaseAlphabet := B32.Alphabet;
27.       // Property that allows you to get The Base Char (Padder) used to perform the Encoding.
28.       BaseSpecial := B32.Special;
29.      // There are some other important properties but those are left for you to figure out. :)
30.      // Also no need to "Free" the Created Instance Since it is Reference Counted.
31.     end;
32.  

Unit Tests.

To Run Unit Tests,

For FPC 3.0.0 and above

Simply compile and run "BaseNcoding.Tests" project in "FreePascal.Tests" Folder.

For Delphi 2009 and above

Method One (Using DUnit Test Runner)

 To Build and Run the Unit Tests For Delphi 10 Seattle (should be similar for
 other versions)

1). Open Project Options of Unit Test (BaseNcoding.Tests) in "Delphi.Tests" Folder.

2). Change Target to All Configurations (Or "Base" In Older Delphi Versions.)

3). In Output directory add ".\$(Platform)\$(Config)" without the quotes.

4). In Search path add "$(BDS)\Source\DUnit\src" without the quotes.

5). In Unit output directory add "." without the quotes.

6). In Unit scope names (If Available), Delete "DUnitX" from the List.

Press Ok and save, then build and run.

Method Two (Using TestInsight) (Preferred).

1). Download and Install TestInsight.

2). Open Project Options of Unit Test (BaseNcoding.Tests.TestInsight) in "Delphi.Tests"
    Folder.

3). Change Target to All Configurations (Or "Base" In Older Delphi Versions.)

4). In Unit scope names (If Available), Delete "DUnitX" from the List.

5). To Use TestInsight, right-click on the project, then select
    "Enable for TestInsight" or "TestInsight Project".
    Save Project then Build and Run Test Project through TestInsight.

License

This "Software" is Licensed Under MIT License (MIT) .

https://github.com/Xor-el/BaseNcodingPascal

[AlexTP]

It is good library. Pls, make a Wiki page about it. All details here not needed, they must be in wiki. How to install and etc. http://wiki.freepascal.org/JvXPBar