【unitrix】 4.0 类型级数值表示系统(types.rs)

一、源码

这段代码实现了一个类型级(type-level)的数值表示系统，用于在Rust的类型系统中编码数值信息。

use core::marker::PhantomData;
use crate::sealed::Sealed;//===============================================
// 特殊浮点值枚举
//===============================================/// 特殊浮点值（NaN/±∞）
#[derive(Debug, PartialEq, Default)]
pub enum Special {#[default]Nan,            // Not a NumberInfinity,       // Positive infinityNegInfinity,    // 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>(PhantomData<Other>);impl<Other> Default for B0<Other> {fn default() -> Self {B0(PhantomData)}
}/// 二进制补码的1位：
/// - `Other`: 整数的高位类型或小数的低位类型
/// - 示例：`B1<P1>` 表示二进制 `011`（十进制 +3）
#[derive(Eq, PartialEq, Clone, Copy, Debug)]
pub struct B1<Other>(PhantomData<Other>);impl<Other> Default for B1<Other> {fn default() -> Self {B1(PhantomData)}
}//===============================================
// 复合数值类型表示
//===============================================/// **定点数表示（整数部分 + 小数部分）**
/// - `IntPart`: 整数部分（二进制补码表示，如 `B1<P1>` 表示整数 3）
/// - `FracPart`: 小数部分（二进制小数，使用 `B0`/`B1` 嵌套链表示，以 `Z0` 结束）
/// 
/// # 表示规则
/// - **整数部分**：标准二进制补码（同整数规则）
/// - **小数部分**：从高位到低位（2^{-1}, 2^{-2}, ...）的链式结构：
///   - `B0<Next>` = 当前小数位为 0
///   - `B1<Next>` = 当前小数位为 1
///   - `Z0` = 小数部分结束符
/// 
/// # 示例
/// 3.5 的定点表示：
/// - 整数部分: `B1<P1>`（二进制 `11` = 3）
/// - 小数部分: `B1<Z0>`（二进制 `0.1` = 0.5）
/// - 完整类型: `FixedPoint<B1<P1>, B1<Z0>>`
#[derive(Eq, PartialEq, Clone, Copy, Debug, Default)]
pub struct FixedPoint<IntPart, FracPart>(PhantomData<(IntPart, FracPart)>);/// **类型级浮点数（科学计数法 M × 2^E）**
/// - `Significand`: 尾数（定点数，用 `FixedPoint<IntPart, FracPart>` 表示）
/// - `Exponent`: 指数（二进制补码表示）
/// - 支持特殊值：NaN, ±∞
#[derive(Clone, Copy, Debug)]
pub struct Float<Significand, Exponent>(PhantomData<(Significand, Exponent)>);impl<Significand, Exponent> Default for Float<Significand, Exponent> {fn default() -> Self {Float(PhantomData)}
}/// **原生数值的包装类型**
/// - 在自定义类型和原生类型间搭建桥梁
/// - 支持类型安全的运算符重载
/// - 示例：`Var(3) + P1` → `i32 + 类型级1`
#[derive(Debug, Clone, Copy, PartialEq, 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() -> Self {B0(PhantomData)}
}impl<Other> B1<Other> {#[inline]pub fn new() -> Self {B1(PhantomData)}
}impl<IntPart, FracPart> FixedPoint<IntPart, FracPart> {#[inline]pub fn new() -> Self {FixedPoint(PhantomData)}
}impl<Significand, Exponent> Float<Significand, Exponent> {#[inline]pub fn new() -> Self {Float(PhantomData)}
}//===============================================
// 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 Float<Significand, Exponent> {}
impl Sealed for Var<i8> {}
impl Sealed for Var<i16> {}
impl Sealed for Var<i32> {}
impl Sealed for Var<i64> {}
impl Sealed for Var<i128> {}
impl Sealed for Var<isize> {}
impl Sealed for Var<f32> {}
impl Sealed for Var<f64> {}

二、源码分析

1. 特殊浮点值枚举 (Special)

pub enum Special {#[default]Nan,            // 非数字Infinity,       // 正无穷NegInfinity,    // 负无穷
}

这个枚举表示浮点数中的特殊值：NaN(非数字)、正无穷和负无穷。
2. 基础数值类型表示

终结符类型

• Z0: 表示二进制0的终结，用于构建类型级数字

• P1: 表示正1的终结符，独立使用时值为+1

• N1: 表示负1的终结符，独立使用时值为-1

二进制位类型

+ B0<Other>: 表示二进制0位，Other是更高位的类型+ B1<Other>: 表示二进制1位，Other是更高位的类型

这些类型使用PhantomData来持有泛型参数而不实际存储值，纯粹用于类型系统计算。
3. 复合数值类型表示

定点数 (FixedPoint<IntPart, FracPart>)

pub struct FixedPoint<IntPart, FracPart>(PhantomData<(IntPart, FracPart)>);

表示定点数，其中：

• IntPart: 整数部分，用二进制补码表示

• FracPart: 小数部分，用二进制小数表示（链式结构，以Z0结束）

例如：FixedPoint<B1, B1> 表示3.5（整数部分11=3，小数部分0.1=0.5）

浮点数 (Float<Significand, Exponent>)

pub struct Float<Significand, Exponent>(PhantomData<(Significand, Exponent)>);

表示科学计数法的浮点数：

• Significand: 尾数（定点数）

• Exponent: 指数（二进制补码表示）

原生数值包装 (Var)

pub struct Var<T>(pub T);

包装原生数值类型，用于在自定义类型和原生类型间搭建桥梁，支持类型安全的运算符重载。
4. 构造函数实现

为所有类型提供了new()构造函数，返回默认实例。由于这些类型只用于类型系统，实际值并不重要。
5. Sealed trait 实现

impl Sealed for Special {}
impl Sealed for Z0 {}
// ...其他实现...

Sealed trait用于限制这些类型的实现只能在本模块内进行，防止外部代码扩展这些类型的行为。

三、设计目的

这个系统的主要目的是在Rust的类型系统中编码数值信息，使得：

1. 可以在编译期进行数值计算和验证2. 实现类型安全的运算符重载3. 构建精确的数值表示系统

这种技术常见于类型级编程(type-level programming)和嵌入式领域编程，可以在编译期捕获更多错误，提高运行时安全性。