Generic math

.NET 7 introduces new math-related generic interfaces to the base class library. The availability of these interfaces means you can constrain a type parameter of a generic type or method to be "number-like". In addition, C# 11 and later lets you define static virtual interface members. Because operators must be declared as static, this new C# feature lets operators be declared in the new interfaces for number-like types.

Together, these innovations allow you to perform mathematical operations generically—that is, without having to know the exact type you're working with. For example, if you wanted to write a method that adds two numbers, previously you had to add an overload of the method for each type (for example, static int Add(int first, int second) and static float Add(float first, float second)). Now you can write a single, generic method, where the type parameter is constrained to be a number-like type. For example:

static T Add<T>(T left, T right)
    where T : INumber<T>
{
    return left + right;
}

In this method, the type parameter T is constrained to be a type that implements the new System.Numerics.INumber interface. System.Numerics.INumber implements the System.Numerics.IAdditionOperators interface, which contains the + operator). That allows the method to generically add the two numbers. The method can be used with any of .NET's built-in numeric types, because they've all been updated to implement System.Numerics.INumber in .NET 7.

Library authors will benefit most from the generic math interfaces, because they can simplify their code base by removing "redundant" overloads. Other developers will benefit indirectly, because the APIs they consume may start supporting more types.

#The interfaces

The interfaces were designed to be both fine-grained enough that users can define their own interfaces on top, while also being granular enough that they're easy to consume. To that extent, there are a few core numeric interfaces that most users will interact with, such as System.Numerics.INumber and System.Numerics.IBinaryInteger. The more fine-grained interfaces, such as System.Numerics.IAdditionOperators and System.Numerics.ITrigonometricFunctions, support these types and are available for developers who define their own domain-specific numeric interfaces.

• Numeric interfaces
• Operator interfaces
• Function interfaces
• Parsing and formatting interfaces

#Numeric interfaces

This section describes the interfaces in System.Numerics that describe number-like types and the functionality available to them.

¹The binary floating-point types are System.Double (double), System.Half, and System.Single (float).

²The binary integer types are System.Byte (byte), System.Int16 (short), System.Int32 (int), System.Int64 (long), System.Int128, System.IntPtr (nint), System.SByte (sbyte), System.UInt16 (ushort), System.UInt32 (uint), System.UInt64 (ulong), System.UInt128, and System.UIntPtr (nuint).

The interface you're most likely to use directly is System.Numerics.INumber, which roughly corresponds to a real number. If a type implements this interface, it means that a value has a sign (this includes unsigned types, which are considered positive) and can be compared to other values of the same type. System.Numerics.INumberBase confers more advanced concepts, such as complex and imaginary numbers, for example, the square root of a negative number. Other interfaces, such as System.Numerics.IFloatingPointIeee754, were created because not all operations make sense for all number types—for example, calculating the floor of a number only makes sense for floating-point types. In the .NET base class library, the floating-point type System.Double implements System.Numerics.IFloatingPointIeee754 but System.Int32 doesn't.

Several of the interfaces are also implemented by various other types, including System.Char, System.DateOnly, System.DateTime, System.DateTimeOffset, System.Decimal, System.Guid, System.TimeOnly, and System.TimeSpan.

The following table shows some of the core APIs exposed by each interface.

¹To help understand the behavior of the three Create* methods, consider the following examples.

Example when given a value that's too large:

• byte.CreateChecked(384) will throw an System.OverflowException.
• byte.CreateSaturating(384) returns 255 because 384 is greater than System.Byte.MaxValue (which is 255).
• byte.CreateTruncating(384) returns 128 because it takes the lowest 8 bits (384 has a hex representation of 0x0180, and the lowest 8 bits is 0x80, which is 128).

Example when given a value that's too small:

• byte.CreateChecked(-384) will throw an System.OverflowException.
• byte.CreateSaturating(-384) returns 0 because -384 is smaller than System.Byte.MinValue (which is 0).
• byte.CreateTruncating(-384) returns 128 because it takes the lowest 8 bits (384 has a hex representation of 0xFE80, and the lowest 8 bits is 0x80, which is 128).

The Create* methods also have some special considerations for IEEE 754 floating-point types, like float and double, as they have the special values PositiveInfinity, NegativeInfinity, and NaN. All three Create* APIs behave as CreateSaturating. Also, while MinValue and MaxValue represent the largest negative/positive "normal" number, the actual minimum and maximum values are NegativeInfinity and PositiveInfinity, so they clamp to these values instead.

#Operator interfaces

The operator interfaces correspond to the various operators available to the C# language.

• They explicitly don't pair operations such as multiplication and division since that isn't correct for all types. For example, Matrix4x4 * Matrix4x4 is valid, but Matrix4x4 / Matrix4x4 isn't valid.
• They typically allow the input and result types to differ to support scenarios such as dividing two integers to obtain a double, for example, 3 / 2 = 1.5, or calculating the average of a set of integers.

#Function interfaces

The function interfaces define common mathematical APIs that apply more broadly than to a specific numeric interface. These interfaces are all implemented by System.Numerics.IFloatingPointIeee754, and may get implemented by other relevant types in the future.

#Parsing and formatting interfaces

Parsing and formatting are core concepts in programming. They're commonly used when converting user input to a given type or displaying a type to the user. These interfaces are in the System namespace.

¹This interface isn't new, nor is it generic. However, it's implemented by all number types and represents the inverse operation of IParsable.

For example, the following program takes two numbers as input, reading them from the console using a generic method where the type parameter is constrained to be System.IParsable. It calculates the average using a generic method where the type parameters for the input and result values are constrained to be System.Numerics.INumber, and then displays the result to the console.

using System.Globalization;
using System.Numerics;

static TResult Average<T, TResult>(T first, T second)
    where T : INumber<T>
    where TResult : INumber<TResult>
{
    return TResult.CreateChecked( (first + second) / T.CreateChecked(2) );
}

static T ParseInvariant<T>(string s)
    where T : IParsable<T>
{
    return T.Parse(s, CultureInfo.InvariantCulture);
}

Console.Write("First number: ");
var left = ParseInvariant<float>(Console.ReadLine());

Console.Write("Second number: ");
var right = ParseInvariant<float>(Console.ReadLine());

Console.WriteLine($"Result: {Average<float, float>(left, right)}");

/* This code displays output similar to:

First number: 5.0
Second number: 6
Result: 5.5
*/

#See also

• Generic math in .NET 7 (blog post)