【time-rs】Duration 结构体详解

这是一个 Rust 时间库中的Duration结构体实现，提供高精度的时间跨度表示。

1. 主要特性

• 纳秒级精度：由整秒和纳秒部分组成
• 支持负值：与标准库的std::time::Duration不同，支持负时间间隔
• 安全边界检查：使用RangedI32确保纳秒值在有效范围（-999,999,999 到 999,999,999）

2. 核心结构

pubstructDuration{seconds:i64,// 整秒数nanoseconds:Nanoseconds,// 纳秒部分（带范围检查）padding:Padding,// 用于编译器优化（niche value optimization）}

3. 时间单位常量

提供了常用时间单位的预定义常量：

// 基本单位pubconstNANOSECOND:Self=Self::nanoseconds(1);pubconstMICROSECOND:Self=Self::microseconds(1);pubconstMILLISECOND:Self=Self::milliseconds(1);pubconstSECOND:Self=Self::seconds(1);pubconstMINUTE:Self=Self::minutes(1);pubconstHOUR:Self=Self::hours(1);pubconstDAY:Self=Self::days(1);pubconstWEEK:Self=Self::weeks(1);// 特殊值pubconstZERO:Self=Self::seconds(0);pubconstMIN:Self=Self::new_ranged(i64::MIN,Nanoseconds::MIN);pubconstMAX:Self=Self::new_ranged(i64::MAX,Nanoseconds::MAX);

4. 构造函数

多种构造方式：

// 从秒和纳秒创建letd1=Duration::new(1,500_000_000);// 1.5秒// 从时间单位创建letd2=Duration::hours(2);// 2小时letd3=Duration::minutes(30);// 30分钟// 从浮点数创建letd4=Duration::seconds_f64(1.5);// 1.5秒letd5=Duration::seconds_f32(0.5);// 0.5秒// 从小单位创建letd6=Duration::milliseconds(1500);// 1500毫秒letd7=Duration::microseconds(500);// 500微秒letd8=Duration::nanoseconds(100);// 100纳秒

5. 查询方法

获取整数值

letduration=Duration::hours(2)+Duration::minutes(30);duration.whole_hours();// 2duration.whole_minutes();// 150duration.whole_seconds();// 9000duration.whole_days();// 0

获取小数部分

letduration=Duration::seconds(1)+Duration::milliseconds(500);duration.as_seconds_f64();// 1.5duration.as_seconds_f32();// 1.5duration.subsec_milliseconds();// 500duration.subsec_microseconds();// 500000duration.subsec_nanoseconds();// 500000000

6. 属性检查

letpos=Duration::seconds(5);letneg=Duration::seconds(-5);letzero=Duration::ZERO;pos.is_positive();// truepos.is_negative();// falsepos.is_zero();// falseneg.is_positive();// falseneg.is_negative();// trueneg.is_zero();// falsezero.is_zero();// true

7. 数学运算

加法

letd1=Duration::seconds(5);letd2=Duration::seconds(3);// 普通加法（可能panic）letsum=d1+d2;// 8秒// 检查溢出的加法letchecked=d1.checked_add(d2);// Some(8秒)// 饱和加法letsaturated=Duration::MAX.saturating_add(d2);// Duration::MAX

减法

letd1=Duration::seconds(5);letd2=Duration::seconds(3);letdiff=d1-d2;// 2秒letneg_diff=d2-d1;// -2秒letchecked=d1.checked_sub(d2);// Some(2秒)

乘除法

letd=Duration::seconds(10);letmultiplied=d*2;// 20秒letdivided=d/2;// 5秒letfloat_mul=d*1.5;// 15秒letfloat_div=d/2.5;// 4秒

取反

letd=Duration::seconds(5);letnegated=-d;// -5秒

8. 与标准库互操作

usestd::time::DurationasStdDuration;// 从标准库转换letstd_duration=StdDuration::from_secs(5);lettime_duration=Duration::try_from(std_duration).unwrap();// 转换为标准库（无符号）letunsigned=time_duration.unsigned_abs();// 与标准库比较assert_eq!(Duration::seconds(5),StdDuration::from_secs(5));assert!(Duration::seconds(10)>StdDuration::from_secs(5));

9. 格式化显示

letduration=Duration::hours(2)+Duration::minutes(30);// 完整格式println!("{}",duration);// "2h30m0s"// 简洁格式（带精度）println!("{:.2}",duration);// "2.50h"println!("{:.0}",duration);// "3h"

10. 设计亮点

1. 范围安全性：使用RangedI32保证纳秒值始终有效
2. 零成本抽象：编译时检查，运行时无额外开销
3. 完备的数学运算：支持各种算术操作
4. 良好的错误处理：提供 panic 和 Result 两种风格的 API
5. 与标准库兼容：便于与现有代码集成

11. 性能优化

• Niche Value Optimization：通过Padding字段优化内存布局
• 内联函数：大多数方法标记为#[inline]
• 常量求值：尽可能在编译时计算
• 避免分支：使用位操作处理浮点数转换

12. 使用场景

• 时间间隔计算：计算两个时间点之间的差值
• 定时任务：设置延迟或周期性执行
• 性能测量：测量代码执行时间
• 时间运算：进行时间加减运算
• 序列化/反序列化：作为时间数据的中间表示

这个实现特别适合需要处理相对时间、倒计时、时间差计算的场景，弥补了标准库Duration不支持负值的不足。