StringExtensions.cs

namespace Texnomic.Types.Extensions;

/// <summary>
/// Extension methods for <see cref="string"/> values, primarily hexadecimal parsing helpers.
/// </summary>
/// <remarks>
/// All hex-parsing members assume <c>0x</c>-prefixed input and forward to the corresponding
/// <see cref="ReadOnlySpan{T}"/> extensions for the actual decoding.
/// </remarks>
public static class StringExtensions
{
    extension(string Value)
    {
        /// <summary>
        /// Returns a copy of <paramref name="Value"/> with a leading <c>0x</c> removed, or the
        /// original string when no prefix is present.
        /// </summary>
        /// <returns>The unprefixed payload, or <paramref name="Value"/> unchanged when it does not start with <c>0x</c>.</returns>
        public string RemoveHexPrefix()
            => Value.StartsWith("0x")
                ? new string(Value.AsSpan()[2..])
                : Value;

        /// <summary>Parses a <c>0x</c>-prefixed hexadecimal string into a byte array.</summary>
        /// <returns>The decoded bytes.</returns>
        public byte[] HexToBytes() => Value.AsSpan().HexToBytes();

        /// <summary>Parses a <c>0x</c>-prefixed hexadecimal string into a <see cref="BigDecimal"/>.</summary>
        /// <returns>The decoded value via the unsigned 256-bit path.</returns>
        public BigDecimal HexToBigDecimal() => Value.AsSpan().HexToBigDecimal();

        /// <summary>Parses a <c>0x</c>-prefixed hexadecimal string into an unsigned 256-bit integer.</summary>
        public BigInteger HexToUInt256() => Value.AsSpan().HexToUInt256();

        /// <summary>Parses a <c>0x</c>-prefixed hexadecimal string into a signed 256-bit integer (two's-complement).</summary>
        public BigInteger HexToInt256() => Value.AsSpan().HexToInt256();

        /// <summary>Parses a <c>0x</c>-prefixed hexadecimal string into an unsigned 64-bit integer.</summary>
        public ulong HexToUInt64() => Value.AsSpan().HexToUInt64();

        /// <summary>Parses a <c>0x</c>-prefixed hexadecimal string into a signed 64-bit integer.</summary>
        public long HexToInt64() => Value.AsSpan().HexToInt64();

        /// <summary>Parses a <c>0x</c>-prefixed hexadecimal string into an unsigned 32-bit integer.</summary>
        public uint HexToUInt32() => Value.AsSpan().HexToUInt32();

        /// <summary>Parses a <c>0x</c>-prefixed hexadecimal string into a signed 32-bit integer.</summary>
        public int HexToInt32() => Value.AsSpan().HexToInt32();
    }
}