Newshot

一个 Rust 的日期时间库

Translation(model translation, not the source's own text)
This piece is long: the translation covers roughly the first 38556 characters. Use the language link above for the other version.

一个面向 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 就不会以如今的形式存在。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Lobsters
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗