培训
泛型数学
.NET 7 为基类库引入了新的数学相关泛型接口。 提供这些接口意味着可以将泛型类型或方法的类型参数约束为“类似于数字”。 此外,C# 11 及更高版本允许定义 static virtual
接口成员。 由于必须将运算符声明为 static
,因此这一新的 C# 功能可用于在新接口中为类似于数字的类型声明运算符。
总之,这些创新使你可以常规地执行数学运算,也就是说,无需知道正在使用的确切类型。 例如,如果想编写一个将两个数字相加的方法,在以前,必须为每种类型添加方法的重载(例如,static int Add(int first, int second)
和 static float Add(float first, float second)
)。 现在,可以编写一个单一的泛型方法,其中将类型参数约束为类似于数字的类型。 例如:
static T Add<T>(T left, T right)
where T : INumber<T>
{
return left + right;
}
在此方法中,类型参数 T
约束为了实现新 INumber<TSelf> 接口的类型。 INumber<TSelf> 实现了 IAdditionOperators<TSelf,TOther,TResult> 接口,其中包含 + 运算符。 这使得该方法可以常规地将两个数字相加。 该方法可以与 .NET 的任何内置数字类型一起使用,因为它们都已更新为在 .NET 7 中实现 INumber<TSelf>。
库作者将从泛型数学接口中受益最多,因为他们可以通过删除“冗余”重载来简化其代码库。 其他开发人员将间接受益,因为他们使用的 API 可能会开始支持更多类型。
接口设计为既需要足够细化(以便用户可以在上面定义自己的接口),又要足够精细(以便易于使用)。 在这种情况下,大多数用户会与一些核心数字接口进行交互,例如 INumber<TSelf> 和 IBinaryInteger<TSelf>。 更细化的接口(例如 IAdditionOperators<TSelf,TOther,TResult> 和 ITrigonometricFunctions<TSelf>)支持这些类型,并且可供开发人员使用,定义其自己的特定于域的数字接口。
本部分介绍 System.Numerics 中的接口,这些接口描述了类似于数字的类型及其可用的功能。
接口名称 | 说明 |
---|---|
IBinaryFloatingPointIeee754<TSelf> | 公开对实现 IEEE 754 标准的二进制浮点类型1通用的 API。 |
IBinaryInteger<TSelf> | 公开对二进制整数通用的 API2。 |
IBinaryNumber<TSelf> | 公开对二进制数字通用的 API。 |
IFloatingPoint<TSelf> | 公开对浮点类型通用的 API。 |
IFloatingPointIeee754<TSelf> | 公开对实现 IEEE 754 标准的浮点类型通用的 API。 |
INumber<TSelf> | 公开对可比较数字类型(实际上是“实数”数字域)通用的 API。 |
INumberBase<TSelf> | 公开对所有数字类型(实际上是“复数”数字域)通用的 API。 |
ISignedNumber<TSelf> | 公开对所有有符号数字类型通用的 API(例如 NegativeOne 的概念)。 |
IUnsignedNumber<TSelf> | 公开对所有无符号数字类型通用的 API。 |
IAdditiveIdentity<TSelf,TResult> | 公开 (x + T.AdditiveIdentity) == x 的概念。 |
IMinMaxValue<TSelf> | 公开 T.MinValue 和 T.MaxValue 的概念。 |
IMultiplicativeIdentity<TSelf,TResult> | 公开 (x * T.MultiplicativeIdentity) == x 的概念。 |
1二进制浮点类型是 Double (double
)、Half 和 Single (float
)。
2二进制整数类型是 Byte (byte
)、Int16 (short
)、Int32 (int
)、Int64 (long
)、Int128、IntPtr (nint
)、SByte (sbyte
)、UInt16 (ushort
)、UInt32 (uint
)、UInt64 (ulong
)、UInt128 和 UIntPtr (nuint
)。
最有可能直接使用的接口是 INumber<TSelf>,它大致对应于一个实数。 如果某个类型实现了此接口,则意味着一个值有一个符号(这包括 unsigned
类型,这些类型被认为是正数)并且可以与相同类型的其他值进行比较。 INumberBase<TSelf> 提供复数和虚数等更高级的概念,例如负数的平方根。 创建其他接口(例如 IFloatingPointIeee754<TSelf>)是因为并非所有操作都对所有数字类型都有意义。例如,计算数字的下限仅对浮点类型有意义。 在 .NET 基类库中,浮点类型 Double 实现 IFloatingPointIeee754<TSelf>,但 Int32 不实现。
一些接口也由各种其他类型实现,包括 Char、DateOnly、DateTime、DateTimeOffset、Decimal、Guid、TimeOnly 和 TimeSpan。
下表显示了每个接口公开的一些核心 API。
接口 | API 名称 | 说明 |
---|---|---|
IBinaryInteger<TSelf> | DivRem |
同时计算商和余数。 |
LeadingZeroCount |
计算二进制表示中的前导零位数。 | |
PopCount |
计算二进制表示中的设置位数。 | |
RotateLeft |
向左旋转位,有时也称为循环左移。 | |
RotateRight |
向右旋转位,有时也称为循环右移。 | |
TrailingZeroCount |
计算二进制表示中的尾随零位数。 | |
IFloatingPoint<TSelf> | Ceiling |
将值向正无穷方向舍入。 +4.5 变为 +5,-4.5 变为 -4。 |
Floor |
将值向负无穷方向舍入。 +4.5 变为 +4,-4.5 变为 -5。 | |
Round |
使用指定的舍入模式对值进行舍入。 | |
Truncate |
将值向零舍入。 +4.5 变为 +4,-4.5 变为 -4。 | |
IFloatingPointIeee754<TSelf> | E |
获取一个值,该值表示该类型的欧拉数。 |
Epsilon |
获取该类型的大于零的最小可表示值。 | |
NaN |
获取表示类型 NaN 的值。 |
|
NegativeInfinity |
获取表示类型 -Infinity 的值。 |
|
NegativeZero |
获取表示类型 -Zero 的值。 |
|
Pi |
获取表示类型 Pi 的值。 |
|
PositiveInfinity |
获取表示类型 +Infinity 的值。 |
|
Tau |
获取表示类型 Tau (2 * Pi ) 的值。 |
|
(其他) | (实现函数接口下列出的全部接口。) | |
INumber<TSelf> | Clamp |
将值限制为不大于也不小于指定的最小值和最大值。 |
CopySign |
将指定值的符号设置为与另一个指定值相同。 | |
Max |
返回两个值中的较大值,如果任一输入为 NaN ,则返回 NaN 。 |
|
MaxNumber |
返回两个值中的较大值,如果一个输入为 NaN ,则返回数字。 |
|
Min |
返回两个值中的较小值,如果任一输入为 NaN ,则返回 NaN 。 |
|
MinNumber |
返回两个值中的较小值,如果一个输入为 NaN ,则返回数字。 |
|
Sign |
返回 -1 表示负值,0 表示零,+1 表示正值。 | |
INumberBase<TSelf> | One |
获取类型的值 1。 |
Radix |
获取类型的基数。 Int32 返回 2。 Decimal 返回 10。 | |
Zero |
获取类型的值 0。 | |
CreateChecked |
创建一个值,如果输入不合适,则引发 OverflowException。1 | |
CreateSaturating |
创建一个值,如果输入不合适,则钳制为 T.MinValue 或 T.MaxValue 。1 |
|
CreateTruncating |
从一个值创建另一个值,如果输入不适合,则环绕处理。1 | |
IsComplexNumber |
如果值具有非零实部和非零虚部,则返回 true。 | |
IsEvenInteger |
如果值为偶数整数,则返回 true。 2.0 返回 true ,2.2 返回 false 。 |
|
IsFinite |
如果值不是无限值且不是 NaN ,则返回 true。 |
|
IsImaginaryNumber |
如果值的实部为零,则返回 true。 这意味着 0 是虚构的,而 1 + 1i 不是。 |
|
IsInfinity |
如果值表示无穷大,则返回 true。 | |
IsInteger |
如果值为整数,则返回 true。 2.0 和 3.0 返回 true ,2.2 和 3.1 返回 false 。 |
|
IsNaN |
如果值表示 NaN ,则返回 true。 |
|
IsNegative |
如果值为负,则返回 true。 这包括 -0.0。 | |
IsPositive |
如果值为正,则返回 true。 这包括 0 和 +0.0。 | |
IsRealNumber |
如果值的虚部为零,则返回 true。 这意味着 0 是实数,所有 INumber<T> 类型也是如此。 |
|
IsZero |
如果值表示零,则返回 true。 这包括 0、+0.0 和 -0.0。 | |
MaxMagnitude |
返回绝对值较大的值,如果任一输入为 NaN ,则返回 NaN 。 |
|
MaxMagnitudeNumber |
返回绝对值较小的值,如果一个输入为 NaN ,则返回数字。 |
|
MinMagnitude |
返回绝对值较小的值,如果任一输入为 NaN ,则返回 NaN 。 |
|
MinMagnitudeNumber |
返回绝对值较小的值,如果一个输入为 NaN ,则返回数字。 |
|
ISignedNumber<TSelf> | NegativeOne |
获取类型的值 -1。 |
1为帮助理解三种 Create*
方法的行为,请考虑以下示例。
给定值过大时的示例:
byte.CreateChecked(384)
将引发 OverflowException。byte.CreateSaturating(384)
返回 255,因为 384 大于 Byte.MaxValue(即 255)。byte.CreateTruncating(384)
返回 128,因为采用最低 8 位(384 的十六进制表示为0x0180
,最低 8 位为0x80
,即 128)。
给定值过小时的示例:
byte.CreateChecked(-384)
将引发 OverflowException。byte.CreateSaturating(-384)
返回 0,因为 -384 小于 Byte.MinValue(即 0)。byte.CreateTruncating(-384)
返回 128,因为采用最低 8 位(384 的十六进制表示为0xFE80
,最低 8 位为0x80
,即 128)。
Create*
方法对 IEEE 754 浮点类型也有一些特殊考虑,例如 float
和 double
,因为它们具有特殊值 PositiveInfinity
、NegativeInfinity
和 NaN
。 所有三个 Create*
API 都表现为 CreateSaturating
。 此外,虽然 MinValue
和 MaxValue
表示最大的负/正“正常”数,但实际的最小值和最大值是 NegativeInfinity
和 PositiveInfinity
,因此它们改为钳制这些值。
运算符接口对应于可用于 C# 语言的各种运算符。
- 它们明确地不对乘法和除法等操作进行配对,因为这并非对所有类型都正确。 例如,
Matrix4x4 * Matrix4x4
有效,但Matrix4x4 / Matrix4x4
无效。 - 它们通常允许输入类型和结果类型不同,以支持诸如将两个整数相除以获取
double
(例如3 / 2 = 1.5
)或计算一组整数的平均值等方案。
接口名称 | 定义的运算符 |
---|---|
IAdditionOperators<TSelf,TOther,TResult> | x + y |
IBitwiseOperators<TSelf,TOther,TResult> | x & y 、“x | y”、x ^ y 和 ~x |
IComparisonOperators<TSelf,TOther,TResult> | x < y 、x > y 、x <= y 和 x >= y |
IDecrementOperators<TSelf> | --x 和 x-- |
IDivisionOperators<TSelf,TOther,TResult> | x / y |
IEqualityOperators<TSelf,TOther,TResult> | x == y 和 x != y |
IIncrementOperators<TSelf> | ++x 和 x++ |
IModulusOperators<TSelf,TOther,TResult> | x % y |
IMultiplyOperators<TSelf,TOther,TResult> | x * y |
IShiftOperators<TSelf,TOther,TResult> | x << y 和 x >> y |
ISubtractionOperators<TSelf,TOther,TResult> | x - y |
IUnaryNegationOperators<TSelf,TResult> | -x |
IUnaryPlusOperators<TSelf,TResult> | +x |
备注
除了常规的 unchecked 运算符之外,一些接口还定义了 checked 运算符。 Checked 运算符在 checked 上下文中调用,并允许用户定义的类型定义溢出行为。 如果实现了 checked 运算符,例如 CheckedSubtraction(TSelf, TOther),则还必须实现 unchecked 的运算符,例如 Subtraction(TSelf, TOther)。
函数接口定义了比特定数值接口更广泛应用的泛型数学 API。 这些接口都由 IFloatingPointIeee754<TSelf> 实现,未来可能会由其他相关类型实现。
接口名称 | 说明 |
---|---|
IExponentialFunctions<TSelf> | 公开支持 e^x 、e^x - 1 、2^x 、2^x - 1 、10^x 和 10^x - 1 的指数函数。 |
IHyperbolicFunctions<TSelf> | 公开支持 acosh(x) 、asinh(x) 、atanh(x) 、cosh(x) 、sinh(x) 和 tanh(x) 的双曲线函数。 |
ILogarithmicFunctions<TSelf> | 公开支持 ln(x) 、ln(x + 1) 、log2(x) 、log2(x + 1) 、log10(x) 和 log10(x + 1) 的对数函数。 |
IPowerFunctions<TSelf> | 公开支持 x^y 的幂函数。 |
IRootFunctions<TSelf> | 公开支持 cbrt(x) 和 sqrt(x) 的根函数。 |
ITrigonometricFunctions<TSelf> | 公开支持 acos(x) 、asin(x) 、atan(x) 、cos(x) 、sin(x) 和 tan(x) 的三角函数。 |
解析和格式化是编程中的核心概念。 它们通常在将用户输入转换为给定类型或向用户显示类型时使用。 这些接口位于 System 命名空间中。
接口名称 | 说明 |
---|---|
IParsable<TSelf> | 公开对 T.Parse(string, IFormatProvider) 和 T.TryParse(string, IFormatProvider, out TSelf) 的支持。 |
ISpanParsable<TSelf> | 公开对 T.Parse(ReadOnlySpan<char>, IFormatProvider) 和 T.TryParse(ReadOnlySpan<char>, IFormatProvider, out TSelf) 的支持。 |
IFormattable1 | 公开对 value.ToString(string, IFormatProvider) 的支持。 |
ISpanFormattable1 | 公开对 value.TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider) 的支持。 |
1此接口不是新接口,也不是泛型接口。 但是,它由所有数字类型实现,表示 IParsable
的逆运算。
例如,以下程序将两个数字作为输入,使用类型参数限制为 IParsable<TSelf> 的泛型方法从控制台读取它们。 该程序使用泛型方法计算平均值,其中将输入和结果值的类型参数约束为 INumber<TSelf>,然后将结果显示到控制台。
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
*/