
2026/11/17 1:53
Jiff 1.0:Rust の日付時刻ライブラリ
RSS: https://news.ycombinator.com/rss
要約▶
Japanese Translation:
Jiff 1.0 は、日付変更線(DST)の堅牢なルールと複雑なタイムゾーン操作を処理するために設計された、エコシステム後援の安定した Rust ライブラリを導入します。これは JavaScript の Temporal に着想を得ていますが、Rust の標準ライブラリとの命名衝突を回避するため(例えば
Instant ではなく Timestamp を使用するなど)、独自のアプローチで設計されています。多くの代替案とは異なり、このメジャーバージョンに対する永続的な安定性を保証しており、開発者は日付算術の正確性に信頼できると同時に、予期せぬ破壊的変更を恐れる必要がありません。ICU4X プロジェクトを jiff-icu クレートを通じて活用することで、非グレゴリオ calendars とローカルに依存するフォーマットをサポートし、グローバル向けアプリケーションにおいて高い柔軟性を発揮します。そのコアアーキテクチャには、Timestamp、Span、civil::Date、および ZonedDateTime といった明確なタイプが含まれており、これにより開発者は変化する日長を考慮した精密な計算を実行でき、遷移時の曖昧な時刻に対する特定の戦略を用いて物理時間とカレンダー単位の間を滑らかに変換することが可能になります。uv、Cargo、Starship、Nushell、および AWS LLRT などのツールで広く採用されている Jiff は、Rust の日付・時刻管理における信頼性の新たな基準を設定しており、解析、フォーマット、および期間算術の堅牢な処理を通じて、プログラミングにおいて最も持続的な課題の一つに対する包括的なソリューションを提供します。本文
Jiff 1.0 リリースと API ガイダンス:Rust 用日付時刻処理ライブラリ
Jiff は Rust 用の堅牢な日付時刻処理ライブラリです。本リリースでは、Jiff 1.0 の正式公開を宣言するとともに、その API の主要機能を紹介します。
対象読者: 便利で堅牢な日付時刻処理が必要な Rust プログラマーの方へ。
目次
Jiff 1.0 のコミットメント
Jiff はすでに uv、Cargo、Starship、fd、Nushell、mise、Jujutsu、uutils/coreutils など多数のプロジェクトで生産環境で使用されています。また、AWS LLRT における Temporal インプリメンテーションの基礎としても採用されています。
もし Jiff の API に重大な欠陥が特定される場合を除き、開発者は Jiff 1.0 を恒久化(安定版)することをコミットしています。これは、Jiff が公開依存関係として意図されており、semver 互換性の確保が生態系にとって重要だからです。
不具合変更リストについては CHANGELOG を参照してください。
導入
プログラミングにおいて、日付時刻処理ライブラリの核心は、コンピュータシステムによる時間概念(Unix タイムなど)と人間による時間概念(カレンダー、時差など)の交点にあります。多くのライブラリが複雑さをユーザーに委ねてきましたが、Jiff はそれらの複雑性をカプセル化し、ユーザーが間違うことを困難にするように設計されています。
追試する
本ブログの例を追うために、以下のコマンドで新しい Cargo プロジェクトを作成してください。
mkdir jiff-playground cd jiff-playground cargo init --bin cargo add jiff anyhow $EDITOR src/main.rs
コードを
src/main.rs にコピーし、以下を実行します:
cargo run
用語集
日付時刻ドメインには紛らわしい用語が多いため、以下の定義に合意しておくことが重要です。
- Civil Time(民事時間): あなたがお使いの時計から見る時刻。特定の地理的領域での人間の協調合意です。(ローカル時刻、素の時刻とも呼ばれます)
- UTC (Coordinated Universal Time): 世界中の民事時間の基礎となる時間標準です。
- TAI (International Atomic Time): 原子時計によって測定される時間標準です(平均陽子時間とは直接連結されていません)。
- Leap Second(閏秒): TAI を平均陽子時間に近づけるための調整であり、UTC の基礎を形成します。
- Unix Time: UTC ですが、閏秒は無視しています。
注: 本記事では TAI と閏秒の詳細機能には言及しませんが、Unix タイムと UTC の違いを理解するために記載しました。
日付時刻の玉ねぎ (The DateTime Onion)
Jiff のコアタイプは「玉ねぎ」のように層を重ねることで理解できます。以下の階層構造があります:
civil::Date- 特定の場所とは無関係な素のグレゴリオ日付です。
civil::Time- 特定の場所とは無関係でナノ秒精度を持つ素のクロック上の時間です。
civil::DateTime
とcivil::Date
を組み合わせたものです(特定の場所とは無関係)。civil::Time
Timestamp- 地理的位置に関係なく曖昧性のない特定の時点を表します。Unix エポクからのナノ秒数で表現されます。
TimeZone
をTimestamp
にマッピングするためのルールセットです(IANA Time Zone Database Identifier を使用)。civil::DateTime
ZonedDateTime
、Timestamp
、そしてcivil::DateTime
を組み合わせたもので、特定の地理的位置における特定の時点を表します。TimeZone
コードでの使い分け
Zoned DateTime を作成するには、以下の 2 つのアプローチがあります。
1. 時計やカレンダーの時間を起点にする場合
まず民事 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 は "ZonedDateTime" の略です。 let zdt = datetime.in_tz("America/New_York")?; assert_eq!(zdt.timestamp().as_second(), 1793572200); Ok(()) }
2. データベースやシステムコールの特定の時点を起点にする場合
まず Timestamp を作成し、時区を適用します(逆マッピングされます)。
use jiff::{civil, Timestamp}; fn main() -> anyhow::Result<()> { let timestamp = Timestamp::from_second(1793572200)?; let zdt = timestamp.in_tz("America/New_York")?; // 期待される civil DateTime let expected = civil::date(2026, 11, 1).at(17, 30, 0, 0); assert_eq!(zdt.datetime(), expected); Ok(()) }
時区の定義と曖昧性
Zoned DateTime は オフセット(UTC から民事時刻への調整量)を持っています。例えば、ニューヨークは UTC-5 です。
時区には「Fold(重複時間)」と「Gap(欠落時間)」の 2 つの遷移が存在します。Jiff はこれらにどう対処するかを理解する必要があります。
Fold (重複時間) の例
サマータイム移行で時計を速く動かす場合(例:2:00 → 1:00)。この時刻は 1 回だけ存在しませんが、2 回存在するようになります。
use jiff::{civil::date, tz::TimeZone}; fn main() -> anyhow::Result<()> { let tz = TimeZone::get("America/New_York")?; // サマータイム: UTC-4 let zdt = date(2026, 11, 1).at(0, 30, 0, 0).to_zoned_datetime(tz.clone())?; assert_eq!(zdt.offset(), -(4 * 3600)); // 標準時間: UTC-5 let zdt = date(2026, 11, 1).at(2, 30, 0, 0).to_zoned_datetime(tz.clone())?; assert_eq!(zdt.offset(), -(5 * 3600)); // 曖昧な時刻 1:30 はどちらか? // Jiff デフォルト(Compatible)は「最初の繰り返し」を選択します。 let zdt = date(2026, 11, 1).at(1, 30, 0, 0).to_zoned_datetime(tz.clone())?; assert_eq!(zdt.offset(), -(4 * 3600)); // UTC-4(夏時間)を選択 Ok(()) }
デフォルトの「互換性のある」戦略以外に、
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); // Compatible: デフォルト、最初の繰り返しを選択 let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?; // Earlier: 常に早いもの(Fold なら Compatible と同じ) let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?; // Later: 常に遅いもの(Fold なら 2 つ目の発生を選択、UTC-5) let zdt = tz.to_ambiguous_zoned_datetime(dt).later()?; // Unambiguous: 曖昧性があればエラーを返す 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 (欠落時間) の例
サマータイム移行で時計を遅く動かす場合(例:1:00 → 3:00)。この時刻は存在しなくなります。
デフォルトの「互換性のある」戦略では、ギャップの場合には**後方の時刻(より遅いオフセットを持つ方)**を選択します。
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: ギャップの場合、後方の時刻を選択(UTC-4) let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?; assert_eq!(zdt.offset(), -(4 * 3600)); // Earlier: 常に早いものを選択(ギャップ前は UTC-5) let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?; assert_eq!(zdt.offset(), -(5 * 3600)); Ok(()) }
期間 (Durations)
Jiff は 2 つの期間タイプを提供します。
Span- カレンダー単位(年、月、日)と物理的時間単位(時、分、秒など)を両方組み合わせた強力なハイブリッド型。
- 推奨: 常に
を好ましい期間タイプとして使用してください。個々の単元の値を保持するため、意味的な正確さが保てます。Span
SignedDuration
の符号付きバージョン。96 ビット整数のナノ秒数に対応します。std::time::Duration- 物理的時間のみを表し、カレンダー単位は表現できません。
基本的な操作例
use jiff::{civil, ToSpan}; fn main() -> anyhow::Result<()> { // 日付間の差 let d1 = civil::date(2024, 2, 1); let d2 = civil::date(2024, 3, 1); let span = d2 - d1; // Span を取得 assert_eq!(span.get_days(), 29); // 日付に期間を追加(ToSpan ティレットを使用) let span = 29.days(); assert_eq!(d1.checked_add(span)?, civil::date(2024, 3, 1)); Ok(()) }
いつ Jiff を使うべきか?
Jiff は常に最適ではありません。以下の場合は標準ライブラリを使用することを検討してください。
- 単調増加時間(モノトニック時間)の測定:
を使用します。std::time::Instant - Unix エポクからの整数秒数だけで十分な場合:
が完璧に動作します。RFC 3339 変換などは不要です。std::time::SystemTime
Jiff は、RFC 3339 形式や複雑な日付操作が必要になった場合に役立ちます。
解析とフォーマット化
文字列からの変換(解析)および印刷(フォーマット)は Jiff の主要部分です。
FromStr と Display
Jiff のすべての日付時刻タイプは
FromStr と Display を実装しています。
- 柔軟な解析: 構成要素が欠けていても成功します(不足分はゼロとして扱われます)。
// "2026-10-31T05" -> 分と秒は 0 に補完されます let dt: civil::DateTime = "2026-10-31T05".parse()?; - ZonedDateTime の特殊ケース:
は常に RFC 9557 構文(時区指定子ZonedDateTime
)を使用します。[...]
「親しみやすい」期間形式
ISO 8601(例:
P11Y2M28DT5H30M)は読み取りにくいため、Jiff は独自の「親しみやすい」フォーマットを採用しています。
- 無損失で、英語話者にとって読みやすいです。
- 例:
,40d
,3 days, 4 hours, 59 minutes
など。2h30m
use jiff::{ToSpan}; // 親しみやすい形式を解析(ISO 8601 もサポート) let span: Span = "6y 10mo 3d 23h".parse()?; assert_eq!(span.fieldwise(), 6.years().months(10).days(3).hours(23)); // 印刷時はフォーマットフラグを使用します let span = 2000.milliseconds(); assert_eq!(format!("{span:#}"), "2000ms"); // "2000ms" と表示
strptime と strftime
Jiff は POSIX の
strptime と strftime をほぼ完全にサポートしています。
use jiff::{civil}; // 解析 (strptime) let date = civil::Date::strptime("%m/%d/%Y", "11/13/2026")?; // フォーマット (strftime) 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
モジュール
jiff::fmtより高度な制御(RFC 2822 解析、カスタム曖昧性解決など)が必要な場合は
jiff::fmt モジュールを使用します。
例:Temporal RFC 9557 の曖昧性戦略の指定 デフォルトの「互換性のある」戦略を変更して、特定の時刻(Fold/Gap)をどう解釈するかを制御できます。
use jiff::{fmt::temporal::DateTimeParser, tz::Disambiguation}; fn main() -> anyhow::Result<()> { let string = "2026-04-05T02:30[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..."); Ok(()) }
ICU4X インテグレーションによる言語設定に依存するフォーマット化
ローカル(Locale)を考慮したフォーマットには
jiff-icu クレイトが必要になります。
cargo add icu jiff-icu
use icu::locale::locale; use icu::datetime::{fieldsets, DateTimeFormatter}; use jiff_icu::ConvertFrom as _; fn main() -> anyhow::Result<()> { let zdt: ZonedDateTime = "2024-09-10T23:37:20-04[America/New_York]".parse()?; // ICU へ変換 let icu_zdt = icu::time::ZonedDateTime::<Iso, TimeZoneInfo<AtTime>>::convert_from(&zdt); // フォーマット作成 (fr-LA: French - Luxembourg) let formatter = DateTimeFormatter::try_new( locale!("fr-LA").into(), fieldsets::YMDET::medium().with_zone(fieldsets::zone::SpecificLong), )?; // 出力例: "mar. 10 sept. 2024, 23:37:20 heure d'été de l'est nord-américain" assert_eq!(formatter.format(&icu_zdt).to_string(), ...); Ok(()) }
日付操作
Jiff は DateTime タイプ上で豊富なメソッドを提供します。
日付の基礎
civil::Date など、すべての DateTime タイプは各構成要素(年、月、日)へのアクセサーを持ちます。無効な値を指定するとエラーになります。
- コンストラクター:
Date::new() - 簡易生成(パニック版):
(入力が無効ならパニック)const { civil::date(...) } - 現在時刻取得:
またはTimestamp::now()ZonedDateTime::now() - 既存値の変更:
Date::with().day(...).month(...).build()
日付算術
Jiff は期間の追加・減算をサポートします。
Span、SignedDuration、std::time::Duration のいずれかを受け入れます。
use jiff::{civil, ToSpan, SignedDuration}; fn main() -> anyhow::Result<()> { // 日付間の差(Span を取得) let d1 = civil::date(2024, 5, 31); let d2 = civil::date(2024, 9, 30); assert_eq!(d2 - d1, 122.days().fieldwise()); // 期間を付与(Safe Add) let d = civil::date(2025, 1, 31); let next_month = d.checked_add(1.month())?; assert_eq!(next_month, civil::date(2025, 2, 28)); Ok(()) }
ZonedDateTime 特有の注意点: 異なる時区の
ZonedDateTime を減算すると、結果は時間単位になります(日長は時区で異なるため)。より大きな単元(日など)を返すにはオプションを指定します。
日付丸め
Jiff の丸め機能は日の単位以下に限定されています。
など、特定の粒度へ丸めることができます。Unit::Minute- 時区移行への対応: サマータイム遷移時に丸めが発生しても正しく動作します(例:11:30 が分岐点になる場合など)。
他の暦
Jiff そのものはグレゴリオ暦のみサポートしていますが、ICU4X を介して他の暦(ヘブル暦など)を扱えます。
クレイトを使用し、DateTime 間の相互変換を行います。jiff-icu
どの DateTime タイプを使うべきか?
| 目的 | タイプ | 特徴 |
|---|---|---|
| 特定の日時を扱う | | 地理的位置(時区)を含む絶対的な瞬間時間 |
| 時区無関係な時刻 | | Unix エポクからの秒数ベースの絶対時間 |
| 計算やパースのみ | | 特定の場所を考慮しない、日付と時間の組み合わせ |
ヒント:
やcivil::DateTimeを時区付きに変換するにはTimestampを使用します。.in_tz("TZ_NAME")
Span 操作
Span は期間の値を保持するハイブリッド型です。
- バランス調整 (
): 単元の単位を整理できます(例:1h 30m -> 90m)。roundlet span = 1.hour().minutes(30); // バランス調整後 let adjusted = span.round(SpanRound::new().largest(Unit::Minute))?; assert_eq!(adjusted.to_string(), "PT90M"); - 比較:
で個別単元値を、Span::fieldwise()
で総物理時間として比較できます。Span::compare() - 合計時間:
で浮動小数点数の合計時間を取得します(カレンダー単位の場合は相対日付が必要です)。span.total(Unit)
結論
これまで Jiff の主要な機能を紹介してきました。Rust エコシステムにおける日付時刻処理のパフォーマンスと堅牢性を追求するために、Jiff は強力な選択肢です。
動機: 既存ライブラリ(chrono, time)の API が局所最適解に陥っていたため、より一貫性のある「DateTime Onion」モデルで再設計しました。 インスピレーション: Temporal JavaScript 仕様から学びつつ、Rust の特性(安全性、ゼロコスト抽象化)を活かしています。
Jiff は単なる日付処理以上のものを提供します。まずは playground で試してみることから始めてください。