Added several enhancements including parsing, formatting and conversion. (#57)

Author: MrMatthewLayton

OnixLabs.Core/Text/Base64FormatProvider.cs

@@ -0,0 +1,52 @@
+// Copyright 2020 ONIXLabs
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
+
+namespace OnixLabs.Core.Text;
+
+/// <summary>
+/// Represents a Base-64 format provider.
+/// </summary>
+public sealed class Base64FormatProvider : Enumeration<Base64FormatProvider>, IFormatProvider
+{
+    /// <summary>
+    /// Gets the RFC 4648 Base-64 format provider.
+    /// </summary>
+    public static readonly Base64FormatProvider Rfc4648 = new(0, nameof(Rfc4648), "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=");
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Base64FormatProvider"/> class.
+    /// </summary>
+    /// <param name="value">The value of the enumeration entry.</param>
+    /// <param name="name">The name of the enumeration entry.</param>
+    /// <param name="alphabet">The alphabet of the format provider.</param>
+    private Base64FormatProvider(int value, string name, string alphabet) : base(value, name)
+    {
+        Alphabet = alphabet;
+    }
+
+    /// <summary>
+    /// Gets the alphabet of the current <see cref="Base64FormatProvider"/> instance.
+    /// </summary>
+    public string Alphabet { get; }
+
+    /// <summary>Gets an object that provides formatting services for the specified type.</summary>
+    /// <param name="formatType">An object that specifies the type of format object to return.</param>
+    /// <returns>
+    /// Returns an instance of the object specified by <paramref name="formatType"/>,
+    /// if the <see cref="T:IFormatProvider"/> implementation can supply that type of object; otherwise, <see langword="null"/>.
+    /// </returns>
+    public object? GetFormat(Type? formatType) => formatType == typeof(Base64FormatProvider) ? this : null;
+}

OnixLabs.Core/Text/Extensions.cs

@@ -0,0 +1,82 @@
+// Copyright 2020 ONIXLabs
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
+using System.ComponentModel;
+
+namespace OnixLabs.Core.Text;
+
+/// <summary>
+/// Provides extension methods for read-only spans.
+/// </summary>
+// ReSharper disable UnusedMethodReturnValue.Global
+[EditorBrowsable(EditorBrowsableState.Never)]
+public static class Extensions
+{
+    /// <summary>
+    /// Converts the current <see cref="T:Byte[]"/> into a new <see cref="Base16"/> instance.
+    /// </summary>
+    /// <param name="value">The <see cref="T:Byte[]"/> value to convert.</param>
+    /// <returns>Returns a new <see cref="Base16"/> instance.</returns>
+    public static Base16 ToBase16(this byte[] value) => new(value);
+
+    /// <summary>
+    /// Converts the current <see cref="T:Byte[]"/> into a new <see cref="Base32"/> instance.
+    /// </summary>
+    /// <param name="value">The <see cref="T:Byte[]"/> value to convert.</param>
+    /// <returns>Returns a new <see cref="Base32"/> instance.</returns>
+    public static Base32 ToBase32(this byte[] value) => new(value);
+
+    /// <summary>
+    /// Converts the current <see cref="T:Byte[]"/> into a new <see cref="Base58"/> instance.
+    /// </summary>
+    /// <param name="value">The <see cref="T:Byte[]"/> value to convert.</param>
+    /// <returns>Returns a new <see cref="Base58"/> instance.</returns>
+    public static Base58 ToBase58(this byte[] value) => new(value);
+
+    /// <summary>
+    /// Converts the current <see cref="T:Byte[]"/> into a new <see cref="Base64"/> instance.
+    /// </summary>
+    /// <param name="value">The <see cref="T:Byte[]"/> value to convert.</param>
+    /// <returns>Returns a new <see cref="Base64"/> instance.</returns>
+    public static Base64 ToBase64(this byte[] value) => new(value);
+
+    /// <summary>
+    /// Converts the current <see cref="ReadOnlySpan{Byte}"/> into a new <see cref="Base16"/> instance.
+    /// </summary>
+    /// <param name="value">The <see cref="ReadOnlySpan{Byte}"/> value to convert.</param>
+    /// <returns>Returns a new <see cref="Base16"/> instance.</returns>
+    public static Base16 ToBase16(this ReadOnlySpan<byte> value) => new(value);
+
+    /// <summary>
+    /// Converts the current <see cref="ReadOnlySpan{Byte}"/> into a new <see cref="Base32"/> instance.
+    /// </summary>
+    /// <param name="value">The <see cref="ReadOnlySpan{Byte}"/> value to convert.</param>
+    /// <returns>Returns a new <see cref="Base32"/> instance.</returns>
+    public static Base32 ToBase32(this ReadOnlySpan<byte> value) => new(value);
+
+    /// <summary>
+    /// Converts the current <see cref="ReadOnlySpan{Byte}"/> into a new <see cref="Base58"/> instance.
+    /// </summary>
+    /// <param name="value">The <see cref="ReadOnlySpan{Byte}"/> value to convert.</param>
+    /// <returns>Returns a new <see cref="Base58"/> instance.</returns>
+    public static Base58 ToBase58(this ReadOnlySpan<byte> value) => new(value);
+
+    /// <summary>
+    /// Converts the current <see cref="ReadOnlySpan{Byte}"/> into a new <see cref="Base64"/> instance.
+    /// </summary>
+    /// <param name="value">The <see cref="ReadOnlySpan{Byte}"/> value to convert.</param>
+    /// <returns>Returns a new <see cref="Base64"/> instance.</returns>
+    public static Base64 ToBase64(this ReadOnlySpan<byte> value) => new(value);
+}

OnixLabs.Core/Text/IBaseCodec.cs

@@ -51,6 +51,86 @@ public interface IBaseCodec
     /// </summary>
     public static Base64Codec Base64 => new();
 
+    /// <summary>
+    /// Obtains a base <see cref="string"/> representation of the specified <see cref="ReadOnlySpan{Byte}"/> value.
+    /// </summary>
+    /// <param name="value">The value to convert.</param>
+    /// <param name="provider">
+    /// The <see cref="IFormatProvider"/> which will be used to obtain the base representation.
+    /// <remarks> Allowed values for this parameter are <see cref="Base16FormatProvider"/>, <see cref="Base32FormatProvider"/>, <see cref="Base58FormatProvider"/>, and <see cref="Base64FormatProvider"/>.</remarks>
+    /// </param>
+    /// <returns>Returns a base <see cref="string"/> representation of the specified <see cref="ReadOnlySpan{Byte}"/> value.</returns>
+    /// <exception cref="FormatException">If the specified <see cref="ReadOnlySpan{Byte}"/> value cannot be converted.</exception>
+    public static string GetString(ReadOnlySpan<byte> value, IFormatProvider provider)
+    {
+        if (TryGetString(value, provider, out string result)) return result;
+        throw new FormatException(EncodingFormatException);
+    }
+
+    /// <summary>
+    /// Obtains a new <see cref="T:byte[]"/> array by converting the specified <see cref="ReadOnlySpan{Char}"/> value.
+    /// </summary>
+    /// <param name="value">The value to convert.</param>
+    /// <param name="provider">
+    /// The <see cref="IFormatProvider"/> which will be used to convert the specified <see cref="ReadOnlySpan{Char}"/> value.
+    /// <remarks> Allowed values for this parameter are <see cref="Base16FormatProvider"/>, <see cref="Base32FormatProvider"/>, <see cref="Base58FormatProvider"/>, and <see cref="Base64FormatProvider"/>.</remarks>
+    /// </param>
+    /// <returns>Returns a new <see cref="T:byte[]"/> array by converting the specified <see cref="ReadOnlySpan{Char}"/> value.</returns>
+    /// <exception cref="FormatException">If the specified <see cref="ReadOnlySpan{Char}"/> value cannot be converted.</exception>
+    public static byte[] GetBytes(ReadOnlySpan<char> value, IFormatProvider provider)
+    {
+        if (TryGetBytes(value, provider, out byte[] result)) return result;
+        throw new FormatException(DecodingFormatException);
+    }
+
+    /// <summary>
+    /// Tries to obtain a base <see cref="string"/> representation of the specified <see cref="ReadOnlySpan{Byte}"/> value.
+    /// </summary>
+    /// <param name="value">The value to convert.</param>
+    /// <param name="provider">
+    /// The <see cref="IFormatProvider"/> which will be used to obtain the base representation.
+    /// <remarks> Allowed values for this parameter are <see cref="Base16FormatProvider"/>, <see cref="Base32FormatProvider"/>, <see cref="Base58FormatProvider"/>, and <see cref="Base64FormatProvider"/>.</remarks>
+    /// </param>
+    /// <param name="result"> A base <see cref="string"/> representation of the specified <see cref="ReadOnlySpan{Byte}"/> value, or an empty string if the value cannot be converted.</param>
+    /// <returns>Returns <see langword="true"/> if the conversion was successful; otherwise, <see langword="false"/>.</returns>
+    public static bool TryGetString(ReadOnlySpan<byte> value, IFormatProvider provider, out string result)
+    {
+        result = string.Empty;
+
+        return provider switch
+        {
+            Base16FormatProvider => Base16.TryEncode(value, provider, out result),
+            Base32FormatProvider => Base32.TryEncode(value, provider, out result),
+            Base58FormatProvider => Base58.TryEncode(value, provider, out result),
+            Base64FormatProvider => Base64.TryEncode(value, provider, out result),
+            _ => false
+        };
+    }
+
+    /// <summary>
+    /// Tries to obtain a new <see cref="T:byte[]"/> array by converting the specified <see cref="ReadOnlySpan{Char}"/> value.
+    /// </summary>
+    /// <param name="value">The value to convert.</param>
+    /// <param name="provider">
+    /// The <see cref="IFormatProvider"/> which will be used to convert the specified <see cref="ReadOnlySpan{Char}"/> value.
+    /// <remarks> Allowed values for this parameter are <see cref="Base16FormatProvider"/>, <see cref="Base32FormatProvider"/>, <see cref="Base58FormatProvider"/>, and <see cref="Base64FormatProvider"/>.</remarks>
+    /// </param>
+    /// <param name="result">A new <see cref="T:byte[]"/> array by converting the specified <see cref="ReadOnlySpan{Char}"/> value, or an empty <see cref="T:byte[]"/> array if the value cannot be converted.</param>
+    /// <returns>Returns <see langword="true"/> if the conversion was successful; otherwise, <see langword="false"/>.</returns>
+    public static bool TryGetBytes(ReadOnlySpan<char> value, IFormatProvider provider, out byte[] result)
+    {
+        result = [];
+
+        return provider switch
+        {
+            Base16FormatProvider => Base16.TryDecode(value, provider, out result),
+            Base32FormatProvider => Base32.TryDecode(value, provider, out result),
+            Base58FormatProvider => Base58.TryDecode(value, provider, out result),
+            Base64FormatProvider => Base64.TryDecode(value, provider, out result),
+            _ => false
+        };
+    }
+
     /// <summary>
     /// Encodes the specified <see cref="ReadOnlySpan{T}"/> value into a Base-N <see cref="String"/> representation.
     /// </summary>

OnixLabs.Security.Cryptography/DigitalSignature.Parse.cs

@@ -0,0 +1,70 @@
+// Copyright 2020 ONIXLabs
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
+using OnixLabs.Core.Text;
+
+namespace OnixLabs.Security.Cryptography;
+
+public readonly partial struct DigitalSignature
+{
+    /// <summary>
+    /// Parses the specified <see cref="String"/> value into a <see cref="DigitalSignature"/> value.
+    /// </summary>
+    /// <param name="value">The value to parse.</param>
+    /// <param name="provider">The format provider that will be used to decode the specified value.</param>
+    /// <returns>Returns a new <see cref="DigitalSignature"/> instance, parsed from the specified <see cref="String"/> value.</returns>
+    public static DigitalSignature Parse(string value, IFormatProvider? provider = null) => Parse(value.AsSpan(), provider);
+
+    /// <summary>
+    /// Parses the specified <see cref="ReadOnlySpan{Char}"/> value into a <see cref="DigitalSignature"/> value.
+    /// </summary>
+    /// <param name="value">The value to parse.</param>
+    /// <param name="provider">The format provider that will be used to decode the specified value.</param>
+    /// <returns>Returns a new <see cref="DigitalSignature"/> instance, parsed from the specified <see cref="ReadOnlySpan{Char}"/> value.</returns>
+    public static DigitalSignature Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null)
+    {
+        if (TryParse(value, provider, out DigitalSignature result)) return result;
+        throw new FormatException($"The input string '{value}' was not in a correct format.");
+    }
+
+    /// <summary>
+    /// Tries to parse the specified <see cref="String"/> value into a <see cref="DigitalSignature"/> value.
+    /// </summary>
+    /// <param name="value">The value to parse.</param>
+    /// <param name="provider">The format provider that will be used to decode the specified value.</param>
+    /// <param name="result">
+    /// A new <see cref="DigitalSignature"/> instance, parsed from the specified <see cref="String"/> value, or the default
+    /// <see cref="DigitalSignature"/> value if the specified <see cref="String"/> could not be parsed.
+    /// </param>
+    /// <returns>Returns <see langword="true"/> if the specified value was decoded successfully; otherwise, <see langword="false"/>.</returns>
+    public static bool TryParse(string? value, IFormatProvider? provider, out DigitalSignature result) => TryParse(value.AsSpan(), provider, out result);
+
+    /// <summary>
+    /// Tries to parse the specified <see cref="ReadOnlySpan{Char}"/> value into a <see cref="DigitalSignature"/> value.
+    /// </summary>
+    /// <param name="value">The value to parse.</param>
+    /// <param name="provider">The format provider that will be used to decode the specified value.</param>
+    /// <param name="result">
+    /// A new <see cref="DigitalSignature"/> instance, parsed from the specified <see cref="ReadOnlySpan{Char}"/> value, or the default
+    /// <see cref="DigitalSignature"/> value if the specified <see cref="ReadOnlySpan{Char}"/> could not be parsed.
+    /// </param>
+    /// <returns>Returns <see langword="true"/> if the specified value was decoded successfully; otherwise, <see langword="false"/>.</returns>
+    public static bool TryParse(ReadOnlySpan<char> value, IFormatProvider? provider, out DigitalSignature result)
+    {
+        bool isDecoded = IBaseCodec.TryGetBytes(value, provider ?? Base16FormatProvider.Invariant, out byte[] bytes);
+        result = new DigitalSignature(bytes);
+        return isDecoded;
+    }
+}

OnixLabs.Security.Cryptography/DigitalSignature.To.cs

@@ -13,7 +13,9 @@
 // limitations under the License.
 
 using System;
+using System.Text;
 using OnixLabs.Core;
+using OnixLabs.Core.Text;
 
 namespace OnixLabs.Security.Cryptography;
 
@@ -26,8 +28,15 @@ public readonly partial struct DigitalSignature
     public byte[] ToByteArray() => value.Copy();
 
     /// <summary>
-    /// Returns a <see cref="String"/> that represents the current object.
+    /// Returns a <see cref="string"/> that represents the current object.
     /// </summary>
-    /// <returns>Returns a <see cref="String"/> that represents the current object.</returns>
-    public override string ToString() => Convert.ToHexString(value).ToLower();
+    /// <param name="provider">The format provider that will be used to determine the format of the string.</param>
+    /// <returns>Returns a <see cref="string"/> that represents the current object.</returns>
+    public string ToString(IFormatProvider provider) => IBaseCodec.GetString(ToByteArray(), provider);
+
+    /// <summary>
+    /// Returns a <see cref="string"/> that represents the current object.
+    /// </summary>
+    /// <returns>Returns a <see cref="string"/> that represents the current object.</returns>
+    public override string ToString() => ToString(Base16FormatProvider.Invariant);
 }

OnixLabs.Security.Cryptography/DigitalSignature.cs

@@ -20,7 +20,7 @@ namespace OnixLabs.Security.Cryptography;
 /// Represents a cryptographic digital signature.
 /// </summary>
 /// <param name="value">The underlying value of the cryptographic digital signature.</param>
-public readonly partial struct DigitalSignature(ReadOnlySpan<byte> value) : ICryptoPrimitive<DigitalSignature>
+public readonly partial struct DigitalSignature(ReadOnlySpan<byte> value) : ICryptoPrimitive<DigitalSignature>, ISpanParsable<DigitalSignature>
 {
     private readonly byte[] value = value.ToArray();
 }