浮点数到小型整数类型的转换采用饱和转换

在 .NET 11 中,对 sbyte、byte、ushort、short 和 char 的未检查浮点转换现在会在目标类型的边界处具有饱和行为。 太小或太大的值分别设置为目标类型的最小值或最大值。

此更改延续了.NET 9 中关于浮点数到整数转换的更改,该更改将从float和double到int、uint、long和ulong的转换进行了标准化。 .NET 11 将饱和度扩展到 8 位和 16 位目标。

此更改适用于 CoreCLR(包括其解释器)以及 Native AOT。 此更改中不包括 Mono。

有关详细信息,请参阅 dotnet/runtime#128604。

引入的版本

.NET 11

以前的行为

以前,当该值溢出目标类型或为 NaN 时,.NET 不保证未检查的浮点数到整数转换的结果。 在不同的运行时实现(如 CoreCLR 和 Mono)之间、在不同的体系结构(如 x86、x64、Arm32、Arm64 和 WebAssembly)之间,以及在同一体系结构内的不同硬件指令集(如 x87、SSE2、AVX 和 AVX-512)之间,结果可能有所不同。

.NET 9 的这项重大变更特别提到了 x86 和 x64,在这些平台上,转换在发生溢出时通常会返回哨兵值。 Arm64 已按约定使用饱和转换。 这一变更将转换统一为到更宽整数类型的转换,而不是将旧的哨兵结果确立为一种约定。

对于较小的整数类型,在 .NET 9 和 .NET 10 中,CoreCLR 中一种常见的转换序列是先饱和转换为 int,然后通过截掉高位来缩小为目标类型。 此序列解释了许多应用程序遇到的行为,但它不是直接浮点到小整型转换的保证协定。

下表显示了当运行时 float 或 double 的值为 x 时,该两步序列的结果。 这些输入都可放入 int,因此这些示例单独展示了“仅保留目标的低 8 位或低 16 位、丢弃其余所有位”所产生的影响。 对于 sbyte 和 short,保留位按有符号解释;对于 ushort、char 和 byte,则按无符号解释。 char 的结果以数字形式显示。

转换为 x 的值 保留低位 上一个结果示例
sbyte 或 byte 298 0x2A 42
sbyte -298 0xD6 -42
byte -42 0xD6 214
short, ushort, 或 char 65578 0x002A 42
short -65578 0xFFD6 -42
ushort 或 char -42 0xFFD6 65494

例如,以下代码可能返回 42:

static short ConvertValue(double value)
{
    return unchecked((short)value);
}

short result = ConvertValue(65578.0);

中间 int 为 65578 (0x0001002A)。 由于仅保留其低 16 位,结果为 42(0x002A),而不是饱和到 short.MaxValue。

新行为

从 .NET 11 开始,未经检查的转换会饱和到目标类型的边界值。 位于目标范围内的有限值仍会向零舍入。 NaN 转换为零。

转换为 小于最小值,包括负无穷大 高于最大值,包括正无穷大 NaN
sbyte -128 (sbyte.MinValue) 127 (sbyte.MaxValue) 0
byte 0 (byte.MinValue) 255 (byte.MaxValue) 0
short -32768 (short.MinValue) 32767 (short.MaxValue) 0
ushort 0 (ushort.MinValue) 65535 (ushort.MaxValue) 0
char 0 (char.MinValue) 65535 (char.MaxValue) 0

前面的示例现在返回 32767 (short.MaxValue) 而不是 42。 同样,从 byte 转换为 255 现在返回 -42,而不是 42;从 ushort 转换为 0 现在返回 65494,而不是 298。

由于它们通过 float 进行转换,因此相应的从 Half 开始的未经检查的转换也会采用新的行为。 ConvertToInteger<TInteger>(Single) 和 ConvertToInteger<TInteger>(Double) 现在都会对这些小型目标类型正确地采用饱和处理。

受检转换保持不变,并在转换溢出时仍会引发 OverflowException。 此更改不会更改整数到整数窄转换,也不会更改.NET 9 更改所涵盖的更宽整数和矢量转换。

破坏性变更的类型

此更改为行为更改。

更改原因

.NET 9 这一更改确立了向更宽的整数类型转换时的饱和行为,但对于超出范围的值和 NaN,转换为 8 位和 16 位目标类型时的行为仍然依赖于硬件和具体实现。 此更改使这些转换具有确定性的饱和行为,并使 JIT、CoreCLR 解释器和本机 AOT 的预初始化值保持一致。

如果你的代码依赖于超出范围输入的先前结果,请更新它,使其尽可能预期在目标类型的边界处发生饱和。

如果需要在这些更改之前常用的平台原生行为,最简单的解决方法是 ConvertToIntegerNative<TInteger>(Single) 或 ConvertToIntegerNative<TInteger>(Double)。 例如,如果 x 是 double,则将直接 (ushort)x 强制转换替换为 double.ConvertToIntegerNative<ushort>(x);如果它是 float,则替换为 float.ConvertToIntegerNative<ushort>(x)。

还可以显式地选择中间转换。 以下示例使用 double 输入 x 和 ushort 目标:

所需行为 Conversion
平台原生地转换为目标类型,这通常会恢复早期的行为 double.ConvertToIntegerNative<ushort>(x)
先饱和到 int,然后再缩小,与常见的 .NET 9 和 .NET 10 CoreCLR 序列一致 unchecked((ushort)(int)x)
先执行平台原生转换为 int,然后再进行窄化,这与 .NET 9 之前常见的顺序一致 unchecked((ushort)double.ConvertToIntegerNative<int>(x))

对于float输入,请使用float.ConvertToIntegerNative,并将sbyte替换为相应的目标类型:byte、short或char。

与 .NET 9 中的更改一样,对于超出范围的值或 NaN,ConvertToIntegerNative不能保证重现之前的结果。 它选择对当前平台有效的行为,这些行为可以跨运行时、体系结构或硬件修订进行更改。 显式使用 (ushort)(int)x 则会选择先转换为 int 的饱和转换,然后再进行整数缩窄;它并不会恢复所有历史实现的行为。

如果转换后的值用作数组索引、缓冲区偏移量或长度,请验证生成的值是否在所需的边界内。 在一台机器上能产生可用值的转换,并不能说明平台原生的转换在另一台机器上也会产生可用值。

受影响的 API