一个面向 Rust 的日期时间库
Jiff 是一个面向 Rust 的日期时间库,它鼓励你跳进“成功的坑”。Jiff 将时区处理放到 API 的最前面,从而自动处理许多与夏令时相关的常见问题。Jiff 已经在 Rust 生态中得到广泛采用。
Jiff 的发音像“gif”,其中“g”是“gem”里的软音“g”。
这篇博客通过浏览其 API 来介绍 Jiff 1.0 的发布。
目标读者:需要进行便捷日期时间处理的 Rust 程序员。
目录
- Jiff 1.0 的承诺
- 简介 跟着做 术语 DateTime 洋葱 定义时区 持续时间 什么时候应该使用 Jiff?
- 跟着做
- DateTime 洋葱
- 定义时区
- 什么时候应该使用 Jiff?
- 解析与格式化 FromStr 与 Display “友好”的 Duration 格式 strptime 与 strftime jiff::fmt 模块 通过 ICU4X 集成进行区域设置敏感的格式化
- FromStr 与 Display
- “友好”的 Duration 格式
- strptime 与 strftime
- jiff::fmt 模块
- 通过 ICU4X 集成进行区域设置敏感的格式化
- 日期操作 日期基础 日期算术
- Civil time:你在时钟上看到的时间。一般来说,也是你大致地理周边的人同样看到的时间。也就是说,民用时是特定地理区域内人们为交流时间而达成的人类协调约定。民用时也称为:本地时间、普通时间、naive time、时钟时间等。
- UTC:Coordinated Universal Time 的缩写;它是一种时间标准,是世界各地民用时的基础。它最初旨在大致对应平太阳时。
- TAI:International Atomic Time 的缩写;它是通过原子钟测量的时间标准。它不直接与平太阳时关联。
- 闰秒:对 TAI 的调整,使其更接近平太阳时,从而构成 UTC 的基础。
- Unix 时间:UTC,但忽略闰秒。
TAI 和闰秒不会成为这篇博客的主题,但这里列出它们是为了说明 Unix 时间与 UTC 之间的区别。
DateTime 洋葱
为了过渡到 Jiff 的一些核心类型,我逐渐把它的 datetime 类型想象成洋葱。按相反的顺序,我们可以逐层构建,一直构建到 ZonedDateTime。那么让我们从更多术语开始,不过这次它们也是 Jiff 中的类型:
- civil::Date 是一个普通的公历日期,不依附于任何特定地点。
- civil::Time 是时钟上的普通时间,精确到纳秒,不依附于任何特定地点。
- civil::DateTime 结合 civil::Date 和 civil::Time,同时提供公历日期和时钟时间。它也不依附于任何特定地点。
- Timestamp 是一个明确的具体时间瞬间,与地理位置无关,表示为自 Unix 纪元以来的纳秒数。
- TimeZone 是一组规则,用于在特定地理区域内将 Timestamp 映射到 civil::DateTime,反之亦然。
- ZonedDateTime 结合 Timestamp、civil::DateTime 和 TimeZone,以表示特定地理位置中的特定时间瞬间。
为了更具体一些,我们可以看看这在代码中是什么样子。由于时区可以将 civil datetime 映射到时间瞬间,创建 zoned datetime 的一种方式只需要 civil datetime 和一个时区:
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 is an initialism for "ZonedDateTime"
let zdt = datetime.in_tz("America/New_York")?;
assert_eq!(zdt.timestamp().as_second(), 1793572200);
Ok(())
}
创建 zoned datetime 的另一种方式只需要一个 timestamp 和一个时区。这是因为时区也可以将 timestamp 映射到特定的 civil datetime:
use jiff::{civil, Timestamp};
fn main() -> anyhow::Result<()> {
let timestamp = Timestamp::from_second(1793572200)?;
let zdt = timestamp.in_tz("America/New_York")?;
// This is a shortcut for creating a civil datetime.
// The previous example spells it out a bit more verbosely
// for clarity.
let expected = civil::date(2026, 11, 1).at(17, 30, 0, 0);
assert_eq!(zdt.datetime(), expected);
Ok(())
}
注意,在两种情况下我们如何得到等价的 zoned datetime,但我们是从不同方向切入的。第一种情况下,我们从一个可能在时钟和日历
2026-11-01T22:30:00 - 05:00 = 2026-11-01T17:30:00
确实,每个带时区的 datetime 都带有一个与之关联的偏移量:
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 时区数据库标识符。IANA 时区数据库是一组时区定义,可以通过简短的标识符字符串来引用。例如:Australia/Sydney、Asia/Tokyo、Europe/Berlin。
当一个 civil datetime 与一个偏移量结合时,你得到的始终是时间中的一个瞬间。
引入了偏移量的概念之后,我们现在可以更精确地定义时区。时区是一个地理区域,在该区域内民用时钟保持一致,并且提供以下内容:
- 从时间中的一个瞬间到 UTC 偏移量的映射。施加于一个瞬间的偏移量会产生一个 civil datetime。
- 从 civil datetime 到可能产生歧义的 UTC 偏移量的映射。施加于一个 civil datetime 的偏移量会产生一个瞬间。
这两种映射在前面的示例中都已演示过,但由于存在一些潜在的歧义,从 civil datetime 到偏移量的映射似乎相当复杂。这种歧义何时出现?当一个 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”(即时钟拨回)时,也就是当存在一个使民用时间向后移动的时区过渡时,Jiff 如何解决这一歧义。但我们实际上可以深入使用更低层的 API 来改变该歧义的解决方式。默认情况下,Jiff 使用一种“compatible”策略,它总是选择 fold 中某个时间的第一次重复。但也可以通过直接在 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);
// The same that Jiff uses by default.
let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?;
assert_eq!(zdt.offset(), offset(-4));
// Always selects the earlier datetime.
// For a fold, this is the same as the
// default "compatible" strategy.
let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?;
assert_eq!(zdt.offset(), offset(-4));
// Always selects the later datetime.
// For a fold, this selects the second
// occurrence of the 1AM hour!
let zdt = tz.to_ambiguous_zoned_datetime(dt).later()?;
assert_eq!(zdt.offset(), offset(-5));
// Always returns an error when there
// is any ambiguity.
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);
// The "compatible" strategy selects
// the later time in the case of gaps.
let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?;
assert_eq!(zdt.offset(), offset(-4));
// Always selects the earlier datetime.
// For a gap, this selects the hour
// before the gap.
let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?;
assert_eq!(zdt.offset(), offset(-5));
// Always selects the later datetime.
// For a gap, this is the same as the
// default "compatible" strategy.
let zdt = tz.to_ambiguous_zoned_datetime(dt).later()?;
assert_eq!(zdt.offset(), offset(-4));
// Always returns an error when there
// is any ambiguity.
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);
// or, equivalently:
assert_eq!(d1.until(d2)?.get_days(), 29);
// Flipping d1 and d2 gives the same result,
// but negative.
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);
// This convenient syntax comes from the
// `ToSpan` extension 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
注意,在上面的示例中,我们实际上从使用 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));
// Calendar and physical time units can // be combined! 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 hours 的 span 与 120 minutes 的 span 是不同的 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 并不总是合适的选择。有时用更简单的东西就能应付。
首先,如果你在程序中测量某件事花费的时间,几乎肯定应该使用单调时间。这可以通过 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<()> { // assume start came from somewhere // over a network 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 民用日期时间,其对应的时刻未知。
Jiff 实际实现的,是用于灵活地从字符串解析日期时间的 Temporal RFC 9557 / ISO 8601 语法。对大多数用例来说,只需按 RFC 3339、RFC 9557 或 ISO 8601 来理解就足够了。但 Jiff 确实支持解析在这三种规范中均无效的字符串。例如,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()?; // While the string we parsed didn't have any offset, // one was automatically added by consulting the time // zone definition for the civil datetime provided. 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 时长格式确实存在一些不足之处,我们将在下一节中讨论。
## “友好”的时长格式
一个 Rust 的日期时间库
由于 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()?;
// The spans have different unit values! 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(()) }
对于希望 span 的字符串格式忠实表示 span 所有可能不同值的情况,这可能并不理想。
由于这两个原因,Jiff 自带一种定制的“friendly”持续时间格式。该 friendly 格式是无损的,并且对英语使用者来说,旨在比 ISO 8601 持续时间格式更易读。以下是一些都是有效 friendly 持续时间的示例:
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
解析 friendly 持续时间和解析 ISO 8601 持续时间一样容易:Span 和 SignedDuration 上的 FromStr 实现同时支持 ISO 8601 持续时间和 friendly 持续时间:
let span: Span = "6y 10mo 3d 23h".parse()?; // Recall that Span::fieldwise permits // equality comparisons on Span in a // unit-by-unit fashion. assert_eq!(span.fieldwise(), 6.years().months(10).days(3).hours(23));
打印 friendly 持续时间确实需要多花一点功夫,因为它不是默认格式。除了 Span::to_string(),还可以通过 Rust 的格式化机制使用“alternative”语法:
let span = 2000.milliseconds(); // This also demonstrates that our unit // values are preserved. 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 和 POSIX strftime 例程远非格式化与解析日期时间的理想方式,但它们无处不在,而且大多数程序员都熟悉它们。由于它们无处不在,并且能够格式化和解析定制日期时间格式很有用,Jiff 提供了这些例程的实现,且大多与 POSIX 兼容。
Jiff 中的每个日期时间类型都带有 strptime 和 strftime 例程。例如,要解析美国月/日/年格式的民用日期:
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 日期时间存在歧义时,如何更改默认的消歧策略。例如,澳大利亚悉尼在当地时间 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 的第一次出现,而 UTC 偏移 +10:00 对应第二次出现。
use jiff::{fmt::temporal::DateTimeParser, tz::Disambiguation};
fn main() -> anyhow::Result<()> { let string = "2026-04-05T02:30[Australia/Sydney]";
// "compatible" 是默认策略,它在 fold(通常是从夏令时 // 切换到标准时)中选择较早的那个时间,在 gap(通常是 // 从标准时切换到夏令时)中选择较晚的那个时间。 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" 总是选择 fold 中的第一次出现, // 或者 gap 之前的时间。 // 所以在此例中它与 compatible 相同, // 因为我们的民用时间处于 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" 总是选择 fold 中的第二次出现, // 或者 gap 之后的时间。 // 所以对于 fold 而言,它与 "compatible" 不同。 // 注意这里选择的是 UTC +10:00 偏移。 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" 意味着如果该时刻存在歧义, // 就返回一个错误。 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 模块还包含许多本文不会涉及的其他好东西,包括但不限于:
- 直接格式化到已有分配内存中的能力。
- 将 datetime 解析为其各个组成部分。
- 用于 serde 集成的辅助工具。
## Locale Sensitive Formatting via ICU4X Integration
任何关于 datetime 格式化的章节,都不能不谈到 locale。在此语境下,locale 是一组用于格式化 datetime 的用户偏好设置。当你需要把 datetime 呈现给不期望 RFC 3339、RFC 9557 或 ISO 8601 标准格式的最终用户时,这很有用。
Jiff 自身不提供任何处理 locale 的设施。相反,用户可以通过 ICU4X 项目选择启用这一支持。要在 Jiff 与 ICU4X 之间进行转换,可以使用 jiff-icu 集成 crate。
下面是一个示例,展示如何在 fr-LA locale 中格式化一个带时区的 datetime:(要使其生效,你需要对项目运行 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<()> { // Firstly, do a conversion from Jiff's zoned datetime to ICU's. 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, );
// Second, create a datetime formatter for the fr-LA locale: let formatter = DateTimeFormatter::try_new( locale!("fr-LA").into(), fieldsets::YMDET::medium().with_zone(fieldsets::zone::SpecificLong), )?;
// Thirdly, format the 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 提供了大量用于定制 datetime 格式化的选项。进一步探索它超出了本博客的范围。
## Date Manipulation
一个面向 Rust 的日期时间库
Jiff 在其日期时间类型上提供了许多方法,以尽可能让它们的使用舒适且不易出错。
## 日期基础
每个日期时间类型都提供一个 new 构造器,让调用者能够从其各个组成部分构建它。在大多数情况下,这个构造器是可失败的。例如:
use jiff::civil::Date;
fn main() -> anyhow::Result<()> { let d = Date::new(2024, 2, 29)?; // All datetime types have convenient // accessors for each of their components. 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(), "parameter 'day' for 2025-02 is invalid, must be in range 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}"); // Example output: 2026-11-15T14:17:21.80099287Z
// This will automatically fetch your system's configured time zone. let now = ZonedDateTime::now(); println!("{now}"); // Example output: 2026-11-15T09:17:21.80102125-05:00[America/New_York]
Ok(()) }
除了构造器之外,还可以使用 Date::with API 从旧日期值构造新的日期值:
let d1 = const { civil::date(2024, 2, 29) }; // This API doesn't break just because 31 // is supplied before a month that has 31 // days. Any order is fine! This is because // errors are deferred until build() is // called. 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));
此外,由于 datetime onion,所有这些 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)会落入间隙或重叠时,会自动选择 “compatible” 消歧策略:
// For a zoned datetime that lands // in a fold, the earlier instant is // chosen by default. 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]" );
// And for a gap, the later instant // is chosen by default. 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]" );
要覆盖此行为,你可以下探到 civil 日期时间,执行操作,然后使用 TimeZone::to_ambiguous_zoned_datetime 来控制确切的消歧策略:
// For a zoned datetime that lands // in a fold, the earlier instant is // chosen by default. But let's say // we want the later instant. let zdt =
所有这些方法在 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 实现:
- SignedDuration
- std::time::Duration
这意味着 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 的东西。下面是一个这样的例子,我们可以覆盖返回的持续时间中的最大单位:
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
接下来我们继续讨论舍入,不过这次是应用于日期时间本身。
## 日期舍入
Jiff 中的日期舍入仅限于天及更低的单位。因此,它仅适用于 ZonedDateTime、Timestamp、civil::DateTime、civil::Time,而不适用于 civil::Date。
对日期时间进行舍入的一个常见示例是降低精度。例如,系统时钟可能提供纳秒精度,但也许我们只关心最接近的半小时:
use jiff::{civil::date, Unit};
fn main() -> anyhow::Result<()> { let zdt = date(2024, 11, 2) .at(17, 46, 20, 123_456_789) .in_tz("America/New_York")?; assert_eq!( zdt.to_string(), "2024-11-02T17:46:20.123456789-04:00[America/New_York]" );
// 舍入到最接近的半小时。 let rounded = zdt.round((Unit::Minute, 30))?; assert_eq!( rounded.to_string(), "2024-11-02T18:00:00-04:00[America/New_York]" );
Ok(()) }
与时间跨度舍入一样,对 ZonedDateTime 进行舍入时会考虑时区转换:
let zdt = date(2024, 11, 3) .at(11, 45, 20, 123_456_789) .in_tz("America/New_York")?;
// 舍入到最接近的一天。 let rounded = zdt.round(Unit::Day)?; assert_eq!( rounded.to_string(), "2024-11-04T00:00:00-05:00[America/New_York]" );
请注意,在上面的示例中,我们的时间 11:45 AM 是在正午之前,但结果仍然向上舍入到下一天。这是因为这一天的中点是 11:30 AM,因为到 11:30 AM 时,已经过去了 12.5 小时,这是由于纽约离开夏令时导致 1 AM 小时重复出现。
## 其他日历
Jiff 本身除前推格里高利历外不支持任何其他日历。可以改用 ICU4X crate 来处理非格里高利历,并使用 jiff-icu crate 在日期时间类型之间进行转换:(使用 cargo add icu jiff-icu 使此示例可用。)
use icu::{ calendar::{types::Month, Date as IcuDate}, time::{DateTime as IcuDateTime, Time as IcuTime}, }; use jiff::civil::DateTime; use jiff_icu::ConvertTryFrom as _;
fn main() -> anyhow::Result<()> { // 首先,使用希伯来历创建一个 ICU 日期时间。 let datetime = IcuDateTime { date: IcuDate::try_new_hebrew_v2(5785, Month::new(5), 4)?, time: IcuTime::try_new(17, 30, 0, 0)?, };
// 其次,将其转换为 civil 日期时间。 // 这将自动使用 ICU 将 // 日期从希伯来历转换为 // 格里高利历(或 ISO)历。 let zdt = DateTime::convert_try_from(datetime)?; assert_eq!(zdt.to_string(), "2025-02-02T17:30:00"); Ok(()) }
ICU4X API 支持更多日历。
## 我应该使用哪种 DateTime 类型?
Jiff 中有 3 种可能容易混淆的日期时间类型:
- civil::DateTime
- ZonedDateTime
何时应该使用其中的哪一种而不是另一种?
初步来说,如果你可以使用 ZonedDateTime,那么它可能就是你想要选择的类型。它表示特定地理位置中的特定时间点。也就是说,它同时具有 Timestamp 和 TimeZone。
如果你只需要在 UTC 中工作或只处理系统时间,那么 Timestamp 可能是正确的选择。这对于表示不与任何时区关联的特定时间点很有用。
civil::DateTime 适用于你不关心特定时间点且计算应与时区无关的场景。例如,从用户界面日期时间选择器解析日期时间信息时。
请记住,通过提供时区,civil::DateTime 和 Timestamp 都可以转换为 ZonedDateTime。
## Span 操作
我们已经了解了如何向日期时间值添加 span,以及如何获取日期时间值之间的差作为 span。但我们还没有探索 Span 本身可用的 API。
文章标题:A datetime library for Rust
正文:
首先,我们可以通过构造函数来构建一个 Span,它会返回一个所有单位都设置为 0 的 Span:
use jiff::Span;
let span = Span::new();
Span 同时实现了 Copy 且不可变。我们可以通过链式方法调用来创建新的 span:
let span = Span::new().hours(1).minutes(30); assert_eq!(span.to_string(), "PT1H30M");
或者我们可以使用 ToSpan 这个便捷 trait,它在整数类型上添加了用于构建 span 的方法:
use jiff::ToSpan;
let span = 1.hour().minutes(30); assert_eq!(span.to_string(), "PT1H30M");
但请注意,像 Span::hours 和 ToSpan::hours 这样的方法在整数超出 Span 支持的限制时会 panic。当你的 span 是程序中的字面量时,这没问题,因为 panic 意味着存在 bug。但如果你的输入来自最终用户,最好使用可失败的方法:
let span = Span::new().try_hours(1)?.try_minutes(30)?; assert_eq!(span.to_string(), "PT1H30M");
Span 会保留每个单独的单位值。这意味着 90 分钟和 1 小时 30 分钟,虽然它们表示相同的持续时间,但在内存中实际上是不同的值:
let span1 = 1.hour().minutes(30); let span2 = 90.minutes(); assert_eq!(span1.to_string(), "PT1H30M"); assert_eq!(span2.to_string(), "PT90M");
这为调用者在表示持续时间时提供了最大的灵活性。这使得即使持续时间累加起来达到更大的单位,也能以特定单位来表示。例如,电影的时长通常以分钟表示,即使时长超过一小时也是如此。这可以通过 Span::round 以编程方式调整:
use jiff::{SpanRound, ToSpan, Unit};
fn main() -> anyhow::Result<()> { let span1 = 1.hour().minutes(30); let span2 = span1.round(SpanRound::new().largest(Unit::Minute))?; assert_eq!(span2.to_string(), "PT90M");
Ok(()) }
你也可以反过来操作:
use jiff::{SpanRound, ToSpan, Unit};
fn main() -> anyhow::Result<()> { let span1 = 90.minutes(); let span2 = span1.round(SpanRound::new().largest(Unit::Hour))?; assert_eq!(span2.to_string(), "PT1H30M");
Ok(()) }
尽管这个 API 的名字叫 round,但这两个示例都没有进行实际的舍入。相反,由于我们只设置了最大单位,这个 API 执行的是单位平衡。单位平衡是指所有单位值向上进位到更大的单位,直到达到配置的最大单位。这也适用于日历单位,但你需要提供一个相对日期:
use jiff::{civil, SpanRound, ToSpan, Unit};
fn main() -> anyhow::Result<()> { let span = 2756.hours(); let dt = civil::date(2020, 1, 1).at(0, 0, 0, 0); let round = SpanRound::new().largest(Unit::Year).relative(dt); assert_eq!(span.round(round)?.to_friendly(), "3mo 23d 20h"); Ok(()) }
没有相对日期,就无法知道一个月有多少小时。也就是说,一旦涉及日历单位,除非应用了某种上下文,否则 span 不能被解释为物理时间持续时间。
这甚至适用于天本身,因为一天有时可能多于或少于 24 小时。以
use jiff::{SpanRound, ToSpan, Unit};
fn main() -> anyhow::Result<()> { let span = 2.hours().minutes(30); let round = SpanRound::new().smallest(Unit::Hour); assert_eq!(span.round(round)?.to_friendly(), "3h"); Ok(()) }
你还可以将其舍入模式从默认值(“half-expand”,也就是你在学校学过的舍入方式)改为截断(或其他几种模式之一):
use jiff::{RoundMode, SpanRound, ToSpan, Unit};
fn main() -> anyhow::Result<()> { let span = 2.hours().minutes(30); let round = SpanRound::new().smallest(Unit::Hour).mode(RoundMode::Trunc); assert_eq!(span.round(round)?.to_friendly(), "2h"); Ok(()) }
还可以指定舍入增量,以舍入到最接近的单位值。例如,舍入到最接近的半小时:
use jiff::{SpanRound, ToSpan, Unit};
fn main() -> anyhow::Result<()> { let span = 2.hours().minutes(31); let round = SpanRound::new().smallest(Unit::Minute).increment(30); assert_eq!(span.round(round)?.to_friendly(), "2h 30m"); Ok(()) }
由于仅根据内存中的值无法轻松正确比较 Span 值,因此提供了专门的比较例程 Span::compare:
let span1 = 2.hours(); let span2 = 120.minutes(); assert!(span1.compare(span2)?.is_eq());
另外,还可以将 Span 转换为以任意单位表示的浮点值。例如:
use jiff::{ToSpan, Unit};
fn main() -> anyhow::Result<()> { let span = 90.minutes(); assert_eq!(span.total(Unit::Hour)?, 1.5); Ok(()) }
转换为日历单位需要相对日期,原因与上文讨论的相同:
use jiff::{civil, ToSpan, Unit};
fn main() -> anyhow::Result<()> { let span = 24.hours(); assert_eq!( span.total((Unit::Month, civil::date(2026, 6, 1)))?, 0.03333333333333333 ); assert_eq!( span.total((Unit::Month, civil::date(2026, 7, 1)))?, 0.03225806451612903 ); Ok(()) }
## 结论
到目前为止,我们已经探索了 Jiff API 的很大一部分。我们没有谈及每一个角落,但我认为已经覆盖了最重要的部分。
最后,我们将简要讨论动机和灵感。
## 动机
每当我在 Rust 中需要处理日期时间时,我总是感到困惑。我应该用 chrono 还是 time?如何从时间戳获取本地时间?如何使用系统的时区数据库?如何进行日历运算?
在我开始开发 Jiff 之前,这种困惑已经烦到让我考虑编写自己的 crate。我觉得 chrono 和 time 的 API 都有改进空间。我个人觉得这个领域相当有趣,因此着手构建一个更好的方案。
为什么不改进现有解决方案(比如 chrono 或 time),而是向生态系统中再添加一个选择?我确实认为选择过多有实质性缺点,但我得出结论:chrono 和 time(在 2024 年)都已达到局部最大值。此外,在 2024 年,我还不是日期时间处理方面的专家。正是通过构建一个日期时间库,我才成为专家。因此,说服 crate 维护者走向一个截然不同的方向将是一项艰巨的任务。
Jiff 的设计和比较文档包含了更多关于动机以及 Jiff、chrono 和 time 之间具体示例的细节。
## 灵感
Jiff 深受 Temporal 启发,后者是 JavaScript 用于日期和时间管理的标准库解决方案。Jiff 继承了 API 设计、功能,甚至日期时间值的解析/格式化。但请注意,Jiff 不是,也不打算成为 Temporal 规范的 100% 兼容实现。Jiff 首先且最重要的是一个 Rust 生态系统库。
一个面向 Rust 的日期时间库
话虽如此,如果你熟悉 Temporal 和 Rust,那么你很可能会发现,Jiff 相当直接地把 Temporal 的 API 转译成了 Rust。这个示例展示了如何使用 Temporal 相对于某个日期,把日历跨度舍入到最接近的天数:
const duration = Temporal.Duration.from({ months: 1, days: 1, hours: 1 }); const roundedDuration = duration.round({ largestUnit: "days", smallestUnit: "days", relativeTo: Temporal.PlainDateTime.from("2022-01-01"), }); console.log(roundedDuration); // "P32D"
下面是 Jiff 中的等效操作:
use jiff::{SpanRound, ToSpan, Unit};
fn main() -> anyhow::Result<()> { let span = 1.month().days(1).hours(1); let rounded_span = span.round( SpanRound::new() .largest(Unit::Day) .smallest(Unit::Day) .relative("2022-01-01".parse::<jiff::civil::Date>()?), )?; assert_eq!(rounded_span.to_string(), "P32D"); Ok(()) }
这些示例的主要区别在于,Jiff 的持续时间类型命名为 Span,而不是 Duration。这样做是为了避免与 Rust 标准库的 std::time::Duration 类型混淆。
以下是一些其他区别:
- Temporal 的 Instant 类型在 Jiff 中命名为 Timestamp,以避免与 Rust 标准库的 std::time::Instant 类型混淆。
- Temporal 的“plain”日期和时间类型在 Jiff 中称为“civil”。
- Jiff 仅支持格里高利历。
- Jiff 的日期时间范围仅扩展到 +/- 9999,而 Temporal 的范围更大。
可以说,如果没有 Temporal,Jiff 就不会以如今的形式存在。