Chronotope Chrono Versions Save

This release fixes a panic introduced in chrono 0.4.27 in FromStr<DateTime<Utc>> (#1253).

Chrono now has a Discord channel.

Fixes

• Fix arbitrary string slicing in parse_rfc3339_relaxed (#1254)

Deprecations

• Deprecate TimeZone::datetime_from_str (#1251)

Documentation

• Correct documentation for FromStr for Weekday and Month (#1226, thanks @wfraser)

Internal improvements

• Revert "add test_issue_866" (#1238)
• CI: run tests on i686 and wasm32-wasi (#1237)
• CI: Include doctests for code coverage (#1248)
• Move benchmarks to a separate crate (#1243) This allows us to upgrade the criterion dependency to 5.1 without changing our MSRV.
• Add Discord link to README (#1240, backported in #1256)

Thanks to all contributors on behalf of the chrono team, @djc and @pitdicker!

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.

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.

Added

• Duration + Date overloading is now allowed.

Changed

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

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.

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.

Language changes.

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

Fixed tests per language changes and .travis.yml.

This also switches to the crates.io dependency unconditionally.

Language changes.

• Eq no longer accepts the reflexive type parameter. (this doesn't change the actual interface, as Eq is simply a marker for total ordering. PartialEq retains it.)

Language changes.

• #[deriving] is now #[derive].
• prelude no longer imports many items by default.
• [T, ..n] is no longer valid.
• a temporary fix for #[derive(Hash)] failing out.
• the formatting error uses a dedicated type instead of IoError.