BurntSushi /jiff

A datetime library for Rust that encourages you to jump into the pit of success.

★ 3,154⑂ 141👁 15⑃ 356● 288▤ 0
RustUnlicenseCreated 2024-02-17
More from this author
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

Discussions

Snapshot: 2026-11-17T21:58:29Z · Data license Apache-2.0 · JSON