HN 日本語サマリー

← 一覧へ戻る
プログラミング

Jiff 1.0: Rustのための日時ライブラリ

Jiff 1.0: A datetime library for Rust (burntsushi.net)

429 pointsby burntsushi92 コメント

要約

Rust言語用の新しい日時ライブラリ「Jiff」がバージョン1.0に到達しました。Jiffは、APIの中心にタイムゾーン処理を据えることで、夏時間(DST)に関連する多くの一般的な問題を自動的に処理します。このライブラリはすでにRustエコシステムで広く採用されており、uv、Cargo、Starshipなどのプロジェクトで使用されています。Jiff 1.0は、APIの安定性と長期的なサポートを約束しています。

全文翻訳

Rustのための日時ライブラリ

Jiffは、Rustのための日時ライブラリで、成功への近道に飛び込むことを奨励します。Jiffは、タイムゾーン処理をAPIの中心に据えることで、夏時間(DST)に関連する多くの一般的な問題を自動的に処理します。JiffはすでにRustエコシステムで広く採用されています。

Jiffは、「gif」を柔らかい「g」で発音するのと同じように、「ジェフ」と発音します。

このブログでは、Jiff 1.0リリースを発表し、そのAPIをツアーします。

対象読者: 便利な日時処理を必要とするRustプログラマー。

目次

Jiff 1.0のコミットメント

Jiffはすでに多くのプロジェクトで本番環境で使用されています。uv、Cargo、Starship、fd、Nushell、mise、Jujutsu、uutils/coreutils、さらにはAWS LLRTでのTemporal実装の基盤としても使用されています。1.0と呼ぶ時が来ました。

JiffのAPIに重大な欠陥が見つからない限り、Jiff 1.0を無期限にサポートする予定です。これは、Jiffが他のライブラリの公開APIに登場するエコシステム構築ブロックであることを意図しているため重要です。これにより、Jiffは魅力的な公開依存関係となり、セマンティックバージョニング(semver)互換性のないリリースはエコシステムに大きな問題を引き起こす可能性が高くなります。それらは軽々しく行われることはありません。

Jiff 0.2とJiff 1.0の間の破壊的な変更のリストについては、CHANGELOGを参照してください。

はじめに

プログラミングにおいて、日時ライブラリのコア機能は、コンピュータシステムの時間概念と人間の時間概念の交差点にあります。システム時間の一般的な概念はUnix時間です。人間の時間概念ははるかに複雑ですが、最も一般的なモデルはグレゴリオ暦と12時間または24時間時計の組み合わせです。すべての日時ライブラリのコアには、これらの概念間の変換を行うルーチンがあります。

日時ライブラリは通常、これ以上の機能を提供します。実際、日時処理は歴史的に非常に困難でした。私自身の信念では、その困難さはドメインの不適切なモデリングから来ています。多くの日時ライブラリは、複雑さを再利用可能なコードのバンドルにカプセル化するのではなく、複雑さの一部またはすべてをユーザーに渡します。Jiffは代わりに、複雑さをカプセル化し、ユーザーが間違ったことをしにくいようにすることに懸命に取り組んでいます。(Jiffがこれを最初に行ったわけではありません!)

このブログのセクションでは、非常に基本的な紹介を行います。

一緒にやってみよう

このブログの例を一緒に実行するには、jiffとanyhowに依存する新しいCargoプロジェクトを作成してください。

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

ほとんどの例は、自己完結型の完全なRustプログラムです。コードをコピーして、src/main.rsにあるものを置き換えてください。その後、プログラムを実行します。

cargo run
用語

辞書を提示するのは気が進みませんが、日時ドメインは紛らわしい用語で散乱しているため、共有語彙を整理することが重要だと思います。このセクションはできるだけ小さく保ちました。(「タイムゾーン」のような用語は、後続のセクションでの探求を通じて定義するのが最善であるため、ここでは省略されています。)

  • 市民時間(Civil time): 時計に表示される時間。そして一般的に、あなたの近似的な地理的近傍の人間が見る時間。つまり、市民時間は、特定の地理的地域で時間を伝えるための人間が調整した合意です。市民時間は、ローカルタイム、プレーンタイム、ナイーブタイム、クロックタイムなどとも呼ばれます。
  • UTC: 協定世界時の略。世界中の市民時間の基礎となる時間標準です。元々は平均太陽時に大まかに対応することを意図していました。
  • TAI: 国際原子時の略。原子時計で測定された時間標準です。平均太陽時とは直接関連していません。
  • うるう秒(Leap second): TAIを平均太陽時に近づけるための調整であり、UTCの基礎を形成します。
  • Unix時間(Unix time): UTCですが、うるう秒は無視されます。

TAIとうるう秒は、このブログの機能ではありませんが、Unix時間とUTCの違いを伝えるためにここにリストされています。

日時(DateTime)の玉ねぎ

Jiffのコア型の一部を紹介するために、その日時型を玉ねぎのように考えるようになりました。逆順に、ZonedDateTimeまでその層を積み上げていくことができます。では、用語から始めましょう。ただし、これらはJiffの型でもあります。

  • civil::Dateは、特定の場所に紐付けられていない、プレーンなグレゴリオ暦の日付です。
  • civil::Timeは、特定の場所に紐付けられていない、ナノ秒精度でのプレーンな時計上の時間です。
  • civil::DateTimeは、civil::Dateとcivil::Timeを組み合わせて、グレゴリオ暦の日付と時計上の時間を提供します。これも特定の場所に紐付けられていません。
  • Timestampは、Unixエポックからのナノ秒数を表す、地理的な場所に関係なく、曖昧さのない特定の一瞬の時間です。
  • TimeZoneは、特定の地理的地域で、Timestampをcivil::DateTimeにマッピングし、その逆を行うためのルールのセットです。
  • ZonedDateTimeは、Timestamp、civil::DateTime、およびTimeZoneを組み合わせて、特定の地理的な場所での特定の一瞬の時間を表します。

これをもう少し具体的にするために、コードでどのように見えるかを見てみましょう。タイムゾーンは市民日時から瞬間にマッピングできるため、ゾーン付き日時を作成する1つの方法は、市民日時とタイムゾーンのみを必要とします。

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

別のゾーン付き日時を作成する方法は、タイムスタンプとタイムゾーンのみを必要とします。これは、タイムゾーンがタイムスタンプから特定の市民日時をマッピングできるためです。

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

両方のケースで同等のゾーン付き日時が得られることに注意してください。ただし、異なる方向からアプローチしています。最初のケースでは、時計やカレンダーで見かける可能性のある時間から始めます。2番目のケースでは、データベースやファイルシステム、その他のシステムコールから取得する可能性のある特定の一瞬の時間から始めます。

タイムゾーンの定義

ゾーン付き日時の玉ねぎの例には、1つの要素が欠けています。それはタイムゾーンオフセットです。オフセットは、市民日時を取得するためにUTC時間を調整する必要がある時間の量を示します。たとえば、ニューヨークのUTCで2026-11-01T22:30:00という時間を考えてみましょう。ニューヨークに住む人の市民日時を取得するには、5時間引く必要があります。

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

実際、すべてのゾーン付き日時には関連付けられたオフセットがあります。

use jiff::{civil, tz, Timestamp};

fn main() -> anyhow::Result<()> {
    let timestamp = Timestamp::from_second(1793572200)?;
    let zdt = timestamp.in_tz("America/New_York")?;
    assert_eq!(zdt.offset().seconds(), -(5 * 60 * 60));

    let dt = civil::date(2026, 11, 1).at(17, 30, 0, 0);
    let zdt = dt.in_tz("America/New_York")?;
    assert_eq!(zdt.offset(), tz::offset(-5));

    Ok(())
}

注意: 上記の例で見られるAmerica/New_Yorkという文字列は、IANAタイムゾーンデータベース識別子です。IANAタイムゾーンデータベースは、短い識別子文字列で参照できるタイムゾーン定義のコレクションです。例: Australia/Sydney、Asia/Tokyo、Europe/Berlin。

市民日時がオフセットと組み合わされると、常に特定の一瞬の時間になります。

オフセットの概念を導入すると、タイムゾーンのより正確な定義を与えることができます。タイムゾーンとは、市民時計が一致し、以下のものを提供する地理的地域です。

  • UTCからのオフセットを特定の一瞬の時間にマッピングします。特定の一瞬に適用されるオフセットは、市民日時を生成します。
  • 市民日時からUTCへのオフセットへのマッピングを提供します。市民日時に適用されるオフセットは、特定の一瞬を生成します。

両方のマッピングは以前の例で実証されましたが、市民日時からオフセットへのマッピングは、潜在的な曖昧さのためにかなり複雑になるようです。その曖昧さはいつ生じるのでしょうか?曖昧なオフセットは、市民日時がこのタイムゾーンで有効な時計時間に一致しない場合(例: 夏時間のために時計が進められた場合)や、複数の有効な時計時間がある場合(例: 夏時間のために時計が戻された場合)に発生します。

例を見てみましょう。最初の例では、ニューヨークでの夏時間から標準時間への移行時期の時間を調べます。ニューヨークでは、午前2時に時計が1時間戻されました。これにより、午前1時の時間が繰り返されました。

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));

    // しかし、午前1時30分は何を意味するのでしょうか?最初の繰り返しでしょうか、それとも2番目でしょうか?
    // 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が「フォールド」が発生した場合、またはタイムゾーン遷移で市民時間が逆方向に進む場合に、曖昧さをどのように解決するかを示しています。しかし、実際には低レベルのAPIを掘り下げて、その曖昧さがどのように解決されるかを変えることができます。デフォルトでは、Jiffは「互換性のある」戦略を使用し、フォールドで時間の最初の繰り返しを常に選択します。しかし、TimeZoneのAPIを直接使用して他の戦略を選択できます。

use jiff::{
    civil::date,
    tz::{offset, TimeZone},
};

fn main() -> anyhow::Result<()> {
    let tz = TimeZone::get("America/New_York")?;
    let dt = date(2026, 11, 1).at(1, 30, 0, 0);

    // Jiffがデフォルトで使用するものと同じです。
    let zdt = tz.to_ambiguous_zoned_datetime(dt).compatible()?;
    assert_eq!(zdt.offset(), offset(-4));

    // 常に早い方の日時を選択します。
    // フォールドの場合、これはデフォルトの「互換性のある」戦略と同じです。
    let zdt = tz.to_ambiguous_zoned_datetime(dt).earlier()?;
    assert_eq!(zdt.offset(), offset(-4));

    // 常に遅い方の日時を選択します。
    // フォールドの場合、これは午前1時の時間の2番目の出現を選択します!
    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(())
}

ギャップ、つまり市民時計でスキップされる市民時間があるタイムゾーン遷移にも同じ考え方が適用されます。たとえば、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);

    // 「互換性のある」戦略は、ギャップの場合に遅い方の時間を選択します。
    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));

    // 常に遅い方の日時を選択します。
    // ギャップの場合、これはデフォルトの「互換性のある」戦略と同じです。
    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(())
}
期間(Durations)

残りのコア型は2つあり、どちらも期間の概念を表します。

  • Spanは、カレンダー単位(年、月、週、日)と物理時間単位(時、分、秒、ミリ秒、マイクロ秒、ナノ秒)の両方を組み合わせた強力なハイブリッド期間です。個々の単位値を保持する堅牢な型です。
  • SignedDurationは、std::time::Durationの符号付きバージョンであり、常に96ビット整数のナノ秒数に対応します。物理時間(時単位以下)のみを表し、カレンダー単位(日単位以上)は表せません。

可能な限りSpanを使用してください。簡単な例として、2つの市民日付間の日数を取得する方法を示します。

use jiff::civil::date;

fn main() -> anyhow::Result<()> {
    let d1 = date(2024, 2, 1);
    let d2 = date(2024, 3, 1);
    let span = d2 - d1;
    assert_eq!(span.get_days(), 29);
    // または、同等に:
    assert_eq!(d1.until(d2)?.get_days(), 29);

    // d1とd2を入れ替えると、結果は同じですが、負になります。
    let span = d1 - d2;
    assert_eq!(span.get_days(), -29);

    Ok(())
}

期間は日付にも追加できます。

use jiff::{civil::date, ToSpan};

fn main() -> anyhow::Result<()> {
    let d1 = date(2024, 2, 1);
    // `ToSpan`拡張トレイトから来る便利な構文です。
    let span = 29.days();
    assert_eq!(d1.checked_add(span)?, date(2024, 3, 1));

    Ok(())
}

一般的に、Spanが関与する操作がある場合、SignedDurationでも同等の操作が利用可能です。

use jiff::{civil::date, SignedDuration};

fn main() -> anyhow::Result<()> {
    let dt1 = date(2024, 2, 1).at(17, 30, 0, 0);
    let sdur = SignedDuration::from_mins(90);
    assert_eq!(dt1.checked_add(sdur)?, date(2024, 2, 1).at(19, 0, 0, 0));

    Ok(())
}

上記の例では、civil::Dateからcivil::DateTimeに切り替えたことに注意してください。これは物理時間単位を追加する方法を示すためです。しかし、Spanはすべての単位を組み合わせるため、同様のことが達成できます。

use jiff::{civil::date, ToSpan};

fn main() -> anyhow::Result<()> {
    let dt1 = date(2024, 2, 1).at(17, 30, 0, 0);
    let span = 1.hour().minutes(30);
    assert_eq!(dt1.checked_add(span)?, date(2024, 2, 1).at(19, 0, 0, 0));

    // カレンダー単位と物理時間単位を組み合わせることができます!
    let span = 1.month().hours(1).minutes(30);
    assert_eq!(dt1.checked_add(span)?, date(2024, 3, 1).at(19, 0, 0, 0));

    Ok(())
}

要するに、可能な限りSpanを使用してください。しかし、それがかさばりすぎたり遅すぎたりする場合は、SignedDurationを使用してください。Spanの主な利点の1つは、各単位値を個別に表すため、期間の元の意味を保持できることです。たとえば、映画の実行時間を分で表すことは一般的ですが、期間が1時間を超える場合でも同様です。実際、2時間のスパンは120分のスパンとは異なるスパンです。

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を使用します。

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();

    // 重い処理を実行
    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<()> {
    // `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で十分です。

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はこれら3つの仕様のいずれにも有効でない文字列の解析もサポートしています。たとえば、2026-11-12[America/New_York]は、2026-11-12T00:00:00[America/New_York]として解析されます。

このセクションでは、Jiffが日時フォーマットと印刷をどのように行うかをツアーします。

FromStrとDisplay

Jiffのすべての日時型と期間型は、標準ライブラリのFromStrおよびDisplayトレイトを実装しています。これは、日時を解析することが自然であることを意味します。

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");

柔軟な解析のもう1つの例は、文字列に別のdatetime型が含まれている場合、それを解析できることです。たとえば、ISO 8601 datetimeから日付を解析できます。

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

ZonedDateTimeは常にRFC 9557構文を使用し、IANAタイムゾーン識別子が含まれます。

let zdt: ZonedDateTime = "2026-10-31T05:30[Australia/Sydney]".parse()?;
// 解析した文字列にはオフセットがありませんでしたが、
// 提供された市民日時を考慮してタイムゾーン定義を参照することで、
// オフセットが自動的に追加されました。
assert_eq!(zdt.to_string(), "2026-10-31T05:30:00+11:00[Australia/Sydney]");

ゾーン付き日時をRFC 3339構文のみを使用して印刷したい場合は、タイムスタンプをゾーン付き日時のオフセットで直接フォーマットすることで実現できます。

let zdt: ZonedDateTime = "2026-10-31T05:30[Australia/Sydney]".parse()?;
assert_eq!(
    zdt.timestamp().display_with_offset(zdt.offset()).to_string(),
    "2026-10-31T05:30:00+11:00",
);

SpanおよびSignedDuration型も、ISO 8601期間フォーマットを介してFromStrおよびDisplayトレイトをサポートしています。例:

use jiff::{SignedDuration, Span};

fn main() -> anyhow::Result<()> {
    let duration = "PT5H30M";

    let span: Span = duration.parse()?;
    assert_eq!(span.to_string(), "PT5H30M");

    let sdur: SignedDuration = duration.parse()?;
    assert_eq!(sdur.to_string(), "PT5H30M");

    Ok(())
}

Spanはカレンダー単位もサポートするハイブリッド期間であるため、カレンダー単位と物理時間単位の両方を持つ期間を解析できます。SignedDurationは物理時間単位のみを持つ期間を解析できます。

use jiff::{SignedDuration, Span};

fn main() -> anyhow::Result<()> {
    let duration = "P11Y2M28DT5H30M";

    let span: Span = duration.parse()?;
    assert_eq!(span.to_string(), "P11Y2M28DT5H30M");

    let err = duration.parse::<SignedDuration>().unwrap_err();
    assert_eq!(
        err.to_string(),
        "parsing ISO 8601 duration in this context requires \
         that the duration contain a time component \
         and no components of days or greater",
    );

    Ok(())
}

ISO 8601期間フォーマットには、次のセクションで説明するいくつかの欠点があります。

「フレンドリー」な期間フォーマット

ISO 8601期間文字列は広範なサポートを享受しているため、JiffではSpanとSignedDurationの両方でデフォルトとなっています。しかし、それには2つの重要な欠点があります。

  1. 読みにくい。たとえば、P11Y2M28DT5H30Mでは、空白がないため、単位値と単位ラベルがすべて連続しています。
  2. ISO 8601期間は、すべての可能なSpan値を一意に表現できません。

2番目の欠点は、例で最もよくわかります。2000ミリ秒のSpanを考えてみましょう。これをISO 8601期間文字列に変換してから再度解析すると、2秒になります。

use jiff::{Span, ToSpan};

fn main() -> anyhow::Result<()> {
    let original = 2000.milliseconds();
    assert_eq!(original.to_string(), "PT2S");

    let got: Span = "PT2S".parse()?;

    // スパンは異なる単位値を持っています!
    assert_eq!(original.get_seconds(), 0);
    assert_eq!(original.get_milliseconds(), 2000);
    assert_eq!(got.get_seconds(), 2);
    assert_eq!(got.get_milliseconds(), 0);

    Ok(())
}

これは、スパンの文字列形式がすべての可能なスパンの異なる値を忠実に表してほしい場合に望ましくないかもしれません。

これらの2つの理由から、Jiffは独自のカスタム「フレンドリー」期間フォーマットを提供しています。フレンドリーフォーマットは非可逆的であり、ISO 8601期間フォーマットよりも英語話者にとって読みやすいように設計されています。以下はすべて有効なフレンドリー期間の例です。

40d
40 days
1y1d
1yr 1d
3d4h59m
3 days, 4 hours, 59 minutes
3d 4h 59m
2h30m
2h 30m
1mo
1w
1 week
1w4d
1 wk 4 days
1m
0.0021s
0s
0d
0 days
3 mins 34s 123ms
3 mins 34.123 secs
3 mins 34,123s
1y1mo1d1h1m1.1s
1yr 1mo 1day 1hr 1min 1.1sec
1 year, 1 month, 1 day, 1 hour, 1 minute 1.1 seconds
1 year, 1 month, 1 day, 01:01:01.1

フレンドリー期間の解析は、ISO 8601期間の解析と同じくらい簡単です。SpanとSignedDurationの両方のFromStr実装は、同時にISO 8601期間とフレンドリー期間をサポートしています。

let span: Span = "6y 10mo 3d 23h".parse()?;
// `Span::fieldwise`が、単位ごとに`Span`の等価比較を許可することを思い出してください。
assert_eq!(span.fieldwise(), 6.years().months(10).days(3).hours(23));

フレンドリー期間の印刷には、デフォルトではないため、もう少し手間がかかります。Span::to_string()の代わりに、Rustのフォーマット機構を介して「代替」構文を使用できます。

let span = 2000.milliseconds();
// これは、単位値が保持されていることも示しています。
assert_eq!(format!("{span:#}"), "2000ms");

より多くのスペース、長い単位ラベル、および各単位を区切るコンマを使用して、スパンをフレンドリーフォーマットで既存の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のすべてのdatetime型には、strptimeとstrftimeルーチンが付属しています。たとえば、米国のmonth/day/yearフォーマットで市民日付を解析するには、次のようになります。

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

または、英語話者にとって読みやすい表現でゾーン付き日時をフォーマットするには、次のようになります。

let zdt = civil::date(2026, 11, 13).at(17, 30, 0, 0).in_tz("Australia/Sydney")?;
assert_eq!(
    zdt.strftime("%a, %b %d, %Y %H:%M %Z").to_string(),
    "Fri, Nov 13, 2026 17:30 AEDT",
);

呼び出し元は、jiff::fmt::strtimeの低レベルAPIを使用して、各解析されたコンポーネントに個別にアクセスすることもできます。

use jiff::{civil, fmt::strtime::BrokenDownTime};

fn main() -> anyhow::Result<()> {
    let tm = BrokenDownTime::parse(
        "%a, %b %d, %Y %H:%M",
        "Fri, Nov 13, 2026 17:30",
    )?;
    assert_eq!(tm.weekday(), Some(civil::Weekday::Friday));
    assert_eq!(tm.month(), Some(11));
    assert_eq!(tm.day(), Some(13));
    assert_eq!(tm.year(), Some(2026));
    assert_eq!(tm.hour(), Some(17));
    assert_eq!(tm.minute(), Some(30));
    assert_eq!(tm.second(), None);

    Ok(())
}
jiff::fmt モジュール

上記のツアーはほとんどのユースケースをカバーするはずですが、解析やフォーマットをより細かく制御したい場合や、RFC 2822などの代替フォーマットをサポートしたい場合があります。jiff::fmtモジュールは、より複雑なAPIを犠牲にして、これらのユースケースに対応することを目的としています。たとえば、&[u8]からRFC 2822日時文字列を解析する例を示します(これにより、呼び出し元はUTF-8検証チェックを回避できます)。

use jiff::fmt::rfc2822;

fn main() -> anyhow::Result<()> {
    static PARSER: rfc2822::DateTimeParser = rfc2822::DateTimeParser::new();

    let data = b"Sat, 13 Jul 2024 15:09:59 -0400";
    let ts = PARSER.parse_timestamp(data)?;
    assert_eq!(ts.to_string(), "2024-07-13T19:09:59Z");
    Ok(())
}

別の例は、提供された市民日時が曖昧な場合に、デフォルトの曖昧化戦略を変更する方法を示しています。たとえば、オーストラリアのシドニーは、現地時間の2026-04-05T03:00:00に時計を進めました。つまり、UTCオフセット+11からUTCオフセット+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]に戻ると、これは2つの異なる一瞬の時間を指す可能性があるため曖昧ですが、その曖昧さを解決する戦略をどのように変更しますか?標準ライブラリのFromStrトレイトではできません。そのため、RFC 2822解析で行ったように、手動で独自のパーサーを構築する必要があります。この例では、それを実行する方法と、さまざまな曖昧化オプションを示します。UTCオフセット+11:00は、シドニーの人々の時計で2026-04-05T02:30の最初の出現に対応し、UTCオフセット+10:00は2番目の出現に対応することを覚えておいてください。

use jiff::{fmt::temporal::DateTimeParser, tz::Disambiguation};

fn main() -> anyhow::Result<()> {
    let string = "2026-04-05T02:30[Australia/Sydney]";

    // 「互換性のある」はデフォルトの戦略であり、フォールド(通常は夏時間から標準時間への移行)では早い方の時間、
    // ギャップ(通常は標準時間から夏時間への移行)では遅い方を選択します。
    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」は常にフォールドでの最初の出現、またはギャップ前の時間を選択します。
    // この場合、市民時間がフォールド内にあるため、互換性のあるものと同じです。
    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」は常にフォールドでの2番目の出現、またはギャップ後の時間を選択します。
    // そのため、フォールドの場合、「互換性のある」とは異なります。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統合クレートを使用できます。

以下は、fr-LAロケールでゾーン付き日時をフォーマットする方法を示す例です。(この例を機能させるには、プロジェクトにcargo add icu jiff-icuを実行する必要があります。)

use icu::
    calendar::Iso,
    datetime::{fieldsets, DateTimeFormatter},
    locale::locale,
    time::{zone::models::AtTime, TimeZoneInfo},
};
use jiff::ZonedDateTime;
use jiff_icu::ConvertFrom as _;

fn main() -> anyhow::Result<()> {
    // まず、Jiffのゾーン付き日時を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ロケールのdatetimeフォーマッタを作成します。
    let formatter = DateTimeFormatter::try_new(
        locale!("fr-LA").into(),
        fieldsets::YMDET::medium().with_zone(fieldsets::zone::SpecificLong),
    )?;

    // 3番目に、ゾーン付き日時をフォーマットします。
    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は、日時型に多くのメソッドを提供しており、それらを快適かつエラーなく使用できるようにしています。

日付の基本

すべてのdatetime型は、呼び出し元がその構成要素から構築できるnewコンストラクタを提供します。ほとんどの場合、このコンストラクタは失敗する可能性があります。例:

use jiff::civil::Date;

fn main() -> anyhow::Result<()> {
    let d = Date::new(2024, 2, 29)?;
    // すべての日時型には、各コンポーネントへの便利なアクセッサがあります。
    assert_eq!(d.year(), 2024);
    assert_eq!(d.month(), 2);
    assert_eq!(d.day(), 29);

    let err = Date::new(2025, 2, 29).unwrap_err();
    assert_eq!(
        err.to_string(),
        "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関数であり、入力が無効な場合はパニックします。有効であることがわかっている入力でのみ使用する必要があります。たとえば、ユーザー提供の値と一緒にこれを使用するのは不適切です。上記のconstブロックのため、無効な値を指定するとコンパイラエラーが発生します。

特定の一瞬の時間を表すdatetime型(つまり、ZonedDateTimeとTimestamp)には、現在の時刻を取得するためのnow()コンストラクタもあります。

use jiff::{Timestamp, ZonedDateTime};

fn main() -> anyhow::Result<()> {
    let now = Timestamp::now();
    println!("{now}");
    // 例: 2026-11-15T14:17:21.80099287Z

    // これは、システムで設定されたタイムゾーンを自動的に取得します。
    let now = ZonedDateTime::now();
    println!("{now}");
    // 例: 2026-11-15T09:17:21.80102125-05:00[America/New_York]

    Ok(())
}

コンストラクタに加えて、Date::with APIを使用して、古い日付値から新しい日付値を構築できます。

let d1 = const { civil::date(2024, 2, 29) };
// このAPIは、31が31日を持つ月より前に供給されても、単に壊れるわけではありません。
// どの順序でも問題ありません!これは、エラーが`build()`が呼び出されるまで遅延されるためです。
let d2 = d1.with().day(31).month(3).build()?;
assert_eq!(d2.to_string(), "2024-03-31");

日付を取得したら、多数のAPIが利用可能です。

let d = civil::date(2025, 7, 10);
assert_eq!(d.weekday(), civil::Weekday::Thursday);
assert_eq!(d.first_of_year(), civil::date(2025, 1, 1));
assert_eq!(d.last_of_year(), civil::date(2025, 12, 31));
assert_eq!(d.first_of_month(), civil::date(2025, 7, 1));
assert_eq!(d.last_of_month(), civil::date(2025, 7, 31));
assert_eq!(d.yesterday()?, civil::date(2025, 7, 9));
assert_eq!(d.tomorrow()?, civil::date(2025, 7, 11));

さらに、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時間を追加するわけではないことを知っています。

// ニューヨークでは、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)がギャップまたはフォールドに着地する場合、「互換性のある」曖昧化戦略が自動的に選択されます。

// フォールドに着地するゾーン付き日時の場合、デフォルトで早い方のインスタントが選択されます。
let zdt = 
    civil::date(2024, 11, 2).at(1, 30, 0, 0).in_tz("America/New_York")?;
let tomorrow = zdt.tomorrow()?;
assert_eq!(
    tomorrow.to_string(),
    "2024-11-03T01:30:00-04:00[America/New_York]"
);

// そしてギャップの場合、遅い方のインスタントがデフォルトで選択されます。
let zdt = 
    civil::date(2024, 3, 9).at(2, 30, 0, 0).in_tz("America/New_York")?;
let tomorrow = zdt.tomorrow()?;
assert_eq!(
    tomorrow.to_string(),
    "2024-03-10T03:30:00-04:00[America/New_York]"
);

この動作をオーバーライドするには、市民日時にドロップダウンし、操作を実行してから、TimeZone::to_ambiguous_zoned_datetimeを使用して正確な曖昧化戦略を制御できます。

// フォールドに着地するゾーン付き日時の場合、デフォルトで早い方のインスタントが選択されます。しかし、遅い方のインスタントが欲しいとしましょう。
let zdt = 
    civil::date(2024, 11, 2).at(1, 30, 0, 0).in_tz("America/New_York")?;
let tomorrow = zdt
    .time_zone()
    .to_ambiguous_zoned_datetime(zdt.datetime().tomorrow()?)
    .later()?;
assert_eq!(
    tomorrow.to_string(),
    // オフセットが-05になっていることに注意してください。
    // これは遅い方のインスタントに対応します。
    "2024-11-03T01:30:00-05:00[America/New_York]"
);

日付型で言及する価値のあるその他のメソッドがいくつかあります。まず、「次の木曜日」や「月の最後の С воскресенье」のようなものを照会する機能です。前者はnth_weekday APIで回答できます。

let zdt1 = civil::date(2024, 7, 10).in_tz("America/New_York")?;
assert_eq!(zdt1.weekday(), civil::Weekday::Wednesday);
// 今週の木曜日ではなく、次の木曜日です!
let zdt2 = zdt1.nth_weekday(2, civil::Weekday::Thursday)?;
assert_eq!(zdt2.weekday(), civil::Weekday::Thursday);
assert_eq!(zdt2.date(), civil::date(2024, 7, 18));

後者はnth_weekday_of_month APIで回答できます。

let zdt1 = civil::date(2024, 7, 10).in_tz("America/New_York")?;
assert_eq!(zdt1.weekday(), civil::Weekday::Wednesday);
// 今月の最後の С воскресенье。
let zdt2 = zdt1.nth_weekday_of_month(-1, civil::Weekday::Sunday)?;
assert_eq!(zdt2.weekday(), civil::Weekday::Sunday);
assert_eq!(zdt2.date(), civil::date(2024, 7, 28));

最後に、ユーザーはseriesを介して便利な時系列イテレータにアクセスできます。

use jiff::{civil, ToSpan};

fn main() -> anyhow::Result<()> {
    let start = civil::date(2024, 7, 10).in_tz("America/New_York")?;
    let mut dates = vec![];
    // 8週間、毎週。
    for zdt in start.series(1.week()).take(8) {
        dates.push(zdt);
    }
    assert_eq!(
        dates,
        vec![
            civil::date(2024, 7, 10).in_tz("America/New_York")?,
            civil::date(2024, 7, 17).in_tz("America/New_York")?,
            civil::date(2024, 7, 24).in_tz("America/New_York")?,
            civil::date(2024, 7, 31).in_tz("America/New_York")?,
            civil::date(2024, 8, 7).in_tz("America/New_York")?,
            civil::date(2024, 8, 14).in_tz("America/New_York")?,
            civil::date(2024, 8, 21).in_tz("America/New_York")?,
            civil::date(2024, 8, 28).in_tz("America/New_York")?,
        ]
    );

    Ok(())
}

これらのメソッドはすべてcivil::Dateおよびcivil::DateTimeでも利用可能であり、それらの間を移動することを非常に自然にするはずです。

日付の算術演算

Jiffのすべてのdatetime型は、期間の加算および減算、および2つのdatetime値間の時間のスパンの計算をサポートしています。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(())
}

ここではstd::ops::Addトレイトのcivil::Dateに対する実装を利用しています。しかし、これを使用する欠点は、日付の値が範囲外になった場合にパニックすることです。これは許容できる場合とそうでない場合があります。しかし、ユーザー入力に対処している場合は、代わりに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>

具体的には、Span、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では一般的です。ここでは、複数の期間型を便利に使用するための方法として使用されています。しかし、後述するように、操作の動作を制御する設定オプションの拡張ポイントとしても使用されます。

期間をdatetime値に加算または減算するだけでなく、2つのdatetime値間の期間を計算することもできます。たとえば、2つの日付間の日数を取得するには、次のようになります。

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());

ただし、日ではなく時間が返されることに注意してください。これは、2つのZonedDateTime値が異なるタイムゾーンにある可能性があるためです。ZonedDateTimeは基本的に特定の一瞬の時間であり、タイムゾーンによっては日間の長さが異なる場合があるため、最大の単位として時間をデフォルトにすると、2つのゾーン付き日時を減算すると常に成功します。ただし、追加のオプションを渡すことで、返される期間のより大きな単位を要求できます。特に、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は、スパンを丸めるためのより強力な設定オプションを提供します。多くの単位値を持つスパンを生成するこの例をご覧ください。

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

これはエンドユーザーに表示するには精度が高すぎるかもしれません。代わりに、スパンを最も近い30分に丸めることを希望するかもしれません。これは、ZonedDateTimeDifferenceを明示的に構築し、そのオプションを設定することで実現できます。

use jiff::{civil::date, RoundMode, ToSpan, Unit, ZonedDateTimeDifference};

fn main() -> anyhow::Result<()> {
    let zdt1 = 
        date(2024, 5, 15).at(14, 30, 54, 0).in_tz("America/New_York")?;
    let zdt2 = date(2024, 5, 31)
        .at(19, 13, 27, 123_456_789)
        .in_tz("America/New_York")?;
    let difference = ZonedDateTimeDifference::new(&zdt2)
        .largest(Unit::Day)
        .smallest(Unit::Minute)
        .increment(30)
        .mode(RoundMode::HalfExpand);
    assert_eq!(
        zdt1.until(difference)?,
        16.days().hours(4).minutes(30).fieldwise(),
    );

    Ok(())
}

また、スパンの丸めは、夏時間などのタイムゾーン遷移を考慮に入れることにも注意してください。たとえば、ニューヨークの2024-11-02 17:30と2024-11-03 04:45を考えてみましょう。ニューヨークは2024年11月3日の午前2時に夏時間を終了したため、それらの間の物理的な時間の長さは12時間15分です。

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日に丸めると、1日に丸められます。しかし、この特定の日の中間点は実際には12時間30分であるため、要求したときにこの期間は0日に丸められます。

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では利用できません。

A common example for rounding a datetime is to reduce precision. For example, a system clock might provide nanosecond precision, but maybe we only care about the nearest half-hour:

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]"
    );

    // 最も近い30分に丸める。
    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分という時間は正午より前ですが、結果は次の日に丸められています。これは、ニューヨークでの夏時間終了への移行により、この日の半ばが実際には午前11時30分であるためです。

その他のカレンダー

Jiff自体は、プロレプティックグレゴリオ暦以外のカレンダーをサポートしていません。代わりにICU4Xクレートを使用して非グレゴリオ暦で作業し、jiff-icuクレートを使用して日時型間で変換できます。(この例を機能させるには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 datetimeを作成します。
    let datetime = IcuDateTime {
        date: IcuDate::try_new_hebrew_v2(5785, Month::new(5), 4)?,
        time: IcuTime::try_new(17, 30, 0, 0)?,
    };

    // 次に、それを市民日時に変換します。
    // これは自動的に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つのdatetime型があります。

それぞれを他の型と比較していつ使用すべきでしょうか?

最初の近似として、ZonedDateTimeを使用できる場合は、それがおそらくあなたが求める型でしょう。それは特定の地理的な場所での特定の一瞬の時間を表します。つまり、TimestampとTimeZoneの両方を持っています。

UTCのみで作業するか、システム時間のみを扱う必要がある場合は、Timestampが適切な選択でしょう。これは、タイムゾーンに接続されていない特定の一瞬の時間を表すのに役立ちます。

civil::DateTimeは、特定の一瞬の時間を気にせず、計算がタイムゾーンから独立して行われるべきコンテキストで役立ちます。たとえば、ユーザーインターフェイスの日時ピッカーから日時情報を解析する場合などです。

civil::DateTimeとTimestampの両方を、タイムゾーンを指定することでZonedDateTimeに変換できることを覚えておいてください。

スパン(Span)操作

スパンをdatetime値に追加したり、datetime値間のスパンを取得したりする方法はすでに見てきましたが、Span自体で利用可能なAPIはまだ探求していません。

まず第一に、コンストラクタを通じてSpanを構築できます。これは、すべての単位が0に設定されたSpanを返します。

use jiff::Span;

let span = Span::new();

SpanはCopyであり、不変です。メソッドチェーンを通じて新しいスパンを作成できます。

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

または、整数型にメソッドを追加してスパンを構築するToSpan便利トレイトを使用することもできます。

use jiff::ToSpan;

let span = 1.hour().minutes(30);
assert_eq!(span.to_string(), "PT1H30M");

ただし、Span::hoursやToSpan::hoursのようなメソッドは、整数がSpanがサポートする制限を超えている場合にパニックすることに注意してください。スパンがプログラムのリテラルである場合は問題ありません。パニックはバグを示すためです。しかし、入力がエンドユーザーから来る場合は、フォール可能なメソッドを使用する方が良いでしょう。

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

スパンは各単位値を個別に保持します。これは、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");

これにより、呼び出し元は期間を表現する上で最大限の柔軟性を得られます。これにより、大きな単位に合計される期間を特定の単位で表現することが可能になります。たとえば、映画の実行時間は、実行時間が1時間を超える場合でも、通常は分で伝えられます。これは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の名前にもかかわらず。代わりに、最大の単位を設定するだけなので、この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(())
}

相対日付がないと、1ヶ月が何時間になるかを知ることはできません。つまり、カレンダー単位が関与すると、スパンは、コンテキストが適用されるまで物理的な時間の期間として解釈できません。

これは、日自体にも当てはまります。なぜなら、日は時々24時間より長かったり短かったりする可能性があるからです。上記の例を考えてみましょう。ゾーン付き日時を相対日付として使用するとどうなるでしょうか?

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

両方のケースで2756時間から開始し、ローマでは2020-03-29が23時間しかなかった(標準時間から夏時間への移行で)ため、期間の時間コンポーネントが20から21に変わったことに注意してください。これは、3mo 23dの日の1つが23時間しかなかったことを意味します。したがって、それを補うために追加の1時間が必要でした。

round APIは実際の丸めも行うことができます。

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

デフォルトの「ハーフエクスパンド」(学校で習った丸め方)から、切り捨て(または他のいくつかのモード)に丸めモードを変更することもできます。

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

丸めインクリメントを指定して、最も近い単位値に丸めることもできます。たとえば、最も近い30分に丸める場合です。

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の開発を始める前、この混乱は私にとって非常に煩わしく、独自のクレートを書くことを検討するほどでした。chronoとtimeの両方のAPIを改善できると感じました。個人的にはこのドメインが非常に興味深く、より良いものを作るために取り掛かりました。

既存のソリューション(chronoやtimeなど)を改善するのではなく、エコシステムにさらに別の選択肢を追加するのはなぜですか?選択肢が多すぎることには確かに欠点があると思いますが、chronoとtimeの両方(2024年時点)が局所的な最大値に達したと結論付けました。さらに、2024年時点では、私は日時処理の専門家ではありませんでした。日時ライブラリを構築して初めて専門家になりました。したがって、クレートのメンテナを根本的に異なる方向に説得するのは大変なことだったでしょう。

Jiffの設計と比較のドキュメントには、Jiff、chrono、time間の動機と具体的な例に関するさらに詳細が含まれています。

インスピレーション

Jiffは、JavaScriptの標準ライブラリによる日付と時刻管理のソリューションであるTemporalに大きく影響を受けています。JiffはAPI設計、機能、さらには日時値の解析/フォーマットを継承しています。ただし、JiffはTemporal仕様の100%互換実装ではなく、またそのように目指しているわけでもありません。Jiffはまず第一に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の期間型がDurationではなくSpanという名前であることです。これは、Rustの標準ライブラリのstd::time::Duration型との混同を避けるために行われました。

その他の違いは次のとおりです。

  • JiffのInstant型は、Rustの標準ライブラリのstd::time::Instant型との混同を避けるためにTimestampという名前です。
  • Jiffの「プレーン」な日付と時刻の型は、Jiffでは「市民」と呼ばれます。
  • Jiffはグレゴリオ暦のみをサポートします。
  • Jiffの日時範囲は+/- 9999までですが、Temporalの範囲はそれより大きいです。

Temporalなしでは、Jiffは今日のその形では存在しなかったと言うのは簡単です。