【unitrix】 4.21 类型级二进制数基本结构体(types.rs)

一、源码

这段代码定义了一个类型级数值系统的 Rust 实现，主要用于在编译时表示和操作各种数值类型。

rust 复制代码

use crate::sealed::Sealed;
use crate::number::{NonZero, TypedInt, Unsigned, Primitive};
//===============================================
// 特殊浮点值枚举
//===============================================

/// 特殊浮点值（NaN/±∞）
#[derive(Debug, PartialEq, Default)]
pub enum Special {
    #[default]
    Nan,            // Not a Number
    Infinity,       // Positive infinity
    NegInfinity,    // Negative infinity
}

//===============================================
// 基础数值类型表示
//===============================================

/// 二进制0的终结表示（类型系统中的原子常量）
/// - 不能作为小数 `B0`/`B1` 的泛型参数
#[derive(Eq, PartialEq, Clone, Copy, Debug, Default)]
pub struct Z0;

/// 正号或小数终结符/数值1表示：
/// - 独立使用：值 = 1
/// - 作为泛型参数时：当前位=1，高位=0
///   - 示例：`B1<P1>` 表示二进制 `011`（十进制 +3）
#[derive(Eq, PartialEq, Clone, Copy, Debug, Default)]
pub struct P1;

/// 负号终结符/数值-1表示：
/// - 独立使用：值 = -1
/// - 作为泛型参数时：当前位=1，高位=1（二进制补码）
///   - 示例：`B0<N1>` 表示二进制 `...1110`（十进制 -2）
#[derive(Eq, PartialEq, Clone, Copy, Debug, Default)]
pub struct N1;

/// 二进制补码的0位：
/// - `Other`: 整数的高位类型或小数的低位类型
/// - 示例：`B0<P1>` 表示二进制 `010`（十进制 +2）
#[derive(Eq, PartialEq, Clone, Copy, Debug)]
pub struct B0<Other>(pub Other);

impl<Other: NonZero> Default for B0<Other> {
    fn default() -> Self {
        B0(Default::default())
    }
}

/// 二进制补码的1位：
/// - `Other`: 整数的高位类型或小数的低位类型
/// - 示例：`B1<P1>` 表示二进制 `011`（十进制 +3）
#[derive(Eq, PartialEq, Clone, Copy, Debug)]
pub struct B1<Other>(pub Other);

impl<Other: NonZero> Default for B1<Other> {
    fn default() -> Self {
        B1(Default::default())
    }
}

//===============================================
// 复合数值类型表示
//===============================================

/// **定点数表示（整数部分 + 小数部分）**
/// - `IntPart`:  整数部分（二进制补码表示，如 `B1<P1>` 表示整数 3）
/// - `FracPart`: 小数部分（二进制小数，单独的Z0、P1，或使用 `B0`/`B1` 嵌套链表示并用 `P1` 结束）
/// 
/// # 表示规则
/// - **整数部分**：标准二进制补码（同整数规则）
/// - **小数部分**：从高位到低位（2^{-1}, 2^{-2}, ...）的链式结构：
///   - `B0<Next>` = 当前小数位为 0
///   - `B1<Next>` = 当前小数位为 1
///   - `P1` = 为1，也是B0、B1结束符
///   - `Z0` = 单独使用，表示0
/// 
/// # 示例
/// 3.5 的定点表示：
/// - 整数部分: `B1<P1>`（二进制 `11` = 3）
/// - 小数部分: `P1`（二进制 `0.1` = 0.5）
/// - 完整类型: `FixedPoint<B1<P1>, B1<Z0>>`
/// 
/// 
///   - 始终为无符号，二进制位是整数部分的延续
///
/// # 二进制布局规则
/// ```text
/// [符号位][整数位][小数位]
///   MSB -----------------> LSB
/// ```
///
/// # 编译时强制约束
/// 1. 整数部分必须为合法二进制补码形式
/// 2. 小数部分禁止包含 `Z0`
/// 3. 两部分都必须以 `P1` 结尾
/// 
/// 
#[derive(Eq, PartialEq, Clone, Copy, Debug)]
pub struct FixedPoint<IntPart, FracPart>(pub IntPart, pub  FracPart);

impl<IntPart: TypedInt, FracPart: Unsigned> Default for FixedPoint<IntPart, FracPart> {
    fn default() -> Self {
        FixedPoint(Default::default(), Default::default())
    }
}

/// **类型级十进制数（尾数用二进制表示，指数为10的幂）**
/// - `Significand`: 尾数（定点数，用 `TypeInt` 表示）
/// - `Exponent`: 指数（二进制补码表示10的幂）
/// - 目前不支持特殊值：NaN, ±∞
#[derive(Eq, PartialEq, Clone, Copy, Debug)]
pub struct Decimal<Significand, Exponent>(pub Significand, pub Exponent);

impl<Significand: NonZero, Exponent: TypedInt> Default for Decimal<Significand, Exponent> {
    fn default() -> Self {
        Decimal(Default::default(),Default::default())
    }
}

/// **原生数值的包装类型**
/// - 在自定义类型和原生类型间搭建桥梁
/// - 支持类型安全的运算符重载
/// - 示例：`Var(3) + P1` → `i32 + 类型级1`
#[derive(Eq, PartialEq, Debug, Clone, Copy, Default)]
pub struct Var<T>(pub T);

//===============================================
// 构造函数实现
//===============================================

impl Z0 {
    #[inline]
    pub fn new() -> Self { Z0 }
}

impl P1 {
    #[inline]
    pub fn new() -> Self { P1 }
}

impl N1 {
    #[inline]
    pub fn new() -> Self { N1 }
}

impl<Other> B0<Other> {
    #[inline]
    pub fn new(other:Other) -> Self { B0(other) }
}

impl<Other> B1<Other> {
    #[inline]
    pub fn new(other: Other) -> Self { B1(other) }
}

impl<IntPart, FracPart> FixedPoint<IntPart, FracPart> {
    #[inline]
    pub fn new(intPart: IntPart, fracPart: FracPart) -> Self {
        FixedPoint(intPart, fracPart)
    }
}

impl<Significand, Exponent> Decimal<Significand, Exponent> {
    #[inline]
    pub fn new(significand: Significand, exponent: Exponent) -> Self {
        Decimal(significand, exponent)
    }
}

//===============================================
// Sealed trait 实现（模块私有约束）
//===============================================

impl Sealed for Special {}
impl Sealed for Z0 {}
impl Sealed for P1 {}
impl Sealed for N1 {}
impl<Other> Sealed for B0<Other> {}
impl<Other> Sealed for B1<Other> {}
impl<IntPart, FracPart> Sealed for FixedPoint<IntPart, FracPart> {}
impl<Significand, Exponent> Sealed for Decimal<Significand, Exponent> {}
impl<T: Primitive> Sealed for Var<T> {}

二、代码分析

特殊浮点值枚举 (Special)

表示三种特殊浮点值：
- Nan (非数字)
- Infinity (正无穷大)
- NegInfinity (负无穷大)
实现了 Debug, PartialEq 和 Default trait

基础数值类型表示

Z0: 表示二进制0的终结表示，类型系统中的原子常量
P1: 表示正号终结符/数值1
N1: 表示负号终结符/数值-1
B0: 表示二进制补码的0位，包含其他部分
B1: 表示二进制补码的1位，包含其他部分

复合数值类型表示

+FixedPoint<IntPart, FracPart>: 定点数表示

IntPart: 整数部分(二进制补码表示)
FracPart: 小数部分(二进制小数表示)
示例：FixedPoint<B1, B1> 表示3.5
Decimal<Significand, Exponent>: 十进制数表示
- Significand: 尾数(定点数表示)
- Exponent: 指数(二进制补码表示10的幂)
Var: 原生数值的包装类型，用于与自定义类型交互

构造函数实现

为所有类型提供了简单的构造函数(new方法)

Sealed trait 实现

为所有类型实现了 Sealed trait
这是一种设计模式，用于限制 trait 只能在当前模块中被实现

三、主要特点：

类型级编程：使用 Rust 的类型系统在编译时表示数值
二进制补码表示：用于表示有符号整数
定点数支持：可以精确表示小数
十进制科学计数法：通过 Decimal 类型支持
类型安全：通过 trait bound 确保类型合法性
零成本抽象：在编译时完成所有计算

这个系统可以用于需要高精度计算或编译时数值计算的场景，如金融计算、物理模拟等。通过类型系统保证数值的正确性，避免运行时错误。