Namespace System.Numerics.Generic - IEEE 754 and custom number types

[c-ohle]

I would like to propose a template solution to support IEEE 754 floating-point and decimal types in arbitrary size.

A implementation for floating-point already exists and can be tested: Generic.Float.cs.
(It is currently part of a project for arbitrary arithmetic in general that can be compiled for NET6 and NET7.)

The function set is identical to the system's other floating-point types and current NET7 naming conventions. INumber / IBinaryFloatingPointIeee754 is fully supported.
For the user it is easy to use and to define number types in any desired precision:

Difference to the system types are only the constants implemented as static properties.

It's not all about to have floating-point for higher precision. It is also to support old and new special formats like Extended Float80 or to emulate the processors with specific internal precisision, rounding modes etc.
To make this easy the solution includes a IFloat<T> template that allows to implement new special number types based on Float<T> that inherit the base functionality inclusive all the INumber interfaces.
Examples for this can be found here: Generic.Types.cs

How it works

The template type definition is simple as possible.
The template parameter defines the struct size and the struct size the default IEEE 735 floating-point type and the binary layout:

public readonly struct Float<T> where T : unmanaged
{
  readonly T p;
}

Based on this principle, a set of number type templates are possible, which could stay in a namespace System.Numerics.Generic:

(The implementation for Decimal<T> is already in work.)

Internally, all template-based number types can use the same calculation core. Once initialized, this core does not require any further memory allocation at runtime. Since the number data is stored in the fixed size defined in the template, calculations with such number types can be performed without memory allocations. This is in contrast to other arbitrary number types such as BigInteger or BigRational, where dynamic buffers are required.

[tannergooding]

Reiterating what I said in #74475, this is not something the BCL would be interested in providing.

Having a type that takes a T but which doesn't actually use the T for anything other than sizing information is problematic on multiple levels and I don't see such a proposal ever passing API review. It also comes with numerous usability concerns since a user could pass in (byte, Guid, nuint) and due to the LayoutKind.Auto mechanics of ValueTuple it may differ in size and behavior across different platforms/architectures.

Providing non-standard or largely deprecated formats, such as the 80-bit "extended-precision" format provided by the x87 FPU, is a non-goal of the BCL. Adding more "custom" formats is likewise problematic and comes with many negative downsides.

We may in the future provide an IEEE 754 binary128 type (sometimes called Quad), but that would be an explicit Float128 or similar name. We may likewise in the future provide some BigFloat type, but that would likewise follow the IEEE 754 requirements and would match existing BCL patterns to ensure that developers can easily use and intuitively understand the type and its API surface.

[c-ohle]

@bartonjs thanks for discussion.

As mentioned before, so far it was for compatibility with NET6. For NET7 and later the plan is to constrain the type parameter with a static interface what allows also more specific informations for processor emulations etc. The information needed for the algorythms matches in a 64 bit field. Such interface based floting-point type definition can therefore be a really small and compact but readable.
It's currently as static fields but the static props below can show how the interface could look like.

[tannergooding]

It's a discussion.

Its a discussion that was stemmed off of an issue where the area owners had already explicitly stated "no" and why.

I would really like to know which criteria are violated.

There have been multiple examples given in the original issue, which were reiterated in this discussion, and similar examples given in some of the other issues opened.

so far it was for compatibility with NET6. For NET7 and later the plan is to constrain the type parameter with a static interface what allows also more specific informations for processor emulations etc.

You cannot make a generic constraint more restrictive in a later version of the code, such changes are breaking and that's a "core" consideration for anything exposed in the BCL (stability over time to ensure binary breaks don't occur).

There is no scenario under which you could declare some Float<long> and have it map to a double or some Float<UInt128> and have it map to a hypothetical Float128. This is unintuitive and confusing behavior. It is likewise not infinitely extensible and becomes increasingly more verbose to use the more "bits" you want to represent (such as if you wanted to represent a Float256 or larger).

---

More generally, the BCL follows the "Framework Design Guidelines". Most of the rules for which can be found here: https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/

We then have an entire book that expands on this in more detail including with annotations from members of the API review team: https://www.amazon.com/Framework-Design-Guidelines-Conventions-Addison-Wesley/dp/0135896460/

Almost anything exposed by the BCL is available to all developers "out of the box". We have very stringent requirements to maintain backwards compatibility, to minimally consider forward compatibility so logical extensions to a given type/API can still be made, to be generally consistent with what is already exposed by the BCL, to ensure that types/APIs are easily usable by the target audience, to ensure that code is intuitive to read/maintain/understand, etc.

As indicated the proposals provided so far do not meet this criteria. The area owners are interested in providing some features like Rational, 128-bit IEEE 754 binary float, IEEE 754 decimal, or even "big float/decimal". However, such APIs will need to fit the existing shapes, standards/conventions, and expectations that existing and similar BCL types already follow.

[c-ohle]

@tannergooding

stated "no" and why.

There was no remaining argument why.

There have been multiple examples given in the original issue

It's a whole new approach - unlike the BigRational discussion we had and the technical issues there.

You cannot make a generic constraint more restrictive in a later version of the code

By later I mean tomorrow and not a later framework version.

There is no scenario under which you could declare some Float ...

it would look like this:

  Float<FloatType128X64> x;  
  Float<FloatType32SIMD> y;

or this:

using Float128 = System.Numerics.Generic.Float<FloatType128X64>;
 

Where FloatType128X64 is like a really small key struct type.
Nothing confusing. Everything is type safe and extensible based on the bitmask that already exists.

The real question is - is there a better solution to realize something like this?

[tannergooding]

The real question is - is there a better solution to realize something like this?

"Better" is subjective and what is better for the BCL may not be what is best for your personal scenario or interests.

For the BCL, explicit types such as Float128 or Float256 are better than some generic type whose size is keyed off a "magic" FloatType32SIMD.

Nothing confusing. Everything is type safe and extensible based on the bitmask that already exists.

Not confusing to you. This will be confusing to customers and other developers.

[c-ohle]

@tannergooding

For the BCL, explicit types such as Float128 or Float256 are better than some generic type whose size is keyed off a "magic" FloatType32SIMD.

And that's why I added already a Float128 type as example. This is not a template.
For the user from outside is no difference to other float-number types. Value struct, fixed size, same interfaces, same functions.
And full IBinaryFloatingPointIeee754 support. IFloat<Float128> serves only as implementation helper for this.
Also possible to write all new. Makes finally no difference but more code.
full implementation

public readonly struct Float128 : IFloat<Float128>, IComparable<Float128>, IEquatable<Float128>, IComparable, ISpanFormattable    
{
    public static Float128 operator +(Float128 a, Float128 b) => new Float128(a.p + b.p);
    public static Float128 operator -(Float128 a, Float128 b) => new Float128(a.p - b.p);
    // and so on...

    //private:
    [StructLayout(LayoutKind.Sequential, Size = 16)]
    private readonly struct UInt128 { } // NET6 has no UInt128 
    private readonly Float<UInt128> p;
}

It's all there what you want.
End user view - documentation