chrono 0.1.14

Date and time library for Rust failed to build chrono-0.1.14

Chrono 0.1.13

Chrono on Travis CI

Date and time handling for Rust. (also known as rust-chrono) It aims to be a feature-complete superset of the time library. In particular,

  • Chrono strictly adheres to ISO 8601.

There were several previous attempts to bring a good date and time library to Rust, which Chrono builts upon and should acknowledge:

Complete Documentation



Chrono used to have a Duration type, which represents the time span. Now Rust standard library includes it as std::time::duration::Duration and Chrono simply reexports it.

Date and Time

Chrono provides a DateTime type for the combined date and time.

DateTime, among others, is timezone-aware and must be constructed from the timezone object (Offset). DateTimes with different offsets do not mix, but can be converted to each other.

You can get the current date and time in the UTC timezone (UTC::now()) or in the local timezone (Local::now()).

use chrono::{UTC, Local, DateTime};

let utc: DateTime<UTC> = UTC::now();       // e.g. `2014-11-28T12:45:59.324310806Z`


use chrono::{UTC, Offset, Weekday, LocalResult};

assert_eq!(dt, UTC.yo(2014, 189).and_hms(9, 10, 11));
assert_eq!(dt, UTC.isoywd(2014, 28, Weekday::Tue).and_hms(9, 10, 11));

assert_eq!(dt, UTC.ymd(2014, 7, 8).and_hms_micro(9, 10, 11, 12_000));
assert_eq!(dt, UTC.ymd(2014, 7, 8).and_hms_nano(9, 10, 11, 12_000_000));

// dynamic verification
assert_eq!(UTC.ymd_opt(2014, 7, 8).and_hms_opt(21, 15, 33),
           LocalResult::Single(UTC.ymd(2014, 7, 8).and_hms(21, 15, 33)));
assert_eq!(UTC.ymd_opt(2014, 7, 38).and_hms_opt(21, 15, 33), LocalResult::None);


use chrono::{UTC, Local, Datelike, Timelike, Weekday, Duration};

let dt = Local::now();

// property accessors

// offset accessor and manipulation
assert_eq!(dt.offset().local_minus_utc(), Duration::hours(9));
assert_eq!(dt.with_offset(UTC), UTC.ymd(2014, 11, 28).and_hms_nano(12, 45, 59, 324310806));

// a sample of property manipulations (validates dynamically)
assert_eq!(dt.with_day(32), None);

// arithmetic operations
assert_eq!(UTC.ymd(2014, 11, 14).and_hms(8, 9, 10) - UTC.ymd(2014, 11, 14).and_hms(10, 9, 8),
assert_eq!(UTC.ymd(1970, 1, 1).and_hms(0, 0, 0) + Duration::seconds(1_000_000_000),

Formatting is done via the format method, which format is equivalent to the familiar strftime format. The default to_string method and {:?} specifier also give a reasonable representation.

use chrono::{UTC, Offset};

let dt = UTC.ymd(2014, 11, 28).and_hms(12, 0, 9);


Individual date and time

Chrono also provides an individual date type (Date) and time type (Time). They also have offsets attached, and have to be constructed via offsets. Most operations available to DateTime are also available to Date and Time whenever appropriate.

use chrono::{UTC, Local, Offset, LocalResult, Datelike, Weekday};

assert_eq!(UTC::today(), UTC::now().date());

assert_eq!(UTC.ymd(2014, 11, 28).weekday(), Weekday::Fri);
assert_eq!(UTC.ymd_opt(2014, 11, 31), LocalResult::None);
assert_eq!(UTC.hms_milli(7, 8, 9, 10).format("%H%M%S").to_string(), "070809");

DateTime has two methods, date and time, which return narrow views to its date and time components respectively.

Naive date and time

Chrono provides naive counterparts to Date, Time and DateTime as NaiveDate, NaiveTime and NaiveDateTime respectively.

They have almost equivalent interfaces as their timezone-aware twins, but are not associated to offsets obviously and can be quite low-level. They are mostly useful for building blocks for higher-level types.





Chrono inherently does not support an inaccurate or partial date and time representation. Any operation that can be ambiguous will return None in such cases. For example, "a month later" of 2014-01-30 is not well-defined and consequently UTC.ymd(2014, 1, 30).with_month(2) returns None.

Advanced offset handling and date/time parsing is not yet supported (but is planned).