3,154
stars
141
forks
15
watchers
356
prs
288
issues
0
releases
README
Jiff
====
Jiff is a datetime library for Rust that encourages you to jump into the
pit of success. The focus of this library is providing high level datetime
primitives that are difficult to misuse and have reasonable performance. Jiff
supports automatic and seamless integration with the Time Zone Database, DST
aware arithmetic and rounding, formatting and parsing zone aware datetimes
losslessly, opt-in Serde support and a whole lot more.
Jiff takes enormous inspiration from [Temporal], which is a [TC39] proposal to
improve datetime handling in JavaScript.
Dual-licensed under MIT or the UNLICENSE.
[TC39]: https://tc39.es/
[Temporal]: https://tc39.es/proposal-temporal/docs/index.html
Documentation
API documentation on docs.rs
Comparison with chrono, time, hifitime and icu
The API design rationale for Jiff
Platform support
CHANGELOG
Example
Here is a quick example that shows how to parse a typical RFC 3339 instant,
convert it to a zone aware datetime, add a span of time and losslessly print
it:
rust
use jiff::{Timestamp, ToSpan};
fn main() - Result {
let time: Timestamp = "2024-07-11T01:14:00Z".parse()?;
let zoned = time.in_tz("America/New_York")?.checked_add(1.month().hours(2))?;
assert_eq!(zoned.to_string(), "2024-08-10T23:14:00-04:00[America/New_York]");
// Or, if you want an RFC3339 formatted string:
assert_eq!(zoned.timestamp().to_string(), "2024-08-11T03:14:00Z");
Ok(())
}
There are many more examples in the documentation.
Usage
Jiff is on crates.io and can be
used by adding jiff to your dependencies in your project's Cargo.toml.
Or more simply, just run cargo add jiff.
Here is a complete example that creates a new Rust project, adds a dependency
on jiff, creates the source code for a simple datetime program and then runs
it.
First, create the project in a new directory:
text
$ cargo new jiff-example
$ cd jiff-example
Second, add a dependency on jiff:
text
$ cargo add jiff
Third, edit src/main.rs. Delete what's there and replace it with this:
rust
use jiff::{Unit, ZonedDateTime};
fn main() - Result {
let now = ZonedDateTime::now().round(Unit::Second)?;
println!("{now}");
Ok(())
}
Fourth, run it with cargo run:
text
$ cargo run
Compiling jiff v0.2.0 (/home/andrew/rust/jiff)
Compiling jiff-play v0.2.0 (/home/andrew/tmp/scratch/rust/jiff-play)
Finished dev profile [unoptimized + debuginfo] target(s) in 1.37s
Running target/debug/jiff-play
2024-07-10T19:54:20-04:00[America/New_York]
The first time you run the program will show more output like above. But
subsequent runs shouldn't have to re-compile the dependencies.
Crate features
Jiff has several crate features for customizing support for Rust's standard
library, serde support and whether to embed a copy of the Time Zone Database
into your binary.
The "crate features" section of the
documentation lists the full set of supported features.
Performance
The most important design goal of Jiff is to be a Top issues
#408Feature request: Recurrence rule expansion support12 comments · 2025-09-07#384jiff_diesel: default serialization format for sqlite is especially error-prone10 comments · 2025-06-01#542Big increases in file size after v0.2.165 comments · 2026-04-24#590Feat: enable custom TimeZone implementations4 comments · 2026-06-23#251reconsider approach to `Span` integration for PostgreSQL in `jiff-diesel` (and probably `jiff-sqlx`)4 comments · 2025-02-11#30export `TimeZone` to TZif3 comments · 2024-07-22#637Why does enabling `tzdb-bundle-always` not disable lookups of the system time zone database if `tzdb-zoneinfo` is enabled?2 comments · 2026-08-11#715COMPARE.md symlink is broken1 comments · 2026-11-17
Discussions
#663Counting Days In Span Without Weekends1 comments · 2026-10-16#636Could `jiff-tzdb` build the time zone database based on the host's at compile time?2 comments · 2026-08-10#626Why does subtracting two `Timestamps` return a `Span` instead of a `SignedDuration`1 comments · 2026-08-05#621How to strictly parse an RFC3339 timestamp?1 comments · 2026-08-02#552How do I iterate over days starting with tommorow or yesterday?2 comments · 2026-05-16#560Why don't Jiff's `strftime` and `strptime` routines validate the format string separately from formatting or parsing a datetime?2 comments · 2026-05-04#544Why isn't `std::fmt::Debug` implemented for types like `jiff::civil::Date`?2 comments · 2026-04-30#536Questions about Span range and arithmetic1 comments · 2026-04-09