Hacker News Best

Jiff 1.0: A datetime library for Rust

8.5内容质量

TL;DR · AI 摘要

Jiff 1.0 是一个专为 Rust 设计的日期时间库,致力于简化时间处理并解决时区问题,已在多个项目中广泛应用。

核心要点

  • Jiff 1.0 已在多个 Rust 项目中使用,包括 Cargo 和 Starship。
  • Jiff 通过将时区处理置于 API 的核心,简化了时间处理的复杂性。
  • Jiff 的设计目标是成为 Rust 生态系统中的基础构建模块。

结构提纲

按章节快速跳转。

  1. §The Jiff 1.0 Commitment

    Jiff 1.0 已经在多个项目中使用,并承诺长期维护其 API。

  2. Jiff 的核心功能是将系统时间与人类时间概念进行转换。

  3. 读者可以通过创建 Cargo 项目并添加 Jiff 依赖来跟随示例。

  4. Jiff 提供了多种解析和格式化时间的方法,包括 strptime 和 strftime。

  5. Jiff 支持多种日期操作,包括日期计算和日历转换。

  6. Jiff 的目标是成为 Rust 生态系统中的基础构建模块。

思维导图

用一张图看清主题之间的关系。

查看大纲文本(无障碍 / 无 JS 友好)
  • Jiff 1.0
    • 核心功能
      • 时间处理
      • 时区处理
    • 应用
      • Cargo
      • Starship
      • AWS LLRT
    • 目标
      • 成为 Rust 生态系统中的基础构建模块

金句 / Highlights

值得收藏与分享的关键句。

  • Jiff is already used in production in many projects: uv, Cargo, Starship, fd, Nushell, mise, Jujutsu, uutils/coreutils and even as the basis for a Temporal implementation in AWS LLRT.

    — The Jiff 1.0 Commitment

    ⬇︎ 下载 PNG𝕏 分享到 X
  • Jiff instead tries hard to encapsulate the complexity and make it difficult for users to do something wrong.

    — Introduction

    ⬇︎ 下载 PNG𝕏 分享到 X
  • Unless some significant defect is found in Jiff’s API, my plan is to commit to Jiff 1.0 indefinitely.

    — The Jiff 1.0 Commitment

    ⬇︎ 下载 PNG𝕏 分享到 X
#Rust#datetime#Jiff#时间处理
打开原文

一个用于 Rust 的日期时间库 - Andrew Gallant 的博客

Jiff 是一个用于 Rust 的日期时间库,它鼓励你直接进入成功之坑。Jiff 通过将时区处理置于 API 的核心位置,自动处理与夏令时相关的许多常见问题。Jiff 已经在 Rust 生态系统中得到了广泛应用。

Jiff 的发音类似于“gif”,但“g”是柔和的,就像“gem”中的“g”一样。

这篇博客通过介绍其 API 来宣布 Jiff 1.0 的发布。

目标读者:需要方便日期时间处理的 Rust 程序员。

目录

  • Jiff 1.0 的承诺
  • 介绍 术语 日期时间洋葱 定义时区 持续时间 我应该在什么时候使用 Jiff?
  • 解析和格式化 FromStr 和 Display “友好”的持续时间格式 strptime 和 strftime jiff::fmt 模块 通过 ICU4X 集成实现本地化格式化
  • 日期操作 日期基础 日期算术 日期舍入 其他历法 我应该使用哪种日期时间类型?
  • 时间段操作
  • 结论 动机 灵感

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 成为一个有吸引力的公共依赖项,这意味着与语义版本不兼容的发布可能会对生态系统造成重大影响。这些发布将不会轻易进行。

要查看 Jiff 0.2 和 Jiff 1.0 之间的重大更改列表,请查阅 CHANGELOG。

介绍

在编程中,日期时间库的核心功能位于计算机系统的时间概念和人类的时间概念的交汇点。系统时间的主流概念是 Unix 时间。人类的时间概念要复杂得多,但最受欢迎的模型是格里高利历配合 12 小时或 24 小时的时钟。每个日期时间库的核心都有一些例程,用于在这些概念之间进行转换。

一个日期时间库通常提供的不仅仅是这些。事实上,日期时间处理历来非常困难。我自己的看法是,这种困难来自于对领域建模的不足。而不是将复杂性封装在可重用的代码包中,许多日期时间库将部分或全部复杂性传递给用户。Jiff 则努力封装复杂性,使用户难以出错。(Jiff 并不是第一个这样做的人!)

在本博客的这一部分,我们将做一些非常基础的介绍。

跟随示例

要跟随本博客中的示例,请创建一个依赖于 jiff 和 anyhow 的新 Cargo 项目:

code
mkdir jiff-playground
cd jiff-playground
cargo init --bin
cargo add jiff anyhow
$EDITOR src/main.rs

大多数示例都是完整的自包含 Rust 程序。只需复制代码并替换 src/main.rs 中的内容。然后运行程序:

code
cargo run

术语

我不太愿意提供一个字典。然而,datetime 领域中充满了容易混淆的术语,因此我认为明确我们共同的词汇非常重要。我已尽可能将本节保持得简短。一些术语(如“时区”)在此省略,因为它们最好通过后续章节的探索来定义。

  • 民用时间(Civil time):你手表上显示的时间。一般来说,也是你所在大致地理区域的人们所看到的时间。换句话说,民用时间是人类在特定地理区域协调沟通时间的一种协议。民用时间也被称为:本地时间、普通时间、简单时间、钟表时间等。
  • UTC:协调世界时(Coordinated Universal Time)的缩写;它是一种时间标准,是全球民用时间的基础。它最初旨在大致对应于平均太阳时。
  • TAI:国际原子时(International Atomic Time)的缩写;它是一种由原子钟测量的时间标准。它与平均太阳时没有直接联系。
  • 闰秒(Leap second):对 TAI 的调整,使其更接近平均太阳时,从而形成 UTC 的基础。
  • Unix 时间:忽略闰秒的 UTC。

TAI 和闰秒不会是本文的重点,但它们在此列出是为了说明 Unix 时间与 UTC 之间的区别。

日期时间洋葱

为了过渡到 Jiff 的一些核心类型,我开始将它的日期时间类型比作洋葱。按相反的顺序,我们可以从最底层逐步构建到 ZonedDateTime。因此,让我们继续介绍一些术语,这些术语同时也是 Jiff 中的类型:

  • civil::Date 是一个普通的格里高利日期,不与任何特定的位置相关联。
  • civil::Time 是一个精确到纳秒的钟表时间,不与任何特定位置相关联。
  • civil::DateTime 将 civil::Date 和 civil::Time 结合,提供一个格里高利日期和一个钟表时间。它也不与任何特定位置相关联。
  • Timestamp 是一个无论地理位置如何,都明确表示特定时间点的值,表示为自 Unix 纪元以来的纳秒数。
  • TimeZone 是一组规则,用于在特定地理区域中将 Timestamp 映射到 civil::DateTime,反之亦然。
  • ZonedDateTime 将 Timestamp、civil::DateTime 和 TimeZone 结合,表示特定地理区域中的特定时间点。

为了更具体地说明这一点,我们可以在代码中看到它的样子。由于时区可以从民用日期时间映射到时间点,因此创建一个带时区的日期时间只需要一个民用日期时间和一个时区:

code
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
(())
}

创建一个带时区的日期时间的另一种方法只需要一个时间戳和一个时区。这是因为时区也可以将时间戳映射到特定的民用日期时间:

code
use
jiff
::
{
civil
,
Timestamp
};
fn
main
()
->
anyhow
::
Result
<
()
>
{
let
timestamp
=
Timestamp
::
from_second
(
1793572200
)
?
;
let
zdt
=
timestamp
.
in_tz
(
"America/New_York"
)
?
;
// 这是创建一个民用日期时间的快捷方式。
// 前一个示例为了清晰度,用更冗长的方式表达。
let
expected
=
civil
::
date
(
2026
,
11
,
1
).
at
(
17
,
30
,
0
,
0
);
assert_eq!
(
zdt
.
datetime
(),
expected
);
Ok
(())
}

请注意,我们在这两种情况下都得到了等效的带时区的日期时间,但我们的出发点不同。第一种情况,我们从可能在我们的时钟和日历上看到的时间开始。第二种情况,我们从可能从数据库、文件系统或其他系统调用中获得的特定时间点开始。

定义时区

在带时区的日期时间洋葱示例中,还缺少一个部分:时区偏移量。偏移量表示为了获得民用时间,必须调整UTC时间的量。例如,考虑UTC时间2026-11-01T22:30:00。为了获得纽约居民的民用时间,需要减去5小时:

code
2026-11-01T22:30:00 - 05:00 = 2026-11-01T17:30:00

确实,每个带时区的日期时间都与一个偏移量相关联:

code
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。

当民用日期时间与偏移量结合时,你得到的总是时间的一个瞬间。

引入了偏移量的概念后,我们现在可以给出时区的更精确定义。时区是一个地理区域,其中民用时钟一致,并提供以下映射:

  • 从一个时间点到UTC的偏移量。应用偏移量到一个时间点会得到一个民用日期时间。
  • 从一个民用日期时间到UTC的可能有歧义的偏移量。应用偏移量到一个民用日期时间会得到一个时间点。

这两个映射在之前的示例中已经展示过,但从民用日期时间到偏移量的映射似乎由于一些潜在的歧义而变得复杂。这种歧义何时出现?当民用日期时间要么不对应于这个时区的有效时钟时间(例如,当为夏令时调整时钟向前移动时),或者可能存在多个有效时钟时间(例如,当为夏令时调整时钟向后移动时),就会出现歧义的偏移量。

让我们看一些示例。在第一个示例中,我们将查看纽约从夏令时过渡到标准时间时的周围时间。在纽约,时钟在凌晨2点正好被“调回”一小时。这导致1点的小时重复了一次。

code
use
jiff
::
{
civil
::
date
,
tz
::
{
offset
,
TimeZone
},
};
fn
main
()
->
anyhow
::
Result
<
()
>
{
let
tz
=
TimeZone
::
get
(
"America/New_York"
)
?
;
// 在夏令时期间,纽约与UTC的时区偏移为-04:00。
let
zdt
=
date
(
2026
,
11
,
1
).
at
(
0
,
30
,
0
,
0
).
to_zoned_datetime
(
tz
.
clone
())
?
;
assert_eq!
(
zdt
.
offset
(),
offset
(
-
4
));
// 在标准时间期间,纽约与UTC的时区偏移为-05:00。
let
zdt
=
date
(
2026
,
11
,
1
).
at
(
2
,
30
,
0
,
0
).
to_zoned_datetime
(
tz
.
clone
())
?
;
assert_eq!
(
zdt
.
offset
(),
offset
(
-
5
));
// 但是01:30AM是什么意思?是第一次重复还是第二次?
// Jiff默认会自动选择第一次。
let
zdt
=
date
(
2026
,
11
,
1
).
at
(
1
,
30
,
0
,
0
).
to_zoned_datetime
(
tz
.
clone
())
?
;
assert_eq!
(
zdt
.
offset
(),
offset
(
-
4
));
Ok
(())
}

上面的例子展示了Jiff在发生“fold”(即时间转换时将民用时间向后调整)时如何解决歧义。但实际上,我们还可以深入到更底层的API中,以改变这种歧义的解决方式。默认情况下,Jiff使用一种“兼容”策略,总是选择“fold”中时间的第一次重复。但是,也可以通过直接在TimeZone上使用API来选择其他策略:

code
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”,这与默认的“兼容”策略相同。
let
zdt
=
tz
.
to_ambiguous_zoned_datetime
(
dt
).
earlier
()
?
;
assert_eq!
(
zdt
.
offset
(),
offset
(
-
4
));
// 总是选择较晚的时间。
// 对于“fold”,这会选择1AM小时的第二次出现!
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点:

code
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 作为时间间隔类型。以下是一个简单的示例,展示了如何获取两个日历日期之间的天数:

code
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
(())
}

时间间隔也可以添加到日期上:

code
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:

code
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 来完成相同的操作,因为它结合了所有单位:

code
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,就尽量使用它。但当它过于笨重或运行速度太慢时,可以改用 SignedDuration。Span 的一个关键优势在于,因为它将每个单位的值表示得非常明确,因此可以保留持续时间的原始含义。例如,即使持续时间超过一小时,通常也会用分钟来表示电影的播放时长。事实上,2 小时的跨度与 120 分钟的跨度是两个不同的跨度:

code
use
jiff
::
ToSpan
;
fn
main
()
->
anyhow
::
Result
<
()
>
{
let
span1
=
2.
hours
();
let
span2
=
120.
minutes
();
// 这意味着这些跨度在内存中是不同的值。
assert_ne!
(
span1
.
fieldwise
(),
span2
.
fieldwise
());
Ok
(())
}

Span::fieldwise 方法会将 Span 转换为一个值,该值的单位可以按字段逐一比较。若要根据跨度所代表的实际物理持续时间进行比较,可以使用 Span::compare:

code
let
span1
=
2.
hours
();
let
span2
=
120.
minutes
();
assert!
(
span1
.
compare
(
span2
)
?
.
is_eq
());

这只是一个关于 Jiff 中持续时间的简要介绍。它们的功能远不止于此。你甚至可以尝试玩一玩上面的示例,来探索它的各种细节。我们将在后面的部分中更详细地介绍它们的 API。

我应该在什么情况下使用 Jiff?

Jiff 并不总是最佳选择。有时,使用更简单的方案就足够了。

首先,如果你在程序中测量某个操作所花费的时间,那么你几乎肯定应该使用单调时间。这可以通过 std::time::Instant 实现:

code
use
std
::
time
::
{
Duration
,
Instant
};
fn
main
()
->
anyhow
::
Result
<
()
>
{
let
start
=
Instant
::
now
();
// 执行一些繁重的工作
std
::
thread
::
sleep
(
Duration
::
from_secs
(
1
));
let
elapsed
=
Instant
::
now
().
duration_since
(
start
);
println!
(
"
{elapsed:?}
"
);
Ok
(())
}

如果你确实需要使用系统时钟来计算经过的时间,那么 Jiff 非常适合这种情况:

code
use
std
::
time
::
Duration
;
use
jiff
::
Timestamp
;
fn
main
()
->
anyhow
::
Result
<
()
>
{
// 假设 `start` 是从网络上的某个地方获取的
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 完全可以:

code
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
(())
}

Jiff 开始变得有用的地方,是你需要的不仅仅是自 Unix 纪元以来的整数秒数。例如,要将 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 特性。这意味着解析日期时间是自然的:

code
let
ts
:
Timestamp
=
"2026-10-31T05:15:00Z"
.
parse
()
?
;

并打印它们:

code
println!
(
"
{ts}
"
);

解析是灵活的,即使缺少某些组件,解析仍然可以成功。例如,没有分钟或秒时,这些组件默认为零:

code
let
dt
:
civil
::
DateTime
=
"2026-10-31T05"
.
parse
()
?
;
assert_eq!
(
dt
.
to_string
(),
"2026-10-31T05:00:00"
);

另一个灵活解析的例子是,如果字符串包含另一种日期类型,那么可以解析该类型。例如,可以从 ISO 8601 日期时间中解析出一个日期:

code
let
d
:
civil
::
Date
=
"2026-10-31T05:30"
.
parse
()
?
;
assert_eq!
(
d
.
to_string
(),
"2026-10-31"
);

ZonedDateTime 始终使用 RFC 9557 语法,其中包括 IANA 时区标识符:

code
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 语法打印带时区的日期时间,可以通过使用带时区日期时间的偏移量直接格式化时间戳来实现:

code
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 特性。例如:

code
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 只能解析包含物理时间单位的持续时间:

code
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 秒:

code
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 持续时间格式更容易阅读。以下是一些有效友好持续时间的示例:

code
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 持续时间和友好持续时间:

code
let
span
:
Span
=
"6y 10mo 3d 23h"
.
parse
()
?
;
// 回忆一下,`Span::fieldwise` 允许
// 在单位对单位的基础上对 `Span` 进行
// 等于比较。
assert_eq!
(
span
.
fieldwise
(),
6.
years
().
months
(
10
).
days
(
3
).
hours
(
23
));

打印一个友好的持续时间需要多做一些工作,因为它不是默认行为。除了使用 Span::to_string(),还可以通过 Rust 的格式化机制使用“替代”语法:

code
let
span
=
2000.
milliseconds
();
// 这也展示了我们的单位
// 值被保留下来。
assert_eq!
(
format!
(
"
{span:#}
"
),
"2000ms"
);

还可以使用更底层的友好打印器来自定义输出。例如,以下是如何使用更多间距、更长的单位标签和逗号分隔每个单位,将一个持续时间以友好格式写入现有 String 中:

code
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 提供了与这些函数基本兼容的实现。

Jiff 中的每个日期时间类型都带有 strptime 和 strftime 函数。例如,要解析美国月份/日期/年份格式的民用日期:

code
let
date
=
civil
::
Date
::
strptime
(
"%m/%d/%Y"
,
"11/13/2026"
)
?
;
assert_eq!
(
date
.
to_string
(),
"2026-11-13"
);

或者,要以对英语使用者更易读的方式格式化一个带时区的日期时间:

code
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,以单独访问每个解析后的组件:

code
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 验证检查):

code
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
(())
}

另一个示例展示了如何在提供的民用日期时间存在歧义时更改默认的歧义解决策略。例如,2026年4月5日03:00:00(澳大利亚悉尼当地时间),时钟被调慢了。也就是说,时区从UTC偏移+11变为UTC偏移+10。那么如果我们尝试解析时钟上重复时间的日期时间,会发生什么呢?

code
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出现的时间,就在悉尼结束夏令时期之前。现在,数据本身实际上可以选择所需的偏移量:

code
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年4月5日02:30[Australia/Sydney],它存在歧义,因为它可能指的是两个不同的时间瞬间。我们如何修改解决这种歧义的策略呢?我们不能使用标准库的FromStr trait,因此我们必须手动构建自己的解析器,就像我们上面对RFC 2822解析所做的那样。这个示例展示了如何做到这一点,并展示了所有不同的歧义解决选项。请记住,UTC偏移+11:00对应于悉尼居民时钟上2026年4月5日02:30的第一个出现,而UTC偏移+10:00对应于第二个出现。

code
use
jiff
::
{
fmt
::
temporal
::
DateTimeParser
,
tz
::
Disambiguation
};
fn
main
()
->
anyhow
::
Result
<
()
>
{
let
string
=
"2026-04-05T02:30[Australia/Sydney]"
;
// "compatible" 是默认策略,它在重叠(通常是从夏令时转为标准时间)中选择较早的时间,
// 在间隔(通常是从标准时间转为夏令时)中选择较晚的时间。
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" 总是选择重叠中的第一个出现时间,或间隔前的时间。
// 所以在这种情况下,这与 "compatible" 相同,
// 因为我们的时间处于重叠中。
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" 总是选择重叠中的第二个出现时间,或间隔后的时间。
// 所以这与 "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 模块包含许多其他有用的工具,这里我们不一一介绍,包括但不限于:

  • 直接格式化到现有分配中的能力。
  • 将日期时间解析为其各个组成部分。
  • 用于与 serde 集成的辅助工具。

通过 ICU4X 集成实现本地化敏感格式化

任何关于日期时间格式化的部分都不可能不涉及本地化。在此上下文中,本地化是一组用户偏好设置,用于格式化日期时间。当你希望向最终用户展示一个日期时间,而用户并不期望使用 RFC 3339、RFC 9557 或 ISO 8601 的标准格式时,这非常有用。

Jiff 本身不提供任何处理本地化的功能。相反,用户可以通过 ICU4X 项目选择启用此支持。为了在 Jiff 和 ICU4X 之间进行转换,可以使用 jiff-icu 集成 crate。

以下是一个示例,展示如何在 fr-LA 本地化中格式化带时区的日期时间:(要使此示例正常工作,你需要在项目中运行 cargo add icu jiff-icu。)

code
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 的时区日期时间转换为 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 语言环境创建一个日期时间格式器:
let
formatter
=
DateTimeFormatter
::
try_new
(
locale!
(
"fr-LA"
).
into
(),
fieldsets
::
YMDET
::
medium
().
with_zone
(
fieldsets
::
zone
::
SpecificLong
),
)
?
;
// 第三,格式化时区日期时间。
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 提供了多种方法用于其日期时间类型,以尽可能使其使用过程舒适且无错误。

日期基础

每个日期时间类型都提供了一个新的构造函数,允许调用者从其组成部分构建它。在大多数情况下,这个构造函数是可能失败的。例如:

code
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
(),
"parameter 'day' for `2025-02` is invalid, must be in range `1..=28`"
,
);
Ok
(())
}

由于创建日期非常常见,当您知道输入是有效时,还有一种简写方式可以这样做:

code
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() 构造函数用于获取当前时间:

code
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 从旧的日期值构建新的日期值:

code
let
d1
=
const
{
civil
::
date
(
2024
,
2
,
29
)
};
// 这个 API 不会因为提供了 31
// 在一个只有 31 天的月份之前而中断。任何顺序都可以!这是因为
// 错误会延迟到调用 `build()` 时才发生。
let
d2
=
d1
.
with
().
day
(
31
).
month
(
3
).
build
()
?
;
assert_eq!
(
d2
.
to_string
(),
"2024-03-31"
);

一旦你有了一个日期,就有大量可用的 API:

code
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 的洋葱结构,所有这些 API 在 civil::DateTime 和 ZonedDateTime 上也都可以使用:

code
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 小时:

code
// 在 2024-11-03 凌晨 2 点,纽约时间在从夏令时转换为标准时间时
// 向后调整了 1 小时。这意味着 2024-11-03 在纽约实际上有 25 小时。
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
));
// 它们之间的物理时间差是 25 小时!
let
span
=
tomorrow
-
zdt
;
assert_eq!
(
format!
(
"
{span:#}
"
),
"25h"
);

注意:我们将在下一节中讨论日期算术。

当 ZonedDateTime::tomorrow()(以及其他生成 ZonedDateTime 的 API)落在间隙或重叠区域时,会自动选择“兼容”的歧义解决策略:

code
// 对于落在重叠区域的时区日期时间,默认选择较早的时刻。
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]"
);

要覆盖这种行为,你可以降级到 civil 日期时间,执行操作,然后使用 TimeZone::to_ambiguous_zoned_datetime 来控制确切的歧义解决策略:

code
// 对于落在重叠时间的带时区的日期时间,默认选择较早的时刻。但假设我们想要较晚的时刻。
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 来回答:

code
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 来回答:

code
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 方法访问一个方便的时间序列迭代器:

code
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 开始:

code
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 而不是这种方法:

code
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
(())
}

让我们再来看一些涉及月份和年份的其他示例:

code
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 上也可以使用:

code
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 的类型签名,可以看到它实际上是多态的:

code
pub
fn
checked_add
<
A
:
Into
<
ZonedDateTimeArithmetic
>>
(
&
self
,
duration
:
A
,
)
->
Result
<
ZonedDateTime
,
Error
>

具体来说,它接受任何可以转换为 ZonedDateTimeArithmetic 的类型。在这种情况下,以下类型有 From trait 的实现:

  • Span
  • SignedDuration
  • std::time::Duration

这意味着 ZonedDateTime::checked_add 可以接受这些持续时间值中的任意一种:

code
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 中很常见。在这里,它只是用来提供一种方便的方式来使用多种持续时间类型。但正如我们所看到的,它还用于提供一个扩展点,用于控制操作如何工作的配置选项。

除了从日期时间值中添加或减去持续时间之外,还可以计算两个日期时间值之间的持续时间。例如,获取两个日期之间的天数:

code
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 来计算日期之间的跨度:

code
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 上也可以使用:

code
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 是多态的:

code
pub
fn
until
<
'a
,
A
:
Into
<
ZonedDateTimeDifference
<
'a
>>>
(
&
self
,
other
:
A
,
)
->
Result
<
Span
,
Error
>

也就是说,调用者在这里不仅限于传递 ZonedDateTime,还可以传递任何可以转换为 ZonedDateTimeDifference 的内容。以下是一个示例,其中我们可以在返回的持续时间中覆盖最大的单位:

code
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 提供了更强大的配置选项,用于对返回的跨度进行四舍五入。以下是一个示例,它生成一个包含许多单位值的跨度:

code
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
(())
}

这可能对最终用户来说过于精确。相反,也许我们希望将跨度四舍五入到最近的半小时。我们可以通过显式构建 ZonedDateTimeDifference 并配置其选项来实现这一点:

code
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
(())
}

还要注意,对跨度进行四舍五入时会考虑时区转换,例如夏令时。例如,让我们取 2024-11-02 17:30 和 2024-11-03 04:45 在纽约的时间。由于纽约在 2024-11-03 凌晨 2 点停止了夏令时,它们之间的实际时间是 12 小时 15 分钟:

code
let
zdt1
=
date
(
2024
,
11
,
2
).
at
(
17
,
30
,
0
,
0
).
in_tz
(
"America/New_York"
)
?
;
let
zdt2
=
date
(
2024
,
11
,
3
).
at
(
4
,
45
,
0
,
0
).
in_tz
(
"America/New_York"
)
?
;
assert_eq!
(
zdt2
-
zdt1
,
12.
hours
().
minutes
(
15
).
fieldwise
());

通常,如果我们按天数四舍五入,这会向上舍入为 1 天。但由于这一天的中点实际上是 12 小时 30 分钟,当我们请求时,这个持续时间会向下舍入为 0 天:

code
use
jiff
::
{
civil
::
date
,
RoundMode
,
ToSpan
,
Unit
,
ZonedDateTimeDifference
};
fn
main
()
->
anyhow
::
Result
<
()
>
{
let
zdt1
=
date
(
2024
,
11
,
2
).
at
(
17
,
30
,
0
,
0
).
in_tz
(
"America/New_York"
)
?
;
let
zdt2
=
date
(
2024
,
11
,
3
).
at
(
4
,
45
,
0
,
0
).
in_tz
(
"America/New_York"
)
?
;
let
difference
=
ZonedDateTimeDifference
::
new
(
&
zdt2
)
.
largest
(
Unit
::
Day
)
.
smallest
(
Unit
::
Day
)
.
mode
(
RoundMode
::
HalfExpand
);
assert_eq!
(
zdt1
.
until
(
difference
)
?
,
0.
days
().
fieldwise
());
Ok
(())
}

接下来,我们将继续讨论四舍五入,但这次是应用于日期时间本身。

日期四舍五入

在 Jiff 中,日期四舍五入仅限于天数或更小的单位。因此,它仅适用于 ZonedDateTime、Timestamp、civil::DateTime、civil::Time,但不适用于 civil::Date。

一个常见的日期时间四舍五入的例子是减少精度。例如,系统时钟可能提供纳秒精度,但也许我们只关心最近的半小时:

code
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 的四舍五入也了解时区转换:

code
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,因为在纽约从夏令时过渡到标准时间时,1:00 AM 的小时重复了,到 11:30 AM 时,已经过去了 12.5 小时。

其他日历

Jiff 本身不支持任何其他日历,除了扩展的格里高利日历。可以使用 ICU4X crate 来处理非格里高利日历,并使用 jiff-icu crate 在日期时间类型之间进行转换:(使用 cargo add icu jiff-icu 使这个示例正常工作。)

code
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 支持更多日历。

我应该使用哪种日期时间类型?

在 Jiff 中,有三种可能让人混淆的日期时间类型:

  • civil::DateTime
  • Timestamp
  • ZonedDateTime

在什么情况下应该使用其中的某一种而不是其他?

大致来说,如果你可以使用 ZonedDateTime,那么这可能是你想要使用的类型。它表示特定地理区域中的一个具体时间点。也就是说,它同时具有 Timestamp 和 TimeZone。

如果你只需要在 UTC 或者仅仅处理系统时间,那么 Timestamp 可能是更合适的选择。这对于表示与任何时区无关的具体时间点很有用。

civil::DateTime 在那些不关心具体时间点、并且计算应与时区无关的上下文中很有用。例如,当从用户界面的日期时间选择器中解析日期时间信息时。

请记住,civil::DateTime 和 Timestamp 都可以通过提供时区信息转换为 ZonedDateTime。

时间跨度操作

我们已经看到了如何将时间跨度添加到日期时间值中,以及如何通过日期时间值之间的差异获取时间跨度。但到目前为止,我们还没有探索 Span 本身提供的 API。

首先,我们可以通过其构造函数创建一个 Span,该构造函数返回一个所有单位都设置为 0 的 Span:

rust
use jiff::Span;
let span = Span::new();

Span 既是 Copy 也是不可变的。我们可以通过方法链来创建新的 Span:

rust
let span = Span::new().hours(1).minutes(30);
assert_eq!(span.to_string(), "PT1H30M");

或者,我们可以使用 ToSpan 便捷 trait,它为整数类型添加了用于构建时间跨度的方法:

rust
use jiff::ToSpan;
let span = 1.hour().minutes(30);
assert_eq!(span.to_string(), "PT1H30M");

不过请注意,像 Span::hours 和 ToSpan::hours 这样的方法在整数超出 Span 支持的范围时会引发 panic。这在你的程序中使用字面量时间跨度时是没问题的,因为 panic 表示程序中的错误。但如果你的输入来自最终用户,最好使用可失败的方法:

rust
let span = Span::new().try_hours(1)?.try_minutes(30)?;
assert_eq!(span.to_string(), "PT1H30M");

时间跨度保留每个单独的单位值。这意味着 90 分钟和 1 小时 30 分钟,尽管它们表示相同的持续时间,但在内存中实际上是不同的值:

rust
let span1 = 1.hour().minutes(30);
let span2 = 90.minutes();
assert_eq!(span1.to_string(), "PT1H30M");
assert_eq!(span2.to_string(), "PT90M");

这使得调用者在表示持续时间时具有最大的灵活性。这使得即使它们加起来等于更大的单位,也可以用特定单位表示持续时间。例如,电影的运行时间通常以分钟表示,即使运行时间超过一小时。这可以通过使用 Span::round 来编程调整:

rust
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(())
}

你也可以反向操作:

rust
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 并没有真正执行四舍五入,尽管它的名称如此。实际上,由于我们只设置了最大的单位,这个 API 正在执行单位平衡。单位平衡是指所有单位值向上滚动到更大的单位,直到达到配置的最大单位。即使对于日历单位也是如此,但你需要提供一个相对日期:

rust
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
(())
}

如果没有相对日期,就无法知道一个月中有多少小时。也就是说,一旦涉及日历单位,除非应用了上下文,否则一个时间跨度无法被解释为一个物理时间长度。

即使是天数本身也是如此,因为一天有时可能超过或少于 24 小时。以上面的示例为例。如果我们使用一个带时区的日期时间作为相对日期,会发生什么呢?

rust
use
jiff
::
{
civil
,
SpanRound
,
ToSpan
,
Unit
};
fn
main
()
->
anyhow
::
Result
<
()
>
{
let
span
=
2756.
hours
();
let
zdt
=
civil
::
date
(
2020
,
1
,
1
).
at
(
0
,
0
,
0
,
0
).
in_tz
(
"Europe/Rome"
)
?
;
let
round
=
SpanRound
::
new
().
largest
(
Unit
::
Year
).
relative
(
&
zdt
);
assert_eq!
(
span
.
round
(
round
)
?
.
to_friendly
(),
"3mo 23d 21h"
);
Ok
(())
}

请注意,时间跨度的小时部分从 20 变成了 21。为什么?因为我们两种情况都从 2756 小时开始,而 2020 年 3 月 29 日在罗马只有 23 小时(从标准时间转换为夏令时)。这意味着在 3mo 23d 中的某一天只有 23 小时。因此,需要额外加一小时来弥补。

round API 还可以执行真正的四舍五入:

rust
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”(类似于你在学校学到的四舍五入方式)更改为截断(或其它几种模式之一):

rust
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
(())
}

你还可以指定一个四舍五入增量,以四舍五入到最近的单位值。例如,四舍五入到最近的半小时:

rust
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:

此外,你还可以将 Span 转换为任何单位的浮点数值。例如:

rust
use
jiff
::
{
ToSpan
,
Unit
};
fn
main
()
->
anyhow
::
Result
<
()
>
{
let
span
=
90.
minutes
();
assert_eq!
(
span
.
total
(
Unit
::
Hour
)
?
,
1.5
);
Ok
(())
}

转换为日历单位需要一个相对日期,原因与上面讨论的一样:

code
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 的启发极大,Temporal 是 JavaScript 标准库中用于日期和时间管理的解决方案。Jiff 继承了 API 设计、功能,甚至日期时间值的解析和格式化。但请注意,Jiff 并不是,也不旨在成为 Temporal 规范的 100% 兼容实现。Jiff 首要目标是作为 Rust 生态系统中的一个库。

话虽如此,如果你熟悉 Temporal 和 Rust,那么你很可能会发现 Jiff 是 Temporal API 在 Rust 中的一个相对直接的翻译。这个示例展示了如何使用 Temporal 将日历跨度四舍五入到相对于某个日期的最近天数:

code
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 中的等效操作:

code
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 类型混淆。

还有一些其他区别:

  • 为了与 Rust 标准库 std::time::Instant 类型区分开来,Jiff 中将 Temporal 的 Instant 类型命名为 Timestamp。
  • Temporal 的“普通”日期和时间类型在 Jiff 中被称为“civil”。
  • Jiff 仅支持格里高利历。
  • Jiff 的日期时间范围仅扩展到 ±9999,而 Temporal 的范围更大。

可以说,如果没有 Temporal,Jiff 不可能以今天的形式存在。