Jiff 1.0 has been released as a production-ready datetime library for Rust, moving into a stable release phase after being adopted by major projects including Cargo, Starship, and Nushell. Developed by Andrew Gallant (BurntSushi), the library seeks to solve the inherent difficulties of datetime programming by modeling the domain more accurately rather than passing complexity to the user.
The DateTime Onion Model
Jiff organizes datetime types into a layered structure referred to as the 'DateTime Onion.' This model separates human-centric 'civil time' from machine-centric 'timestamps.' A civil date or time is unattached to any specific location, while a Timestamp represents an unambiguous instant in time as nanoseconds since the Unix epoch.
The outermost layer is the ZonedDateTime, which combines a Timestamp, a civil DateTime, and a TimeZone. A TimeZone acts as a set of rules for mapping between these layers, specifically handling the conversion between an instant in time and the civil clock time seen by humans in a specific geographic region.
“Jiff instead tries hard to encapsulate the complexity and make it difficult for users to do something wrong.”
— A datetime library for Rust - Andrew Gallant's Blog
Handling Ambiguity and Transitions
A core feature of Jiff is how it handles 'folds' and 'gaps' caused by daylight saving time. A fold occurs when clocks are set back, causing a civil time to repeat; a gap occurs when clocks skip forward, leaving certain civil times non-existent.
Jiff provides specific APIs to resolve these ambiguities. By default, it uses a 'compatible' strategy, but developers can explicitly choose 'earlier' or 'later' strategies, or use an 'unambiguous' check that returns an error if a datetime falls into a fold or gap.
Ecosystem Integration and Stability
The move to version 1.0 signifies a commitment to indefinite API stability. This is intended to make Jiff a reliable building block for other libraries, where semver-incompatible changes would cause significant friction for downstream users.
While Jiff simplifies common problems by encapsulating complexity, it requires developers to understand the distinction between civil time and absolute timestamps. This distinction is central to the library's design to prevent logic errors that occur when these two concepts are conflated.
What Hacker News readers are saying
- Open question: One commenter who works on orbital simulations asked how the library handles various time scales beyond TAI, noting that they currently have to perform these conversions manually. comment ↗
- Skeptical: A commenter expressed a preference for using the established Chrono library, noting that they typically prefer standard tools over new alternatives in the Rust ecosystem. comment ↗
- Alternative: Another user suggested that a different library might be better suited for specific use cases involving non-Unix time scales. comment ↗
- Skeptical: One reader expressed disappointment that a modern language like Rust does not include an extensive datetime library within its standard library. comment ↗
Summarized opinions from the Hacker News thread, not verified facts. Read the full discussion ↗
