v0.1.6

Fixed tests per language changes and .travis.yml.

This also switches to the crates.io dependency unconditionally.

v0.1.5

Language changes.

• Add and Sub requires a value instead of a reference.
• Tuple indexing is now ungated.

v0.1.4

Language changes.

• Copy is now opt-in. Every Copyable type is made to implement Copy. While unlikely, I haven't deeply thought about Copyability so it might change in 0.2.

Added

• Added a BIG (friendly) limitation section to the README.

Fixed

• Fixed a bug that Date::and_* methods with an offset that can change the date are
  off by one day.

v0.1.3

Added

• {Date,Time,DateTime}::with_offset methods have been added.

• LocalResult now implements a common set of traits.

• LocalResult::and_* methods have been added.
  They are useful for safely chaining LocalResult<Date<Off>> methods to make LocalResult<DateTime<Off>>.

Changed

• Offset::name now returns SendStr.

• {Date,Time} - Duration overloadings are now allowed.

v0.1.2

Added

• Duration + Date overloading is now allowed.

Changed

• Chrono no longer needs num dependency.
• Removed unused unsafe checks.

v0.1.1

Language changes, updated documentations.

• std::fmt::WriteError is now std::fmt::Error.
• abandoned rust-ci for documentations (sorry, but it didn't work
  nowdays ;_;), we are now publishing directly to Github pages.

v0.1.0

The initial version that was available to crates.io. Description from README of chrono 0.1.3:

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

• Chrono strictly adheres to ISO 8601.
• Chrono is timezone-aware by default, with separate timezone-naive types.
• Chrono is space-optimal and (while not being the primary goal) reasonably efficient.

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

• Initial research on the wiki
• Dietrich Epp's datetime-rs
• Luis de Bethencourt's rust-datetime

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

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

let utc: DateTime<UTC> = UTC::now();       // e.g. `2014-11-28T12:45:59.324310806Z`
let local: DateTime<Local> = 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.

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

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

let dt = UTC.ymd(2014, 7, 8).and_hms_milli(9, 10, 11, 12); // `2014-07-08T09:10:11.012Z`
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, 8).and_hms_opt(80, 15, 33), LocalResult::None);
assert_eq!(UTC.ymd_opt(2014, 7, 38).and_hms_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:

# /* 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).and_hms_nano(21, 45, 59, 324310806);

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

// 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(29).unwrap().weekday(), Weekday::Sat); // 2014-11-29 is Saturday
assert_eq!(dt.with_day(32), None);
assert_eq!(dt.with_year(-300).unwrap().num_days_from_ce(), -109606); // November 29, 301 BCE

// arithmetic operations
assert_eq!(UTC.ymd(2014, 11, 14).and_hms(8, 9, 10) - UTC.ymd(2014, 11, 14).and_hms(10, 9, 8),
           Duration::seconds(-2 * 3600 + 2));
assert_eq!(UTC.ymd(1970, 1, 1).and_hms(0, 0, 0) + Duration::seconds(1_000_000_000),
           UTC.ymd(2001, 9, 9).and_hms(1, 46, 40));
assert_eq!(UTC.ymd(1970, 1, 1).and_hms(0, 0, 0) - Duration::seconds(1_000_000_000),
           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.

use chrono::{UTC, Offset};

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

assert_eq!(dt.to_string(), "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.

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

# // these *may* fail, but only very rarely. just rerun the test if you were that unfortunate ;)
assert_eq!(UTC::today(), UTC::now().date());
assert_eq!(Local::today(), Local::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".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.