2018-04-02 00:08:47 +00:00
[Chrono][docsrs]: Date and Time for Rust
========================================
2014-04-01 17:14:57 +00:00
2018-04-20 03:23:21 +00:00
[![Join the chat at https://gitter.im/chrono-rs/chrono ](https://badges.gitter.im/chrono-rs/chrono.svg )](https://gitter.im/chrono-rs/chrono?utm_source=badge& utm_medium=badge& utm_campaign=pr-badge& utm_content=badge)
2014-11-28 14:53:22 +00:00
[![Chrono on Travis CI][travis-image]][travis]
2016-08-16 18:05:09 +00:00
[![Chrono on Appveyor][appveyor-image]][appveyor]
[![Chrono on crates.io][cratesio-image]][cratesio]
2017-02-05 21:15:57 +00:00
[![Chrono on docs.rs][docsrs-image]][docsrs]
2014-04-01 17:14:57 +00:00
2017-02-05 20:49:32 +00:00
[travis-image]: https://travis-ci.org/chronotope/chrono.svg?branch=master
[travis]: https://travis-ci.org/chronotope/chrono
[appveyor-image]: https://ci.appveyor.com/api/projects/status/2ia91ofww4w31m2w/branch/master?svg=true
[appveyor]: https://ci.appveyor.com/project/chronotope/chrono
2016-08-16 18:05:09 +00:00
[cratesio-image]: https://img.shields.io/crates/v/chrono.svg
[cratesio]: https://crates.io/crates/chrono
2018-04-02 00:08:47 +00:00
[docsrs-image]: https://docs.rs/chrono/badge.svg
[docsrs]: https://docs.rs/chrono
2017-02-05 21:15:57 +00:00
Date and time handling for Rust.
2016-01-23 05:33:20 +00:00
It aims to be a feature-complete superset of
2016-01-28 07:14:03 +00:00
the [time ](https://github.com/rust-lang-deprecated/time ) library.
2014-11-28 14:53:22 +00:00
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,
2017-02-20 07:04:32 +00:00
which Chrono builds upon and should acknowledge:
2014-11-28 14:53:22 +00:00
2015-08-08 04:09:44 +00:00
* [Initial research on
the wiki](https://github.com/rust-lang/rust-wiki-backup/blob/master/Lib-datetime.md)
2014-11-28 14:53:22 +00:00
* Dietrich Epp's [datetime-rs ](https://github.com/depp/datetime-rs )
* Luis de Bethencourt's [rust-datetime ](https://github.com/luisbg/rust-datetime )
2014-04-01 17:14:57 +00:00
2017-06-21 17:54:26 +00:00
Any significant changes to Chrono are documented in
the [`CHANGELOG.md` ](https://github.com/chronotope/chrono/blob/master/CHANGELOG.md ) file.
2014-09-14 05:29:52 +00:00
2015-02-15 12:26:11 +00:00
## Usage
Put this in your `Cargo.toml` :
```toml
[dependencies]
2017-06-20 18:27:46 +00:00
chrono = "0.4"
2015-02-15 12:26:11 +00:00
```
2017-07-09 19:33:11 +00:00
Or, if you want [Serde ](https://github.com/serde-rs/serde ) include the feature
like this:
2016-07-25 18:45:53 +00:00
2016-06-22 04:51:18 +00:00
```toml
[dependencies]
2017-07-09 19:33:11 +00:00
chrono = { version = "0.4", features = ["serde"] }
2016-06-22 04:51:18 +00:00
```
2016-07-25 18:45:53 +00:00
Then put this in your crate root:
2015-02-15 12:26:11 +00:00
2015-02-18 16:48:29 +00:00
```rust
2015-02-15 12:26:11 +00:00
extern crate chrono;
```
2017-02-05 23:17:01 +00:00
Avoid using `use chrono::*;` as Chrono exports several modules other than types.
If you prefer the glob imports, use the following instead:
```rust
use chrono::prelude::*;
```
2014-12-13 13:16:38 +00:00
## Overview
### Duration
2014-11-28 14:53:22 +00:00
2017-02-05 23:17:01 +00:00
Chrono currently uses
the [`time::Duration` ](https://doc.rust-lang.org/time/time/struct.Duration.html ) type
from the `time` crate to represent the magnitude of a time span.
Since this has the same name to the newer, standard type for duration,
the reference will refer this type as `OldDuration` .
Note that this is an "accurate" duration represented as seconds and
2017-02-05 20:49:32 +00:00
nanoseconds and does not represent "nominal" components such as days or
2017-02-05 23:17:01 +00:00
months.
Chrono does not yet natively support
the standard [`Duration` ](https://doc.rust-lang.org/std/time/struct.Duration.html ) type,
but it will be supported in the future.
Meanwhile you can convert between two types with
[`Duration::from_std` ](https://doc.rust-lang.org/time/time/struct.Duration.html#method.from_std )
and
[`Duration::to_std` ](https://doc.rust-lang.org/time/time/struct.Duration.html#method.to_std )
methods.
2014-11-28 14:53:22 +00:00
2014-12-13 13:16:38 +00:00
### Date and Time
2014-11-28 14:53:22 +00:00
2016-06-14 04:20:21 +00:00
Chrono provides a
2017-06-21 05:03:49 +00:00
[**`DateTime`** ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html )
2016-06-14 04:20:21 +00:00
type to represent a date and a time in a timezone.
For more abstract moment-in-time tracking such as internal timekeeping
that is unconcerned with timezones, consider
[`time::SystemTime` ](https://doc.rust-lang.org/std/time/struct.SystemTime.html ),
which tracks your system clock, or
[`time::Instant` ](https://doc.rust-lang.org/std/time/struct.Instant.html ), which
is an opaque but monotonically-increasing representation of a moment in time.
`DateTime` is timezone-aware and must be constructed from
2017-06-20 18:27:46 +00:00
the [**`TimeZone`** ](https://docs.rs/chrono/0.4.0/chrono/offset/trait.TimeZone.html ) object,
2016-07-25 18:45:53 +00:00
which defines how the local date is converted to and back from the UTC date.
There are three well-known `TimeZone` implementations:
2017-06-21 15:33:17 +00:00
* [**`Utc`** ](https://docs.rs/chrono/0.4.0/chrono/offset/struct.Utc.html ) specifies the UTC time zone. It is most efficient.
2016-07-25 18:45:53 +00:00
2017-06-21 05:03:49 +00:00
* [**`Local`** ](https://docs.rs/chrono/0.4.0/chrono/offset/struct.Local.html ) specifies the system local time zone.
2016-07-25 18:45:53 +00:00
2017-06-21 05:03:49 +00:00
* [**`FixedOffset`** ](https://docs.rs/chrono/0.4.0/chrono/offset/struct.FixedOffset.html ) specifies
2016-07-25 18:45:53 +00:00
an arbitrary, fixed time zone such as UTC+09:00 or UTC-10:30.
This often results from the parsed textual date and time.
Since it stores the most information and does not depend on the system environment,
you would want to normalize other `TimeZone` s into this type.
`DateTime` s with different `TimeZone` types are distinct and do not mix,
but can be converted to each other using
2017-06-21 05:03:49 +00:00
the [`DateTime::with_timezone` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.with_timezone ) method.
2014-11-28 14:53:22 +00:00
2016-07-25 18:45:53 +00:00
You can get the current date and time in the UTC time zone
2017-06-21 15:33:17 +00:00
([`Utc::now()`](https://docs.rs/chrono/0.4.0/chrono/offset/struct.Utc.html#method.now))
2016-07-25 18:45:53 +00:00
or in the local time zone
2017-06-21 05:03:49 +00:00
([`Local::now()`](https://docs.rs/chrono/0.4.0/chrono/offset/struct.Local.html#method.now)).
2014-11-28 14:53:22 +00:00
2017-04-10 20:24:32 +00:00
```rust
2017-02-05 23:17:01 +00:00
use chrono::prelude::*;
2014-11-28 14:53:22 +00:00
2017-06-21 15:33:17 +00:00
let utc: DateTime< Utc > = Utc::now(); // e.g. `2014-11-28T12:45:59.324310806Z`
2014-11-28 14:53:22 +00:00
let local: DateTime< Local > = Local::now(); // e.g. `2014-11-28T21:45:59.324310806+09:00`
2017-04-10 20:24:32 +00:00
```
2014-11-28 14:53:22 +00:00
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.
2017-04-10 20:24:32 +00:00
```rust
2017-02-05 23:17:01 +00:00
use chrono::prelude::*;
use chrono::offset::LocalResult;
2014-11-28 14:53:22 +00:00
2017-06-21 15:33:17 +00:00
let dt = Utc.ymd(2014, 7, 8).and_hms(9, 10, 11); // `2014-07-08T09:10:11Z`
2014-11-28 14:53:22 +00:00
// July 8 is 188th day of the year 2014 (`o` for "ordinal")
2017-06-21 15:33:17 +00:00
assert_eq!(dt, Utc.yo(2014, 189).and_hms(9, 10, 11));
2014-11-28 14:53:22 +00:00
// July 8 is Tuesday in ISO week 28 of the year 2014.
2017-06-21 15:33:17 +00:00
assert_eq!(dt, Utc.isoywd(2014, 28, Weekday::Tue).and_hms(9, 10, 11));
2014-11-28 14:53:22 +00:00
2017-06-21 15:33:17 +00:00
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));
2014-11-28 14:53:22 +00:00
// dynamic verification
2017-06-21 15:33:17 +00:00
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);
2015-02-18 17:21:52 +00:00
// other time zone objects can be used to construct a local datetime.
// obviously, `local_dt` is normally different from `dt` , but `fixed_dt` should be identical.
let local_dt = Local.ymd(2014, 7, 8).and_hms_milli(9, 10, 11, 12);
let fixed_dt = FixedOffset::east(9 * 3600).ymd(2014, 7, 8).and_hms_milli(18, 10, 11, 12);
assert_eq!(dt, fixed_dt);
2017-04-10 20:24:32 +00:00
```
2014-11-28 14:53:22 +00:00
Various properties are available to the date and time, and can be altered individually.
2017-06-20 18:27:46 +00:00
Most of them are defined in the traits [`Datelike` ](https://docs.rs/chrono/0.4.0/chrono/trait.Datelike.html ) and
[`Timelike` ](https://docs.rs/chrono/0.4.0/chrono/trait.Timelike.html ) which you should `use` before.
2014-11-28 14:53:22 +00:00
Addition and subtraction is also supported.
The following illustrates most supported operations to the date and time:
2017-04-10 20:24:32 +00:00
```rust
2017-02-05 23:17:01 +00:00
use chrono::prelude::*;
use time::Duration;
2014-11-28 14:53:22 +00:00
// assume this returned `2014-11-28T21:45:59.324310806+09:00` :
let dt = Local::now();
// 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
2015-01-12 17:03:12 +00:00
// time zone accessor and manipulation
2017-02-06 19:05:05 +00:00
assert_eq!(dt.offset().fix().local_minus_utc(), 9 * 3600);
2015-01-12 17:03:12 +00:00
assert_eq!(dt.timezone(), FixedOffset::east(9 * 3600));
2017-06-21 15:33:17 +00:00
assert_eq!(dt.with_timezone(& Utc), Utc.ymd(2014, 11, 28).and_hms_nano(12, 45, 59, 324310806));
2014-11-28 14:53:22 +00:00
// 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
2017-06-21 15:33:17 +00:00
let dt1 = Utc.ymd(2014, 11, 14).and_hms(8, 9, 10);
let dt2 = Utc.ymd(2014, 11, 14).and_hms(10, 9, 8);
2017-02-05 23:17:01 +00:00
assert_eq!(dt1.signed_duration_since(dt2), Duration::seconds(-2 * 3600 + 2));
assert_eq!(dt2.signed_duration_since(dt1), Duration::seconds(2 * 3600 - 2));
2017-06-21 15:33:17 +00:00
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));
2017-04-10 20:24:32 +00:00
```
2014-11-28 14:53:22 +00:00
2017-06-21 05:03:49 +00:00
Formatting is done via the [`format` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.format ) method,
2014-11-28 14:53:22 +00:00
which format is equivalent to the familiar `strftime` format.
2017-06-20 18:27:46 +00:00
(See the [`format::strftime` module documentation ](https://docs.rs/chrono/0.4.0/chrono/format/strftime/index.html#specifiers )
2016-07-25 18:45:53 +00:00
for full syntax.)
2015-02-18 20:08:00 +00:00
2015-01-09 18:27:24 +00:00
The default `to_string` method and `{:?}` specifier also give a reasonable representation.
2017-06-21 05:03:49 +00:00
Chrono also provides [`to_rfc2822` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.to_rfc2822 ) and
[`to_rfc3339` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.to_rfc3339 ) methods
2016-07-25 18:45:53 +00:00
for well-known formats.
2014-11-28 14:53:22 +00:00
2017-04-10 20:24:32 +00:00
```rust
2017-02-05 23:17:01 +00:00
use chrono::prelude::*;
2014-11-28 14:53:22 +00:00
2017-06-21 15:33:17 +00:00
let dt = Utc.ymd(2014, 11, 28).and_hms(12, 0, 9);
2015-01-09 18:27:24 +00:00
assert_eq!(dt.format("%Y-%m-%d %H:%M:%S").to_string(), "2014-11-28 12:00:09");
assert_eq!(dt.format("%a %b %e %T %Y").to_string(), "Fri Nov 28 12:00:09 2014");
2014-11-28 14:53:22 +00:00
assert_eq!(dt.format("%a %b %e %T %Y").to_string(), dt.format("%c").to_string());
2015-01-09 18:27:24 +00:00
assert_eq!(dt.to_string(), "2014-11-28 12:00:09 UTC");
2015-02-18 20:08:00 +00:00
assert_eq!(dt.to_rfc2822(), "Fri, 28 Nov 2014 12:00:09 +0000");
assert_eq!(dt.to_rfc3339(), "2014-11-28T12:00:09+00:00");
2018-01-24 23:55:10 +00:00
assert_eq!(format!("{:?}", dt), "2014-11-28T12:00:09Z");
let now = Utc::now();
// Will display today's date with nanoseconds
println!("{:?}", now); // 2018-1-24T12:00:00.000000000Z
2017-04-10 20:24:32 +00:00
```
2014-11-28 14:53:22 +00:00
2015-02-18 16:48:29 +00:00
Parsing can be done with three methods:
2016-07-25 18:45:53 +00:00
1. The standard [`FromStr` ](https://doc.rust-lang.org/std/str/trait.FromStr.html ) trait
(and [`parse` ](https://doc.rust-lang.org/std/primitive.str.html#method.parse ) method
2017-06-21 15:33:17 +00:00
on a string) can be used for parsing `DateTime<FixedOffset>` , `DateTime<Utc>` and
2016-07-25 18:45:53 +00:00
`DateTime<Local>` values. This parses what the `{:?}`
([`std::fmt::Debug`](https://doc.rust-lang.org/std/fmt/trait.Debug.html))
format specifier prints, and requires the offset to be present.
2015-02-04 17:37:54 +00:00
2017-06-21 05:03:49 +00:00
2. [`DateTime::parse_from_str` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.parse_from_str ) parses
2016-07-25 18:45:53 +00:00
a date and time with offsets and returns `DateTime<FixedOffset>` .
2015-02-18 16:48:29 +00:00
This should be used when the offset is a part of input and the caller cannot guess that.
It *cannot* be used when the offset can be missing.
2017-06-21 05:03:49 +00:00
[`DateTime::parse_from_rfc2822` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.parse_from_rfc2822 )
2016-07-25 18:45:53 +00:00
and
2017-06-21 05:03:49 +00:00
[`DateTime::parse_from_rfc3339` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.parse_from_rfc3339 )
2016-07-25 18:45:53 +00:00
are similar but for well-known formats.
2015-02-04 17:37:54 +00:00
2017-06-20 18:27:46 +00:00
3. [`Offset::datetime_from_str` ](https://docs.rs/chrono/0.4.0/chrono/offset/trait.TimeZone.html#method.datetime_from_str ) is
2016-07-25 18:45:53 +00:00
similar but returns `DateTime` of given offset.
2015-02-18 16:48:29 +00:00
When the explicit offset is missing from the input, it simply uses given offset.
2016-01-23 05:33:20 +00:00
It issues an error when the input contains an explicit offset different
from the current offset.
2015-02-04 17:37:54 +00:00
2016-07-25 18:45:53 +00:00
More detailed control over the parsing process is available via
2017-06-20 18:27:46 +00:00
[`format` ](https://docs.rs/chrono/0.4.0/chrono/format/index.html ) module.
2015-02-04 17:37:54 +00:00
2017-04-10 20:24:32 +00:00
```rust
2017-02-05 23:17:01 +00:00
use chrono::prelude::*;
2015-02-04 17:37:54 +00:00
2017-06-21 15:33:17 +00:00
let dt = Utc.ymd(2014, 11, 28).and_hms(12, 0, 9);
2015-02-18 17:21:52 +00:00
let fixed_dt = dt.with_timezone(&FixedOffset::east(9*3600));
2015-02-18 16:48:29 +00:00
// method 1
2017-06-21 15:33:17 +00:00
assert_eq!("2014-11-28T12:00:09Z".parse::< DateTime < Utc > >(), Ok(dt.clone()));
assert_eq!("2014-11-28T21:00:09+09:00".parse::< DateTime < Utc > >(), Ok(dt.clone()));
2015-02-18 17:21:52 +00:00
assert_eq!("2014-11-28T21:00:09+09:00".parse::< DateTime < FixedOffset > >(), Ok(fixed_dt.clone()));
2015-02-18 16:48:29 +00:00
// method 2
assert_eq!(DateTime::parse_from_str("2014-11-28 21:00:09 +09:00", "%Y-%m-%d %H:%M:%S %z"),
2015-02-18 17:21:52 +00:00
Ok(fixed_dt.clone()));
2016-01-23 05:33:20 +00:00
assert_eq!(DateTime::parse_from_rfc2822("Fri, 28 Nov 2014 21:00:09 +0900"),
Ok(fixed_dt.clone()));
2015-02-18 20:08:00 +00:00
assert_eq!(DateTime::parse_from_rfc3339("2014-11-28T21:00:09+09:00"), Ok(fixed_dt.clone()));
// method 3
2017-06-21 15:33:17 +00:00
assert_eq!(Utc.datetime_from_str("2014-11-28 12:00:09", "%Y-%m-%d %H:%M:%S"), Ok(dt.clone()));
assert_eq!(Utc.datetime_from_str("Fri Nov 28 12:00:09 2014", "%a %b %e %T %Y"), Ok(dt.clone()));
2015-02-04 17:37:54 +00:00
// oops, the year is missing!
2017-06-21 15:33:17 +00:00
assert!(Utc.datetime_from_str("Fri Nov 28 12:00:09", "%a %b %e %T %Y").is_err());
2015-02-04 17:37:54 +00:00
// oops, the format string does not include the year at all!
2017-06-21 15:33:17 +00:00
assert!(Utc.datetime_from_str("Fri Nov 28 12:00:09", "%a %b %e %T").is_err());
2015-02-04 17:37:54 +00:00
// oops, the weekday is incorrect!
2017-06-21 15:33:17 +00:00
assert!(Utc.datetime_from_str("Sat Nov 28 12:00:09 2014", "%a %b %e %T %Y").is_err());
2017-04-10 20:24:32 +00:00
```
2015-02-04 17:37:54 +00:00
2015-02-18 20:42:18 +00:00
### Individual date
2014-11-28 14:53:22 +00:00
2017-06-21 05:03:49 +00:00
Chrono also provides an individual date type ([**`Date`**](https://docs.rs/chrono/0.4.0/chrono/struct.Date.html)).
2015-02-18 20:42:18 +00:00
It also has time zones attached, and have to be constructed via time zones.
Most operations available to `DateTime` are also available to `Date` whenever appropriate.
2014-11-28 14:53:22 +00:00
2017-04-10 20:24:32 +00:00
```rust
2017-02-05 23:17:01 +00:00
use chrono::prelude::*;
use chrono::offset::LocalResult;
2014-11-28 14:53:22 +00:00
2017-06-21 15:33:17 +00:00
assert_eq!(Utc::today(), Utc::now().date());
2014-11-28 14:53:22 +00:00
assert_eq!(Local::today(), Local::now().date());
2017-06-21 15:33:17 +00:00
assert_eq!(Utc.ymd(2014, 11, 28).weekday(), Weekday::Fri);
assert_eq!(Utc.ymd_opt(2014, 11, 31), LocalResult::None);
assert_eq!(Utc.ymd(2014, 11, 28).and_hms_milli(7, 8, 9, 10).format("%H%M%S").to_string(),
2015-02-18 20:08:00 +00:00
"070809");
2017-04-10 20:24:32 +00:00
```
2014-11-28 14:53:22 +00:00
2015-02-18 20:42:18 +00:00
There is no timezone-aware `Time` due to the lack of usefulness and also the complexity.
2017-06-21 05:03:49 +00:00
`DateTime` has [`date` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.date ) method
2016-07-25 18:45:53 +00:00
which returns a `Date` which represents its date component.
2017-06-21 05:03:49 +00:00
There is also a [`time` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.time ) method,
2016-07-25 18:45:53 +00:00
which simply returns a naive local time described below.
2014-11-28 14:53:22 +00:00
2014-12-13 13:16:38 +00:00
### Naive date and time
2014-11-28 14:53:22 +00:00
2015-02-18 20:42:18 +00:00
Chrono provides naive counterparts to `Date` , (non-existent) `Time` and `DateTime`
2017-06-21 05:03:49 +00:00
as [**`NaiveDate`** ](https://docs.rs/chrono/0.4.0/chrono/naive/struct.NaiveDate.html ),
[**`NaiveTime`** ](https://docs.rs/chrono/0.4.0/chrono/naive/struct.NaiveTime.html ) and
[**`NaiveDateTime`** ](https://docs.rs/chrono/0.4.0/chrono/naive/struct.NaiveDateTime.html ) respectively.
2014-11-28 14:53:22 +00:00
They have almost equivalent interfaces as their timezone-aware twins,
2015-01-12 17:03:12 +00:00
but are not associated to time zones obviously and can be quite low-level.
2014-11-28 14:53:22 +00:00
They are mostly useful for building blocks for higher-level types.
2014-04-01 17:14:57 +00:00
2015-02-18 20:42:18 +00:00
Timezone-aware `DateTime` and `Date` types have two methods returning naive versions:
2017-06-21 05:03:49 +00:00
[`naive_local` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.naive_local ) returns
2016-07-25 18:45:53 +00:00
a view to the naive local time,
2017-06-21 05:03:49 +00:00
and [`naive_utc` ](https://docs.rs/chrono/0.4.0/chrono/struct.DateTime.html#method.naive_utc ) returns
2016-07-25 18:45:53 +00:00
a view to the naive UTC time.
2015-02-18 20:42:18 +00:00
2014-12-13 13:16:38 +00:00
## Limitations
Only proleptic Gregorian calendar (i.e. extended to support older dates) is supported.
Be very careful if you really have to deal with pre-20C dates, they can be in Julian or others.
Date types are limited in about +/- 262,000 years from the common epoch.
Time types are limited in the nanosecond accuracy.
2016-07-25 18:45:53 +00:00
[Leap seconds are supported in the representation but
2017-06-21 05:03:49 +00:00
Chrono doesn't try to make use of them](https://docs.rs/chrono/0.4.0/chrono/naive/struct.NaiveTime.html#leap-second-handling).
2014-12-13 13:16:38 +00:00
(The main reason is that leap seconds are not really predictable.)
Almost *every* operation over the possible leap seconds will ignore them.
2016-01-23 05:33:20 +00:00
Consider using `NaiveDateTime` with the implicit TAI (International Atomic Time) scale
if you want.
2014-12-13 13:16:38 +00:00
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
2017-06-21 15:33:17 +00:00
and consequently `Utc.ymd(2014, 1, 30).with_month(2)` returns `None` .
2014-12-13 13:16:38 +00:00
2017-06-20 18:27:46 +00:00
Advanced time zone handling is not yet supported.
For now you can try the [Chrono-tz ](https://github.com/chronotope/chrono-tz/ ) crate instead.
2015-07-05 06:26:30 +00:00