Jiff 1.0 发布:Rust 日期时间库
Jiff 是一个 Rust 的日期时间库,旨在让你轻松步入成功之坑。它把时区处理放在 API 的核心位置,自动应对夏令时等诸多常见问题。目前 Jiff 已在 Rust 生态中得到广泛采用。
Jiff 的发音同“gem”里的软 g,读起来像 “gif”。
本文将通过一次 API 导览来宣布 Jiff 1.0 的发布。
目标读者:需要便捷日期时间处理的 Rust 程序员。
目录
Jiff 1.0 的承诺
Jiff 已在多个生产项目中投入使用,包括 uv、Cargo、Starship、fd、Nushell、mise、Jujutsu、uutils/coreutils,甚至被用作 AWS LLRT 中 Temporal 实现的基础。现在是正式宣布 1.0 版本的时刻了。
除非在 Jiff API 中发现重大缺陷,我计划无限期地承诺维护 Jiff 1.0。这一点至关重要,因为 Jiff 的定位是生态系统的构建基石,其他库的公开 API 中将会包含它。这使得 Jiff 成为一个有吸引力的公开依赖项,意味着 semver 不兼容的版本更新可能会给生态系统带来巨大痛苦。因此,这类变更不会轻易做出。
要了解 Jiff 0.2 到 1.0 之间所有破坏性变更的列表,请查阅 CHANGELOG。
引言
在编程中,日期时间库的核心功能位于计算机系统的时间概念和人类的时间概念的交叉点。系统时间的通用概念是 Unix 时间。人类的时间概念要复杂得多,但最流行的模型是将 公历 与 12 小时或 24 小时制时钟结合使用。每个日期时间库的核心都包含某种在这两个概念之间进行转换的例程。
日期时间库通常提供的功能远不止于此。事实上,日期时间处理在历史上一直非常困难。我个人认为,这种困难源于领域建模不佳。许多日期时间库没有将复杂性封装在可复用的代码包中,而是将部分或全部复杂性转嫁给用户。Jiff 则努力将复杂性封装起来,让用户很难做出错误操作。(Jiff 并非首创!)
在博客的这一部分,我们将进行一些非常基础的介绍。
跟着做
要跟随本博客的示例,请创建一个依赖于 jiff 和 anyhow 的新 Cargo 项目:
mkdir jiff-playground
cd jiff-playground
cargo init --bin
cargo add jiff anyhow
$EDITOR src/main.rs
大部分示例都是完整独立的 Rust 程序。直接复制代码,替换 src/main.rs 里的内容即可,然后运行:
cargo run
术语
我很不情愿罗列一串定义,但日期时间领域充满了容易混淆的概念,统一一下词汇还是很有必要的。这一节我尽量写得简短。(像“时区”这样的术语这里没有列出,因为放在后面章节结合实际探索来讲更清楚。)
- Civil time(民用时):你时钟上显示的时间,大体上也是你周边的人看到的时间。换句话说,民用时是某个特定地理区域内人们协商一致的计时方式。它还有很多别名:local time、plain time、naive time、clock time 等。
- UTC:即 Coordinated Universal Time(协调世界时),是全球民用时的基础时间标准,最初的设计意图是大致对应平太阳时。
- TAI:即 International Atomic Time(国际原子时),由原子钟测量的时间标准,与平太阳时没有直接关联。
- 闰秒(Leap second):对 TAI 的一种调整,使其更接近平太阳时,并由此构成 UTC 的基础。
- Unix time:就是 UTC,但忽略了闰秒。
TAI 和闰秒不会是本文的重点,列出它们只是为了说明 Unix time 与 UTC 的区别。
DateTime 洋葱
为了引出 Jiff 的核心类型,我把它的日期时间类型想象成一颗洋葱:从内到外逐层构建,最外层是 ZonedDateTime。那我们再认识几个术语吧——这一次,它们同时也是 Jiff 中的类型:
civil::Date是一个纯粹的格里高利历日期,不关联任何具体位置。civil::Time表示时钟上的一个时间,精度达到纳秒,不绑定任何具体地理位置。civil::DateTime将civil::Date和civil::Time组合在一起,同时提供格里高利日期和时钟时间,同样不绑定任何具体地理位置。Timestamp表示与地理位置无关的、明确的时间点,其数值为自 Unix 纪元以来经过的纳秒数。TimeZone是一套用于在特定地理区域内将Timestamp映射为civil::DateTime以及反向映射的规则。ZonedDateTime将Timestamp、civil::DateTime和TimeZone三者组合,表示特定地理位置上的一个具体时间。
为了更直观地理解,我们可以看看代码中的表现。由于时区可以将 civil 日期时间映射为一个时间点,创建带时区的日期时间的一种方法只需要 civil 日期时间和时区:
use jiff::civil;
fn main() -> anyhow::Result<()> {
let date = civil::date(2026, 11, 1);
let time = civil::time(17, 30, 0, 0);
let datetime = date.to_datetime(time);
// zdt 是 "ZonedDateTime" 的缩写
let zdt = datetime.in_tz("America/New_York")?;
assert_eq!(zdt.timestamp().as_second(), 1793572200);
Ok(())
}
另一种创建带时区日期时间的方法只需要时间戳和时区。这是因为时区也可以将时间戳映射为某个特定的 civil 日期时间:
use jiff::{civil, Timestamp};
fn main() -> anyhow::Result<()> {
let timestamp = Timestamp::from_second(1793572200)?;
let zdt = timestamp.in_tz("America/New_York")?;
// 这是创建 civil 日期时间的简写形式。
// 上例为了清晰,写得更详细一些。
let expected = civil::date(2026, 11, 1).at(17, 30, 0, 0);
assert_eq!(zdt.datetime(), expected);
Ok(())
}
注意这两种方式得到了等价的时区时间,但出发点不同。第一种是从我们在时钟和日历上看到的日期时间出发,第二种则是从某个具体的时间瞬间出发——这种瞬间通常来自数据库、文件系统或其他系统调用。
时区的定义
前面“洋葱”式的时区时间示例中还缺少一块:偏移量(offset)。偏移量表示需要把 UTC 时间调整多少才能得到民用时间。例如 UTC 时间 2026-11-01T22:30:00,要得到纽约居民的民用时间,需要减去 5 小时:
2026-11-01T22:30:00 - 05:00 = 2026-11-01T17:30:00
实际上,每个时区时间都关联着一个偏移量:
use jiff::{civil, tz, Timestamp};
fn main() -> anyhow::Result<()> {
let timestamp = Timestamp::from_second(1793572200)?;
let zdt = timestamp.in_tz("America/New_York")?;
assert_eq!(zdt.offset().seconds(), -(5 * 60 * 60));
let dt = civil::date(2026, 11, 1).at(17, 30, 0, 0);
let zdt = dt.in_tz("America/New_York")?;
assert_eq!(zdt.offset(), tz::offset(-5));
Ok(())
}
注意:上面示例中的
America/New_York字符串是一个 IANA Time Zone Database 标识符。IANA Time Zone Database 是一个时区定义的集合,可以通过简短的标识符字符串来引用,例如Australia/Sydney、Asia/Tokyo、Europe/Berlin。
民用日期时间加上偏移量之后,得到的总是一个明确的时间瞬间。
有了偏移量的概念,现在可以给时区一个更精确的定义了。时区是一个民用时钟保持一致的地理区域,它提供以下功能:
- 从时间瞬间到 UTC 偏移量的映射。对某个瞬间应用偏移量,即可得到民用日期时间。
- 从民用日期时间到可能存在歧义的 UTC 偏移量的映射。对某个民用日期时间应用偏移量,即可得到时间瞬间。
之前的示例已经演示过这两种映射方式,但从 civil datetime 到 offset 的映射看起来有些复杂,主要源于潜在的模糊性。这种模糊性何时出现?当 civil datetime 在该时区中不对应有效的时钟时间(例如因夏令时拨快时钟导致的时间跳变),或者存在多个有效的时钟时间(例如因夏令时拨慢时钟导致的时间重复)时,就会发生偏移量模糊。
来看几个例子。在第一个例子中,我们将观察纽约从夏令时切换到标准时间期间的时刻。在纽约,时钟在凌晨 2 点整被“拨慢”了一小时,这导致 1 点钟这一小时重复了。
use jiff::{
civil::date,
tz::{offset, TimeZone},
};
fn main() -> anyhow::Result<()> {
let tz = TimeZone::get("America/New_York")?;
// During summer time, New York's offset from UTC is -04:00.
let zdt = date(2026, 11, 1).at(0, 30, 0, 0).to_zoned_datetime(tz.clone())?;
assert_eq!(zdt.offset(), offset(-4));
// During standard time, New York's offset from UTC is -05:00.
let zdt = date(2026, 11, 1).at(2, 30, 0, 0).to_zoned_datetime(tz.clone())?;
assert_eq!(zdt.offset(), offset(-5));
// But what does 01:30AM mean? Is it the first repetition or the second?
// Jiff automatically chooses the first by default.
let zdt = date(2026, 11, 1).at(1, 30, 0, 0).to_zoned_datetime(tz.clone())?;
assert_eq!(zdt.offset(), offset(-4));
Ok(())
}
上述示例展示了当发生“折叠”(fold),即时区转换使 civil time 回拨时,Jiff 如何解决模糊性。不过,我们可以深入使用更低层级的 API 来改变模糊性的解决方式。默认情况下,Jiff 采用“兼容”策略,始终选择折叠中时间的第一次重复。但可以通过直接在 TimeZone 上使用 API 来选择其他策略:
use jiff::{
civil::date,
tz::{offset, TimeZone},
};
fn main() -> anyhow::Result<()> {
let tz = TimeZone::get("America/New_York")?;
let dt = date(2026, 11, 1).at(1, 30, 0, 0);
// 与 Jiff 默认使用的策略相同。
let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?;
assert_eq!(zdt.offset(), offset(-4));
// 总是选择较早的时间点。
// 对于 fold 情况,这与默认的
// "compatible" 策略效果相同。
let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?;
assert_eq!(zdt.offset(), offset(-4));
// 总是选择较晚的时间点。
// 对于 fold 情况,这会选择凌晨 1 点
// 第二次出现的时刻!
let zdt = tz.to_ambiguous_zoned_datetime(dt).later()?;
assert_eq!(zdt.offset(), offset(-5));
// 只要存在歧义,就总是返回错误。
assert_eq!(
tz.to_ambiguous_zoned_datetime(dt)
.unambiguous()
.unwrap_err()
.to_string(),
"error converting datetime to instant in time zone America/New_York: \
datetime is ambiguous \
since it falls into a fold between offsets -04 and -05",
);
Ok(())
}
同样的思路也适用于间隙(gap),即时钟切换时会跳过某些民用时间的时区转换。比如 2026 年 3 月 8 日凌晨 2 点,民用时间直接跳到了凌晨 3 点:
use jiff::{
civil::date,
tz::{offset, TimeZone},
};
fn main() -> anyhow::Result<()> {
let tz = TimeZone::get("America/New_York")?;
let dt = date(2026, 3, 8).at(2, 30, 0, 0);
// "compatible" 策略在遇到时间间隙时,选择较晚的时间。
let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?;
assert_eq!(zdt.offset(), offset(-4));
// 始终选择较早的日期时间。
// 对于间隙,这会选取间隙前一个小时。
let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?;
assert_eq!(zdt.offset(), offset(-5));
// 始终选择较晚的日期时间。
// 对于间隙,这与默认的 "compatible" 策略效果相同。
let zdt = tz.to_ambiguous_zoned_datetime(dt).later()?;
assert_eq!(zdt.offset(), offset(-4));
// 只要存在歧义,总是返回错误。
assert_eq!(
tz.to_ambiguous_zoned_datetime(dt)
.unambiguous()
.unwrap_err()
.to_string(),
"error converting datetime to instant in time zone America/New_York: \
datetime is ambiguous \
since it falls into a gap between offsets -05 and -04",
);
Ok(())
}
时长
剩下的两个核心类型都涉及某种“时长”的概念:
Span是一种强大的混合时长类型,融合了日历单位(年、月、周、天)和物理时间单位(时、分、秒、毫秒、微秒、纳秒)。它是一个功能丰富的类型,能保留各个单位的独立数值。SignedDuration是std::time::Duration的带符号版本,始终对应一个 96 位整数的纳秒数。它只能表示物理时间(小时及以下单位),不能表示日历单位(天及以上单位)。
只要条件允许,Span 是首选的时长类型。下面是一个简单示例,展示如何获取两个民用日期之间相隔的天数:
use jiff::civil::date;
fn main() -> anyhow::Result<()> {
let d1 = date(2024, 2, 1);
let d2 = date(2024, 3, 1);
let span = d2 - d1;
assert_eq!(span.get_days(), 29);
// 或者等价写法:
assert_eq!(d1.until(d2)?.get_days(), 29);
// 交换 d1 和 d2 的顺序,结果相同,
// 但为负数。
let span = d1 - d2;
assert_eq!(span.get_days(), -29);
Ok(())
}
时长也可以加到日期上:
use jiff::{civil::date, ToSpan};
fn main() -> anyhow::Result<()> {
let d1 = date(2024, 2, 1);
// 这个便捷语法来自 `ToSpan`
// 扩展 trait。
let span = 29.days();
assert_eq!(d1.checked_add(span)?, date(2024, 3, 1));
Ok(())
}
一般来说,凡是涉及 Span 的操作,都有对应的 SignedDuration 版本:
use jiff::{civil::date, SignedDuration};
fn main() -> anyhow::Result<()> {
let dt1 = date(2024, 2, 1).at(17, 30, 0, 0);
let sdur = SignedDuration::from_mins(90);
assert_eq!(dt1.checked_add(sdur)?, date(2024, 2, 1).at(19, 0, 0, 0));
Ok(())
}
注意上面的例子中,我们实际上从 civil::Date 换成了 civil::DateTime,这是为了演示如何添加物理时间单位。不过用 Span 也能达到同样效果,因为它把所有单位组合在一起:
use jiff::{civil::date, ToSpan};
fn main() -> anyhow::Result<()> {
let dt1 = date(2024, 2, 1).at(17, 30, 0, 0);
let span = 1.hour().minutes(30);
assert_eq!(dt1.checked_add(span)?, date(2024, 2, 1).at(19, 0, 0, 0));
// 日历单位和物理时间单位
// 可以组合使用!
let span = 1.month().hours(1).minutes(30);
assert_eq!(dt1.checked_add(span)?, date(2024, 3, 1).at(19, 0, 0, 0));
Ok(())
}
简单来说,能用 Span 就用 Span;当它太笨重或太慢时,再用 SignedDuration。Span 的一个关键优势是,由于每个单位的值都是独立保存的,时长可以保留原本的语义。比如电影的片长通常用分钟表示,即使超过一小时也是如此。实际上,“2 小时”和“120 分钟”是两个不同的 span:
use jiff::ToSpan;
fn main() -> anyhow::Result<()> {
let span1 = 2.hours();
let span2 = 120.minutes();
// This means the spans are distinct values
// in memory.
assert_ne!(span1.fieldwise(), span2.fieldwise());
Ok(())
}
Span::fieldwise 方法会将 Span 转换为可按字段逐一比较的值。若需根据 Span 实际代表的物理时长进行比较,请改用 Span::compare:
let span1 = 2.hours();
let span2 = 120.minutes();
assert!(span1.compare(span2)?.is_eq());
以上是对 Jiff 中时长的简要介绍。其功能远不止于此,你还可以尝试操作上述示例,探索其更多细节。我们将在后续章节中详细介绍其 API。
何时应使用 Jiff?
Jiff 并非在所有场景下都适用,有时使用更简单的方案就足够了。
首先,如果你在测量程序某部分耗时,几乎肯定应使用单调时钟(monotonic time)。可通过 std::time::Instant 获取:
use std::time::{Duration, Instant};
fn main() -> anyhow::Result<()> {
let start = Instant::now();
// do some serious work
std::thread::sleep(Duration::from_secs(1));
let elapsed = Instant::now().duration_since(start);
println!("{elapsed:?}");
Ok(())
}
若确实需要基于系统时钟计算经过的时间,Jiff 提供了很大的便利:
use std::time::Duration;
use jiff::Timestamp;
fn main() -> anyhow::Result<()> {
// assume `start` came from somewhere
// over a network
let start = Timestamp::now();
std::thread::sleep(Duration::from_secs(1));
let elapsed = Timestamp::now().duration_since(start);
println!("{elapsed}");
Ok(())
}
但针对此场景,你实际上并不需要 Jiff。std::time::SystemTime 完全可以胜任:
use std::time::{Duration, SystemTime};
fn main() -> anyhow::Result<()> {
// 假设 `start` 来自网络上的某个地方
let start = SystemTime::now();
std::thread::sleep(Duration::from_secs(1));
let elapsed = SystemTime::now().duration_since(start)?;
println!("{elapsed:?}");
Ok(())
}
当你需要的不只是 Unix 纪元以来的秒数时,Jiff 就开始发挥作用了。比如,要把 SystemTime 转换成 2026-11-14T21:34:00Z 这样的 RFC 3339 时间戳,需要相当繁琐的数学计算。
如果你完全在 UTC 下工作、不关心本地时间、只用 Unix 时间戳,那 Rust 标准库不会让你失望。
解析与格式化
字符串与时间类型的相互转换是 Jiff 的重要组成部分。Jiff 的重点是通过以下标准实现互操作性:
- RFC 3339 定义了以人类可读的日期时间表示固定偏移时刻的格式,例如
2026-11-12T15:36:00-05:00。这是Timestamp使用的序列化格式。 - RFC 9557 在 RFC 3339 的基础上扩展并增加了时区信息,例如
2026-11-12T15:36:00-05:00[America/New_York]。这是ZonedDateTime使用的序列化格式。 - ISO 8601 覆盖了其余大部分场景,包括时长和日期时间。例如
P5Y3MT20H是 ISO 8601 时长,2026-11-12T15:30:00是 ISO 8601 日期时间,它对应的时刻是未知的。
2026-11-12[America/New_York] 会被解析为等效于 2026-11-12T00:00:00[America/New_York] 的形式。
本部分将介绍 Jiff 的日期时间格式化与输出机制。
FromStr 与 Display
Jiff 中的所有日期时间和时长类型均实现了标准库的 FromStr 和 Display trait。这意味着解析日期时间的操作非常自然:
let ts: Timestamp = "2026-10-31T05:15:00Z".parse()?;
同时也支持直接打印:
println!("{ts}");
解析过程具有灵活性,即使某些组件缺失,解析依然会成功。例如,若省略分钟或秒,这些组件默认取值为零:
let dt: civil::DateTime = "2026-10-31T05".parse()?;
assert_eq!(dt.to_string(), "2026-10-31T05:00:00");
灵活解析的另一个体现是:如果一个字符串中包含另一种日期类型的信息,就可以直接解析出该类型。例如,可以从 ISO 8601 格式的日期时间字符串中解析出日期部分:
let d: civil::Date = "2026-10-31T05:30".parse()?;
assert_eq!(d.to_string(), "2026-10-31");
ZonedDateTime 始终采用 RFC 9557 语法,并包含 IANA 时区标识符:
let zdt: ZonedDateTime = "2026-10-31T05:30[Australia/Sydney]".parse()?;
// 尽管解析的原始字符串中没有偏移量,
// 但系统会根据提供的民用日期时间查询时区定义,
// 自动补全了对应的偏移量。
assert_eq!(zdt.to_string(), "2026-10-31T05:30:00+11:00[Australia/Sydney]");
如果你只想用 RFC 3339 语法打印一个带时区的日期时间,可以直接用该时区日期时间的偏移量来格式化时间戳:
let zdt: ZonedDateTime = "2026-10-31T05:30[Australia/Sydney]".parse()?;
assert_eq!(
zdt.timestamp().display_with_offset(zdt.offset()).to_string(),
"2026-10-31T05:30:00+11:00",
);
Span 和 SignedDuration 类型也基于 ISO 8601 时长格式实现了 FromStr 和 Display trait。例如:
use jiff::{SignedDuration, Span};
fn main() -> anyhow::Result<()> {
let duration = "PT5H30M";
let span: Span = duration.parse()?;
assert_eq!(span.to_string(), "PT5H30M");
let sdur: SignedDuration = duration.parse()?;
assert_eq!(sdur.to_string(), "PT5H30M");
Ok(())
}
由于 Span 是一种同时支持日历单位的混合时长类型,它可以解析包含日历单位和物理时间单位的时长;而 SignedDuration 只能解析物理时间单位的时长:
use jiff::{SignedDuration, Span};
fn main() -> anyhow::Result<()> {
let duration = "P11Y2M28DT5H30M";
let span: Span = duration.parse()?;
assert_eq!(span.to_string(), "P11Y2M28DT5H30M");
let err = duration.parse::<SignedDuration>().unwrap_err();
assert_eq!(
err.to_string(),
"parsing ISO 8601 duration in this context requires \
that the duration contain a time component \
and no components of days or greater",
);
Ok(())
}
不过,ISO 8601 时长格式存在一些不足,我们将在下一节讨论。
“友好”时长格式
ISO 8601 时长字符串被广泛支持,因此 Jiff 中 Span 和 SignedDuration 的默认格式就是它。但它有两个明显的缺点:
- 可读性差。例如在
P11Y2M28DT5H30M中,由于没有空格,数值和单位标签全都挤在一起。 - ISO 8601 时长无法无歧义地表示所有可能的
Span值。
第二个缺点最好通过例子来说明。假设有一个 2000 毫秒的 Span。如果将它转换为 ISO 8601 时长字符串,再解析回来,结果会变成 2 秒:
use jiff::{Span, ToSpan};
fn main() -> anyhow::Result<()> {
let original = 2000.milliseconds();
assert_eq!(original.to_string(), "PT2S");
let got: Span = "PT2S".parse()?;
// 两个时长在不同单位下的值不同!
assert_eq!(original.get_seconds(), 0);
assert_eq!(original.get_milliseconds(), 2000);
assert_eq!(got.get_seconds(), 2);
assert_eq!(got.get_milliseconds(), 0);
Ok(())
}
如果你希望时长的字符串格式能忠实地表示其所有不同的值,这种转换可能就不是我们想要的。
基于上述两个原因,Jiff 自带了一种定制的“友好”时长格式。这种格式是非有损的,而且相比 ISO 8601 时长格式,它更容易被英语使用者阅读。以下是一些合法的友好时长示例:
40d
40 days
1y1d
1yr 1d
3d4h59m
3 days, 4 hours, 59 minutes
3d 4h 59m
2h30m
2h 30m
1mo
1w
1 week
1w4d
1 wk 4 days
1m
0.0021s
0s
0d
0 days
3 mins 34s 123ms
3 mins 34.123 secs
3 mins 34,123s
1y1mo1d1h1m1.1s
1yr 1mo 1day 1hr 1min 1.1sec
1 year, 1 month, 1 day, 1 hour, 1 minute 1.1 seconds
1 year, 1 month, 1 day, 01:01:01.1
解析友好时长的方法跟解析 ISO 8601 时长一样简单:Span 和 SignedDuration 上的 FromStr 实现同时支持 ISO 8601 时长和友好时长:
let span: Span = "6y 10mo 3d 23h".parse()?;
// 回想一下,`Span::fieldwise` 允许
// 以逐单位比较的方式对 `Span` 进行相等性比较。
assert_eq!(span.fieldwise(), 6.years().months(10).days(3).hours(23));
输出友好时长需要多花一点心思,因为它不是默认格式。可以借助 Rust 格式化机制,使用“替代”语法来代替 Span::to_string():
let span = 2000.milliseconds();
// 这也说明了单位的值会被保留。
assert_eq!(format!("{span:#}"), "2000ms");
还可以使用更底层的 friendly 打印器来自定义输出。例如,下面的代码演示了如何把一个 span 以 friendly 格式写入现有的 String,并使用更多空格、更长的单位标签,以及用逗号分隔各个单位:
use jiff::{fmt::friendly, ToSpan};
fn main() -> anyhow::Result<()> {
static PRINTER: friendly::SpanPrinter = friendly::SpanPrinter::new()
.comma_after_designator(true)
.spacing(friendly::Spacing::BetweenUnitsAndDesignators)
.designator(friendly::Designator::Verbose);
let span = 6.years().months(10).days(3).hours(23);
let mut buf = String::new();
PRINTER.print_span(&span, &mut buf)?;
assert_eq!(buf, "6 years, 10 months, 3 days, 23 hours");
Ok(())
}
更多细节请参阅 jiff::fmt::friendly 模块文档,其中包括一份精确描述该格式语法的说明。
strptime 与 strftime
POSIX 的 strptime 和 strftime 算不上格式化和解析日期时间的理想方案,但它们无处不在,大多数程序员也都熟悉。正是由于其普及程度,以及解析和格式化自定义日期时间格式的实用价值,Jiff 提供了基本兼容 POSIX 的这两个函数的实现。
Jiff 中每种日期时间类型都自带 strptime 和 strftime 方法。例如,解析美式 month/day/year 格式的日期:
let date = civil::Date::strptime("%m/%d/%Y", "11/13/2026")?;
assert_eq!(date.to_string(), "2026-11-13");
或者把一个带时区的日期时间格式化成英语使用者易读的形式:
let zdt = civil::date(2026, 11, 13).at(17, 30, 0, 0).in_tz("Australia/Sydney")?;
assert_eq!(
zdt.strftime("%a, %b %d, %Y %H:%M %Z").to_string(),
"Fri, Nov 13, 2026 17:30 AEDT",
);
调用方还可以使用 jiff::fmt::strtime 中更底层的 API,单独获取每个解析出来的组件:
use jiff::{civil, fmt::strtime::BrokenDownTime};
fn main() -> anyhow::Result<()> {
let tm = BrokenDownTime::parse(
"%a, %b %d, %Y %H:%M",
"Fri, Nov 13, 2026 17:30",
)?;
assert_eq!(tm.weekday(), Some(civil::Weekday::Friday));
assert_eq!(tm.month(), Some(11));
assert_eq!(tm.day(), Some(13));
assert_eq!(tm.year(), Some(2026));
assert_eq!(tm.hour(), Some(17));
assert_eq!(tm.minute(), Some(30));
assert_eq!(tm.second(), None);
Ok(())
}
jiff::fmt 模块
上述概览已涵盖绝大多数场景,但有时需要更精细地控制解析或格式化逻辑,或者支持 RFC 2822 等替代格式。jiff::fmt 模块专为这些高级用例设计,代价是 API 稍显复杂。举例来说,假设我们要从 &[u8] 解析一个 RFC 2822 格式的时间戳字符串(这样可以跳过 UTF-8 校验):
use jiff::fmt::rfc2822;
fn main() -> anyhow::Result<()> {
static PARSER: rfc2822::DateTimeParser = rfc2822::DateTimeParser::new();
let data = b"Sat, 13 Jul 2024 15:09:59 -0400";
let ts = PARSER.parse_timestamp(data)?;
assert_eq!(ts.to_string(), "2024-07-13T19:09:59Z");
Ok(())
}
另一个示例展示了当输入的本地时间(civil datetime)存在歧义时,如何调整默认的消歧策略。例如,澳大利亚悉尼在当地时间 2026-04-05T03:00:00 时拨慢时钟,即从 UTC 偏移量 +11 切换到 +10。此时,如果尝试解析因时钟回调而重复出现的时间段,会发生什么?
use jiff::ZonedDateTime;
fn main() -> anyhow::Result<()> {
let zdt: ZonedDateTime = "2026-04-05T02:30[Australia/Sydney]".parse()?;
assert_eq!(zdt.to_string(), "2026-04-05T02:30:00+11:00[Australia/Sydney]");
Ok(())
}
在此,系统选取了 02:30 的首次出现时间,即悉尼结束夏令时的前一刻。实际上,数据本身也可以指定期望的时区偏移量:
use jiff::ZonedDateTime;
fn main() -> anyhow::Result<()> {
let zdt: ZonedDateTime =
"2026-04-05T02:30+11:00[Australia/Sydney]".parse()?;
assert_eq!(zdt.to_string(), "2026-04-05T02:30:00+11:00[Australia/Sydney]");
let zdt: ZonedDateTime =
"2026-04-05T02:30+10:00[Australia/Sydney]".parse()?;
assert_eq!(zdt.to_string(), "2026-04-05T02:30:00+10:00[Australia/Sydney]");
Ok(())
}
但这段代码能正常解析,是因为数据本身不存在歧义——既然提供了时区偏移量,具体的时间点就是确定的。再看 2026-04-05T02:30[Australia/Sydney],它确实有歧义,可能对应两个不同的时间点。那我们该怎么调整处理这种歧义的策略呢?标准库的 FromStr trait 做不到这一点,所以只能像前面对 RFC 2822 的解析那样,手动构建解析器。下面的例子演示了具体做法以及所有可选的消歧方式。请记住:UTC 偏移量 +11:00 对应悉尼居民时钟上 2026-04-05T02:30 的第一次出现,而 +10:00 对应第二次出现。
use jiff::{fmt::temporal::DateTimeParser, tz::Disambiguation};
fn main() -> anyhow::Result<()> {
let string = "2026-04-05T02:30[Australia/Sydney]";
// "compatible" is the default strategy, which selects
// the earlier time in a fold (usually moving from daylight
// saving time to standard time) and the later time in a
// gap (usually moving from standard time to daylight
// saving time).
let parser = DateTimeParser::new().disambiguation(Disambiguation::Compatible);
let zdt = parser.parse_zoned_datetime(string)?;
assert_eq!(zdt.to_string(), "2026-04-05T02:30:00+11:00[Australia/Sydney]");
// "earlier" always selects the first occurrence
// in a fold, or the time before a gap.
// So this is the same as compatible in this case,
// since our civil time is in a fold.
let parser = DateTimeParser::new().disambiguation(Disambiguation::Earlier);
let zdt = parser.parse_zoned_datetime(string)?;
assert_eq!(zdt.to_string(), "2026-04-05T02:30:00+11:00[Australia/Sydney]");
// "later" always selects the second occurrence
// in a fold, or the time after a gap.
// So this is different from "compatible" for a
// fold. Notice that the UTC +10:00 offset is
// chosen.
let parser = DateTimeParser::new().disambiguation(Disambiguation::Later);
let zdt = parser.parse_zoned_datetime(string)?;
assert_eq!(zdt.to_string(), "2026-04-05T02:30:00+10:00[Australia/Sydney]");
// "reject" means that if the instant is ambiguous,
// then an error is returned.
let parser = DateTimeParser::new().disambiguation(Disambiguation::Reject);
let err = parser.parse_zoned_datetime(string).unwrap_err();
assert_eq!(
err.to_string(),
"error converting datetime to instant \
in time zone Australia/Sydney: \
datetime is ambiguous since it falls \
into a fold between offsets +11 and +10",
);
Ok(())
}
jiff::fmt 模块还包含许多其他实用功能,这里不一一展开,主要包括但不限于:
- 将格式化结果直接写入已有内存分配(避免重新分配)。
- 将日期时间解析为各个独立组成部分。
- 为
serde集成提供辅助功能。
通过 ICU4X 集成实现感知本地化的格式化
谈日期时间格式化,就不能不提 locale(区域设置)。所谓 locale,就是一组用于格式化日期时间的用户偏好。当你想向最终用户展示日期时间,而他们并不习惯 RFC 3339、RFC 9557 或 ISO 8601 这类标准格式时,locale 就派上用场了。
Jiff 本身不提供任何处理 locale 的功能,用户可以通过 ICU4X 项目来获得这方面的支持。如果需要在 Jiff 和 ICU4X 之间做转换,可以使用 jiff-icu 这个集成 crate。
下面这个例子演示了如何按 fr-LA locale 格式化一个带时区的日期时间:
(运行前需要先执行 cargo add icu jiff-icu 添加依赖。)
use icu::{
calendar::Iso,
datetime::{fieldsets, DateTimeFormatter},
locale::locale,
time::{zone::models::AtTime, TimeZoneInfo},
};
use jiff::ZonedDateTime;
use jiff_icu::ConvertFrom as _;
fn main() -> anyhow::Result<()> {
// 首先,把 Jiff 的 zoned datetime 转换成 ICU 的对应类型。
let jiff_zdt: ZonedDateTime =
"2024-09-10T23:37:20-04[America/New_York]".parse()?;
let icu_zdt =
icu::time::ZonedDateTime::<Iso, TimeZoneInfo<AtTime>>::convert_from(
&jiff_zdt,
);
// 然后,为 fr-LA locale 创建一个日期时间格式化器:
let formatter = DateTimeFormatter::try_new(
locale!("fr-LA").into(),
fieldsets::YMDET::medium().with_zone(fieldsets::zone::SpecificLong),
)?;
// 最后,格式化这个 zoned datetime。
assert_eq!(
formatter.format(&icu_zdt).to_string(),
"mar. 10 sept. 2024, 23:37:20 heure d'été de l'Est nord-américain",
);
Ok(())
}
ICU4X 的 API 为日期时间格式化提供了大量自定义选项,这里就不再深入展开,超出本文范围了。
日期操作
Jiff 为它的日期时间类型提供了丰富的方法,力求用起来顺手又不易出错。
日期基础
每种日期时间类型都提供一个 new 构造函数,允许调用者用各个组成部分来构建实例。在大多数情况下,这个构造可能会失败。例如:
use jiff::civil::Date;
fn main() -> anyhow::Result<()> {
let d = Date::new(2024, 2, 29)?;
// 所有日期时间类型都提供便捷的
// 访问器以获取其各个组成部分。
assert_eq!(d.year(), 2024);
assert_eq!(d.month(), 2);
assert_eq!(d.day(), 29);
let err = Date::new(2025, 2, 29).unwrap_err();
assert_eq!(
err.to_string(),
"参数 'day' 在 `2025-02` 中无效,取值范围为 `1..=28`",
);
Ok(())
}
由于创建日期非常常见,当已知输入有效时,可以使用简写形式来创建:
let d = const { civil::date(2024, 2, 29) };
assert_eq!(d.year(), 2024);
assert_eq!(d.month(), 2);
assert_eq!(d.day(), 29);
也就是说,civil::date 是一个 const 函数,若输入无效将会 panic。它仅适用于已知有效的输入。例如,用用户提供的值调用它是极不合适的。由于上方使用了 const 块,若尝试提供无效值,编译器将报错。
对于表示时间瞬间的日期时间类型(即 ZonedDateTime 和 Timestamp),还提供一个 now() 构造方法用于获取当前时间:
use jiff::{Timestamp, ZonedDateTime};
fn main() -> anyhow::Result<()> {
let now = Timestamp::now();
println!("{now}");
// 示例输出: 2026-11-15T14:17:21.80099287Z
// 这将自动获取系统配置的时区。
let now = ZonedDateTime::now();
println!("{now}");
// 示例输出: 2026-11-15T09:17:21.80102125-05:00[America/New_York]
Ok(())
}
除了构造方法,还可以使用 Date::with API 基于旧日期值构造新日期:
let d1 = const { civil::date(2024, 2, 29) };
// 即使先传入 31(对应拥有 31 天的月份之前的位置),
// 该 API 也不会报错。任何顺序都可以!这是因为
// 错误被延迟到调用 `build()` 时处理。
let d2 = d1.with().day(31).month(3).build()?;
assert_eq!(d2.to_string(), "2024-03-31");
一旦拥有日期对象,可用的 API 非常丰富:
let d = civil::date(2025, 7, 10);
assert_eq!(d.weekday(), civil::Weekday::Thursday);
assert_eq!(d.first_of_year(), civil::date(2025, 1, 1));
assert_eq!(d.last_of_year(), civil::date(2025, 12, 31));
assert_eq!(d.first_of_month(), civil::date(2025, 7, 1));
assert_eq!(d.last_of_month(), civil::date(2025, 7, 31));
assert_eq!(d.yesterday()?, civil::date(2025, 7, 9));
assert_eq!(d.tomorrow()?, civil::date(2025, 7, 11));
而且,得益于“日期时间洋葱”的分层设计,这些 API 在 civil::DateTime 和 ZonedDateTime 上同样可用:
let create_zdt =
|date: civil::Date| -> Result<ZonedDateTime, jiff::Error> {
date.at(0, 0, 0, 0).in_tz("America/New_York")
};
let zdt = create_zdt(civil::date(2025, 7, 10))?;
assert_eq!(zdt.weekday(), civil::Weekday::Thursday);
assert_eq!(zdt.first_of_year()?, create_zdt(civil::date(2025, 1, 1))?);
assert_eq!(zdt.last_of_year()?, create_zdt(civil::date(2025, 12, 31))?);
assert_eq!(zdt.first_of_month()?, create_zdt(civil::date(2025, 7, 1))?);
assert_eq!(zdt.last_of_month()?, create_zdt(civil::date(2025, 7, 31))?);
assert_eq!(zdt.yesterday()?, create_zdt(civil::date(2025, 7, 9))?);
assert_eq!(zdt.tomorrow()?, create_zdt(civil::date(2025, 7, 11))?);
ZonedDateTime 上的这些操作还会考虑时区切换。比如,ZonedDateTime 知道 tomorrow() 并不总是等于加 24 小时:
// On 2024-11-03 at 2AM in New York, time was rolled
// back 1 hour in the transition from daylight saving
// time to standard time. That means 2024-11-03 was
// actually 25 hours long in New York.
let zdt =
civil::date(2024, 11, 2).at(17, 25, 0, 0).in_tz("America/New_York")?;
let tomorrow = zdt.tomorrow()?;
assert_eq!(tomorrow.datetime(), civil::date(2024, 11, 3).at(17, 25, 0, 0));
// The physical time difference between them is 25 hours!
let span = tomorrow - zdt;
assert_eq!(format!("{span:#}"), "25h");
注:日期运算我们将在下一节讨论。
当 ZonedDateTime::tomorrow()(以及其他返回 ZonedDateTime 的 API)落在时间间隙或折叠区间时,系统会自动选择“兼容”的消歧策略:
// 对于落在折叠区间
// 的带时区时间,默认
// 选择较早的时刻。
let zdt =
civil::date(2024, 11, 2).at(1, 30, 0, 0).in_tz("America/New_York")?;
let tomorrow = zdt.tomorrow()?;
assert_eq!(
tomorrow.to_string(),
"2024-11-03T01:30:00-04:00[America/New_York]"
);
// 而对于间隙,默认
// 选择较晚的时刻。
let zdt =
civil::date(2024, 3, 9).at(2, 30, 0, 0).in_tz("America/New_York")?;
let tomorrow = zdt.tomorrow()?;
assert_eq!(
tomorrow.to_string(),
"2024-03-10T03:30:00-04:00[America/New_York]"
);
若要覆盖这一行为,可以退回到民用时间类型执行操作,随后使用 TimeZone::to_ambiguous_zoned_datetime 来精确控制消歧策略:
// 对于落在折叠区间
// 的带时区时间,默认
// 选择较早的时刻。但假设
// 我们想要较晚的时刻。
let zdt =
civil::date(2024, 11, 2).at(1, 30, 0, 0).in_tz("America/New_York")?;
let tomorrow = zdt
.time_zone()
.to_ambiguous_zoned_datetime(zdt.datetime().tomorrow()?)
.later()?;
assert_eq!(
tomorrow.to_string(),
// 注意时差现在变为 -05,
// 对应的是较晚的
// 时刻。
"2024-11-03T01:30:00-05:00[America/New_York]"
);
日期类型还有几个值得一提的方法。首先是查询诸如“下下周四”或“本月最后一个周日”等信息的能力。前者可以通过 nth_weekday API 实现:
let zdt1 = civil::date(2024, 7, 10).in_tz("America/New_York")?;
assert_eq!(zdt1.weekday(), civil::Weekday::Wednesday);
// 不是本周四,而是下周!
let zdt2 = zdt1.nth_weekday(2, civil::Weekday::Thursday)?;
assert_eq!(zdt2.weekday(), civil::Weekday::Thursday);
assert_eq!(zdt2.date(), civil::date(2024, 7, 18));
而后者则可以通过 nth_weekday_of_month API 实现:
let zdt1 = civil::date(2024, 7, 10).in_tz("America/New_York")?;
assert_eq!(zdt1.weekday(), civil::Weekday::Wednesday);
// 这个月的最后一个周日。
let zdt2 = zdt1.nth_weekday_of_month(-1, civil::Weekday::Sunday)?;
assert_eq!(zdt2.weekday(), civil::Weekday::Sunday);
assert_eq!(zdt2.date(), civil::date(2024, 7, 28));
最后,用户还可以通过 series 获得一个便捷的时间序列迭代器:
use jiff::{civil, ToSpan};
fn main() -> anyhow::Result<()> {
let start = civil::date(2024, 7, 10).in_tz("America/New_York")?;
let mut dates = vec![];
// 每周一次,共 8 周。
for zdt in start.series(1.week()).take(8) {
dates.push(zdt);
}
assert_eq!(
dates,
vec![
civil::date(2024, 7, 10).in_tz("America/New_York")?,
civil::date(2024, 7, 17).in_tz("America/New_York")?,
civil::date(2024, 7, 24).in_tz("America/New_York")?,
civil::date(2024, 7, 31).in_tz("America/New_York")?,
civil::date(2024, 8, 7).in_tz("America/New_York")?,
civil::date(2024, 8, 14).in_tz("America/New_York")?,
civil::date(2024, 8, 21).in_tz("America/New_York")?,
civil::date(2024, 8, 28).in_tz("America/New_York")?,
]
);
Ok(())
}
这些方法在 civil::Date 和 civil::DateTime 上也同样可用,所以在这些类型之间切换会非常自然。
日期运算
Jiff 中所有日期时间类型都支持加减时间长度,以及计算两个日期时间值之间的时间跨度。先从 civil::Date 开始:
use jiff::{civil, ToSpan};
fn main() -> anyhow::Result<()> {
let d1 = civil::date(2024, 7, 30);
let d2 = d1 + 2.days();
assert_eq!(d2, civil::date(2024, 8, 1));
Ok(())
}
这里用到了 civil::Date 的 std::ops::Add trait 实现。不过这样做的缺点是,一旦日期值超出有效范围,程序就会 panic。这也许可以接受,也许不行。但如果你要处理用户输入,就应该改用 Date::checked_add:
use jiff::{civil, ToSpan};
fn main() -> anyhow::Result<()> {
let d1 = civil::date(2024, 7, 30);
let d2 = d1.checked_add(2.days())?;
assert_eq!(d2, civil::date(2024, 8, 1));
Ok(())
}
再来看几个涉及月份和年份的例子:
let d = civil::date(2024, 5, 31);
assert_eq!(d.checked_add(1.month())?, civil::date(2024, 6, 30));
assert_eq!(d.checked_add(2.months())?, civil::date(2024, 7, 31));
let d = civil::date(2025, 1, 31);
assert_eq!(d.checked_add(1.month())?, civil::date(2025, 2, 28));
let d = civil::date(2024, 2, 29);
let span = 1.year().months(2).days(5);
assert_eq!(d.checked_add(span)?, civil::date(2025, 5, 4));
和 Date 的其他方法一样,这些方法在 ZonedDateTime 上同样可用:
let d = civil::date(2024, 5, 31).at(13, 45, 0, 0).in_tz("America/New_York")?;
assert_eq!(
d.checked_add(1.month())?,
civil::date(2024, 6, 30).at(13, 45, 0, 0).in_tz("America/New_York")?
);
看一下 ZonedDateTime::checked_add 的类型签名,可以发现它其实是多态的:
pub fn checked_add<A: Into<ZonedDateTimeArithmetic>>(
&self,
duration: A,
) -> Result<ZonedDateTime, Error>
具体来说,它接受任何能转换为 ZonedDateTimeArithmetic 的类型。目前有以下几种类型实现了相应的 From trait:
也就是说,ZonedDateTime::checked_add 可以接受上面任意一种时长值:
use jiff::{civil, SignedDuration};
fn main() -> anyhow::Result<()> {
let d =
civil::date(2024, 5, 31).at(13, 45, 0, 0).in_tz("America/New_York")?;
assert_eq!(
d.checked_add(SignedDuration::from_mins(45))?,
civil::date(2024, 5, 31).at(14, 30, 0, 0).in_tz("America/New_York")?
);
Ok(())
}
这种多态在 Jiff 中很常见。这里它只是提供了一种便捷方式,让你可以使用多种时长类型。但后面我们会看到,它还被用作配置选项的扩展点,用来控制操作的具体行为。
除了在日期时间值上加减时长,还可以计算两个日期时间之间的时长。例如,求两个日期之间相差的天数:
use jiff::{civil, ToSpan};
fn main() -> anyhow::Result<()> {
let d1 = civil::date(2024, 5, 31);
let d2 = civil::date(2024, 9, 30);
assert_eq!(d2 - d1, 122.days().fieldwise());
Ok(())
}
同样,我们也可以用 Date::until 来计算两个日期之间的时间跨度:
let d1 = civil::date(2024, 5, 31);
let d2 = civil::date(2024, 9, 30);
assert_eq!(d1.until(d2)?, 122.days().fieldwise());
和 Date::checked_add 一样,这个方法在 ZonedDateTime::until 上也可用:
let zdt1 = civil::date(2024, 5, 31).in_tz("America/New_York")?;
let zdt2 = civil::date(2024, 9, 30).in_tz("America/New_York")?;
assert_eq!(zdt1.until(&zdt2)?, 2928.hours().fieldwise());
注意,返回的是小时数而不是天数。这是因为两个 ZonedDateTime 可能位于不同的时区。由于 ZonedDateTime 本质上是时间上的一个瞬时点,而一天的长度会因时区而异,所以默认以小时作为最大单位,可以保证两个带时区日期时间相减总能成功。不过,你可以通过传入额外选项来请求返回更大单位的时长。值得注意的是,ZonedDateTime::until 也是多态的:
pub fn until<'a, A: Into<ZonedDateTimeDifference<'a>>>(
&self,
other: A,
) -> Result<Span, Error>
也就是说,调用方并不局限于传入 ZonedDateTime,任何能转换为 ZonedDateTimeDifference 的类型都可以。比如下面这个例子,我们可以覆盖 duration 中返回的最大单位:
use jiff::{civil, ToSpan, Unit};
fn main() -> anyhow::Result<()> {
let zdt1 = civil::date(2024, 5, 31).in_tz("America/New_York")?;
let zdt2 = civil::date(2024, 9, 30).in_tz("America/New_York")?;
assert_eq!(
zdt1.until((Unit::Month, &zdt2))?,
3.months().days(30).fieldwise()
);
Ok(())
}
ZonedDateTimeDifference 为返回 span 的舍入提供了更强大的配置选项。看这个例子,它生成了一个包含多个单位的 span:
use jiff::{civil::date, ToSpan, Unit};
fn main() -> anyhow::Result<()> {
let zdt1 =
date(2024, 5, 15).at(14, 30, 54, 0).in_tz("America/New_York")?;
let zdt2 = date(2024, 5, 31)
.at(19, 13, 27, 123_456_789)
.in_tz("America/New_York")?;
assert_eq!(
zdt1.until((Unit::Day, &zdt2))?,
16.days()
.hours(4)
.minutes(42)
.seconds(33)
.milliseconds(123)
.microseconds(456)
.nanoseconds(789)
.fieldwise(),
);
Ok(())
}
对最终用户来说,这个精度可能太高了。我们或许希望把 span 舍入到最近的半小时。为此可以显式构建一个 ZonedDateTimeDifference 并配置其选项:
use jiff::{civil::date, RoundMode, ToSpan, Unit, ZonedDateTimeDifference};
fn main() -> anyhow::Result<()> {
let zdt1 =
date(2024, 5, 15).at(14, 30, 54, 0).in_tz("America/New_York")?;
let zdt2 = date(2024, 5, 31)
.at(19, 13, 27, 123_456_789)
.in_tz("America/New_York")?;
let difference = ZonedDateTimeDifference::new(&zdt2)
.largest(Unit::Day)
.smallest(Unit::Minute)
.increment(30)
.mode(RoundMode::HalfExpand);
assert_eq!(
zdt1.until(difference)?,
16.days().hours(4).minutes(30).fieldwise(),
);
Ok(())
}
还需要注意,span 的舍入会考虑夏令时这类时区切换。举个例子,在纽约,从 2024-11-02 17:30 到 2024-11-03 04:45。由于纽约在 2024-11-03 凌晨 2 点结束了夏令时,两者之间的实际物理时间是 12 小时 15 分钟: