update/text

Updated the Core/Text implementation to include more constructors, better documentation, and fewer allocations.

Author: MrMatthewLayton

OnixLabs.Core/Text/Base16.Convertible.cs

@@ -14,66 +14,32 @@
 
 using System;
 using System.Buffers;
-using System.Text;
 
 namespace OnixLabs.Core.Text;
 
 public readonly partial struct Base16
 {
-    /// <summary>
-    /// Gets the underlying <see cref="byte"/> array representation of the current <see cref="Base16"/> instance as a new <see cref="ReadOnlyMemory{T}"/> instance.
-    /// </summary>
-    /// <returns>Return the underlying <see cref="byte"/> array representation of the current <see cref="Base16"/> 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="Base16"/> instance as a new <see cref="ReadOnlySpan{T}"/> instance.
-    /// </summary>
-    /// <returns>Return the underlying <see cref="byte"/> array representation of the current <see cref="Base16"/> instance as a new <see cref="ReadOnlySpan{T}"/> instance.</returns>
+    /// <inheritdoc/>
     public ReadOnlySpan<byte> AsReadOnlySpan() => value;
 
-    /// <summary>
-    /// Create a new <see cref="Base16"/> instance from the specified <see cref="byte"/> array.
-    /// </summary>
-    /// <param name="value">The value from which to create a new <see cref="Base16"/> instance.</param>
-    /// <returns>Returns a new <see cref="Base16"/> instance from the specified <see cref="byte"/> array.</returns>
-    public static implicit operator Base16(byte[] value) => new(value);
-
-    /// <summary>
-    /// Create a new <see cref="Base16"/> instance from the specified <see cref="ReadOnlySpan{T}"/> value.
-    /// </summary>
-    /// <param name="value">The value from which to create a new <see cref="Base16"/> instance.</param>
-    /// <returns>Returns a new <see cref="Base16"/> instance from the specified <see cref="ReadOnlySpan{T}"/> value.</returns>
+    /// <inheritdoc/>
     public static implicit operator Base16(ReadOnlySpan<byte> value) => new(value);
 
-    /// <summary>
-    /// Create a new <see cref="Base16"/> instance from the specified <see cref="ReadOnlySequence{T}"/> value.
-    /// </summary>
-    /// <param name="value">The value from which to create a new <see cref="Base16"/> instance.</param>
-    /// <returns>Returns a new <see cref="Base16"/> instance from the specified <see cref="ReadOnlySequence{T}"/> value.</returns>
+    /// <inheritdoc/>
+    public static implicit operator Base16(ReadOnlyMemory<byte> value) => new(value);
+
+    /// <inheritdoc/>
     public static implicit operator Base16(ReadOnlySequence<byte> value) => new(value);
 
-    /// <summary>
-    /// Create a new <see cref="Base16"/> instance from the specified <see cref="string"/> value.
-    /// <remarks>The <see cref="string"/> value will be encoded using the <see cref="Encoding.UTF8"/> encoding.</remarks>
-    /// </summary>
-    /// <param name="value">The value from which to create a new <see cref="Base16"/> instance.</param>
-    /// <returns>Returns a new <see cref="Base16"/> instance from the specified <see cref="string"/> value.</returns>
-    public static implicit operator Base16(string value) => new(value);
+    /// <inheritdoc/>
+    public static implicit operator Base16(ReadOnlySpan<char> value) => new(value);
 
-    /// <summary>
-    /// Create a new <see cref="Base16"/> instance from the specified <see cref="char"/> array.
-    /// <remarks>The <see cref="char"/> array will be encoded using the <see cref="Encoding.UTF8"/> encoding.</remarks>
-    /// </summary>
-    /// <param name="value">The value from which to create a new <see cref="Base16"/> instance.</param>
-    /// <returns>Returns a new <see cref="Base16"/> instance from the specified <see cref="char"/> array.</returns>
-    public static implicit operator Base16(char[] value) => new(value);
+    /// <inheritdoc/>
+    public static implicit operator Base16(ReadOnlyMemory<char> value) => new(value);
 
-    /// <summary>
-    /// Create a new <see cref="Base16"/> instance from the specified <see cref="ReadOnlySequence{T}"/> value.
-    /// <remarks>The <see cref="ReadOnlySequence{T}"/> value will be encoded using the <see cref="Encoding.UTF8"/> encoding.</remarks>
-    /// </summary>
-    /// <param name="value">The value from which to create a new <see cref="Base16"/> instance.</param>
-    /// <returns>Returns a new <see cref="Base16"/> instance from the specified <see cref="ReadOnlySequence{T}"/> value.</returns>
+    /// <inheritdoc/>
     public static implicit operator Base16(ReadOnlySequence<char> value) => new(value);
 }

OnixLabs.Core/Text/Base16.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.Core.Text;
 
 public readonly partial struct Base16
 {
-    /// <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(Base16 other) => other.value.SequenceEqualOrNull(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 Base16 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 ==(Base16 left, Base16 right) => EqualityComparer<Base16>.Default.Equals(left, right);
+    /// <inheritdoc/>
+    public static bool operator ==(Base16 left, Base16 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 !=(Base16 left, Base16 right) => !EqualityComparer<Base16>.Default.Equals(left, right);
+    /// <inheritdoc/>
+    public static bool operator !=(Base16 left, Base16 right) => !left.Equals(right);
 }

OnixLabs.Core/Text/Base16.Format.cs

@@ -18,16 +18,11 @@ namespace OnixLabs.Core.Text;
 
 public readonly partial struct Base16
 {
-    /// <summary>
-    /// Tries to format the value of the current instance into the provided span of characters.
-    /// </summary>
-    /// <param name="destination">The span in which to write this instance's value formatted as a span of characters.</param>
-    /// <param name="charsWritten">When this method returns, contains the number of characters that were written in <paramref name="destination" />.</param>
-    /// <param name="format">A span containing the characters that represent a standard or custom format string that defines the acceptable format for <paramref name="destination" />.</param>
-    /// <param name="provider">An optional object that supplies culture-specific formatting information for <paramref name="destination" />.</param>
-    /// <returns>Returns <see langword="true"/> if the formatting was successful; otherwise, <see langword="false"/>.</returns>
-    bool ISpanFormattable.TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider)
-    {
-        return ToString(format, provider).TryCopyTo(destination, out charsWritten);
-    }
+    /// <inheritdoc/>
+    bool ISpanFormattable.TryFormat(
+        Span<char> destination,
+        out int charsWritten,
+        ReadOnlySpan<char> format,
+        IFormatProvider? provider
+    ) => ToString(format, provider).TryCopyTo(destination, out charsWritten);
 }

OnixLabs.Core/Text/Base16.Parse.cs

@@ -18,44 +18,16 @@ namespace OnixLabs.Core.Text;
 
 public readonly partial struct Base16
 {
-    /// <summary>
-    /// Parses the specified Base-16 encoded <see cref="String"/> value into a <see cref="Base16"/> value.
-    /// </summary>
-    /// <param name="value">The Base-16 encoded 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="Base16"/> instance, parsed from the specified Base-16 encoded <see cref="String"/> value.</returns>
+    /// <inheritdoc/>
     public static Base16 Parse(string value, IFormatProvider? provider = null) => Parse(value.AsSpan(), provider);
 
-    /// <summary>
-    /// Parses the specified Base-16 encoded <see cref="ReadOnlySpan{T}"/> value into a <see cref="Base16"/> value.
-    /// </summary>
-    /// <param name="value">The Base-16 encoded 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="Base16"/> instance, parsed from the specified Base-16 encoded <see cref="ReadOnlySpan{T}"/> value.</returns>
+    /// <inheritdoc/>
     public static Base16 Parse(ReadOnlySpan<char> value, IFormatProvider? provider = null) => new(IBaseCodec.Base16.Decode(value, provider));
 
-    /// <summary>
-    /// Tries to parse the specified Base-16 encoded <see cref="String"/> value into a <see cref="Base16"/> value.
-    /// </summary>
-    /// <param name="value">The Base-16 encoded 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="Base16"/> instance, parsed from the specified Base-16 encoded <see cref="String"/> value,
-    /// or the default <see cref="Base16"/> value if the specified Base-16 encoded <see cref="String"/> could not be parsed.
-    /// </param>
-    /// <returns>Returns <see langword="true"/> if the specified Base-16 value was decoded successfully; otherwise, <see langword="false"/>.</returns>
+    /// <inheritdoc/>
     public static bool TryParse(string? value, IFormatProvider? provider, out Base16 result) => TryParse(value.AsSpan(), provider, out result);
 
-    /// <summary>
-    /// Tries to parse the specified Base-16 encoded <see cref="ReadOnlySpan{T}"/> value into a <see cref="Base16"/> value.
-    /// </summary>
-    /// <param name="value">The Base-16 encoded 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="Base16"/> instance, parsed from the specified Base-16 encoded <see cref="ReadOnlySpan{T}"/> value,
-    /// or the default <see cref="Base16"/> value if the specified Base-16 encoded <see cref="ReadOnlySpan{T}"/> could not be parsed.
-    /// </param>
-    /// <returns>Returns <see langword="true"/> if the specified Base-16 value was decoded successfully; otherwise, <see langword="false"/>.</returns>
+    /// <inheritdoc/>
     public static bool TryParse(ReadOnlySpan<char> value, IFormatProvider? provider, out Base16 result)
     {
         if (IBaseCodec.Base16.TryDecode(value, provider, out byte[] bytes))

OnixLabs.Core/Text/Base16.To.cs

@@ -18,32 +18,15 @@ namespace OnixLabs.Core.Text;
 
 public readonly partial struct Base16
 {
-    /// <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);
 
-    /// <summary>
-    /// Formats the value of the current instance using the specified format.
-    /// </summary>
-    /// <param name="formatProvider">The provider to use to format the value.</param>
-    /// <returns>The value of the current instance in the specified format.</returns>
+    /// <inheritdoc/>
     public string ToString(IFormatProvider? formatProvider) => ToString(null, formatProvider);
 
-    /// <summary>
-    /// Formats the value of the current instance using the specified format.
-    /// </summary>
-    /// <param name="format">The format to use.</param>
-    /// <param name="formatProvider">The provider to use to format the value.</param>
-    /// <returns>The value of the current instance in the specified format.</returns>
+    /// <inheritdoc/>
     public string ToString(string? format, IFormatProvider? formatProvider) => ToString(format.AsSpan(), formatProvider);
 
-    /// <summary>
-    /// Formats the value of the current instance using the specified format.
-    /// </summary>
-    /// <param name="format">The format to use.</param>
-    /// <param name="formatProvider">The provider to use to format the value.</param>
-    /// <returns>The value of the current instance in the specified format.</returns>
+    /// <inheritdoc/>
     public string ToString(ReadOnlySpan<char> format, IFormatProvider? formatProvider) => IBaseCodec.Base16.Encode(value, formatProvider);
 }

OnixLabs.Core/Text/Base16.cs

@@ -21,44 +21,69 @@ namespace OnixLabs.Core.Text;
 /// <summary>
 /// Represents a Base-16 value.
 /// </summary>
-/// <param name="value">The <see cref="ReadOnlySpan{T}"/> with which to initialize the <see cref="Base16"/> instance.</param>
-public readonly partial struct Base16(ReadOnlySpan<byte> value) : IBaseValue<Base16>
+// ReSharper disable MemberCanBePrivate.Global
+public readonly partial struct Base16 : IBaseValue<Base16>
 {
-    private readonly byte[] value = value.ToArray();
+    private readonly byte[] value;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="Base16"/> struct.
     /// </summary>
-    /// <param name="value">The <see cref="ReadOnlySequence{T}"/> with which to initialize the <see cref="Base16"/> instance.</param>
-    // ReSharper disable once MemberCanBePrivate.Global
-    public Base16(ReadOnlySequence<byte> value) : this(ReadOnlySpan<byte>.Empty) => value.CopyTo(out this.value);
+    /// <remarks>
+    /// This constructor is intentionally marked <see langword="private"/> and is used exclusively to initialize the underlying <see cref="byte"/> array.
+    /// Because <see cref="Base16"/> is designed to be immutable, external array references are not permitted.
+    /// The overloaded constructors below ensure immutability by creating defensive copies of the provided arrays.
+    /// </remarks>
+    /// <param name="value">The value from which to initialize the new <see cref="Base16"/> instance.</param>
+    private Base16(byte[] value) => this.value = value;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="Base16"/> struct.
     /// </summary>
-    /// <param name="value">The <see cref="string"/> with which to initialize the <see cref="Base16"/> instance.</param>
-    /// <param name="encoding">The <see cref="Encoding"/> which will be used to obtain the underlying value.</param>
-    // ReSharper disable once MemberCanBePrivate.Global
-    public Base16(string value, Encoding? encoding = null) : this(encoding.GetOrDefault().GetBytes(value))
+    /// <param name="value">The value from which to initialize the new <see cref="Base16"/> instance.</param>
+    public Base16(ReadOnlySpan<byte> value) : this(value.ToArray())
     {
     }
 
     /// <summary>
     /// Initializes a new instance of the <see cref="Base16"/> struct.
     /// </summary>
-    /// <param name="value">The <see cref="char"/> array with which to initialize the <see cref="Base16"/> instance.</param>
-    /// <param name="encoding">The <see cref="Encoding"/> which will be used to obtain the underlying value.</param>
-    // ReSharper disable once MemberCanBePrivate.Global
-    public Base16(char[] value, Encoding? encoding = null) : this(encoding.GetOrDefault().GetBytes(value))
+    /// <param name="value">The value from which to initialize the new <see cref="Base16"/> instance.</param>
+    public Base16(ReadOnlyMemory<byte> value) : this(value.ToArray())
     {
     }
 
     /// <summary>
     /// Initializes a new instance of the <see cref="Base16"/> struct.
     /// </summary>
-    /// <param name="value">The <see cref="ReadOnlySequence{T}"/> with which to initialize the <see cref="Base16"/> instance.</param>
-    /// <param name="encoding">The <see cref="Encoding"/> which will be used to obtain the underlying value.</param>
-    // ReSharper disable once MemberCanBePrivate.Global
+    /// <param name="value">The value from which to initialize the new <see cref="Base16"/> instance.</param>
+    public Base16(ReadOnlySequence<byte> value) : this(value.ToArray())
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Base16"/> struct.
+    /// </summary>
+    /// <param name="value">The value from which to initialize the new <see cref="Base16"/> instance.</param>
+    /// <param name="encoding">The <see cref="Encoding"/> that will be used to transform the specified value, or <see langword="null"/> to use the default <see cref="Encoding"/>.</param>
+    public Base16(ReadOnlySpan<char> value, Encoding? encoding = null) : this(encoding.GetBytes(value))
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Base16"/> struct.
+    /// </summary>
+    /// <param name="value">The value from which to initialize the new <see cref="Base16"/> instance.</param>
+    /// <param name="encoding">The <see cref="Encoding"/> that will be used to transform the specified value, or <see langword="null"/> to use the default <see cref="Encoding"/>.</param>
+    public Base16(ReadOnlyMemory<char> value, Encoding? encoding = null) : this(encoding.GetBytes(value.Span))
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Base16"/> struct.
+    /// </summary>
+    /// <param name="value">The value from which to initialize the new <see cref="Base16"/> instance.</param>
+    /// <param name="encoding">The <see cref="Encoding"/> that will be used to transform the specified value, or <see langword="null"/> to use the default <see cref="Encoding"/>.</param>
     public Base16(ReadOnlySequence<char> value, Encoding? encoding = null) : this(encoding.GetOrDefault().GetBytes(value))
     {
     }