Chrono

Chrono on Travis CI

Date and time handling for Rust. It aims to be a feature-complete superset of the time library. In particular,

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

Complete Documentation

Duration

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()).

~~~~ {.rust} use chrono::{UTC, Local, DateTime};

let utc: DateTime = UTC::now(); // e.g. 2014-11-28T12:45:59.324310806Z let local: DateTime = Local::now(); // e.g. 2014-11-28T21:45:59.324310806+09:00

let _ = utc; let _ = local;

~~~~

Alternatively, you can create your own date and time. This is a bit verbose due to Rust's lack of function and method overloading, but in turn we get a rich combination of initialization methods.

~~~~ {.rust} use chrono::{UTC, Offset, Weekday, LocalResult};

let dt = UTC.ymd(2014, 7, 8).andhms(9, 10, 11); // 2014-07-08T09:10:11Z // July 8 is 188th day of the year 2014 (o for "ordinal") asserteq!(dt, UTC.yo(2014, 189).andhms(9, 10, 11)); // July 8 is Tuesday in ISO week 28 of the year 2014. asserteq!(dt, UTC.isoywd(2014, 28, Weekday::Tue).and_hms(9, 10, 11));

let dt = UTC.ymd(2014, 7, 8).andhmsmilli(9, 10, 11, 12); // 2014-07-08T09:10:11.012Z asserteq!(dt, UTC.ymd(2014, 7, 8).andhmsmicro(9, 10, 11, 12000)); asserteq!(dt, UTC.ymd(2014, 7, 8).andhmsnano(9, 10, 11, 12000_000));

// dynamic verification asserteq!(UTC.ymdopt(2014, 7, 8).andhmsopt(21, 15, 33), LocalResult::Single(UTC.ymd(2014, 7, 8).andhms(21, 15, 33))); asserteq!(UTC.ymdopt(2014, 7, 8).andhmsopt(80, 15, 33), LocalResult::None); asserteq!(UTC.ymdopt(2014, 7, 38).andhms_opt(21, 15, 33), LocalResult::None); ~~~~

Various properties are available to the date and time, and can be altered individually. Most of them are defined in the traits Datelike and Timelike which you should use before. Addition and subtraction is also supported. The following illustrates most supported operations to the date and time:

~~~~ {.rust}

/* we intentionally fake the datetime...

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

// assume this returned 2014-11-28T21:45:59.324310806+09:00: let dt = Local::now();

*/ // up to here. we now define a fixed datetime for the illustrative purpose.

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

let dt = FixedOffset::east(9*3600).ymd(2014, 11, 28).andhmsnano(21, 45, 59, 324310806);

// property accessors asserteq!((dt.year(), dt.month(), dt.day()), (2014, 11, 28)); asserteq!((dt.month0(), dt.day0()), (10, 27)); // for unfortunate souls asserteq!((dt.hour(), dt.minute(), dt.second()), (21, 45, 59)); asserteq!(dt.weekday(), Weekday::Fri); asserteq!(dt.weekday().numberfrommonday(), 5); // Mon=1, ..., Sat=7 asserteq!(dt.ordinal(), 332); // the day of year asserteq!(dt.numdaysfromce(), 735565); // the number of days from and including Jan 1, 1

// offset accessor and manipulation asserteq!(dt.offset().localminusutc(), Duration::hours(9)); asserteq!(dt.withoffset(UTC), UTC.ymd(2014, 11, 28).andhms_nano(12, 45, 59, 324310806));

// a sample of property manipulations (validates dynamically) asserteq!(dt.withday(29).unwrap().weekday(), Weekday::Sat); // 2014-11-29 is Saturday asserteq!(dt.withday(32), None); asserteq!(dt.withyear(-300).unwrap().numdaysfrom_ce(), -109606); // November 29, 301 BCE

// arithmetic operations asserteq!(UTC.ymd(2014, 11, 14).andhms(8, 9, 10) - UTC.ymd(2014, 11, 14).andhms(10, 9, 8), Duration::seconds(-2 * 3600 + 2)); asserteq!(UTC.ymd(1970, 1, 1).andhms(0, 0, 0) + Duration::seconds(1000000000), UTC.ymd(2001, 9, 9).andhms(1, 46, 40)); asserteq!(UTC.ymd(1970, 1, 1).andhms(0, 0, 0) - Duration::seconds(1000000000), UTC.ymd(1938, 4, 24).and_hms(22, 13, 20)); ~~~~

Formatting is done via the format method, which format is equivalent to the familiar strftime format. The default to_string method also gives a reasonable representation.

~~~~ {.rust} use chrono::{UTC, Offset};

let dt = UTC.ymd(2014, 11, 28).andhms(12, 0, 9); asserteq!(dt.format("%Y-%m-%d %H:%M:%S").tostring(), "2014-11-28 12:00:09".intostring()); asserteq!(dt.format("%a %b %e %T %Y").tostring(), "Fri Nov 28 12:00:09 2014".intostring()); asserteq!(dt.format("%a %b %e %T %Y").tostring(), dt.format("%c").tostring());

asserteq!(dt.tostring(), "2014-11-28T12:00:09Z".into_string()); ~~~~

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.

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

// these may fail, but only very rarely. just rerun the test if you were that unfortunate ;)

asserteq!(UTC::today(), UTC::now().date()); asserteq!(Local::today(), Local::now().date());

asserteq!(UTC.ymd(2014, 11, 28).weekday(), Weekday::Fri); asserteq!(UTC.ymdopt(2014, 11, 31), LocalResult::None); asserteq!(UTC.hmsmilli(7, 8, 9, 10).format("%H%M%S").tostring(), "070809".into_string()); ~~~~

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.