Introduction

time is a date and time library for Rust. It is:

  • Easy and safe. time has a straightforward API without footguns.
  • space optimal and efficient. time provides support for dates in the ±9999 year range, with nanosecond precision; ranges up to ±999,999 are supported with the large-dates feature.
  • serde ready. Supports ISO8601, RFC2822 and RFC3339 with the serde-well-known feature. Not in the list? Make your format.
  • const ready. A majority of the API is const, making it ready for resource-constrained applications, with optional macros for easy date creation.
  • no-std support with alloc and std features.
  • numeric traits. Use durations easily: 2.seconds().
  • Supports Windows, Linux, macOS, WebAssembly targets among others.
  • Six-month minimum supported Rust version guarantee.

And more...

Getting started

This short tutorial describes basic usage of time, to get operational quickly.

  1. Install time. Add it to your Cargo.toml. We'll enable macros:
[dependencies]
time = { version = "0.3", features = ["macros"] }
  1. Get the current time With the crate feature std a UTC offset (OffsetDateTime) is available, but with the crate feature local-offset, we can also get the local time.

#![allow(unused)]
fn main() {
use time::OffsetDateTime;

let now = OffsetDateTime::now_utc();
// let local = OffsetDateTime::now_local();

println!("{now}");
}
  1. Create dates and times. We can create dates (Date), dates with times (PrimitiveDateTime) and date times with an UTC offset (OffsetDateTime). A simple Time is also available.

#![allow(unused)]
fn main() {
use time::{Date, PrimitiveDateTime, OffsetDateTime, UtcOffset};
use time::Weekday::Wednesday;

let date = Date::from_iso_week_date(2022, 1, Wednesday).unwrap();
let datetime = date.with_hms(13, 0, 55).unwrap();
let datetime_off = datetime.assume_offset(UtcOffset::from_hms(1, 2, 3).unwrap());

println!("{date}, {datetime}, {datetime_off}");
// 2022-01-01, 2022-01-01 13:00:55.0, 2022-01-01 13:00:55.0 +01:02:03
}

With the macros feature:


#![allow(unused)]
fn main() {
use time::macros::{date, datetime};

let date = date!(2022-01-01);
let datetime = datetime!(2022-01-01 13:00:55);
let datetime_off = datetime!(2022-01-01 13:00:55 +1:02:03);

println!("{date}, {datetime}, {datetime_off}");
// 2022-01-01, 2022-01-01 13:00:55.0, 2022-01-01 13:00:55.0 +01:02:03
}
  1. Manipulate dates and use Durations:

#![allow(unused)]
fn main() {
use time::Duration;
use time::macros::{datetime};

let a = datetime!(2022-01-01 10:00:55);
let b = datetime!(2022-01-01 13:00:00);

let duration: Duration = b - a;

println!("{}", b - a);
// 2h59m5s
}

time vs chrono

time 0.1 was originally a thin wrapper around libc time functions. Because it was relatively barebones, chrono was developed as a richer API on top of time 0.1.

Around 2019, the time crate, which was unmaintained since August 2016, was picked up for maintenance again. time has since been rewritten as of time 0.2, and is incompatible with the 0.1 version.

Today:

  • time has been rewritten from 0.1,and is actively developed.
  • chrono depends on time 0.1, an old version unrelated with current time, and is actively developed as well.

Since they are incompatible with each other, please choose the library that fits your needs.