HiFitime 简介

HiFitime 是一个强大的 Rust 和 Python 库，用于时间管理。它提供广泛的功能，对不同时间尺度上的时间计算进行精确操作，适用于涉及广义相对论和时间膨胀的工程和科学应用。HiFitime 为 1900 年 1 月 1 日 TAI 附近 65,536 年内的精度提供纳秒级精度。HiFitime 还使用了 Kani 模型检查器 进行正式验证，了解更多信息请参阅 此处验证。

大多数 HiFitime 用户只需依赖 Epoch 和 Duration 结构，以及可选的 Weekday 枚举进行基于周的运算。科学应用也可以使用 TimeScale 枚举。

用法

首先，在你的 Rust 项目中使用 cargo add hifitime 安装 hifitime，或者在 Python 中使用 pip install hifitime。

如果从源代码构建，请注意，如果启用了 python 功能，则会构建 Python 包。

纪元（"datetime" 对应物）

在不同时间尺度上创建纪元。

use hifitime::prelude::*;
use core::str::FromStr;
// Create an epoch in UTC
let epoch = Epoch::from_gregorian_utc(2000, 2, 29, 14, 57, 29, 37);
// Or from a string
let epoch_from_str = Epoch::from_str("2000-02-29T14:57:29.000000037 UTC").unwrap();
assert_eq!(epoch, epoch_from_str);
// Creating it from TAI will effectively show the number of leap seconds in between UTC an TAI at that epoch
let epoch_tai = Epoch::from_gregorian_tai(2000, 2, 29, 14, 57, 29, 37);
// The difference between two epochs is a Duration
let num_leap_s = epoch - epoch_tai;
assert_eq!(format!("{num_leap_s}"), "32 s");

// Trivially convert to another time scale
// Either by grabbing a subdivision of time in that time scale
assert_eq!(epoch.to_gpst_days(), 7359.623402777777); // Compare to the GPS time scale

// Or by fetching the exact duration
let mjd_offset = Duration::from_str("51603 days 14 h 58 min 33 s 184 ms 37 ns").unwrap();
assert_eq!(epoch.to_mjd_tt_duration(), mjd_offset); // Compare to the modified Julian days in the Terrestrial Time time scale.

在 Python 中

>>> from hifitime import *
>>> epoch = Epoch("2000-02-29T14:57:29.000000037 UTC")
>>> epoch
2000-02-29T14:57:29.000000037 UTC
>>> epoch_tai = Epoch.init_from_gregorian_tai(2000, 2, 29, 14, 57, 29, 37)
>>> epoch_tai
2000-02-29T14:57:29.000000037 TAI
>>> epoch.timedelta(epoch_tai)
32 s
>>> epoch.to_gpst_days()
7359.623402777777
>>> epoch.to_mjd_tt_duration()
51603 days 14 h 58 min 33 s 184 ms 37 ns
>>> 

HiFitime 提供了 RFC2822、ISO8601 或 RFC3339 等多种日期时间格式。

use hifitime::efmt::consts::{ISO8601, RFC2822, RFC3339};
use hifitime::prelude::*;

let epoch = Epoch::from_gregorian_utc(2000, 2, 29, 14, 57, 29, 37);
// The default Display shows the UTC time scale
assert_eq!(format!("{epoch}"), "2000-02-29T14:57:29.000000037 UTC");
// Format it in RFC 2822
let fmt = Formatter::new(epoch, RFC2822);
assert_eq!(format!("{fmt}"), format!("Tue, 29 Feb 2000 14:57:29"));

// Or in ISO8601
let fmt = Formatter::new(epoch, ISO8601);
assert_eq!(
    format!("{fmt}"),
    format!("2000-02-29T14:57:29.000000037 UTC")
);

// Which is somewhat similar to RFC3339
let fmt = Formatter::new(epoch, RFC3339);
assert_eq!(
    format!("{fmt}"),
    format!("2000-02-29T14:57:29.000000037+00:00")
);

需要一些自定义格式？HiFitime 还支持 C89 令牌，请参阅 文档。

use core::str::FromStr;
use hifitime::prelude::*;

let epoch = Epoch::from_gregorian_utc_hms(2015, 2, 7, 11, 22, 33);

// Parsing with a custom format
assert_eq!(
    Epoch::from_format_str("Sat, 07 Feb 2015 11:22:33", "%a, %d %b %Y %H:%M:%S").unwrap(),
    epoch
);

// And printing with a custom format
let fmt = Format::from_str("%a, %d %b %Y %H:%M:%S").unwrap();
assert_eq!(
    format!("{}", Formatter::new(epoch, fmt)),
    "Sat, 07 Feb 2015 11:22:33"
);

如果您启用了 std 功能（默认），还可以获取当前系统的 UTC 时间，并找到下一个或上一个星期日。

use hifitime::prelude::*;

#[cfg(feature = "std")]
{
    let now = Epoch::now().unwrap();
    println!("{}", now.next(Weekday::Tuesday));
    println!("{}", now.previous(Weekday::Sunday));
}

我们经常需要在两个纪元之间固定步骤查询某些内容。HiFitime 通过 TimeSeries 使这变得非常简单。

use hifitime::prelude::*;

let start = Epoch::from_gregorian_utc_at_midnight(2017, 1, 14);
let end = start + 12.hours();
let step = 2.hours();

let time_series = TimeSeries::inclusive(start, end, step);
let mut cnt = 0;
for epoch in time_series {
    #[cfg(feature = "std")]
    println!("{}", epoch);
    cnt += 1
}
// Check that there are indeed seven two-hour periods in a half a day,
// including start and end times.
assert_eq!(cnt, 7)

在 Python 中

>>> from hifitime import *
>>> start = Epoch.init_from_gregorian_utc_at_midnight(2017, 1, 14)
>>> end = start + Unit.Hour*12
>>> iterator = TimeSeries(start, end, step=Unit.Hour*2, inclusive=True)
>>> for epoch in iterator:
...     print(epoch)
... 
2017-01-14T00:00:00 UTC
2017-01-14T02:00:00 UTC
2017-01-14T04:00:00 UTC
2017-01-14T06:00:00 UTC
2017-01-14T08:00:00 UTC
2017-01-14T10:00:00 UTC
2017-01-14T12:00:00 UTC
>>> 

持续时间

use hifitime::prelude::*;
use core::str::FromStr;

// Create a duration using the `TimeUnits` helping trait.
let d = 5.minutes() + 7.minutes() + 35.nanoseconds();
assert_eq!(format!("{d}"), "12 min 35 ns");

// Or using the built-in enums
let d_enum = 12 * Unit::Minute + 35.0 * Unit::Nanosecond;

// But it can also be created from a string
let d_from_str = Duration::from_str("12 min 35 ns").unwrap();
assert_eq!(d, d_from_str);

HiFitime 保证纳秒级精度，但大多数人类应用程序并不太关心这一点。持续时间可以四舍五入以提供对人类有用的近似值。

use hifitime::prelude::*;

// Create a duration using the `TimeUnits` helping trait.
let d = 5.minutes() + 7.minutes() + 35.nanoseconds();
// Round to the nearest minute
let rounded = d.round(1.minutes());
assert_eq!(format!("{rounded}"), "12 min");

// And this works on Epochs as well.
let previous_post = Epoch::from_gregorian_utc_hms(2015, 2, 7, 11, 22, 33);
let example_now = Epoch::from_gregorian_utc_hms(2015, 8, 17, 22, 55, 01);

// We'll round to the nearest fifteen days
let this_much_ago = example_now - previous_post;
assert_eq!(format!("{this_much_ago}"), "191 days 11 h 32 min 28 s");
let about_this_much_ago_floor = this_much_ago.floor(15.days());
assert_eq!(format!("{about_this_much_ago_floor}"), "180 days");
let about_this_much_ago_ceil = this_much_ago.ceil(15.days());
assert_eq!(format!("{about_this_much_ago_ceil}"), "195 days");

在 Python 中

>>> from hifitime import *
>>> d = Duration("12 min 32 ns")
>>> d.round(Unit.Minute*1)
12 min
>>> d
12 min 32 ns
>>> 

与 time 和 chrono 的比较

首先，time 和 chrono 都是非常出色的库。它们之所以拥有数百万的下载量，是有原因的。其次，hifitime 项目始于 2017 年 10 月，比 time 的复兴时间（约 2019 年）早得多。

两者之间的一个关键区别是，chrono 和 time 都将“时间”和“日期”的概念分开。hifitime 认为这是在物理上不成立的：时间和日期都是相对于给定时间尺度中参考点的偏移。这就是为什么 hifitime 不会将组成日期的各个部分分开，而是只存储相对于 TAI 的固定持续时间。此外，Hifitime 使用模型检查器进行了形式化验证，这比属性测试要彻底得多。

更重要的是，time 和 chrono 都不适用于天文学、天体力学或任何必须考虑相对论速度引起的时间膨胀或缺乏地球作为重力源（这决定了“秒”的“滴答”）的物理。

如果使用 ut1 功能构建，Hifitime 还原生支持 UT1 时间尺度（唯一“真实”的时间）。

特性

• 从 UTC 的系统时间初始化高精度纪元
• 闰秒（如 IETF 每年宣布的那样）
• UTC 表示形式，支持 ISO8601 和 RFC3339 格式，解析速度快（45 纳秒）
• 简单的时序运算支持：加法（例如 2.hours() + 3.seconds()），减法（例如 2.hours() - 3.seconds()），舍入/向下取整/向上取整操作（例如 2.hours().round(3.seconds())）
• 支持纪元和时序的范围内（Epoch 和 Duration 的 linspace）
• 轻松转换许多时间尺度
• 从 ESA 的 Navipedia 进行高保真度历书时间/动态地心坐标系时间（TDB）计算
• 儒略日和改正儒略日
• 对嵌入式设备友好：尽可能使用 no-std 和 const fn