Int32Le.cs

using System;
using System.Buffers.Binary;
using System.ComponentModel;
using System.Globalization;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;

namespace Stardust.Utilities
{
    /// <summary>
    /// Little-endian 32-bit signed integer type.
    /// Stores bytes in little-endian order (least significant byte first).
    /// </summary>
    [Serializable]
    [TypeConverter(typeof(Int32LeTypeConverter))]
    [StructLayout(LayoutKind.Explicit, Size = 4)]
    public struct Int32Le : IComparable, IComparable<Int32Le>, IEquatable<Int32Le>,
                             IFormattable, ISpanFormattable, IParsable<Int32Le>, ISpanParsable<Int32Le>
    {
        [FieldOffset(0)] internal UInt16Le lo;
        [FieldOffset(2)] internal UInt16Le hi;

        /// <summary>Initializes a new <see cref="Int32Le"/> from an <see cref="int"/> value.</summary>
        /// <param name="num">The value to store.</param>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public Int32Le(int num)
        {
            Unsafe.SkipInit(out this);
#if BIG_ENDIAN
            Unsafe.As<Int32Le, int>(ref this) = BinaryPrimitives.ReverseEndianness(num);
#else
            Unsafe.As<Int32Le, int>(ref this) = num;
#endif
        }

        /// <summary>Initializes a new <see cref="Int32Le"/> from a read-only byte span.</summary>
        /// <param name="bytes">A span containing at least 4 bytes.</param>
        /// <exception cref="ArgumentException"><paramref name="bytes"/> has fewer than 4 bytes.</exception>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public Int32Le(ReadOnlySpan<byte> bytes)
        {
            if (bytes.Length < 4) throw new ArgumentException("Span must have at least 4 bytes", nameof(bytes));
            lo = new UInt16Le(bytes);
            hi = new UInt16Le(bytes.Slice(2));
        }

        /// <summary>
        /// Initializes a new <see cref="Int32Le"/> from a read-only byte span whose byte order is specified.
        /// </summary>
        /// <param name="bytes">Source span (must have at least 4 bytes).</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) the source is interpreted as little-endian; if <see langword="true"/> it is interpreted as big-endian and reversed during storage.</param>
        /// <exception cref="ArgumentException">If span is too short.</exception>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public Int32Le(ReadOnlySpan<byte> bytes, bool isBigEndian = false)
        {
            if (bytes.Length < 4) throw new ArgumentException("Span must have at least 4 bytes", nameof(bytes));
            Unsafe.SkipInit(out this);
            Span<byte> dst = MemoryMarshal.AsBytes(MemoryMarshal.CreateSpan(ref this, 1));
            if (isBigEndian)
            {
                for (int i = 0; i < 4; i++) dst[i] = bytes[3 - i];
            }
            else
            {
                bytes[..4].CopyTo(dst);
            }
        }

        /// <summary>
        /// Initializes a new <see cref="Int32Le"/> from a read-only byte span at the given offset.
        /// </summary>
        /// <param name="bytes">Source span (must have at least 4 bytes starting from <paramref name="offset"/>).</param>
        /// <param name="offset">Starting offset in the span.</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) the source is interpreted as little-endian; if <see langword="true"/> it is interpreted as big-endian and reversed during storage.</param>
        /// <exception cref="ArgumentException">If span is too short from the given offset.</exception>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public Int32Le(ReadOnlySpan<byte> bytes, int offset, bool isBigEndian = false)
        {
            if (bytes.Length - offset < 4) throw new ArgumentException("Span must have at least 4 bytes", nameof(bytes));
            Unsafe.SkipInit(out this);
            Span<byte> dst = MemoryMarshal.AsBytes(MemoryMarshal.CreateSpan(ref this, 1));
            if (isBigEndian)
            {
                for (int i = 0; i < 4; i++) dst[i] = bytes[offset + 3 - i];
            }
            else
            {
                bytes.Slice(offset, 4).CopyTo(dst);
            }
        }

        /// <summary>Initializes a new <see cref="Int32Le"/> from a byte array whose byte order is specified.</summary>
        /// <param name="bytes">Source byte array (must have at least 4 bytes).</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) the source is interpreted as little-endian; if <see langword="true"/> it is interpreted as big-endian and reversed during storage.</param>
        /// <exception cref="ArgumentException">The array is too short.</exception>
        public Int32Le(byte[] bytes, bool isBigEndian = false) : this(new ReadOnlySpan<byte>(bytes), isBigEndian) { }

        /// <summary>Initializes a new <see cref="Int32Le"/> from a byte array at the given offset.</summary>
        /// <param name="bytes">Source byte array (must have at least 4 bytes starting from <paramref name="offset"/>).</param>
        /// <param name="offset">The zero-based offset into <paramref name="bytes"/>.</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) the source is interpreted as little-endian; if <see langword="true"/> it is interpreted as big-endian and reversed during storage.</param>
        /// <exception cref="ArgumentException">The array is too short for the given offset.</exception>
        public Int32Le(byte[] bytes, int offset, bool isBigEndian = false) : this(new ReadOnlySpan<byte>(bytes), offset, isBigEndian) { }

        /// <summary>Writes the value to a byte array in the specified byte order.</summary>
        /// <param name="bytes">The destination byte array.</param>
        /// <param name="offset">The zero-based offset into <paramref name="bytes"/>.</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) bytes are written little-endian; if <see langword="true"/> they are written big-endian.</param>
        [Obsolete("Use WriteTo(byte[], int, bool) instead.")]
        public readonly void ToBytes(byte[] bytes, int offset = 0, bool isBigEndian = false)
            => WriteTo(new Span<byte>(bytes), offset, isBigEndian);

        /// <summary>Writes the value to a destination span in the specified byte order.</summary>
        /// <param name="destination">A span with at least 4 bytes of space starting from <paramref name="offset"/>.</param>
        /// <param name="offset">The zero-based offset into <paramref name="destination"/>.</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) bytes are written little-endian; if <see langword="true"/> they are written big-endian.</param>
        /// <exception cref="ArgumentException"><paramref name="destination"/> is too short.</exception>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public readonly void WriteTo(Span<byte> destination, int offset = 0, bool isBigEndian = false)
        {
            if (destination.Length - offset < 4) throw new ArgumentException("Destination span must have at least 4 bytes", nameof(destination));
            if (isBigEndian)
            {
                destination[offset + 0] = hi.hi;
                destination[offset + 1] = hi.lo;
                destination[offset + 2] = lo.hi;
                destination[offset + 3] = lo.lo;
            }
            else
            {
                lo.WriteTo(destination, offset);
                hi.WriteTo(destination, offset + 2);
            }
        }

        /// <summary>Writes the value to a byte array in the specified byte order.</summary>
        /// <param name="destination">Destination byte array (must have at least 4 bytes starting from <paramref name="offset"/>).</param>
        /// <param name="offset">The zero-based offset into <paramref name="destination"/>.</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) bytes are written little-endian; if <see langword="true"/> they are written big-endian.</param>
        /// <exception cref="ArgumentException">The array is too short.</exception>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public readonly void WriteTo(byte[] destination, int offset = 0, bool isBigEndian = false)
            => WriteTo(new Span<byte>(destination), offset, isBigEndian);

        /// <summary>Attempts to write the value to a destination span in the specified byte order.</summary>
        /// <param name="destination">The destination span.</param>
        /// <param name="offset">The zero-based offset into <paramref name="destination"/>.</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) bytes are written little-endian; if <see langword="true"/> they are written big-endian.</param>
        /// <returns><see langword="true"/> if the span was large enough; otherwise <see langword="false"/>.</returns>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public readonly bool TryWriteTo(Span<byte> destination, int offset = 0, bool isBigEndian = false)
        {
            if (destination.Length - offset < 4)
                return false;
            if (isBigEndian)
            {
                destination[offset + 0] = hi.hi;
                destination[offset + 1] = hi.lo;
                destination[offset + 2] = lo.hi;
                destination[offset + 3] = lo.lo;
            }
            else
            {
                lo.WriteTo(destination, offset);
                hi.WriteTo(destination, offset + 2);
            }
            return true;
        }

        /// <summary>Attempts to write the value to a byte array in the specified byte order.</summary>
        /// <param name="destination">Destination byte array.</param>
        /// <param name="offset">The zero-based offset into <paramref name="destination"/>.</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) bytes are written little-endian; if <see langword="true"/> they are written big-endian.</param>
        /// <returns><see langword="true"/> if the array was large enough; otherwise <see langword="false"/>.</returns>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public readonly bool TryWriteTo(byte[] destination, int offset = 0, bool isBigEndian = false)
            => TryWriteTo(new Span<byte>(destination), offset, isBigEndian);

        /// <summary>Reads an <see cref="Int32Le"/> from a read-only byte span in the specified byte order.</summary>
        /// <param name="source">A span containing at least 4 bytes.</param>
        /// <param name="offset">The zero-based offset into <paramref name="source"/>.</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) the source is interpreted as little-endian; if <see langword="true"/> it is interpreted as big-endian.</param>
        /// <returns>The value read from the span.</returns>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le ReadFrom(ReadOnlySpan<byte> source, int offset = 0, bool isBigEndian = false) => new(source, offset, isBigEndian);

        /// <summary>Reads an <see cref="Int32Le"/> from a byte array in the specified byte order.</summary>
        /// <param name="source">A byte array containing at least 4 bytes.</param>
        /// <param name="offset">The zero-based offset into <paramref name="source"/>.</param>
        /// <param name="isBigEndian">If <see langword="false"/> (default) the source is interpreted as little-endian; if <see langword="true"/> it is interpreted as big-endian.</param>
        /// <returns>The value read from the array.</returns>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le ReadFrom(byte[] source, int offset = 0, bool isBigEndian = false) => new(new ReadOnlySpan<byte>(source), offset, isBigEndian);

        /// <summary>Parses a string into an <see cref="Int32Le"/>.</summary>
        /// <param name="s">The string to parse.</param>
        /// <param name="style">The number style to use.</param>
        /// <returns>The parsed value.</returns>
        public static Int32Le Parse(string s, NumberStyles style = NumberStyles.Integer)
        {
            if (style == NumberStyles.HexNumber) s = s.ToLower().Replace("0x", "");
            return new(int.Parse(s, style));
        }

        /// <summary>Parses a string into an <see cref="Int32Le"/> using the specified format provider.</summary>
        /// <param name="s">The string to parse.</param>
        /// <param name="provider">The format provider.</param>
        /// <returns>The parsed value.</returns>
        public static Int32Le Parse(string s, IFormatProvider? provider) => new(int.Parse(s, provider));
        /// <summary>Parses a character span into an <see cref="Int32Le"/> using the specified format provider.</summary>
        /// <param name="s">The character span to parse.</param>
        /// <param name="provider">The format provider.</param>
        /// <returns>The parsed value.</returns>
        public static Int32Le Parse(ReadOnlySpan<char> s, IFormatProvider? provider) => new(int.Parse(s, provider));

        /// <summary>Tries to parse a string into an <see cref="Int32Le"/>.</summary>
        /// <param name="s">The string to parse.</param>
        /// <param name="provider">The format provider.</param>
        /// <param name="result">When successful, the parsed value.</param>
        /// <returns><see langword="true"/> if parsing succeeded; otherwise <see langword="false"/>.</returns>
        public static bool TryParse(string? s, IFormatProvider? provider, out Int32Le result)
        {
            if (int.TryParse(s, provider, out int v)) { result = new(v); return true; }
            result = default; return false;
        }

        /// <summary>Tries to parse a character span into an <see cref="Int32Le"/>.</summary>
        /// <param name="s">The character span to parse.</param>
        /// <param name="provider">The format provider.</param>
        /// <param name="result">When successful, the parsed value.</param>
        /// <returns><see langword="true"/> if parsing succeeded; otherwise <see langword="false"/>.</returns>
        public static bool TryParse(ReadOnlySpan<char> s, IFormatProvider? provider, out Int32Le result)
        {
            if (int.TryParse(s, provider, out int v)) { result = new(v); return true; }
            result = default; return false;
        }

        /// <inheritdoc/>
        public override readonly string ToString() => ((int)this).ToString();
        /// <inheritdoc/>
        public readonly string ToString(string? format, IFormatProvider? formatProvider) => ((int)this).ToString(format, formatProvider);
        /// <inheritdoc/>
        public readonly bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format, IFormatProvider? provider) =>
            ((int)this).TryFormat(destination, out charsWritten, format, provider);

        /// <inheritdoc/>
        public readonly int CompareTo(object? obj) { if (obj == null) throw new ArgumentException("obj is null"); return CompareTo((Int32Le)obj); }
        /// <inheritdoc/>
        public readonly int CompareTo(Int32Le other) => ((int)this).CompareTo((int)other);
        /// <inheritdoc/>
        public override readonly bool Equals(object? obj) => obj != null && Equals((Int32Le)obj);
        /// <inheritdoc/>
        public readonly bool Equals(Int32Le other) => this == other;
        /// <inheritdoc/>
        public override readonly int GetHashCode() => ((int)this).GetHashCode();

        #region Operators

        /// <summary>Returns the value of the operand (unary plus).</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator +(Int32Le a) => a;
        /// <summary>Negates the value (unary minus).</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator -(Int32Le a) => new(-(int)a);
        /// <summary>Adds two values.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator +(Int32Le a, Int32Le b) => new((int)a + (int)b);
        /// <summary>Subtracts two values.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator -(Int32Le a, Int32Le b) => new((int)a - (int)b);
        /// <summary>Determines whether the left operand is greater than the right.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static bool operator >(Int32Le a, Int32Le b) => (int)a > (int)b;
        /// <summary>Determines whether the left operand is less than the right.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static bool operator <(Int32Le a, Int32Le b) => (int)a < (int)b;
        /// <summary>Determines whether the left operand is greater than or equal to the right.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static bool operator >=(Int32Le a, Int32Le b) => (int)a >= (int)b;
        /// <summary>Determines whether the left operand is less than or equal to the right.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static bool operator <=(Int32Le a, Int32Le b) => (int)a <= (int)b;
        /// <summary>Determines whether two values are equal.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static bool operator ==(Int32Le a, Int32Le b) => (int)a == (int)b;
        /// <summary>Determines whether two values are not equal.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static bool operator !=(Int32Le a, Int32Le b) => (int)a != (int)b;
        /// <summary>Multiplies two values.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator *(Int32Le a, Int32Le b) => new((int)a * (int)b);
        /// <summary>Divides two values.</summary>
        /// <exception cref="DivideByZeroException">The divisor is zero.</exception>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator /(Int32Le a, Int32Le b)
        {
            if ((int)b == 0) throw new DivideByZeroException();
            return new((int)a / (int)b);
        }
        /// <summary>Computes the bitwise AND of two values.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator &(Int32Le a, Int32Le b) => new((int)a & (int)b);
        /// <summary>Computes the bitwise OR of two values.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator |(Int32Le a, Int32Le b) => new((int)a | (int)b);
        /// <summary>Computes the bitwise XOR of two values.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator ^(Int32Le a, Int32Le b) => new((int)a ^ (int)b);
        /// <summary>Computes the bitwise complement of the value.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator ~(Int32Le a) => new(~(int)a);
        /// <summary>Shifts the value right by the specified amount.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator >>(Int32Le a, int b) => new((int)a >> b);
        /// <summary>Performs an unsigned (logical) right shift by the specified amount.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator >>>(Int32Le a, int b) => new((int)((uint)(int)a >> b));
        /// <summary>Shifts the value left by the specified amount.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator <<(Int32Le a, int b) => new((int)a << b);
        /// <summary>Computes the remainder of dividing two values.</summary>
        /// <exception cref="DivideByZeroException">The divisor is zero.</exception>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator %(Int32Le a, Int32Le b)
        {
            if ((int)b == 0) throw new DivideByZeroException();
            return new((int)a % (int)b);
        }
        /// <summary>Increments the value by one.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator ++(Int32Le a) => new((int)a + 1);
        /// <summary>Decrements the value by one.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static Int32Le operator --(Int32Le a) => new((int)a - 1);

        #endregion

        #region Conversions

        /// <summary>Implicitly converts an <see cref="Int32Le"/> to an <see cref="int"/>.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
#if BIG_ENDIAN
        public static implicit operator int(Int32Le a) => BinaryPrimitives.ReverseEndianness(Unsafe.As<Int32Le, int>(ref a));
#else
        public static implicit operator int(Int32Le a) => Unsafe.As<Int32Le, int>(ref a);
#endif

        /// <summary>Implicitly converts an <see cref="int"/> to an <see cref="Int32Le"/>.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static implicit operator Int32Le(int a) => new(a);

        /// <summary>Implicitly converts an <see cref="Int32Le"/> to a <see cref="long"/>.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static implicit operator long(Int32Le a) => (int)a;

        /// <summary>Explicitly converts an <see cref="Int32Le"/> to a <see cref="uint"/>.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static explicit operator uint(Int32Le a) => (uint)(int)a;

        /// <summary>Sign-extending conversion from a 16-bit little-endian signed value.</summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public static explicit operator Int32Le(Int16Le v)
        {
            short value = (short)v;
            return new Int32Le(value);
        }

        #endregion
    }
}