update/cryptography

Updated cryptography APIs to include cleaner constructors, fewer allocations, better parsing, and cleaner documentation.

Author: MrMatthewLayton

OnixLabs.Core/Extensions.ISpanParsable.cs

@@ -0,0 +1,46 @@
+// 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;
+
+/// <summary>
+/// Provides extension methods for <see cref="ISpanParsable{TSelf}"/> instances.
+/// </summary>
+[EditorBrowsable(EditorBrowsableState.Never)]
+public static class ISpanParsableExtensions
+{
+    /// <summary>
+    /// Provides extension methods for <see cref="ISpanParsable{TSelf}"/> instances.
+    /// </summary>
+    /// <typeparam name="T">The underlying <see cref="ISpanParsable{TSelf}"/> type.</typeparam>
+    extension<T>(ISpanParsable<T>) where T : ISpanParsable<T>
+    {
+        /// <summary>
+        /// Tries to parse the specified <paramref name="value"/>, or throws a <see cref="FormatException"/> if the value cannot be parsed.
+        /// </summary>
+        /// <param name="value">The value to parse.</param>
+        /// <param name="provider">An object that provides culture-specific formatting information about the value.</param>
+        /// <returns>Returns a new instance of <typeparamref name="T"/> parsed from the specified value.</returns>
+        /// <exception cref="FormatException">If the value cannot be parsed.</exception>
+        public static T ParseOrThrow(ReadOnlySpan<char> value, IFormatProvider? provider = null)
+        {
+            // ReSharper disable once ConvertIfStatementToReturnStatement
+            if (T.TryParse(value, provider, out T? result)) return result;
+            throw new FormatException($"The input string '{value}' was not in a correct format.");
+        }
+    }
+}

OnixLabs.Core/Text/Base16.Parse.cs

@@ -19,13 +19,16 @@ namespace OnixLabs.Core.Text;
 public readonly partial struct Base16
 {
     /// <inheritdoc/>
-    public static Base16 Parse(string value, IFormatProvider? provider = null) => Parse(value.AsSpan(), provider);
+    public static Base16 Parse(string value, IFormatProvider? provider = null) =>
+        Parse(value.AsSpan(), provider);
 
     /// <inheritdoc/>
-    public static Base16 Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) => new(IBaseCodec.Base16.Decode(value, provider));
+    public static Base16 Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) =>
+        new(IBaseCodec.Base16.Decode(value, provider));
 
     /// <inheritdoc/>
-    public static bool TryParse(string? value, IFormatProvider? provider, out Base16 result) => TryParse(value.AsSpan(), provider, out result);
+    public static bool TryParse(string? value, IFormatProvider? provider, out Base16 result) =>
+        TryParse(value.AsSpan(), provider, out result);
 
     /// <inheritdoc/>
     public static bool TryParse(ReadOnlySpan<char> value, IFormatProvider? provider, out Base16 result)

OnixLabs.Core/Text/Base32.Parse.cs

@@ -19,13 +19,16 @@ namespace OnixLabs.Core.Text;
 public readonly partial struct Base32
 {
     /// <inheritdoc/>
-    public static Base32 Parse(string value, IFormatProvider? provider = null) => Parse(value.AsSpan(), provider);
+    public static Base32 Parse(string value, IFormatProvider? provider = null) =>
+        Parse(value.AsSpan(), provider);
 
     /// <inheritdoc/>
-    public static Base32 Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) => new(IBaseCodec.Base32.Decode(value, provider));
+    public static Base32 Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) =>
+        new(IBaseCodec.Base32.Decode(value, provider));
 
     /// <inheritdoc/>
-    public static bool TryParse(string? value, IFormatProvider? provider, out Base32 result) => TryParse(value.AsSpan(), provider, out result);
+    public static bool TryParse(string? value, IFormatProvider? provider, out Base32 result) =>
+        TryParse(value.AsSpan(), provider, out result);
 
     /// <inheritdoc/>
     public static bool TryParse(ReadOnlySpan<char> value, IFormatProvider? provider, out Base32 result)

OnixLabs.Core/Text/Base58.Parse.cs

@@ -19,13 +19,16 @@ namespace OnixLabs.Core.Text;
 public readonly partial struct Base58
 {
     /// <inheritdoc/>
-    public static Base58 Parse(string value, IFormatProvider? provider = null) => Parse(value.AsSpan(), provider);
+    public static Base58 Parse(string value, IFormatProvider? provider = null) =>
+        Parse(value.AsSpan(), provider);
 
     /// <inheritdoc/>
-    public static Base58 Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) => new(IBaseCodec.Base58.Decode(value, provider));
+    public static Base58 Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) =>
+        new(IBaseCodec.Base58.Decode(value, provider));
 
     /// <inheritdoc/>
-    public static bool TryParse(string? value, IFormatProvider? provider, out Base58 result) => TryParse(value.AsSpan(), provider, out result);
+    public static bool TryParse(string? value, IFormatProvider? provider, out Base58 result) =>
+        TryParse(value.AsSpan(), provider, out result);
 
     /// <inheritdoc/>
     public static bool TryParse(ReadOnlySpan<char> value, IFormatProvider? provider, out Base58 result)

OnixLabs.Core/Text/Base64.Parse.cs

@@ -19,13 +19,16 @@ namespace OnixLabs.Core.Text;
 public readonly partial struct Base64
 {
     /// <inheritdoc/>
-    public static Base64 Parse(string value, IFormatProvider? provider = null) => Parse(value.AsSpan(), provider);
+    public static Base64 Parse(string value, IFormatProvider? provider = null) =>
+        Parse(value.AsSpan(), provider);
 
     /// <inheritdoc/>
-    public static Base64 Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) => new(IBaseCodec.Base64.Decode(value, provider));
+    public static Base64 Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) =>
+        new(IBaseCodec.Base64.Decode(value, provider));
 
     /// <inheritdoc/>
-    public static bool TryParse(string? value, IFormatProvider? provider, out Base64 result) => TryParse(value.AsSpan(), provider, out result);
+    public static bool TryParse(string? value, IFormatProvider? provider, out Base64 result) =>
+        TryParse(value.AsSpan(), provider, out result);
 
     /// <inheritdoc/>
     public static bool TryParse(ReadOnlySpan<char> value, IFormatProvider? provider, out Base64 result)

OnixLabs.Core/Text/Extensions.Encoding.cs

@@ -22,7 +22,7 @@ namespace OnixLabs.Core.Text;
 /// Provides extension methods <see cref="Encoding"/> instances.
 /// </summary>
 [EditorBrowsable(EditorBrowsableState.Never)]
-internal static class EncodingExtensions
+public static class EncodingExtensions
 {
     /// <summary>
     /// Provides extension methods <see cref="Encoding"/> instances.

OnixLabs.Security.Cryptography/DigitalSignature.Convertible.cs

@@ -19,34 +19,28 @@ namespace OnixLabs.Security.Cryptography;
 
 public readonly partial struct DigitalSignature
 {
-    /// <summary>
-    /// Gets the underlying <see cref="byte"/> array representation of the current <see cref="DigitalSignature"/> instance as a new <see cref="ReadOnlyMemory{T}"/> instance.
-    /// </summary>
-    /// <returns>Return the underlying <see cref="byte"/> array representation of the current <see cref="DigitalSignature"/> instance as a new <see cref="ReadOnlyMemory{T}"/> instance.</returns>
+    /// <inheritdoc/>
     public ReadOnlyMemory<byte> AsReadOnlyMemory() => value;
 
-    /// <summary>
-    /// Gets the underlying <see cref="byte"/> array representation of the current <see cref="DigitalSignature"/> instance as a new <see cref="ReadOnlySpan{T}"/> instance.
-    /// </summary>
-    /// <returns>Return the underlying <see cref="byte"/> array representation of the current <see cref="DigitalSignature"/> instance as a new <see cref="ReadOnlySpan{T}"/> instance.</returns>
+    /// <inheritdoc/>
     public ReadOnlySpan<byte> AsReadOnlySpan() => value;
 
     /// <summary>
-    /// Create a new <see cref="DigitalSignature"/> instance from the specified <see cref="byte"/> array.
+    /// Creates a new <see cref="DigitalSignature"/> instance from the specified <see cref="ReadOnlySpan{T}"/> value.
     /// </summary>
     /// <param name="value">The value from which to create a new <see cref="DigitalSignature"/> instance.</param>
-    /// <returns>Returns a new <see cref="DigitalSignature"/> instance from the specified <see cref="byte"/> array.</returns>
-    public static implicit operator DigitalSignature(byte[] value) => new(value);
+    /// <returns>Returns a new <see cref="DigitalSignature"/> instance from the specified <see cref="ReadOnlySpan{T}"/> value.</returns>
+    public static implicit operator DigitalSignature(ReadOnlySpan<byte> value) => new(value);
 
     /// <summary>
-    /// Create a new <see cref="DigitalSignature"/> instance from the specified <see cref="ReadOnlySpan{T}"/> value.
+    /// Creates a new <see cref="DigitalSignature"/> instance from the specified <see cref="ReadOnlyMemory{T}"/> value.
     /// </summary>
     /// <param name="value">The value from which to create a new <see cref="DigitalSignature"/> instance.</param>
-    /// <returns>Returns a new <see cref="DigitalSignature"/> instance from the specified <see cref="ReadOnlySpan{T}"/> value.</returns>
-    public static implicit operator DigitalSignature(ReadOnlySpan<byte> value) => new(value);
+    /// <returns>Returns a new <see cref="DigitalSignature"/> instance from the specified <see cref="ReadOnlyMemory{T}"/> value.</returns>
+    public static implicit operator DigitalSignature(ReadOnlyMemory<byte> value) => new(value);
 
     /// <summary>
-    /// Create a new <see cref="DigitalSignature"/> instance from the specified <see cref="ReadOnlySequence{T}"/> value.
+    /// Creates a new <see cref="DigitalSignature"/> instance from the specified <see cref="ReadOnlySequence{T}"/> value.
     /// </summary>
     /// <param name="value">The value from which to create a new <see cref="DigitalSignature"/> instance.</param>
     /// <returns>Returns a new <see cref="DigitalSignature"/> instance from the specified <see cref="ReadOnlySequence{T}"/> value.</returns>

OnixLabs.Security.Cryptography/DigitalSignature.Equatable.cs

@@ -12,46 +12,24 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using System.Collections.Generic;
 using OnixLabs.Core.Linq;
 
 namespace OnixLabs.Security.Cryptography;
 
 public readonly partial struct DigitalSignature
 {
-    /// <summary>
-    /// Checks whether the current object is equal to another object of the same type.
-    /// </summary>
-    /// <param name="other">An object to compare with the current object.</param>
-    /// <returns>Returns <see langword="true"/> if the current object is equal to the other parameter; otherwise, <see langword="false"/>.</returns>
+    /// <inheritdoc/>
     public bool Equals(DigitalSignature other) => value.SequenceEqualOrNull(other.value);
 
-    /// <summary>
-    /// Checks for equality between the current instance and another object.
-    /// </summary>
-    /// <param name="obj">The object to check for equality.</param>
-    /// <returns>Returns <see langword="true"/> if the object is equal to the current instance; otherwise, <see langword="false"/>.</returns>
+    /// <inheritdoc/>
     public override bool Equals(object? obj) => obj is DigitalSignature other && Equals(other);
 
-    /// <summary>
-    /// Serves as a hash code function for the current instance.
-    /// </summary>
-    /// <returns>Returns a hash code for the current instance.</returns>
+    /// <inheritdoc/>
     public override int GetHashCode() => value.GetContentHashCode();
 
-    /// <summary>
-    /// Performs an equality comparison between two object instances.
-    /// </summary>
-    /// <param name="left">The left-hand instance to compare.</param>
-    /// <param name="right">The right-hand instance to compare.</param>
-    /// <returns>Returns <see langword="true"/> if the left-hand instance is equal to the right-hand instance; otherwise, <see langword="false"/>.</returns>
-    public static bool operator ==(DigitalSignature left, DigitalSignature right) => EqualityComparer<DigitalSignature>.Default.Equals(left, right);
+    /// <inheritdoc/>
+    public static bool operator ==(DigitalSignature left, DigitalSignature right) => left.Equals(right);
 
-    /// <summary>
-    /// Performs an inequality comparison between two object instances.
-    /// </summary>
-    /// <param name="left">The left-hand instance to compare.</param>
-    /// <param name="right">The right-hand instance to compare.</param>
-    /// <returns>Returns <see langword="true"/> if the left-hand instance is not equal to the right-hand instance; otherwise, <see langword="false"/>.</returns>
-    public static bool operator !=(DigitalSignature left, DigitalSignature right) => !EqualityComparer<DigitalSignature>.Default.Equals(left, right);
+    /// <inheritdoc/>
+    public static bool operator !=(DigitalSignature left, DigitalSignature right) => !left.Equals(right);
 }

OnixLabs.Security.Cryptography/DigitalSignature.Parse.cs

@@ -13,54 +13,26 @@
 // limitations under the License.
 
 using System;
+using OnixLabs.Core;
 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);
+    /// <inheritdoc/>
+    public static DigitalSignature Parse(string value, IFormatProvider? provider = null) =>
+        Parse(value.AsSpan(), provider);
 
-    /// <summary>
-    /// Parses the specified <see cref="ReadOnlySpan{T}"/> 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{T}"/> 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.");
-    }
+    /// <inheritdoc/>
+    public static DigitalSignature Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) =>
+        DigitalSignature.ParseOrThrow(value, provider);
 
-    /// <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);
+    /// <inheritdoc/>
+    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{T}"/> 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{T}"/> value, or the default
-    /// <see cref="DigitalSignature"/> value if the specified <see cref="ReadOnlySpan{T}"/> could not be parsed.
-    /// </param>
-    /// <returns>Returns <see langword="true"/> if the specified value was decoded successfully; otherwise, <see langword="false"/>.</returns>
+    /// <inheritdoc/>
     public static bool TryParse(ReadOnlySpan<char> value, IFormatProvider? provider, out DigitalSignature result)
     {
         bool isDecoded = IBaseCodec.TryGetBytes(value, provider ?? Base16FormatProvider.Invariant, out byte[] bytes);

OnixLabs.Security.Cryptography/DigitalSignature.To.cs

@@ -19,16 +19,9 @@ namespace OnixLabs.Security.Cryptography;
 
 public readonly partial struct DigitalSignature
 {
-    /// <summary>
-    /// Returns a <see cref="string"/> that represents the current object.
-    /// </summary>
-    /// <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>
+    /// <inheritdoc/>
     public string ToString(IFormatProvider provider) => IBaseCodec.GetString(AsReadOnlySpan(), 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>
+    /// <inheritdoc/>
     public override string ToString() => ToString(Base16FormatProvider.Invariant);
 }