Rust时间戳处理库tai64的使用指南

介绍

tai64是一个用于处理TAI64和TAI64N时间戳的Rust库。TAI(国际原子时)是一种不受闰秒影响的时间标准，TAI64和TAI64N是其64位表示形式，常用于需要精确时间戳的场景。

该库提供了：

• TAI64和TAI64N时间戳的解析和格式化
• 与系统时间的相互转换
• 时间戳的算术运算
• 与其他时间标准的转换

安装

在Cargo.toml中添加依赖：

[dependencies]
tai64 = "3.0"

基本用法

创建TAI64N时间戳

use tai64::TAI64N;

// 获取当前时间的TAI64N时间戳
let now = TAI64N::now();
println!("Current TAI64N timestamp: {}", now);

// 从秒和纳秒创建
let timestamp = TAI64N::from_unix(1_000_000_000, 500_000_000).unwrap();
println!("Timestamp: {}", timestamp);

与系统时间转换

use std::time::SystemTime;
use tai64::TAI64N;

// 系统时间转TAI64N
let system_time = SystemTime::now();
let tai64n = TAI64N::from_system_time(&system_time);
println!("SystemTime to TAI64N: {}", tai64n);

// TAI64N转系统时间
let system_time_back = tai64n.to_system_time();

解析和格式化

use tai64::TAI64N;

// 从字符串解析
let timestamp_str = "4000000037a93c4a00000000";
let parsed = timestamp_str.parse::<TAI64N>().unwrap();
println!("Parsed timestamp: {}", parsed);

// 格式化输出
println!("Hex representation: {}", parsed.to_string());

时间运算

use std::time::Duration;
use tai64::TAI64N;

let now = TAI64N::now();
let one_hour_later = now + Duration::from_secs(3600);
let one_hour_earlier = now - Duration::from_secs(3600);

println!("Now: {}", now);
println!("+1 hour: {}", one_hour_later);
println!("-1 hour: {}", one_hour_earlier);

比较时间戳

use tai64::TAI64N;
use std::thread::sleep;
use std::time::Duration;

let t1 = TAI64N::now();
sleep(Duration::from_secs(1));
let t2 = TAI64N::now();

assert!(t1 < t2);
assert_eq!(t1.cmp(&t2), std::cmp::Ordering::Less);

高级用法

处理TAI64(不带纳秒)

use tai64::TAI64;

let tai64_now = TAI64::now();
println!("TAI64 timestamp: {}", tai64_now);

// 与TAI64N相互转换
let tai64n = tai64_now.to_tai64n();
let back_to_tai64 = tai64n.to_tai64();

自定义格式输出

use tai64::TAI64N;

let now = TAI64N::now();
println!("Unix timestamp: {}", now.unix());
println!("Seconds: {}", now.seconds());
println!("Nanoseconds: {}", now.nanos());

错误处理

use tai64::TAI64N;

let result = TAI64N::from_unix(i64::MAX as u64 + 1, 0);
assert!(result.is_err());
println!("Error: {:?}", result.err().unwrap());

完整示例代码

use std::time::{SystemTime, Duration};
use tai64::{TAI64, TAI64N};

fn main() {
    // 1. 创建时间戳
    println!("=== 创建时间戳 ===");
    let now = TAI64N::now();
    println!("当前TAI64N时间戳: {}", now);
    
    let custom_time = TAI64N::from_unix(1_000_000_000, 500_000_000).unwrap();
    println!("自定义时间戳: {}", custom_time);

    // 2. 系统时间转换
    println!("\n=== 系统时间转换 ===");
    let system_time = SystemTime::now();
    let tai64n = TAI64N::from_system_time(&system_time);
    println!("系统时间 -> TAI64N: {}", tai64n);
    let system_time_back = tai64n.to_system_time();
    println!("TAI64N -> 系统时间: {:?}", system_time_back);

    // 3. 解析和格式化
    println!("\n=== 解析和格式化 ===");
    let timestamp_str = "4000000037a93c4a00000000";
    let parsed = timestamp_str.parse::<TAI64N>().unwrap();
    println!("解析后的时间戳: {}", parsed);
    println!("十六进制表示: {}", parsed.to_string());
    println!("Unix时间戳: {}", parsed.unix());
    println!("秒数: {}", parsed.seconds());
    println!("纳秒: {}", parsed.nanos());

    // 4. 时间运算
    println!("\n=== 时间运算 ===");
    let now = TAI64N::now();
    let one_hour_later = now + Duration::from_secs(3600);
    let one_hour_earlier = now - Duration::from_secs(3600);
    println!("当前: {}", now);
    println!("+1小时: {}", one_hour_later);
    println!("-1小时: {}", one_hour_earlier);

    // 5. TAI64处理
    println!("\n=== TAI64处理 ===");
    let tai64_now = TAI64::now();
    println!("TAI64时间戳: {}", tai64_now);
    let tai64n_from_tai64 = tai64_now.to_tai64n();
    println!("转换为TAI64N: {}", tai64n_from_tai64);
    let back_to_tai64 = tai64n_from_tai64.to_tai64();
    println!("转换回TAI64: {}", back_to_tai64);

    // 6. 错误处理
    println!("\n=== 错误处理 ===");
    match TAI64N::from_unix(i64::MAX as u64 + 1, 0) {
        Ok(_) => println!("创建成功"),
        Err(e) => println!("错误: {}", e),
    }
}

注意事项

1. TAI时间不考虑闰秒，与UTC时间会有差异
2. 在跨系统传输时间戳时，TAI64/TAI64N比本地时间更可靠
3. 对于需要高精度时间戳的场景，TAI64N(带纳秒)比TAI64更合适

这个库非常适合需要精确时间戳记录、跨系统时间同步或需要避免闰秒问题的应用场景。