【time-rs】time-core 中的 convert.rs 文件详解

概述

这个文件是 time-core crate 中的时间单位转换模块，采用编译时计算的零成本抽象设计。它定义了一系列时间单位类型（如纳秒、微秒等）和它们之间的转换关系。

1. 设计哲学

零成本抽象

编译时计算：所有转换系数在编译时确定
无运行时开销：方法调用直接内联为常数
类型安全：防止非法单位转换

标记类型模式

每个时间单位都是一个零大小的标记类型（zero-sized type），只用于类型级别的计算。

2. 核心 trait 系统

密封 trait 设计

rust 复制代码

mod sealed {
    /// 定义两个时间单位之间的比率
    pub trait MultipleOf<T, Output> {
        const VALUE: Output;  // 转换系数
    }
    
    pub trait DefaultOutput<T> {
        type Output;  // 默认返回类型
    }
}

设计特点：

密封模式 ：sealed 模块确保外部代码无法实现这些 trait
泛型参数 ：
- T：目标单位类型
- Output：返回值的数值类型
自定义错误信息 ：使用 on_unimplemented 属性提供友好的编译错误

3. 宏系统详解

`stringify_outputs!` 宏

rust 复制代码

macro_rules! stringify_outputs {
    // 将类型列表转换为文档字符串
}

作用：生成文档中的类型列表，如 "u8, u16, or u32"

`impl_per!` 宏

这是文件的核心，定义了完整的时间单位系统：

宏的结构

rust 复制代码

impl_per! {
    Nanosecond ("nanosecond") per {
        // 对其他单位的转换定义
        Microsecond: [u16]  // [默认返回类型]
            u16|u32|u64|u128|usize|i16|i32|i64|i128|isize = 1_000;  // 整数类型
            f32|f64 = 1_000.;  // 浮点类型
        // 更多单位...
    }
    // 更多时间单位...
}

生成的代码结构

对于每个时间单位（如 Nanosecond）：

定义标记类型：

rust 复制代码

pub struct Nanosecond;  // 零大小类型

实现转换方法：

rust 复制代码

impl Nanosecond {
    // 默认返回类型的方法
    pub const fn per<T>(_larger: T) -> <T as DefaultOutput<Self>>::Output
    
    // 显式指定返回类型的方法
    pub const fn per_t<Output>(larger: impl MultipleOf<Self, Output> + Copy) -> Output
}

实现转换关系：

rust 复制代码

// 为每对单位关系实现 MultipleOf trait
impl MultipleOf<Nanosecond, u16> for Microsecond {
    const VALUE: u16 = 1_000;  // 1 微秒 = 1000 纳秒
}

impl MultipleOf<Nanosecond, f32> for Microsecond {
    const VALUE: f32 = 1_000.;
}

4. 时间单位层级

完整的单位系统

单位	描述	与其他单位的关系
`Nanosecond`	纳秒	最小单位
`Microsecond`	微秒	= 1000 纳秒
`Millisecond`	毫秒	= 1000 微秒
`Second`	秒	= 1000 毫秒
`Minute`	分钟	= 60 秒
`Hour`	小时	= 60 分钟
`Day`	天	= 24 小时
`Week`	周	= 7 天

设计考虑

整型溢出预防：不同转换使用不同大小的整数类型
浮点支持：同时支持整型和浮点计算
默认返回类型：选择足够表示转换结果的最小类型

5. 使用示例

基本用法

rust 复制代码

// 编译时计算：1 秒有多少毫秒？
let ms_per_sec = Millisecond::per(Second);  // 返回 u16，值为 1000

// 显式指定返回类型
let ms_per_sec_f32 = Millisecond::per_t::<f32>(Second);  // 返回 f32，值为 1000.0

// 错误示例（编译时错误）
let invalid = Nanosecond::per(Millisecond);  // 正确：毫秒比纳秒大
let invalid = Millisecond::per(Nanosecond);  // 编译错误：纳秒比毫秒小

实际使用场景

rust 复制代码

// 时间单位转换
fn process_time(duration_ns: u64) {
    let duration_ms = duration_ns / Nanosecond::per(Millisecond) as u64;
    // 相当于：duration_ns / 1_000_000
}

// 浮点精度计算
fn calculate_rate(events_per_week: f64) -> f64 {
    events_per_week / Day::per_t::<f64>(Week)  // 转换为每天的事件数
    // 相当于：events_per_week / 7.0
}

6. 错误处理机制

编译时错误

当尝试不可能的转换时，编译器会提供友好的错误信息：

rust 复制代码

// 编译错误信息示例：
error[E0277]: `Microsecond` is not an integer multiple of `Nanosecond`
  |     let x = Nanosecond::per(Microsecond);
  |                       ^^^ the trait `MultipleOf<Nanosecond, _>` is not implemented for `Microsecond`

错误信息来自：

rust 复制代码

#[diagnostic::on_unimplemented(
    message = "`{Self}` is not an integer multiple of `{T}`"
)]
pub trait MultipleOf<T, Output> { ... }

7. 性能优势

编译时优化

rust 复制代码

// 源代码
let x = Millisecond::per(Second);

// 编译后（完全优化）
let x = 1000u16;  // 直接内联为常数

零运行时开销

无动态分配：所有类型都是零大小的
无虚函数调用：全部是静态分派
无边界检查：转换系数是编译时常数

8. 类型安全设计

防止非法操作

方向性检查：只能从较小单位转换为较大单位
类型边界：自动选择合适大小的数值类型
显式意图：API 设计明确表达转换方向

类型推断示例

rust 复制代码

// 编译器自动推断合适的返回类型
let a: u16 = Millisecond::per(Second);     // 1000 可以放在 u16 中
let b: u32 = Nanosecond::per(Second);      // 1_000_000_000 需要 u32
let c: u64 = Nanosecond::per(Minute);      // 60_000_000_000 需要 u64

9. 扩展性设计

添加新单位

如果需要添加新的时间单位（如 Month）：

在宏调用中添加：

rust 复制代码

impl_per! {
    // ... 现有单位
    Month ("month") per {
        // 定义与其他单位的关系
    }
}

需要考虑的因素：
- 月份天数不固定（28、29、30、31天）
- 可能需要特殊处理或运行时计算

支持自定义数值类型

通过实现 MultipleOf trait，可以支持自定义的数值类型：

rust 复制代码

impl MultipleOf<Second, MyBigInt> for Minute {
    const VALUE: MyBigInt = MyBigInt::new(60);
}

10. 与其他时间库的对比

相对于传统方法的优势

方法	优点	缺点
常量定义	简单直接	容易用错单位，无类型检查
枚举类型	有一定类型安全	运行时开销，需要匹配
trait 系统（本实现）	编译时安全，零成本	实现复杂，学习曲线高

示例对比

rust 复制代码

// 传统方法：容易出错
const MS_PER_SEC: u64 = 1000;
let ms = seconds * MS_PER_SEC;  // 可能用错常数

// 本实现：类型安全
let ms_per_sec = Millisecond::per(Second);  // 编译时保证正确
let ms = seconds * ms_per_sec as u64;

11. 实际工程价值

对 time crate 的贡献

基础构建块：为 Duration 等类型提供单位转换
API 一致性：统一的时间单位处理
性能保证：确保核心操作零成本

代码质量体现

文档完整：每个方法都有详细的文档注释
错误友好：编译错误信息清晰
测试友好：纯函数，易于测试

12. 总结

设计模式总结

标记类型模式：用类型表示单位，无运行时开销
类型级别编程：在编译时计算和验证转换
密封 trait：控制实现的可见性
声明式宏：减少重复代码，保持 DRY

Rust 特性的充分利用

const fn：编译时计算
泛型：灵活的类型支持
trait：定义行为契约
宏：代码生成和元编程

适用场景

时间密集型应用：需要频繁单位转换
嵌入式系统：零运行时开销
科学计算：高精度时间处理
性能敏感代码：避免动态转换开销

13 附源码

rust 复制代码

//! 时间单位之间的转换。

use self::sealed::{DefaultOutput, MultipleOf};

mod sealed {
    /// 用于定义两个时间单位间比例关系的特征。
    ///
    /// 此特征用于在各种结构体上实现 per 方法。
    #[diagnostic::on_unimplemented(message = "`{Self}` is not an integer multiple of `{T}`")]
    pub trait MultipleOf<T, Output> {
        /// 一个时间单位在另一个时间单位中的数量。
        const VALUE: Output;
    }

    pub trait DefaultOutput<T> {
        type Output;
    }
}

/// 给定类型列表，将其格式化为字符串列表。
macro_rules! stringify_outputs {
    (@inner $first:ty) => {
        concat!("or `", stringify!($first), "`")
    };
    (@inner $first:ty, $($t:ty),+) => {
        concat!(stringify_outputs!($first), ", ", stringify_outputs!(@inner $($t),+))
    };
    ($first:ty) => {
        concat!("`", stringify!($first), "`")
    };
    ($($t:ty),+) => {
        stringify_outputs!(@inner $($t),+)
    };
}

// 将此逻辑分离到独立函数中，以便在公有API中既能将T具名化，又能使用impl Trait作为参数。
const fn multiple_of_value<T, U, Output>(_: T) -> Output
where
    T: MultipleOf<U, Output> + Copy,
{
    T::VALUE
}

/// 为所有相关类型声明并实现 Per 特性。恒等转换实现将自动生成。
macro_rules! impl_per {
    ($($t:ident ($str:literal) per {$(
        $larger:ident : [$default_output:ty]

        $($int_output:ty)|+ = $int_value:expr;
        $($float_output:ty)|+ = $float_value:expr;
    )+})*) => {$(
        #[doc = concat!("A unit of time representing exactly one ", $str, ".")]
        #[derive(Debug, Clone, Copy)]
        pub struct $t;

        impl $t {
            #[doc = concat!("Obtain the number of times `", stringify!($t), "` can fit into `T`.")]
            #[doc = concat!("If `T` is smaller than `", stringify!($t), "`, the code will fail to")]
            /// compile. The return type is the smallest unsigned integer type that can represent
            /// the value.
            ///
            /// Valid calls:
            ///
            $(#[doc = concat!(
                "  - `", stringify!($t), "::per(", stringify!($larger), ")` (returns `",
                stringify!($default_output), "`)"
            )])+
            #[inline]
            pub const fn per<T>(_larger: T) -> <T as DefaultOutput<Self>>::Output
            where
                T: MultipleOf<Self, T::Output> + DefaultOutput<Self> + Copy,
            {
                T::VALUE
            }

            #[doc = concat!("Obtain the number of times `", stringify!($t), "` can fit into `T`.")]
            #[doc = concat!("If `T` is smaller than `", stringify!($t), "`, the code will fail to")]
            /// compile. The return type is any primitive numeric type that can represent the value.
            ///
            /// Valid calls:
            ///
            $(#[doc = concat!(
                "  - `", stringify!($t), "::per(", stringify!($larger), ")` (returns ",
                stringify_outputs!($($int_output),+ , $($float_output),+), ")"
            )])+
            #[inline]
            pub const fn per_t<Output>(larger: impl MultipleOf<Self, Output> + Copy) -> Output {
                multiple_of_value(larger)
            }
        }

        $(
            $(impl MultipleOf<$t, $int_output> for $larger {
                const VALUE: $int_output = $int_value;
            })+

            $(impl MultipleOf<$t, $float_output> for $larger {
                const VALUE: $float_output = $float_value;
            })+

            impl DefaultOutput<$t> for $larger {
                type Output = $default_output;
            }
        )+
    )*};
}

impl_per! {
    Nanosecond ("nanosecond") per {
        Nanosecond: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 1; f32|f64 = 1.;
        Microsecond: [u16] u16|u32|u64|u128|usize|i16|i32|i64|i128|isize = 1_000; f32|f64 = 1_000.;
        Millisecond: [u32] u32|u64|u128|usize|i32|i64|i128|isize = 1_000_000; f32|f64 = 1_000_000.;
        Second:
            [u32] u32|u64|u128|usize|i32|i64|i128|isize = 1_000_000_000; f32|f64 = 1_000_000_000.;
        Minute: [u64] u64|u128|i64|i128 = 60_000_000_000; f32|f64 = 60_000_000_000.;
        Hour: [u64] u64|u128|i64|i128 = 3_600_000_000_000; f32|f64 = 3_600_000_000_000.;
        Day: [u64] u64|u128|i64|i128 = 86_400_000_000_000; f32|f64 = 86_400_000_000_000.;
        Week: [u64] u64|u128|i64|i128 = 604_800_000_000_000; f32|f64 = 604_800_000_000_000.;
    }
    Microsecond ("microsecond") per {
        Microsecond: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 1; f32|f64 = 1.;
        Millisecond: [u16] u16|u32|u64|u128|usize|i16|i32|i64|i128|isize = 1_000; f32|f64 = 1_000.;
        Second: [u32] u32|u64|u128|usize|i32|i64|i128|isize = 1_000_000; f32|f64 = 1_000_000.;
        Minute: [u32] u32|u64|u128|usize|i32|i64|i128|isize = 60_000_000; f32|f64 = 60_000_000.;
        Hour: [u32] u32|u64|u128|i64|i128 = 3_600_000_000; f32|f64 = 3_600_000_000.;
        Day: [u64] u64|u128|i64|i128 = 86_400_000_000; f32|f64 = 86_400_000_000.;
        Week: [u64] u64|u128|i64|i128 = 604_800_000_000; f32|f64 = 604_800_000_000.;
    }
    Millisecond ("millisecond") per {
        Millisecond: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 1; f32|f64 = 1.;
        Second: [u16] u16|u32|u64|u128|usize|i16|i32|i64|i128|isize = 1_000; f32|f64 = 1_000.;
        Minute: [u16] u16|u32|u64|u128|usize|i32|i64|i128|isize = 60_000; f32|f64 = 60_000.;
        Hour: [u32] u32|u64|u128|usize|i32|i64|i128|isize = 3_600_000; f32|f64 = 3_600_000.;
        Day: [u32] u32|u64|u128|usize|i32|i64|i128|isize = 86_400_000; f32|f64 = 86_400_000.;
        Week: [u32] u32|u64|u128|usize|i32|i64|i128|isize = 604_800_000; f32|f64 = 604_800_000.;
    }
    Second ("second") per {
        Second: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 1; f32|f64 = 1.;
        Minute: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 60; f32|f64 = 60.;
        Hour: [u16] u16|u32|u64|u128|usize|i16|i32|i64|i128|isize = 3_600; f32|f64 = 3_600.;
        Day: [u32] u32|u64|u128|usize|i32|i64|i128|isize = 86_400; f32|f64 = 86_400.;
        Week: [u32] u32|u64|u128|usize|i32|i64|i128|isize = 604_800; f32|f64 = 604_800.;
    }
    Minute ("minute") per {
        Minute: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 1; f32|f64 = 1.;
        Hour: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 60; f32|f64 = 60.;
        Day: [u16] u16|u32|u64|u128|usize|i16|i32|i64|i128|isize = 1_440; f32|f64 = 1_440.;
        Week: [u16] u16|u32|u64|u128|usize|i16|i32|i64|i128|isize = 10_080; f32|f64 = 10_080.;
    }
    Hour ("hour") per {
        Hour: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 1; f32|f64 = 1.;
        Day: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 24; f32|f64 = 24.;
        Week: [u8] u8|u16|u32|u64|u128|usize|i16|i32|i64|i128|isize = 168; f32|f64 = 168.;
    }
    Day ("day") per {
        Day: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 1; f32|f64 = 1.;
        Week: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 7; f32|f64 = 7.;
    }
    Week ("week") per {
        Week: [u8] u8|u16|u32|u64|u128|usize|i8|i16|i32|i64|i128|isize = 1; f32|f64 = 1.;
    }
}

这个模块是 Rust 类型系统和元编程能力的优秀展示，体现了"零成本抽象"的核心理念。

【time-rs】time-core 中的 convert.rs 文件详解

概述

1. 设计哲学

零成本抽象

标记类型模式

2. 核心 trait 系统

密封 trait 设计

3. 宏系统详解

stringify_outputs! 宏

impl_per! 宏

宏的结构

生成的代码结构

4. 时间单位层级

完整的单位系统

设计考虑

5. 使用示例

基本用法

实际使用场景

6. 错误处理机制

编译时错误

7. 性能优势

编译时优化

零运行时开销

8. 类型安全设计

防止非法操作

类型推断示例

9. 扩展性设计

添加新单位

支持自定义数值类型

10. 与其他时间库的对比

相对于传统方法的优势

示例对比

11. 实际工程价值

对 time crate 的贡献

代码质量体现

12. 总结

设计模式总结

Rust 特性的充分利用

适用场景

13 附源码

`stringify_outputs!` 宏

`impl_per!` 宏