diff --git a/README.md b/README.md index bb3bf5f..4317ed7 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,39 @@ # Sidio.Text.Base32 -Base32 encoding and decoding in .NET +A simple .NET package that converts a byte array to a Base32 string and vice versa. Because the latest framework +features are used, it requires .NET 8.0 or higher. + +[![build](https://github.com/marthijn/Sidio.Text.Base32/actions/workflows/build.yml/badge.svg)](https://github.com/marthijn/Sidio.Text.Base32/actions/workflows/build.yml) +[![NuGet Version](https://img.shields.io/nuget/v/Sidio.Text.Base32)](https://www.nuget.org/packages/Sidio.Text.Base32/) +[![Coverage Status](https://coveralls.io/repos/github/marthijn/Sidio.Text.Base32/badge.svg?branch=main)](https://coveralls.io/github/marthijn/Sidio.Text.Base32?branch=main) + +# Usage +## Encode +```csharp +var myString = "foobar"; +var bytes = Encoding.UTF8.GetBytes(myString); +var base32 = Base32.Encode(bytes); +``` + +## Decode +```csharp +var base32 = "MZXW6YTBOI======"; +var bytes = Base32.Decode(base32); +var myString = Encoding.UTF8.GetString(bytes); +``` + +## Encode hex +```csharp +var myString = "foobar"; +var bytes = Encoding.UTF8.GetBytes(myString); +var base32 = Base32.EncodeHex(bytes); +``` + +## Decode hex +```csharp +var base32 = "CPNMUOJ1E8======"; +var bytes = Base32.DecodeHex(base32); +var myString = Encoding.UTF8.GetString(bytes); +``` + +# References +* [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648) diff --git a/src/Sidio.Text.Base32.Tests/Base32EncodingTests.Hex.cs b/src/Sidio.Text.Base32.Tests/Base32Tests.Hex.cs similarity index 81% rename from src/Sidio.Text.Base32.Tests/Base32EncodingTests.Hex.cs rename to src/Sidio.Text.Base32.Tests/Base32Tests.Hex.cs index bc7b902..6071b1a 100644 --- a/src/Sidio.Text.Base32.Tests/Base32EncodingTests.Hex.cs +++ b/src/Sidio.Text.Base32.Tests/Base32Tests.Hex.cs @@ -4,14 +4,14 @@ namespace Sidio.Text.Base32.Tests; -public partial class Base32EncodingTests +public partial class Base32Tests { [Theory] [ClassData(typeof(Base32HexTestVectors))] - public void FromHexString_ReturnsByteArray(string input, string base32) + public void DecodeHex_ReturnsByteArray(string input, string base32) { // act - var result = Base32Encoding.FromHexString(base32); + var result = Base32.DecodeHex(base32); // assert result.Should().NotBeNull(); @@ -21,13 +21,13 @@ public void FromHexString_ReturnsByteArray(string input, string base32) [Theory] [ClassData(typeof(Base32HexTestVectors))] - public void ToHexString_ReturnsBase32HexString(string input, string base32) + public void EncodeHex_ReturnsBase32HexString(string input, string base32) { // arrange var bytes = Encoding.UTF8.GetBytes(input); // act - var result = Base32Encoding.ToHexString(bytes); + var result = Base32.EncodeHex(bytes); // assert result.Should().NotBeNull(); diff --git a/src/Sidio.Text.Base32.Tests/Base32EncodingTests.cs b/src/Sidio.Text.Base32.Tests/Base32Tests.cs similarity index 82% rename from src/Sidio.Text.Base32.Tests/Base32EncodingTests.cs rename to src/Sidio.Text.Base32.Tests/Base32Tests.cs index 1320031..a81b1a2 100644 --- a/src/Sidio.Text.Base32.Tests/Base32EncodingTests.cs +++ b/src/Sidio.Text.Base32.Tests/Base32Tests.cs @@ -4,14 +4,14 @@ namespace Sidio.Text.Base32.Tests; -public partial class Base32EncodingTests +public partial class Base32Tests { [Theory] [ClassData(typeof(Base32TestVectors))] - public void FromString_ReturnsByteArray(string input, string base32) + public void Decode_ReturnsByteArray(string input, string base32) { // act - var result = Base32Encoding.FromString(base32); + var result = Base32.Decode(base32); // assert result.Should().NotBeNull(); @@ -21,13 +21,13 @@ public void FromString_ReturnsByteArray(string input, string base32) [Theory] [ClassData(typeof(Base32TestVectors))] - public void ToString_ReturnsBase32String(string input, string base32) + public void Encode_ReturnsBase32String(string input, string base32) { // arrange var bytes = Encoding.UTF8.GetBytes(input); // act - var result = Base32Encoding.ToString(bytes); + var result = Base32.Encode(bytes); // assert result.Should().NotBeNull(); diff --git a/src/Sidio.Text.Base32.Tests/Sidio.Text.Base32.Tests.csproj b/src/Sidio.Text.Base32.Tests/Sidio.Text.Base32.Tests.csproj index e439e14..edcfc46 100644 --- a/src/Sidio.Text.Base32.Tests/Sidio.Text.Base32.Tests.csproj +++ b/src/Sidio.Text.Base32.Tests/Sidio.Text.Base32.Tests.csproj @@ -10,11 +10,17 @@ - + + all + runtime; build; native; contentfiles; analyzers; buildtransitive + - - - + + + + all + runtime; build; native; contentfiles; analyzers; buildtransitive + diff --git a/src/Sidio.Text.Base32/Base32Encoding.Hex.cs b/src/Sidio.Text.Base32/Base32.Hex.cs similarity index 72% rename from src/Sidio.Text.Base32/Base32Encoding.Hex.cs rename to src/Sidio.Text.Base32/Base32.Hex.cs index abcc24c..514a914 100644 --- a/src/Sidio.Text.Base32/Base32Encoding.Hex.cs +++ b/src/Sidio.Text.Base32/Base32.Hex.cs @@ -1,6 +1,6 @@ namespace Sidio.Text.Base32; -public static partial class Base32Encoding +public static partial class Base32 { private static readonly char[] Base32HexTable = [ @@ -15,10 +15,10 @@ public static partial class Base32Encoding /// /// The input string. /// A array. - public static byte[] FromHexString(string input) + public static byte[] DecodeHex(string input) { ArgumentNullException.ThrowIfNull(input); - return input.Length == 0 ? [] : FromString(input.AsSpan(), Base32HexDecodeMap); + return input.Length == 0 ? [] : Decode(input.AsSpan(), Base32HexDecodeMap); } /// @@ -26,9 +26,9 @@ public static byte[] FromHexString(string input) /// /// The input array. /// A base32 . - public static string ToHexString(byte[] inArray) + public static string EncodeHex(byte[] inArray) { ArgumentNullException.ThrowIfNull(inArray); - return inArray.Length == 0 ? string.Empty : ToString(new ReadOnlySpan(inArray), Base32HexTable); + return inArray.Length == 0 ? string.Empty : Encode(new ReadOnlySpan(inArray), Base32HexTable); } } \ No newline at end of file diff --git a/src/Sidio.Text.Base32/Base32Encoding.cs b/src/Sidio.Text.Base32/Base32.cs similarity index 87% rename from src/Sidio.Text.Base32/Base32Encoding.cs rename to src/Sidio.Text.Base32/Base32.cs index f059b25..3155aeb 100644 --- a/src/Sidio.Text.Base32/Base32Encoding.cs +++ b/src/Sidio.Text.Base32/Base32.cs @@ -3,7 +3,7 @@ /// /// The base32 encoding class. /// -public static partial class Base32Encoding +public static partial class Base32 { private const char UnitSeparator = (char)0x1F; private const char MaxByte = (char)0xFF; @@ -21,10 +21,10 @@ public static partial class Base32Encoding /// /// The input string. /// A array. - public static byte[] FromString(string input) + public static byte[] Decode(string input) { ArgumentNullException.ThrowIfNull(input); - return input.Length == 0 ? [] : FromString(input.AsSpan(), Base32DecodeMap); + return input.Length == 0 ? [] : Decode(input.AsSpan(), Base32DecodeMap); } /// @@ -32,19 +32,19 @@ public static byte[] FromString(string input) /// /// The input array. /// A base32 . - public static string ToString(byte[] inArray) + public static string Encode(byte[] inArray) { ArgumentNullException.ThrowIfNull(inArray); - return inArray.Length == 0 ? string.Empty : ToString(new ReadOnlySpan(inArray), Base32Table); + return inArray.Length == 0 ? string.Empty : Encode(new ReadOnlySpan(inArray), Base32Table); } - private static byte[] FromString(ReadOnlySpan inputSpan, int[] decodeMap) + private static byte[] Decode(ReadOnlySpan inputSpan, int[] decodeMap) { // remove padding '=' characters from the end of the input var trimmedInput = inputSpan.TrimEnd('='); // calculate the expected output byte array length - // each 8 characters of Base32 results in 5 bytes + // each 8 characters of base32 results in 5 bytes var outputLength = (trimmedInput.Length * 5) / 8; // stack allocation for small arrays @@ -82,7 +82,7 @@ private static byte[] FromString(ReadOnlySpan inputSpan, int[] decodeMap) return outputSpan.ToArray(); } - private static string ToString(ReadOnlySpan inArray, char[] base32Table) + private static string Encode(ReadOnlySpan inArray, char[] base32Table) { // calculate the length of the output: Base32 encoding is 8/5 times the size of the input var outputLength = ((inArray.Length * 8) + 4) / 5; @@ -98,14 +98,14 @@ private static string ToString(ReadOnlySpan inArray, char[] base32Table) var bitCount = 0; var outputIndex = 0; - // process each byte in inputSpan + // process each byte in inArray foreach (var b in inArray) { // shift the buffer left by 8 bits and add the byte value to the buffer bitBuffer = (bitBuffer << 8) | b; bitCount += 8; - // while we have 5 or more bits in the buffer, process a Base32 character + // while we have 5 or more bits in the buffer, process a base32 character while (bitCount >= 5) { // extract the top 5 bits from the buffer diff --git a/src/Sidio.Text.Base32/Sidio.Text.Base32.csproj b/src/Sidio.Text.Base32/Sidio.Text.Base32.csproj index 9cdd82c..8c15b41 100644 --- a/src/Sidio.Text.Base32/Sidio.Text.Base32.csproj +++ b/src/Sidio.Text.Base32/Sidio.Text.Base32.csproj @@ -14,7 +14,7 @@ README.md LICENSE Base32 encoding and decoding in .NET. - base32 encoding decoding text + base32 encoding decoding text rfc4648 https://github.com/marthijn/Sidio.Text.Base32/releases icon.png true