定点数

Alpha: 这是以 const generics 代替 typenum crate 的新主要版本 2.0.0 的 alpha 版本。此版本需要启用具有 generic_const_exprs 功能 的 nightly 编译器。稳定版本 2.0.0 本身将在 generic_const_exprs 功能 稳定之前不会发布。请参阅有关从版本 1 迁移到版本 2 的文档 从版本 1 迁移到版本 2。

fixed crate 提供定点数。

• FixedI8 和 FixedU8 是 8 位定点数。
• FixedI16 和 FixedU16 是 16 位定点数。
• FixedI32 和 FixedU32 是 32 位定点数。
• FixedI64 和 FixedU64 是 64 位定点数。
• FixedI128 和 FixedU128 是 128 位定点数。

一个n位的定点数有f = FRAC位小数位，n − f位整数位。例如，FixedI32<24>是一个32位有符号定点数，总共有n = 32位，小数位f = 24位，整数位n − f = 8位。FixedI32<0>的行为类似于i32，而FixedU32<0>的行为类似于u32。

任何两个相邻的可表示数之间的差在整个定点数的可能范围内是恒定的：Δ = 1/2^f。当f = 0，如FixedI32<0>时，Δ = 1，因为可表示的数是整数，两个连续整数之间的差是1。当f = n时，Δ = 1/2ⁿ，对于有符号数如FixedI32<32>，其值位于−0.5 ≤ x < 0.5的范围内，而对于无符号数如FixedU32<32>，其值位于0 ≤ x < 1的范围内。

主要特性包括

• 表示宽度高达128位的二进制定点数。
• 定点数与数值原语之间的转换。
• 定点数与数值原语之间的比较。
• 从十进制、二进制、八进制和十六进制字符串解析。
• 以十进制、二进制、八进制和十六进制显示。
• 算术和逻辑运算。

此crate不提供十进制定点数。例如，0.001不能精确表示，因为它等于1/10³。只要有小数位足够，就可以精确表示如1/2⁴（0.0625）这样的二进制分数。

此crate不提供一般分析函数。

• 不提供代数函数，例如没有pow。
• 不提供三角函数，例如没有sin或cos。
• 不提供其他超越函数，例如没有log或exp。

这些函数没有提供，因为不同的实现可能具有不同的权衡，例如以牺牲一些正确性换取速度。其他crate可以提供实现。

• cordic crate提供了使用CORDIC算法实现的多种函数。

支持的转换包括以下情况。

• 使用From和Into提供定点数与数值原语之间不可失败的无损转换。这些转换从不失败（不可失败）且不丢失任何位（无损）。
• 使用LossyFrom和LossyInto特性提供定点数与数值原语之间不可失败的有损转换。源可以比目标有更多的小数位。
• 提供使用LosslessTryFrom和LosslessTryInto特质进行的固定点数和无符号原语之间的无损转换，这些特质可以在此处和此处找到。源数据的小数位数不能多于目标数据。
• 提供使用FromFixed和ToFixed特质，或者使用from_num和to_num方法及其校验版本，进行的固定点数和无符号原语之间的校验转换。
• 此外，还实现了az类型转换，用于固定点数和无符号原语之间的转换。
• 可以使用FromStr从十进制字符串解析固定点数，以及使用from_str_binary、from_str_octal和from_str_hex方法从二进制、八进制和十六进制字符串解析。结果四舍五入到最接近的数，对于平局的情况则四舍六入五成双。
• 可以使用Display、Binary、Octal、LowerHex、UpperHex、LowerExp和UpperExp将这些固定点数转换为字符串。输出四舍五入到最接近的数，对于平局的情况则四舍六入五成双。
• 所有固定点数都是普通老数据，因此可以使用bytemuck位转换转换。

新功能

版本 2.0.0-alpha.28.0 新闻（2024-07-25）

• 现在，该软件包需要启用generic_const_exprs特性的夜间编译器。
• 现在，该软件包使用泛型常量表达式来指定小数位数。
• 已放宽Fixed特质的约束。需要小数位数有界的方法已移动到新的子特质FixedBoundFrac。
• 已用INT_BITS和FRAC_BITS替换了关联常量INT_NBITS和FRAC_NBITS，它们可以是负数。
• 《Unwrapped》结构体的方法 from_str_binary、from_str_octal 和 from_str_hex 直接返回值，而不是返回 Result。
• 已弃用的 F128Bits 和 F128 结构体已被移除。它们已被原语 f128 替换。
• 已弃用的宏 const_fixed_from_int 已被移除。它由 1.20.0 版本中的 const_from_int 方法替换。
• 已弃用的可选功能 az 和 f16 已被移除。由于它们所启用的功能现在总是启用，这些功能没有效果。
• 已移除所有已弃用的方法。
• 在 FixedBits 特性中添加了新的泛型关联类型 Fixed。
• 现在，Fixed 特性以及 Saturating、Wrapping 和 Unwrapped 包装器的以下方法现在有一些参数和返回类型，可以是泛型的
  • mul_add、add_prod、mul_acc
• 现在，Fixed 特性的以下方法现在有一些参数和返回类型，可以是泛型的
  • checked_mul_add、checked_add_prod、checked_mul_acc
  • saturating_mul_add、saturating_add_prod、saturating_mul_acc
  • wrapping_mul_add、wrapping_add_prod、wrapping_mul_acc
  • unwrapped_mul_add，unwrapped_add_prod，unwrapped_mul_acc
  • overflowing_mul_add，overflowing_add_prod，overflowing_mul_acc

版本 1.28.0 新闻（2024-07-25）

• 现在这个包需要 rustc 版本 1.79.0 或更高。
• 以下方法被添加到了所有定点数和 Fixed 特性中
  • unchecked_add，unchecked_sub，unchecked_mul_int
• 对于所有定点数和 Fixed 特性，以下方法已被重命名。旧方法名已被弃用。
  • round_ties_to_even 已更名为 round_ties_even
  • checked_round_ties_to_even 已更名为 checked_round_ties_even
  • saturating_round_ties_to_even 已更名为 saturating_round_ties_even
  • wrapping_round_ties_to_even 已更名为 wrapping_round_ties_even
  • unwrapped_round_ties_to_even 已更名为 unwrapped_round_ties_even
  • overflowing_round_ties_to_even 已更名为 overflowing_round_ties_even
• 以下常量已添加到 consts 模块中，并作为与定点类型关联的常量
  • SQRT_2PI，FRAC_1_SQRT_2PI
• 添加了实验性功能 nightly-float。
• 对于实验性功能 num-traits，为所有定点数实现了以下特性
  • ConstZero，ConstOne
  • ToBytes，FromBytes

其他版本

其他版本的详细信息可以在RELEASES.md中找到：RELEASES.md。

快速示例

#![feature(generic_const_exprs)]

use fixed::types::I20F12;

// 19/3 = 6 1/3
let six_and_third = I20F12::from_num(19) / 3;
// four decimal digits for 12 binary digits
assert_eq!(six_and_third.to_string(), "6.3333");
// find the ceil and convert to i32
assert_eq!(six_and_third.ceil().to_num::<i32>(), 7);
// we can also compare directly to integers
assert_eq!(six_and_third.ceil(), 7);

类型I20F12是一个32位有符号定点数，有20位整数位和12位小数位。它是FixedI32<12>的别名。无符号对应类型是U20F12。提供了所有整数位和小数位组合的别名，总位数为8、16、32、64或128位。

#![feature(generic_const_exprs)]

use fixed::types::{I4F4, I4F12};

// -8 ≤ I4F4 < 8 with steps of 1/16 (~0.06)
let a = I4F4::from_num(1);
// multiplication and division by integers are possible
let ans1 = a / 5 * 17;
// 1 / 5 × 17 = 3 2/5 (3.4), but we get 3 3/16 (~3.2)
assert_eq!(ans1, I4F4::from_bits((3 << 4) + 3));
assert_eq!(ans1.to_string(), "3.2");

// -8 ≤ I4F12 < 8 with steps of 1/4096 (~0.0002)
let wider_a = I4F12::from(a);
let wider_ans = wider_a / 5 * 17;
let ans2 = I4F4::from_num(wider_ans);
// now the answer is the much closer 3 6/16 (~3.4)
assert_eq!(ans2, I4F4::from_bits((3 << 4) + 6));
assert_eq!(ans2.to_string(), "3.4");

第二个示例显示了精度和转换问题。变量a的低精度意味着a / 5是3/16而不是1/5，导致不准确的结果ans1 = 3 3/16 (~3.2)。使用更高的精度，我们得到wider_a / 5等于819/4096，得到更准确的中间结果wider_ans = 3 1635/4096。当我们将其转换回四位小数时，我们得到ans2 = 3 6/16 (~3.4)。

请注意，我们可以使用From将I4F4从I4F12转换，因为目标类型具有相同数量的整数位和更多的小数位。从I4F12到I4F4不能使用From，因为我们有更少的小数位，所以使用from_num。

直接写入定点数常量和值

作为const函数可用的lit方法可以用于解析字面量。它支持

• 下划线作为分隔符；
• 二进制、八进制和十六进制数字的前缀“0b”、“0o”和“0x”；
• 可选的十进制指数，使用“e”或“E”作为分隔符，用于十进制、二进制和八进制数字，或者使用“@”作为所有支持基数的分隔符，包括十六进制。

#![feature(generic_const_exprs)]

use fixed::types::I16F16;

// 0.1275e2 is 12.75
const TWELVE_POINT_75: I16F16 = I16F16::lit("0.127_5e2");
// 1.8 hexadecimal is 1.5 decimal, and 18@-1 is 1.8
const ONE_POINT_5: I16F16 = I16F16::lit("0x_18@-1");
// 12.75 + 1.5 = 14.25
let sum = TWELVE_POINT_75 + ONE_POINT_5;
assert_eq!(sum, 14.25);

使用fixed包

fixed包在crates.io上可用。要在您的包中使用它，请在Cargo.toml中将它添加为依赖项。

[dependencies]
fixed = "2.0.0-alpha.28.0"

fixed包的这个alpha版本需要启用generic_const_exprs功能的nightly编译器。

可选功能

fixed包具有以下可选功能

1. arbitrary，默认禁用。此功能提供从原始、无结构的数据生成任意定点数。此功能需要arbitrary crate。
2. borsh，默认禁用。此功能使用borsh crate实现序列化和反序列化。
3. serde，默认禁用。此功能为定点数提供序列化支持。此功能需要serde crate。
4. std，默认禁用。这是在no_std环境下无法实现的功能：目前是对ParseFixedError的Error trait的实现。
5. serde-str，默认禁用。当使用人类可读格式时，定点数以字符串形式序列化以显示值。此功能需要serde和std可选功能。使用此功能时，仅支持小数位数从零到总位数为止的定点数序列化。警告：当此功能启用时序列化的数字，在禁用此功能时无法反序列化，反之亦然。

要启用功能，您可以将依赖项添加到Cargo.toml中，如下所示

[dependencies.fixed]
features = ["serde"]
version = "2.0.0-alpha.28.0"

实验性可选功能

如果删除以下实验性功能，则不会被视为破坏性更改。但是，删除实验性功能将需要增加次要版本号。同样，在增加次要版本号时，可选依赖项可以更新到不兼容的新版本。

1. num-traits，默认禁用。此功能实现了num-traits crate的一些特质。（计划在num-traits crate达到1.0.0版本时将其提升为可选功能。）

从版本1迁移到版本2

要从版本1迁移到版本2，需要以下更改

• 需要临时更改，直到generic_const_exprs功能稳定：使用夜间编译器并使用以下方式启用generic_const_exprs功能

  #![feature(generic_const_exprs)]
  

• 使用整型字面量而不是typenum整型常量，例如使用FixedI32<8>而不是FixedI32<U8>。

• Fixed trait约束已被放宽。需要分数位数有界的方法已移动到新的子特质FixedBoundFrac。对于使用这些特质方法的代码，应将Fixed替换为FixedBoundFrac。

• 类型为 FRAC_NBITS 和 INT_NBITS 的关联常量被替换为类型为 u32 的 FRAC_BITS 和 INT_BITS。

• 对于 Unwrapped 包装器，方法 from_str_binary、from_str_octal 和 from_str_hex 直接返回值，而不是返回一个 Result。

• 已弃用的 F128Bits 和 F128 结构体已被删除。它们被 f128 原语所取代。

• 已弃用的宏 const_fixed_from_int 已被删除。它被 1.20.0 版本中的 const_from_int 方法所取代。

• 已弃用的可选特性 az 和 f16 已被删除。由于从 1.7.0 版本开始，这些功能已被无条件启用，因此它们没有任何效果。

• 已移除所有已弃用的方法。

许可协议

本软件库是免费软件：您可以根据以下任一协议重新分发或修改它

• Apache License 2.0 或
• MIT 许可协议

您自行选择。

贡献

除非您明确表示，否则任何有意提交以包含在您的工作中的贡献（根据 Apache License 2.0 定义），均应按照上述方式双重许可，无需任何额外的条款或条件。