Jiff

Unix

• Current Time: Supported via Rust stdlib.
• IANA Database: Automatically detects /usr/share/zoneinfo. Use TZDIR if located elsewhere. Use tzdb-bundle-always if the database is missing (e.g., minimal Docker).
• System Time Zone: Discovered via /etc/localtime symbolic link metadata. If /etc/localtime is not a symlink, Jiff reads it as a TZif file, which may prevent lossless serialization of the IANA identifier.

Android

• Current Time: Supported via Rust stdlib.
• IANA Database: Uses a 'Concatenated Time Zone Database' format. Jiff supports this on all platforms.
• System Time Zone: Discovered via the persist.sys.timezone property.

Windows

• Current Time: Supported via Rust stdlib.
• IANA Database: Automatically bundled via tzdb-bundle-platform (enabled by default). Can be overridden using TZDIR.
• System Time Zone: Discovered via GetDynamicTimeZoneInformation and mapped to IANA identifiers using CLDR XML data.

WASM

• wasm32-unknown-emscripten: Current time supported via stdlib. IANA database bundled via tzdb-bundle-platform. System time zone is unsupported.
• wasm32-wasi*: Current time supported via stdlib. IANA database bundled via tzdb-bundle-platform. System time zone can be set via TZ environment variable.
• wasm{32,64}-unknown-unknown:
  • Default: Current time panics; IANA database is bundled; System time zone is unsupported.
  • With js feature: Current time uses Date.now; System time zone uses Intl.DateTimeFormat.

Jiff is designed as a general-purpose datetime library that addresses perceived limitations in existing Rust crates like chrono, time, hifitime, and icu.

Key differentiators include:

• Time Zone Handling: Unlike chrono (which requires external crates like chrono-tz or tzfile) or time (which has limited IANA support), Jiff provides full IANA Time Zone Database support out of the box. It abstracts the discovery method, allowing transparent use of either system databases or embedded data.
• Serialization: Jiff follows [RFC 9557] to support embedding IANA time zone identifiers in serialized representations (e.g., 2024-07-21T17:11-04[America/New_York]), ensuring lossless serialization/deserialization of time zone-aware datetimes. chrono typically loses the time zone and only preserves the offset.
• API Ergonomics: Jiff provides consistent methods across different datetime types. For example, methods available on civil::Date are also available on civil::DateTime and Zoned. This simplifies transitions between civil and time zone-aware datetimes (e.g., using Zoned::tomorrow instead of manual conversion steps).
• Error Handling: Jiff prefers returning Result<T, E> with contextualized, human-readable error messages over Option<T> to avoid the need for manual error conversion.
• Specialized Types: Jiff includes a dedicated Timestamp type for Unix epoch seconds, providing a standard way to handle timestamps that is more integrated than DateTime<Utc> in other libraries.

Jiff supports adding non-uniform units (like days) to time zone aware datetimes. It handles DST transitions (23-hour or 25-hour days) correctly so that adding a day preserves the expected civil time. It also allows consistent conversion between calendar units (days) and clock units (hours) using Span.

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

fn main() -> anyhow::Result<()> {
    let zdt1 = date(2024, 3, 9).at(21, 0, 0, 0).in_tz("America/New_York")?;
    let zdt2 = zdt1.checked_add(1.day())?;

    // Even though 2 o'clock didn't occur on 2024-03-10, adding 1 day
    // returns the same civil time the next day.
    assert_eq!(zdt2.to_string(), "2024-03-10T21:00:00-04:00[America/New_York]");
    // The span of time is 23 hours:
    assert_eq!(&zdt2 - &zdt1, 23.hours().fieldwise());
    // But if you ask for the span in units of days, you get exactly 1:
    assert_eq!(zdt1.until((Unit::Day, &zdt2))?, 1.day().fieldwise());

    Ok(())
}