Documentation cleanup.
- The main documentation (`src/lib.rs` AND `README.md`) now properly link to other types when rendered. - The role of `TimeZone` trait is explained more thoroughly. (Hopefully) fixes #82.
This commit is contained in:
Kang Seonghoon
parent
0b3218289f
commit
f41de9b41f
|
|
@ -1,16 +1,19 @@
|
|||
Chrono is mainly written by Kang Seonghoon <public+rust@mearie.org>,
|
||||
and also the following people (in ascending order):
|
||||
|
||||
Ben Eills <ben@beneills.com>
|
||||
Colin Ray <r.colinray@gmail.com>
|
||||
Corey Farwell <coreyf@rwell.org>
|
||||
Dan <dan@ebip.co.uk>
|
||||
Danilo Bargen <mail@dbrgn.ch>
|
||||
David Hewson <dev@daveid.co.uk>
|
||||
David Ross <daboross@daboross.net>
|
||||
David Willie <david.willie.1@gmail.com>
|
||||
Eunchong Yu <kroisse@gmail.com>
|
||||
Huon Wilson <dbau.pp+github@gmail.com>
|
||||
Jisoo Park <xxxyel@gmail.com>
|
||||
Joe Wilm <joe@jwilm.com>
|
||||
John Heitmann <jheitmann@gmail.com>
|
||||
John Nagle <nagle@sitetruth.com>
|
||||
Ken Tossell <ken@tossell.net>
|
||||
Martin Risell Lilja <martin.risell.lilja@gmail.com>
|
||||
|
|
|
|||
6
Makefile
6
Makefile
|
|
@ -21,10 +21,12 @@ README.md: src/lib.rs
|
|||
echo >> $@
|
||||
echo '[travis-image]: https://travis-ci.org/lifthrasiir/rust-chrono.png' >> $@
|
||||
echo '[travis]: https://travis-ci.org/lifthrasiir/rust-chrono' >> $@
|
||||
awk '/^\/\/! # Chrono /,/^\/\/! ## /' $< | cut -b 5- | grep -v '^#' >> $@
|
||||
awk '/^\/\/! # Chrono /,/^\/\/! ## /' $< | cut -b 5- | grep -v '^#' | \
|
||||
sed 's/](\.\//](https:\/\/lifthrasiir.github.io\/rust-chrono\/chrono\//g' >> $@
|
||||
echo '[Complete Documentation][doc]' >> $@
|
||||
echo >> $@
|
||||
echo '[doc]: https://lifthrasiir.github.io/rust-chrono/' >> $@
|
||||
echo >> $@
|
||||
awk '/^\/\/! ## /,!/^\/\/!/' $< | cut -b 5- | grep -v '^# ' >> $@
|
||||
awk '/^\/\/! ## /,!/^\/\/!/' $< | cut -b 5- | grep -v '^# ' | \
|
||||
sed 's/](\.\//](https:\/\/lifthrasiir.github.io\/rust-chrono\/chrono\//g' >> $@
|
||||
|
||||
|
|
|
|||
101
README.md
101
README.md
|
|
@ -36,13 +36,16 @@ Put this in your `Cargo.toml`:
|
|||
chrono = "0.2"
|
||||
```
|
||||
|
||||
Or, if you want [Serde](http://github.com/serde-rs/serde) support, include it like this:
|
||||
Or, if you want [Serde](https://github.com/serde-rs/serde) or
|
||||
[rustc-serialize](https://github.com/rust-lang-nursery/rustc-serialize) support,
|
||||
include the features like this:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
chrono = { version = "0.2", features = ["serde"] }
|
||||
chrono = { version = "0.2", features = ["serde", "rustc-serialize"] }
|
||||
```
|
||||
|
||||
And put this in your crate root:
|
||||
Then put this in your crate root:
|
||||
|
||||
```rust
|
||||
extern crate chrono;
|
||||
|
|
@ -52,16 +55,16 @@ extern crate chrono;
|
|||
|
||||
### Duration
|
||||
|
||||
[`chrono::Duration`](https://lifthrasiir.github.io/rust-chrono/chrono/struct.Duration.html)
|
||||
represents the magnitude of a time span. `Duration` used to be provided by Chrono.
|
||||
[**`Duration`**](https://lifthrasiir.github.io/rust-chrono/chrono/struct.Duration.html)
|
||||
represents the magnitude of a time span. `Duration` used to be provided by Chrono.
|
||||
It has been moved to the `time` crate as the
|
||||
[`time::Duration`](http://doc.rust-lang.org/time/time/struct.Duration.html) type, but is
|
||||
[`time::Duration`](https://doc.rust-lang.org/time/time/struct.Duration.html) type, but is
|
||||
still re-exported from Chrono.
|
||||
|
||||
### Date and Time
|
||||
|
||||
Chrono provides a
|
||||
[`DateTime`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html)
|
||||
[**`DateTime`**](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html)
|
||||
type to represent a date and a time in a timezone.
|
||||
|
||||
For more abstract moment-in-time tracking such as internal timekeeping
|
||||
|
|
@ -72,12 +75,28 @@ which tracks your system clock, or
|
|||
is an opaque but monotonically-increasing representation of a moment in time.
|
||||
|
||||
`DateTime` is timezone-aware and must be constructed from
|
||||
the `TimeZone` object.
|
||||
`DateTime`s with different time zones do not mix, but can be converted to
|
||||
each other using the `DateTime::with_timezone` method.
|
||||
the [**`TimeZone`**](https://lifthrasiir.github.io/rust-chrono/chrono/offset/trait.TimeZone.html) object,
|
||||
which defines how the local date is converted to and back from the UTC date.
|
||||
There are three well-known `TimeZone` implementations:
|
||||
|
||||
You can get the current date and time in the UTC time zone (`UTC::now()`)
|
||||
or in the local time zone (`Local::now()`).
|
||||
* [**`UTC`**](https://lifthrasiir.github.io/rust-chrono/chrono/offset/utc/struct.UTC.html) specifies the UTC time zone. It is most efficient.
|
||||
|
||||
* [**`Local`**](https://lifthrasiir.github.io/rust-chrono/chrono/offset/local/struct.Local.html) specifies the system local time zone.
|
||||
|
||||
* [**`FixedOffset`**](https://lifthrasiir.github.io/rust-chrono/chrono/offset/fixed/struct.FixedOffset.html) specifies
|
||||
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
|
||||
the [`DateTime::with_timezone`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.with_timezone) method.
|
||||
|
||||
You can get the current date and time in the UTC time zone
|
||||
([`UTC::now()`](https://lifthrasiir.github.io/rust-chrono/chrono/offset/utc/struct.UTC.html#method.now))
|
||||
or in the local time zone
|
||||
([`Local::now()`](https://lifthrasiir.github.io/rust-chrono/chrono/offset/local/struct.Local.html#method.now)).
|
||||
|
||||
~~~~ {.rust}
|
||||
use chrono::*;
|
||||
|
|
@ -117,7 +136,8 @@ assert_eq!(dt, fixed_dt);
|
|||
~~~~
|
||||
|
||||
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.
|
||||
Most of them are defined in the traits [`Datelike`](https://lifthrasiir.github.io/rust-chrono/chrono/trait.Datelike.html) and
|
||||
[`Timelike`](https://lifthrasiir.github.io/rust-chrono/chrono/trait.Timelike.html) which you should `use` before.
|
||||
Addition and subtraction is also supported.
|
||||
The following illustrates most supported operations to the date and time:
|
||||
|
||||
|
|
@ -155,12 +175,15 @@ assert_eq!(UTC.ymd(1970, 1, 1).and_hms(0, 0, 0) - Duration::seconds(1_000_000_00
|
|||
UTC.ymd(1938, 4, 24).and_hms(22, 13, 20));
|
||||
~~~~
|
||||
|
||||
Formatting is done via the `format` method,
|
||||
Formatting is done via the [`format`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.format) method,
|
||||
which format is equivalent to the familiar `strftime` format.
|
||||
(See the `format::strftime` module documentation for full syntax.)
|
||||
(See the [`format::strftime` module documentation](https://lifthrasiir.github.io/rust-chrono/chrono/format/strftime/index.html#specifiers)
|
||||
for full syntax.)
|
||||
|
||||
The default `to_string` method and `{:?}` specifier also give a reasonable representation.
|
||||
Chrono also provides `to_rfc{2822,3339}` methods for well-known formats.
|
||||
Chrono also provides [`to_rfc2822`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.to_rfc2822) and
|
||||
[`to_rfc3339`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.to_rfc3339) methods
|
||||
for well-known formats.
|
||||
|
||||
~~~~ {.rust}
|
||||
use chrono::*;
|
||||
|
|
@ -178,23 +201,30 @@ assert_eq!(format!("{:?}", dt), "2014-11-28T12:00:09Z");
|
|||
|
||||
Parsing can be done with three methods:
|
||||
|
||||
1. The standard `FromStr` trait (and `parse` method on a string) can be used for
|
||||
parsing `DateTime<FixedOffset>`, `DateTime<UTC>` and `DateTime<Local>` values.
|
||||
This parses what the `{:?}` (`std::fmt::Debug`) format specifier prints,
|
||||
and requires the offset to be present.
|
||||
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
|
||||
on a string) can be used for parsing `DateTime<FixedOffset>`, `DateTime<UTC>` and
|
||||
`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.
|
||||
|
||||
2. `DateTime::parse_from_str` parses a date and time with offsets and
|
||||
returns `DateTime<FixedOffset>`.
|
||||
2. [`DateTime::parse_from_str`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.parse_from_str) parses
|
||||
a date and time with offsets and returns `DateTime<FixedOffset>`.
|
||||
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.
|
||||
`DateTime::parse_from_rfc{2822,3339}` are similar but for well-known formats.
|
||||
[`DateTime::parse_from_rfc2822`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.parse_from_rfc2822)
|
||||
and
|
||||
[`DateTime::parse_from_rfc3339`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.parse_from_rfc3339)
|
||||
are similar but for well-known formats.
|
||||
|
||||
3. `Offset::datetime_from_str` is similar but returns `DateTime` of given offset.
|
||||
3. [`Offset::datetime_from_str`](https://lifthrasiir.github.io/rust-chrono/chrono/offset/trait.TimeZone.html#method.datetime_from_str) is
|
||||
similar but returns `DateTime` of given offset.
|
||||
When the explicit offset is missing from the input, it simply uses given offset.
|
||||
It issues an error when the input contains an explicit offset different
|
||||
from the current offset.
|
||||
|
||||
More detailed control over the parsing process is available via `format` module.
|
||||
More detailed control over the parsing process is available via
|
||||
[`format`](https://lifthrasiir.github.io/rust-chrono/chrono/format/index.html) module.
|
||||
|
||||
~~~~ {.rust}
|
||||
use chrono::*;
|
||||
|
|
@ -228,7 +258,7 @@ assert!(UTC.datetime_from_str("Sat Nov 28 12:00:09 2014", "%a %b %e %T %Y").is_e
|
|||
|
||||
### Individual date
|
||||
|
||||
Chrono also provides an individual date type (`Date`).
|
||||
Chrono also provides an individual date type ([**`Date`**](https://lifthrasiir.github.io/rust-chrono/chrono/date/struct.Date.html)).
|
||||
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.
|
||||
|
||||
|
|
@ -246,21 +276,27 @@ assert_eq!(UTC.ymd(2014, 11, 28).and_hms_milli(7, 8, 9, 10).format("%H%M%S").to_
|
|||
|
||||
There is no timezone-aware `Time` due to the lack of usefulness and also the complexity.
|
||||
|
||||
`DateTime` has `date` method which returns a `Date` which represents its date component.
|
||||
There is also a `time` method, which simply returns a naive local time described below.
|
||||
`DateTime` has [`date`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.date) method
|
||||
which returns a `Date` which represents its date component.
|
||||
There is also a [`time`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.time) method,
|
||||
which simply returns a naive local time described below.
|
||||
|
||||
### Naive date and time
|
||||
|
||||
Chrono provides naive counterparts to `Date`, (non-existent) `Time` and `DateTime`
|
||||
as `NaiveDate`, `NaiveTime` and `NaiveDateTime` respectively.
|
||||
as [**`NaiveDate`**](https://lifthrasiir.github.io/rust-chrono/chrono/naive/date/struct.NaiveDate.html),
|
||||
[**`NaiveTime`**](https://lifthrasiir.github.io/rust-chrono/chrono/naive/time/struct.NaiveTime.html) and
|
||||
[**`NaiveDateTime`**](https://lifthrasiir.github.io/rust-chrono/chrono/naive/datetime/struct.NaiveDateTime.html) respectively.
|
||||
|
||||
They have almost equivalent interfaces as their timezone-aware twins,
|
||||
but are not associated to time zones obviously and can be quite low-level.
|
||||
They are mostly useful for building blocks for higher-level types.
|
||||
|
||||
Timezone-aware `DateTime` and `Date` types have two methods returning naive versions:
|
||||
`naive_local` returns a view to the naive local time,
|
||||
and `naive_utc` returns a view to the naive UTC time.
|
||||
[`naive_local`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.naive_local) returns
|
||||
a view to the naive local time,
|
||||
and [`naive_utc`](https://lifthrasiir.github.io/rust-chrono/chrono/datetime/struct.DateTime.html#method.naive_utc) returns
|
||||
a view to the naive UTC time.
|
||||
|
||||
## Limitations
|
||||
|
||||
|
|
@ -270,7 +306,8 @@ Be very careful if you really have to deal with pre-20C dates, they can be in Ju
|
|||
Date types are limited in about +/- 262,000 years from the common epoch.
|
||||
Time types are limited in the nanosecond accuracy.
|
||||
|
||||
Leap seconds are supported in the representation but Chrono doesn't try to make use of them.
|
||||
[Leap seconds are supported in the representation but
|
||||
Chrono doesn't try to make use of them](https://lifthrasiir.github.io/rust-chrono/chrono/naive/time/struct.NaiveTime.html#leap-second-what).
|
||||
(The main reason is that leap seconds are not really predictable.)
|
||||
Almost *every* operation over the possible leap seconds will ignore them.
|
||||
Consider using `NaiveDateTime` with the implicit TAI (International Atomic Time) scale
|
||||
|
|
|
|||
117
src/lib.rs
117
src/lib.rs
|
|
@ -30,7 +30,16 @@
|
|||
//! chrono = "0.2"
|
||||
//! ```
|
||||
//!
|
||||
//! And put this in your crate root:
|
||||
//! Or, if you want [Serde](https://github.com/serde-rs/serde) or
|
||||
//! [rustc-serialize](https://github.com/rust-lang-nursery/rustc-serialize) support,
|
||||
//! include the features like this:
|
||||
//!
|
||||
//! ```toml
|
||||
//! [dependencies]
|
||||
//! chrono = { version = "0.2", features = ["serde", "rustc-serialize"] }
|
||||
//! ```
|
||||
//!
|
||||
//! Then put this in your crate root:
|
||||
//!
|
||||
//! ```rust
|
||||
//! extern crate chrono;
|
||||
|
|
@ -40,22 +49,48 @@
|
|||
//!
|
||||
//! ### Duration
|
||||
//!
|
||||
//! Chrono used to have a `Duration` type, which represents the time span.
|
||||
//! This is a simple reexport of
|
||||
//! [`time::Duration`](http://doc.rust-lang.org/time/time/struct.Duration.html) type
|
||||
//! provided by crates.io `time` crate (which originally comes from Chrono).
|
||||
//! [**`Duration`**](./struct.Duration.html)
|
||||
//! represents the magnitude of a time span. `Duration` used to be provided by Chrono.
|
||||
//! It has been moved to the `time` crate as the
|
||||
//! [`time::Duration`](https://doc.rust-lang.org/time/time/struct.Duration.html) type, but is
|
||||
//! still re-exported from Chrono.
|
||||
//!
|
||||
//! ### Date and Time
|
||||
//!
|
||||
//! Chrono provides a `DateTime` type for the combined date and time.
|
||||
//! Chrono provides a
|
||||
//! [**`DateTime`**](./datetime/struct.DateTime.html)
|
||||
//! type to represent a date and a time in a timezone.
|
||||
//!
|
||||
//! `DateTime`, among others, is timezone-aware and must be constructed from
|
||||
//! the `TimeZone` object.
|
||||
//! `DateTime`s with different time zones do not mix, but can be converted to
|
||||
//! each other using the `DateTime::with_timezone` method.
|
||||
//! 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.
|
||||
//!
|
||||
//! You can get the current date and time in the UTC time zone (`UTC::now()`)
|
||||
//! or in the local time zone (`Local::now()`).
|
||||
//! `DateTime` is timezone-aware and must be constructed from
|
||||
//! the [**`TimeZone`**](./offset/trait.TimeZone.html) object,
|
||||
//! which defines how the local date is converted to and back from the UTC date.
|
||||
//! There are three well-known `TimeZone` implementations:
|
||||
//!
|
||||
//! * [**`UTC`**](./offset/utc/struct.UTC.html) specifies the UTC time zone. It is most efficient.
|
||||
//!
|
||||
//! * [**`Local`**](./offset/local/struct.Local.html) specifies the system local time zone.
|
||||
//!
|
||||
//! * [**`FixedOffset`**](./offset/fixed/struct.FixedOffset.html) specifies
|
||||
//! 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
|
||||
//! the [`DateTime::with_timezone`](./datetime/struct.DateTime.html#method.with_timezone) method.
|
||||
//!
|
||||
//! You can get the current date and time in the UTC time zone
|
||||
//! ([`UTC::now()`](./offset/utc/struct.UTC.html#method.now))
|
||||
//! or in the local time zone
|
||||
//! ([`Local::now()`](./offset/local/struct.Local.html#method.now)).
|
||||
//!
|
||||
//! ~~~~ {.rust}
|
||||
//! use chrono::*;
|
||||
|
|
@ -97,7 +132,8 @@
|
|||
//! ~~~~
|
||||
//!
|
||||
//! 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.
|
||||
//! Most of them are defined in the traits [`Datelike`](./trait.Datelike.html) and
|
||||
//! [`Timelike`](./trait.Timelike.html) which you should `use` before.
|
||||
//! Addition and subtraction is also supported.
|
||||
//! The following illustrates most supported operations to the date and time:
|
||||
//!
|
||||
|
|
@ -138,12 +174,15 @@
|
|||
//! UTC.ymd(1938, 4, 24).and_hms(22, 13, 20));
|
||||
//! ~~~~
|
||||
//!
|
||||
//! Formatting is done via the `format` method,
|
||||
//! Formatting is done via the [`format`](./datetime/struct.DateTime.html#method.format) method,
|
||||
//! which format is equivalent to the familiar `strftime` format.
|
||||
//! (See the `format::strftime` module documentation for full syntax.)
|
||||
//! (See the [`format::strftime` module documentation](./format/strftime/index.html#specifiers)
|
||||
//! for full syntax.)
|
||||
//!
|
||||
//! The default `to_string` method and `{:?}` specifier also give a reasonable representation.
|
||||
//! Chrono also provides `to_rfc{2822,3339}` methods for well-known formats.
|
||||
//! Chrono also provides [`to_rfc2822`](./datetime/struct.DateTime.html#method.to_rfc2822) and
|
||||
//! [`to_rfc3339`](./datetime/struct.DateTime.html#method.to_rfc3339) methods
|
||||
//! for well-known formats.
|
||||
//!
|
||||
//! ~~~~ {.rust}
|
||||
//! use chrono::*;
|
||||
|
|
@ -161,23 +200,30 @@
|
|||
//!
|
||||
//! Parsing can be done with three methods:
|
||||
//!
|
||||
//! 1. The standard `FromStr` trait (and `parse` method on a string) can be used for
|
||||
//! parsing `DateTime<FixedOffset>`, `DateTime<UTC>` and `DateTime<Local>` values.
|
||||
//! This parses what the `{:?}` (`std::fmt::Debug`) format specifier prints,
|
||||
//! and requires the offset to be present.
|
||||
//! 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
|
||||
//! on a string) can be used for parsing `DateTime<FixedOffset>`, `DateTime<UTC>` and
|
||||
//! `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.
|
||||
//!
|
||||
//! 2. `DateTime::parse_from_str` parses a date and time with offsets and
|
||||
//! returns `DateTime<FixedOffset>`.
|
||||
//! 2. [`DateTime::parse_from_str`](./datetime/struct.DateTime.html#method.parse_from_str) parses
|
||||
//! a date and time with offsets and returns `DateTime<FixedOffset>`.
|
||||
//! 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.
|
||||
//! `DateTime::parse_from_rfc{2822,3339}` are similar but for well-known formats.
|
||||
//! [`DateTime::parse_from_rfc2822`](./datetime/struct.DateTime.html#method.parse_from_rfc2822)
|
||||
//! and
|
||||
//! [`DateTime::parse_from_rfc3339`](./datetime/struct.DateTime.html#method.parse_from_rfc3339)
|
||||
//! are similar but for well-known formats.
|
||||
//!
|
||||
//! 3. `Offset::datetime_from_str` is similar but returns `DateTime` of given offset.
|
||||
//! 3. [`Offset::datetime_from_str`](./offset/trait.TimeZone.html#method.datetime_from_str) is
|
||||
//! similar but returns `DateTime` of given offset.
|
||||
//! When the explicit offset is missing from the input, it simply uses given offset.
|
||||
//! It issues an error when the input contains an explicit offset different
|
||||
//! from the current offset.
|
||||
//!
|
||||
//! More detailed control over the parsing process is available via `format` module.
|
||||
//! More detailed control over the parsing process is available via
|
||||
//! [`format`](./format/index.html) module.
|
||||
//!
|
||||
//! ~~~~ {.rust}
|
||||
//! use chrono::*;
|
||||
|
|
@ -211,7 +257,7 @@
|
|||
//!
|
||||
//! ### Individual date
|
||||
//!
|
||||
//! Chrono also provides an individual date type (`Date`).
|
||||
//! Chrono also provides an individual date type ([**`Date`**](./date/struct.Date.html)).
|
||||
//! 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.
|
||||
//!
|
||||
|
|
@ -230,21 +276,27 @@
|
|||
//!
|
||||
//! There is no timezone-aware `Time` due to the lack of usefulness and also the complexity.
|
||||
//!
|
||||
//! `DateTime` has `date` method which returns a `Date` which represents its date component.
|
||||
//! There is also a `time` method, which simply returns a naive local time described below.
|
||||
//! `DateTime` has [`date`](./datetime/struct.DateTime.html#method.date) method
|
||||
//! which returns a `Date` which represents its date component.
|
||||
//! There is also a [`time`](./datetime/struct.DateTime.html#method.time) method,
|
||||
//! which simply returns a naive local time described below.
|
||||
//!
|
||||
//! ### Naive date and time
|
||||
//!
|
||||
//! Chrono provides naive counterparts to `Date`, (non-existent) `Time` and `DateTime`
|
||||
//! as `NaiveDate`, `NaiveTime` and `NaiveDateTime` respectively.
|
||||
//! as [**`NaiveDate`**](./naive/date/struct.NaiveDate.html),
|
||||
//! [**`NaiveTime`**](./naive/time/struct.NaiveTime.html) and
|
||||
//! [**`NaiveDateTime`**](./naive/datetime/struct.NaiveDateTime.html) respectively.
|
||||
//!
|
||||
//! They have almost equivalent interfaces as their timezone-aware twins,
|
||||
//! but are not associated to time zones obviously and can be quite low-level.
|
||||
//! They are mostly useful for building blocks for higher-level types.
|
||||
//!
|
||||
//! Timezone-aware `DateTime` and `Date` types have two methods returning naive versions:
|
||||
//! `naive_local` returns a view to the naive local time,
|
||||
//! and `naive_utc` returns a view to the naive UTC time.
|
||||
//! [`naive_local`](./datetime/struct.DateTime.html#method.naive_local) returns
|
||||
//! a view to the naive local time,
|
||||
//! and [`naive_utc`](./datetime/struct.DateTime.html#method.naive_utc) returns
|
||||
//! a view to the naive UTC time.
|
||||
//!
|
||||
//! ## Limitations
|
||||
//!
|
||||
|
|
@ -254,7 +306,8 @@
|
|||
//! Date types are limited in about +/- 262,000 years from the common epoch.
|
||||
//! Time types are limited in the nanosecond accuracy.
|
||||
//!
|
||||
//! Leap seconds are supported in the representation but Chrono doesn't try to make use of them.
|
||||
//! [Leap seconds are supported in the representation but
|
||||
//! Chrono doesn't try to make use of them](./naive/time/struct.NaiveTime.html#leap-second-what).
|
||||
//! (The main reason is that leap seconds are not really predictable.)
|
||||
//! Almost *every* operation over the possible leap seconds will ignore them.
|
||||
//! Consider using `NaiveDateTime` with the implicit TAI (International Atomic Time) scale
|
||||
|
|
|
|||
Loading…
Reference in New Issue