Merge branch 'main' into next

Author: ssg

.gitignore

@@ -12,4 +12,5 @@ packages/
 *.userprefs
 SimpleBase.xml
 .idea/
-BenchmarkDotNet.Artifacts/
+BenchmarkDotNet.Artifacts/
+TestResults/

README.md

@@ -12,8 +12,8 @@ math worked.
 
 Features
 --------
- - [Multibase](https://github.com/multiformats/multibase) support. All formats
-   covered by SimpleBase including a few Base64 variants are supported. Base2, Base8, and Base10 are also supported.
+ - **[Multibase](https://github.com/multiformats/multibase)**: All formats
+   covered by SimpleBase including a few Base64 variants are supported. **Base2**, **Base8**, and **Base10** are also supported.
  - **Base32**: RFC 4648, BECH32, Crockford, z-base-32, Geohash, FileCoin and Extended Hex 
    (BASE32-HEX) flavors with Crockford character substitution, or any other 
    custom flavors.
@@ -40,6 +40,10 @@ To install it from [NuGet](https://www.nuget.org/packages/SimpleBase/):
 
   `Install-Package SimpleBase`
 
+If you need .NET Standard 2.0 compatible version for targeting older .NET Framework or .NET Core, use the 2.x release line instead. It's missing newer features, but still supported:
+
+  `Install-Package SimpleBase -MaximumVersion 2.999.0`
+
 Usage
 ------
 The basic usage for encoding a buffer into, say, Base32, is as simple as:

benchmark/Benchmark.csproj

@@ -18,6 +18,7 @@
     </ItemGroup>
     <ItemGroup>
       <PackageReference Include="BenchmarkDotNet" Version="0.15.5" />
+      <PackageReference Include="BenchmarkDotNet" Version="0.15.2" />
     </ItemGroup>
     <ItemGroup>
         <ProjectReference Include="..\src\SimpleBase.csproj" />

src/Base16Alphabet.cs

@@ -32,7 +32,10 @@ public Base16Alphabet(string alphabet)
     /// Initializes a new instance of the <see cref="Base16Alphabet"/> class.
     /// </summary>
     /// <param name="alphabet">Encoding alphabet.</param>
-    /// <param name="caseSensitive">If the decoding should be performed case sensitive.</param>
+    /// <param name="caseSensitive">
+    ///     <see langword="true"/> if the decoding should be performed case-sensitive,
+    ///     <see langword="false"/> otherwise.
+    /// </param>
     public Base16Alphabet(string alphabet, bool caseSensitive)
         : base(16, alphabet)
     {

src/Base256Emoji.cs

@@ -47,7 +47,7 @@ static string[] createDefaultAlphabet()
     /// <summary>
     /// Create a new instance of Base256Emoji.
     /// </summary>
-    /// <param name="alphabet">An array that contains 256 elements with emoji values corresponding to every byte.</param>
+    /// <param name="alphabet">A string that contains 256 emojis corresponding to every byte.</param>
     public Base256Emoji(string[] alphabet)
     {
         if (alphabet.Length != 256)

src/Base32.cs

@@ -5,7 +5,9 @@
 
 using System;
 using System.IO;
+using System.Runtime.Intrinsics.X86;
 using System.Threading.Tasks;
+using static System.Runtime.InteropServices.JavaScript.JSType;
 
 namespace SimpleBase;
 
@@ -115,6 +117,12 @@ public int GetSafeByteCountForDecoding(ReadOnlySpan<char> text)
     }
 
     /// <inheritdoc/>
+    ///<remarks>
+    ///This formula overestimates the required size to the next multiplier of 8 characters
+    ///to leave space for the padding characters at the end. If this kind of generous
+    ///allocation is a problem, a different formula can be used with non-allocating encoding
+    ///functions like <see cref="TryEncode(ReadOnlySpan{byte}, Span{char}, out int)" />.
+    ///</remarks>
     public int GetSafeCharCountForEncoding(ReadOnlySpan<byte> buffer)
     {
         return (((buffer.Length - 1) / bitsPerChar) + 1) * bitsPerByte;
@@ -229,7 +237,10 @@ public string Encode(ReadOnlySpan<byte> bytes)
     /// Encode a memory span into a Base32 string.
     /// </summary>
     /// <param name="bytes">Buffer to be encoded.</param>
-    /// <param name="padding">Append padding characters in the output.</param>
+    /// <param name="padding">
+    ///     <see langword="true"/> if padding characters should be appended to the return value,
+    ///     <see langword="false"/> otherwise.
+    /// </param>
     /// <returns>Encoded string.</returns>
     public string Encode(ReadOnlySpan<byte> bytes, bool padding)
     {
@@ -300,7 +311,10 @@ public void Encode(Stream input, TextWriter output)
     /// </summary>
     /// <param name="input">Input bytes.</param>
     /// <param name="output">The writer the output is written to.</param>
-    /// <param name="padding">Whether to use padding at the end of the output.</param>
+    /// <param name="padding">
+    ///     <see langword="true"/> if padding characters should be appended to <paramref name="output"/>,
+    ///     <see langword="false"/> otherwise.
+    /// </param>
     public void Encode(Stream input, TextWriter output, bool padding)
     {
         StreamHelper.Encode(input, output, (buffer, lastBlock) =>
@@ -326,7 +340,10 @@ public Task EncodeAsync(Stream input, TextWriter output)
     /// </summary>
     /// <param name="input">Input bytes.</param>
     /// <param name="output">The writer the output is written to.</param>
-    /// <param name="padding">Whether to use padding at the end of the output.</param>
+    /// <param name="padding">
+    ///     <see langword="true"/> if padding characters should be appended to <paramref name="output"/>,
+    ///     <see langword="false"/> otherwise.
+    /// </param>
     /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
     public async Task EncodeAsync(Stream input, TextWriter output, bool padding)
     {
@@ -370,9 +387,12 @@ public bool TryEncode(ReadOnlySpan<byte> bytes, Span<char> output, out int numCh
     /// </summary>
     /// <param name="bytes">Input bytes.</param>
     /// <param name="output">Output buffer.</param>
-    /// <param name="padding">Whether to use padding characters at the end.</param>
-    /// <param name="numCharsWritten">Number of characters written to the output.</param>
-    /// <returns>True if encoding is successful, false if the output is invalid.</returns>
+    /// <param name="padding">
+    ///     <see langword="true"/> if padding characters should be appended to <paramref name="output"/>,
+    ///     <see langword="false"/> otherwise.
+    /// </param>
+    /// <param name="numCharsWritten">Number of characters written to <paramref name="output"/>.</param>
+    /// <returns><see langword="true"/> if encoding is successful, <see langword="false"/> if the output is invalid.</returns>
     public bool TryEncode(
         ReadOnlySpan<byte> bytes,
         Span<char> output,

src/Base58.cs

@@ -5,8 +5,6 @@
 
 using System;
 using System.Diagnostics;
-using System.Runtime.Serialization;
-using System.Security.Cryptography;
 
 namespace SimpleBase;
 
@@ -29,9 +27,7 @@ public sealed class Base58(Base58Alphabet alphabet) : DividingCoder<Base58Alphab
     const int reductionFactor = 733;
 
     const int maxCheckPayloadLength = 256;
-    const int minCheckDecodedBufferSize = 5;
-    const int sha256Bytes = 32;
-    const int sha256DigestBytes = 4;
+
     static readonly Lazy<Base58> bitcoin = new(() => new Base58(Base58Alphabet.Bitcoin));
     static readonly Lazy<Base58> ripple = new(() => new Base58(Base58Alphabet.Ripple));
     static readonly Lazy<Base58> flickr = new(() => new Base58(Base58Alphabet.Flickr));
@@ -102,20 +98,20 @@ public string EncodeCheck(ReadOnlySpan<byte> payload, byte version)
     public string EncodeCheck(ReadOnlySpan<byte> payload, ReadOnlySpan<byte> prefix)
     {
         int totalLength = prefix.Length + payload.Length;
-        int outputLen = totalLength + sha256DigestBytes;
+        int outputLen = totalLength + Sha256.DigestBytes;
         Span<byte> output = (outputLen < Bits.SafeStackMaxAllocSize) ? stackalloc byte[outputLen] : new byte[outputLen];
         prefix.CopyTo(output);
         payload.CopyTo(output[prefix.Length..]);
-        Span<byte> sha256 = stackalloc byte[sha256Bytes];
-        computeDoubleSha256(output[..totalLength], sha256);
-        sha256[..sha256DigestBytes].CopyTo(output[totalLength..]);
+        Span<byte> sha256 = stackalloc byte[Sha256.Bytes];
+        Sha256.ComputeTwice(output[..totalLength], sha256);
+        sha256[..Sha256.DigestBytes].CopyTo(output[totalLength..]);
         return Encode(output);
     }
 
     /// <summary>
     /// Generate a Base58Check string out of a prefix buffer and payload
     /// by skipping leading zeroes in <paramref name="payload"/>.
-    /// Platforms like Tezos expects this behavior.
+    /// Platforms like Tezos expect this behavior.
     /// </summary>
     /// <param name="payload">Address data.</param>
     /// <param name="prefix">Prefix buffer.</param>
@@ -145,8 +141,11 @@ public string EncodeCheckSkipZeroes(ReadOnlySpan<byte> payload, ReadOnlySpan<byt
     /// <param name="address">Address string.</param>
     /// <param name="payload">Output address buffer.</param>
     /// <param name="version">Address version.</param>
-    /// <param name="bytesWritten">Number of bytes written in the output payload.</param>
-    /// <returns>True if address was decoded successfully and passed validation. False, otherwise.</returns>
+    /// <param name="bytesWritten">Number of bytes written to <paramref name="payload"/>.</param>
+    /// <returns>
+    ///     <see langword="true"/> if address was decoded successfully and passed validation.
+    ///     <see langword="false"/> otherwise.
+    /// </returns>
     public bool TryDecodeCheck(
         ReadOnlySpan<char> address,
         Span<byte> payload,
@@ -166,31 +165,30 @@ public bool TryDecodeCheck(
     /// <param name="payload">Output address buffer.</param>
     /// <param name="prefix">Prefix decoded, must have the exact size of the expected prefix.</param>
     /// <param name="payloadBytesWritten">Number of bytes written in the output payload.</param>
-    /// <returns>True if address was decoded successfully and passed validation. False, otherwise.</returns>
+    /// <returns><see langword="true"/> if address was decoded successfully and passed validation, <see langword="false"/> otherwise.</returns>
     public bool TryDecodeCheck(
         ReadOnlySpan<char> address,
         Span<byte> payload,
         Span<byte> prefix,
         out int payloadBytesWritten)
     {
-        Span<byte> buffer = stackalloc byte[maxCheckPayloadLength + sha256DigestBytes + 1];
-        if (!TryDecode(address, buffer, out int decodedBufferSize) || decodedBufferSize < minCheckDecodedBufferSize)
+        payloadBytesWritten = 0;
+        Span<byte> buffer = stackalloc byte[maxCheckPayloadLength + Sha256.DigestBytes + 1];
+        if (!TryDecode(address, buffer, out int decodedBufferSize))
         {
-            payloadBytesWritten = 0;
             return false;
         }
 
         buffer = buffer[..decodedBufferSize];
         buffer[..prefix.Length].CopyTo(prefix);
-        Span<byte> sha256 = stackalloc byte[sha256Bytes];
-        computeDoubleSha256(buffer[..^sha256DigestBytes], sha256);
-        if (!sha256[..sha256DigestBytes].SequenceEqual(buffer[^sha256DigestBytes..]))
+        Span<byte> sha256 = stackalloc byte[Sha256.Bytes];
+        Sha256.ComputeTwice(buffer[..^Sha256.DigestBytes], sha256);
+        if (!sha256[..Sha256.DigestBytes].SequenceEqual(buffer[^Sha256.DigestBytes..]))
         {
-            payloadBytesWritten = 0;
             return false;
         }
 
-        var finalBuffer = buffer[prefix.Length..^sha256DigestBytes];
+        var finalBuffer = buffer[prefix.Length..^Sha256.DigestBytes];
         finalBuffer.CopyTo(payload);
         payloadBytesWritten = finalBuffer.Length;
         return true;
@@ -208,13 +206,13 @@ public string EncodeCb58(ReadOnlySpan<byte> payload)
             throw new ArgumentException($"Payload length {payload.Length} is greater than {maxCheckPayloadLength}", nameof(payload));
         }
 
-        int outputLen = payload.Length + sha256DigestBytes;
+        int outputLen = payload.Length + Sha256.DigestBytes;
         Span<byte> output = (outputLen < Bits.SafeStackMaxAllocSize) ? stackalloc byte[outputLen] : new byte[outputLen];
         payload.CopyTo(output);
-        Span<byte> sha256 = stackalloc byte[sha256Bytes];
-        computeSha256(output[..payload.Length], sha256);
+        Span<byte> sha256 = stackalloc byte[Sha256.Bytes];
+        Sha256.Compute(output[..payload.Length], sha256);
 
-        sha256[^sha256DigestBytes..].CopyTo(output[payload.Length..]);
+        sha256[^Sha256.DigestBytes..].CopyTo(output[payload.Length..]);
         return Encode(output);
     }
 
@@ -223,51 +221,32 @@ public string EncodeCb58(ReadOnlySpan<byte> payload)
     /// </summary>
     /// <param name="address">Address string.</param>
     /// <param name="payload">Output address buffer.</param>
-    /// <param name="bytesWritten">Number of bytes written in the output payload.</param>
-    /// <returns>True if address was decoded successfully and passed validation. False, otherwise.</returns>
+    /// <param name="bytesWritten">Number of bytes written to <paramref name="payload"/>.</param>
+    /// <returns><see langword="true"/> if address was decoded successfully and passed validation. <see langword="false"/> otherwise.</returns>
     public bool TryDecodeCb58(
         ReadOnlySpan<char> address,
         Span<byte> payload,
         out int bytesWritten)
     {
-        Span<byte> buffer = stackalloc byte[maxCheckPayloadLength + sha256DigestBytes];
+        Span<byte> buffer = stackalloc byte[maxCheckPayloadLength + Sha256.DigestBytes];
         if (!TryDecode(address, buffer, out bytesWritten) || bytesWritten < 4)
         {
             return false;
         }
 
         buffer = buffer[..bytesWritten];
-        Span<byte> sha256 = stackalloc byte[sha256Bytes];
-        computeSha256(buffer[..^sha256DigestBytes], sha256);
+        Span<byte> sha256 = stackalloc byte[Sha256.Bytes];
+        Sha256.Compute(buffer[..^Sha256.DigestBytes], sha256);
 
-        if (!sha256[^sha256DigestBytes..].SequenceEqual(buffer[^sha256DigestBytes..]))
+        if (!sha256[^Sha256.DigestBytes..].SequenceEqual(buffer[^Sha256.DigestBytes..]))
         {
             return false;
         }
 
-        var finalBuffer = buffer[..^sha256DigestBytes];
+        var finalBuffer = buffer[..^Sha256.DigestBytes];
         finalBuffer.CopyTo(payload);
         bytesWritten = finalBuffer.Length;
         return true;
     }
 
-    static void computeDoubleSha256(ReadOnlySpan<byte> buffer, Span<byte> output)
-    {
-        Span<byte> tempResult = stackalloc byte[sha256Bytes];
-        computeSha256(buffer, tempResult);
-        computeSha256(tempResult, output);
-    }
-
-    static void computeSha256(ReadOnlySpan<byte> buffer, Span<byte> output)
-    {
-        if (!SHA256.TryHashData(buffer, output, out int bytesWritten))
-        {
-            throw new InvalidOperationException("Couldn't compute SHA256");
-        }
-
-        if (bytesWritten != sha256Bytes)
-        {
-            throw new InvalidOperationException("Invalid SHA256 length");
-        }
-    }
 }

src/Base85Ipv6.cs

@@ -14,11 +14,13 @@ namespace SimpleBase;
 /// Base85 implementation with additional IPv6 coding functions.
 /// </summary>
 /// <remarks>
-/// RFC 1924 sucks, arguably because it's a very early proposal in the history of IPv6:
+/// RFC 1924 sucks, arguably because it was a very early proposal in the history of IPv6:
+/// 
 /// - It contains special chars: It's prone to be confused with other syntactical elements.
 ///   It can even cause security issues due to poor escaping, let alone UX problems.
 /// - Length gains are usually marginal: IPv6 uses zero elimination to reduce the address representation.
 /// - Slow. The algorithm is division based, instead of faster bitwise operations.
+/// 
 /// So, that's why I only included a proof of concept implementation instead of working on optimizing it.
 /// RFC 1924 should die, and this code should only be used to support some obscure standard or code somewhere.
 /// </remarks>
@@ -97,7 +99,7 @@ public IPAddress DecodeIPv6(string text)
     /// </summary>
     /// <param name="text">Encoded text.</param>
     /// <param name="ip">Resulting IPv6 address.</param>
-    /// <returns>True if successful, false otherwise.</returns>
+    /// <returns><see langword="true"/> if successful, <see langword="false"/> otherwise.</returns>
     public bool TryDecodeIPv6(string text, out IPAddress ip)
     {
         if (text.Length != ipv6chars)

src/Bits.cs

@@ -4,6 +4,7 @@
 // </copyright>
 
 using System;
+using System.Runtime.CompilerServices;
 
 namespace SimpleBase
 {
@@ -15,6 +16,7 @@ static class Bits
         /// <summary>
         /// Safe one-shot maximum amount to be allocated on stack for temporary buffers and alike.
         /// </summary>
+        /// <see href="https://learn.microsoft.com/en-us/dotnet/standard/unsafe-code/best-practices#:~:text=For%20example%2C%201024%20bytes%20could%20be%20considered%20a%20reasonable%20upper%20bound." />
         internal const int SafeStackMaxAllocSize = 1024;
 
         /// <summary>
@@ -23,10 +25,11 @@ static class Bits
         internal const int MaxUInt64Digits = 20;
 
         /// <summary>
-        /// Converts a byte array to a hexadecimal string.
+        /// Converts a variable length byte array to a 64-bit unsigned integer.
         /// </summary>
         /// <param name="bytes"></param>
-        /// <returns></returns>
+        /// <returns>Unsigned integer representation of the bytes.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
         internal static ulong PartialBigEndianBytesToUInt64(ReadOnlySpan<byte> bytes)
         {
             if (bytes.Length > sizeof(ulong))
@@ -41,5 +44,20 @@ internal static ulong PartialBigEndianBytesToUInt64(ReadOnlySpan<byte> bytes)
             }
             return result;
         }
+
+        /// <summary>
+        /// Count the number of consecutive zero bytes at the beginning of the given buffer.
+        /// </summary>
+        /// <param name="bytes">Buffer for prefixing zeroes to be counted.</param>
+        /// <returns>Number of zeroes at the beginning of the buffer.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static int CountPrefixingZeroes(ReadOnlySpan<byte> bytes)
+        {
+            int i = 0;
+            for (; i < bytes.Length && bytes[i] == 0; i++)               
+            {
+            }
+            return i;
+        }
     }
 }