【unitrix】 1.6 数值类型基本结构体(types.rs)

一、源码

这段代码定义了一个类型级别的数字表示系统，主要用于编译时的数值计算和类型安全操作。

use core::marker::PhantomData;
use crate::sealed::Sealed;// ========== 常量基础类型定义 ==========
// ========== Constant Basic Type Definitions ==========/// 十进制数字0的终结点表示
/// Terminal representation for decimal 0
///
/// # 说明 (Explanation)
/// - 必须单独使用表示数值0
/// - Must be used standalone to represent value 0
/// - 不能作为B0/B1的泛型参数
/// - Cannot be used as generic parameter for B0/B1
/// - 是类型系统的原子常量
/// - Atomic constant in type system
#[derive(Eq, PartialEq, Clone, Copy, Debug, Default)]
pub struct Z0;/// 二进制数字0的类型表示，用于补码表示法
/// Binary digit 0 representation for two's complement
///
/// # 说明 (Explanation)
/// - 表示最低有效位为0
/// - Represents least significant bit 0
/// - 泛型参数H表示更高位的数字
/// - Generic parameter H represents higher bits
/// - 例如 B0<P1> 表示二进制 010 (十进制 +2)
/// - Example: B0<P1> represents binary 010 (decimal +2)
#[derive(Eq, PartialEq, Clone, Copy, Debug)]
pub struct B0<H>(pub PhantomData<H>);/// 二进制数字1的类型表示，用于补码表示法
/// Binary digit 1 representation for two's complement
///
/// # 说明 (Explanation)
/// - 表示最低有效位为1
/// - Represents least significant bit 1
/// - 泛型参数H表示更高位的数字
/// - Generic parameter H represents higher bits
/// - 例如 B1<P1> 表示二进制 011 (十进制 +3)
/// - Example: B1<P1> represents binary 011 (decimal +3)
#[derive(Eq, PartialEq, Clone, Copy, Debug)]
pub struct B1<H>(pub PhantomData<H>);/// 正数符号结束符/数值1表示
/// Positive sign terminator / numeric 1 representation
///
/// # 说明 (Explanation)
/// - 单独使用时表示数值1
/// - Standalone represents value 1
/// - 作为泛型参数时：
/// - When used as generic parameter:
///   - 该位为1 (current bit is 1)
///   - 更高位都是0 (all higher bits are 0)
///   - 表示正数符号结束 (indicates positive sign termination)
/// - 例如 B1<P1> 表示 011 (+3)
/// - Example: B1<P1> represents 011 (+3)
#[derive(Eq, PartialEq, Clone, Copy, Debug, Default)]
pub struct P1;/// 负数符号结束符/数值-1表示
/// Negative sign terminator / numeric -1 representation
///
/// # 说明 (Explanation)
/// - 单独使用时表示数值-1
/// - Standalone represents value -1
/// - 作为泛型参数时：
/// - When used as generic parameter:
///   - 该位为1 (current bit is 1)
///   - 更高位都是1 (all higher bits are 1)
///   - 表示负数符号结束 (indicates negative sign termination)
/// - 例如 B0<N1> 表示 ...1110 (-2)
/// - Example: B0<N1> represents ...1110 (-2)
#[derive(Eq, PartialEq, Clone, Copy, Debug, Default)]
pub struct N1;impl<H> Default for B0<H> {fn default() -> Self {B0(PhantomData)}
}impl<H> Default for B1<H> {fn default() -> Self {B1(PhantomData)}
}// ========== 变量基础类型定义 ==========
// ========== Variable Basic Type Definition ==========/// 库代码与基础数值类型的桥接器
/// Bridge between library types and primitive numeric types
///
/// # 核心功能 (Core Features)
/// - 实现自定义常量与基础数值类型的混合计算
/// - Enables mixed operations between custom constants and primitive types
/// - 提供类型安全的运算符重载接口
/// - Provides type-safe operator overloading
/// - 支持与类型系统常量的无缝交互
/// - Supports seamless interaction with type-level constants
///
/// # 泛型参数 (Generic Parameters)
/// - `T`: 基础数值类型（i32/i64/f32/f64等）
/// - `T`: Primitive numeric type (i32/i64/f32/f64 etc.)
///
/// # 示例 (Examples)
/// ```
/// use unitrix::number::{Var, Add};
/// 
/// // 类型系统常量与基础数值的混合运算
/// // Mixed operations between type constants and primitives
/// let a = Var(3) + P1;  // i32 + 类型常量1
/// let b = N1 * Var(5.0);     // 类型常量-1 * f64
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub struct Var<T>(pub T);// ========== Sealed 实现 ==========
// ========== Sealed Implementations ==========impl<H> Sealed for B0<H> {}
impl<H> Sealed for B1<H> {}
impl Sealed for Z0 {}
impl Sealed for P1 {}
impl Sealed for N1 {}impl Sealed for Var<i32> {}
impl Sealed for Var<i64> {}
impl Sealed for Var<f32> {}
impl Sealed for Var<f64> {}

二、代码分析

1. 基础类型定义

Z0

• 表示十进制数字0的终结点

• 是类型系统的原子常量，不能作为其他类型的泛型参数

• 单独使用时表示数值0

B0 和 B1

• 用于二进制补码表示法的类型

• B0表示最低有效位为0，B1表示最低有效位为1

• 泛型参数H表示更高位的数字

• 例如：

  • B0 表示二进制010（十进制+2）

  • B1 表示二进制011（十进制+3）

P1 和 N1

• P1表示正数符号结束符/数值1

  • 单独使用时表示1

  • 作为泛型参数时表示该位为1且更高位都是0

• N1表示负数符号结束符/数值-1

  • 单独使用时表示-1

  • 作为泛型参数时表示该位为1且更高位都是1

2. Var 类型

• 桥梁类型，连接自定义类型和基础数值类型（i32/i64/f32/f64等）

• 核心功能：

  • 实现自定义常量与基础数值类型的混合计算

  • 提供类型安全的运算符重载接口

  • 支持与类型系统常量的无缝交互

• 示例用法：

let a = Var(3) + P1;  // i32 + 类型常量1
let b = N1 * Var(5.0); // 类型常量-1 * f64

3. Sealed trait 实现

• 为所有基础类型实现了Sealed trait

• 这是一种设计模式，用于限制这些类型只能被当前crate扩展，防止外部代码实现这些trait

4. 技术细节

• 使用了PhantomData来持有泛型参数而不实际占用空间

• 为B0和B1实现了Default trait

• 所有类型都派生了一些标准trait（Eq, PartialEq, Clone, Copy, Debug等）

三、设计目的

这个系统的主要目的是在类型级别表示数字，使得可以在编译时进行数值计算和类型检查，从而提供类型安全的数值操作。这种技术常用于需要高度类型安全或编译时计算的场景，如物理单位系统、矩阵运算等。

通过这种方式，开发者可以在编译时捕获许多潜在的错误，同时保持运行时的效率，因为所有这些类型信息在编译后都会被擦除。