[API Proposal]: `BigMul` for `nuint` and `nint`

[MineCake147E]

Background and motivation

.NET 9 lacks BigMul API for nuint for some reason.
BigMul is useful for implementing something like multiplicative hashing, decoding factoradic with fixed max input value, Lemire's algorithm for generating bounded random integers efficiently, and fast fraction multiplications (necessary for something like MemoryMarshal.Cast<Vector4, Vector3>()).

API Proposal

namespace System
{
    public readonly struct UIntPtr
    {
        public static nuint BigMul(nuint a, nuint b, out nuint low);
    }

    public readonly struct IntPtr
    {
        public static nint BigMul(nint a, nint b, out nint low);
    }
}

Approved API

• Changed (a, b, out low) to (left, right, out lower) to match the newer versions of these methods.
• Exposed the UInt128 and Int128 versions, too (because we thought they already were public)

namespace System
{
    public readonly partial struct UIntPtr
    {
        public static nuint BigMul(nuint left, nuint right, out nuint lower);
    }

    public readonly partial struct IntPtr
    {
        public static nint BigMul(nint left, nint right, out nint lower);
    }

    public readonly partial struct UInt128
    {
        public static UInt128 BigMul(UInt128 left, UInt128 right, out UInt128 lower);
    }

    public readonly partial struct Int128
    {
        public static Int128 BigMul(Int128 left, Int128 right, out Int128 lower);
    }
}

API Usage

var sb = new StringBuilder("0.");
var low = ~(nuint)0;
while (low > 0)
{
    sb.Append($"{nuint.BigMul(10, low, out low)}");
}
Console.Out.WriteLine(sb);

Alternative Designs

Risks

None

[tannergooding]

You'd need to update the proposal to expose it on nint/nuint instead. It should always be done in pairs and we're no longer versioning System.Math or System.MathF.

[huoyaoyuan]

Given there is already (TSelf, TSelf) DivRem(TSelf, TSelf) in generic math, would it make sense to also expose (TSelf, TSelf) BigMul(TSelf, TSelf) in generic math?

Update: there is already Int128 BigMul(Int64, Int64), which conflicts with the overload. However, there's no definition of "2*nint" type.

[bartonjs]

Video

• Changed (a, b, out low) to (left, right, out lower) to match the newer versions of these methods.
• Exposed the UInt128 and Int128 versions, too (because we thought they already were public)

namespace System
{
    public readonly partial struct UIntPtr
    {
        public static nuint BigMul(nuint left, nuint right, out nuint lower);
    }

    public readonly partial struct IntPtr
    {
        public static nint BigMul(nint left, nint right, out nint lower);
    }

    public readonly partial struct UInt128
    {
        public static UInt128 BigMul(UInt128 left, UInt128 right, out UInt128 lower);
    }

    public readonly partial struct Int128
    {
        public static Int128 BigMul(Int128 left, Int128 right, out Int128 lower);
    }
}