diff --git a/src/lib.rs b/src/lib.rs index 6fc07ae1..80a6e3c6 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,32 +1,33 @@ //! # Chrono: Date and Time for Rust //! -//! Chrono aims to provide all functionality needed to do correct operations on dates and times in the -//! [proleptic Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar): +//! Chrono aims to provide all functionality needed to do correct operations on dates and times in +//! the [proleptic Gregorian calendar]: //! -//! * The [`DateTime`](https://docs.rs/chrono/latest/chrono/struct.DateTime.html) type is timezone-aware -//! by default, with separate timezone-naive types. +//! * The [`DateTime`] type is timezone-aware by default, with separate timezone-naive types. //! * Operations that may produce an invalid or ambiguous date and time return `Option` or -//! [`MappedLocalTime`](https://docs.rs/chrono/latest/chrono/offset/enum.MappedLocalTime.html). -//! * Configurable parsing and formatting with a `strftime` inspired date and time formatting syntax. -//! * The [`Local`](https://docs.rs/chrono/latest/chrono/offset/struct.Local.html) timezone works with -//! the current timezone of the OS. +//! [`MappedLocalTime`]. +//! * Configurable parsing and formatting with a `strftime` inspired date and time formatting +//! syntax. +//! * The [`Local`] timezone works with the current timezone of the OS. //! * Types and operations are implemented to be reasonably efficient. //! -//! Timezone data is not shipped with chrono by default to limit binary sizes. Use the companion crate -//! [Chrono-TZ](https://crates.io/crates/chrono-tz) or [`tzfile`](https://crates.io/crates/tzfile) for -//! full timezone support. +//! Timezone data is not shipped with chrono by default to limit binary sizes. Use the companion +//! crate [Chrono-TZ] or [`tzfile`] for full timezone support. +//! +//! [proleptic Gregorian calendar]: https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar +//! [Chrono-TZ]: https://crates.io/crates/chrono-tz +//! [`tzfile`]: https://crates.io/crates/tzfile //! //! ### Features //! -//! Chrono supports various runtime environments and operating systems, and has -//! several features that may be enabled or disabled. +//! Chrono supports various runtime environments and operating systems, and has several features +//! that may be enabled or disabled. //! //! Default features: //! //! - `alloc`: Enable features that depend on allocation (primarily string formatting). -//! - `std`: Enables functionality that depends on the standard library. This -//! is a superset of `alloc` and adds interoperation with standard library types -//! and traits. +//! - `std`: Enables functionality that depends on the standard library. This is a superset of +//! `alloc` and adds interoperation with standard library types and traits. //! - `clock`: Enables reading the local timezone (`Local`). This is a superset of `now`. //! - `now`: Enables reading the system time (`now`). //! - `wasmbind`: Interface with the JS Date API for the `wasm32` target. @@ -35,16 +36,19 @@ //! //! - `serde`: Enable serialization/deserialization via [serde]. //! - `rkyv`: Deprecated, use the `rkyv-*` features. -//! - `rkyv-16`: Enable serialization/deserialization via [rkyv], using 16-bit integers for integral `*size` types. -//! - `rkyv-32`: Enable serialization/deserialization via [rkyv], using 32-bit integers for integral `*size` types. -//! - `rkyv-64`: Enable serialization/deserialization via [rkyv], using 64-bit integers for integral `*size` types. +//! - `rkyv-16`: Enable serialization/deserialization via [rkyv], +//! using 16-bit integers for integral `*size` types. +//! - `rkyv-32`: Enable serialization/deserialization via [rkyv], +//! using 32-bit integers for integral `*size` types. +//! - `rkyv-64`: Enable serialization/deserialization via [rkyv], +//! using 64-bit integers for integral `*size` types. //! - `rkyv-validation`: Enable rkyv validation support using `bytecheck`. //! - `rustc-serialize`: Enable serialization/deserialization via rustc-serialize (deprecated). //! - `arbitrary`: Construct arbitrary instances of a type with the Arbitrary crate. -//! - `unstable-locales`: Enable localization. This adds various methods with a -//! `_localized` suffix. The implementation and API may change or even be -//! removed in a patch release. Feedback welcome. -//! - `oldtime`: This feature no longer has any effect; it used to offer compatibility with the `time` 0.1 crate. +//! - `unstable-locales`: Enable localization. This adds various methods with a `_localized` suffix. +//! The implementation and API may change or even be removed in a patch release. Feedback welcome. +//! - `oldtime`: This feature no longer has any effect; it used to offer compatibility with the +//! `time` 0.1 crate. //! //! Note: The `rkyv{,-16,-32,-64}` features are mutually exclusive. //! @@ -58,54 +62,45 @@ //! //! ### Time delta / Duration //! -//! Chrono has a [`TimeDelta`] type to represent the magnitude of a time span. This is an -//! "accurate" duration represented as seconds and nanoseconds, and does not represent "nominal" -//! components such as days or months. +//! Chrono has a [`TimeDelta`] type to represent the magnitude of a time span. This is an "accurate" +//! duration represented as seconds and nanoseconds, and does not represent "nominal" components +//! such as days or months. //! //! The [`TimeDelta`] type was previously named `Duration` (and is still available as a type alias //! with that name). A notable difference with the similar [`core::time::Duration`] is that it is a //! signed value instead of unsigned. //! -//! Chrono currently only supports a small number of operations with [`core::time::Duration`] . +//! Chrono currently only supports a small number of operations with [`core::time::Duration`]. //! You can convert between both types with the [`TimeDelta::from_std`] and [`TimeDelta::to_std`] //! methods. //! //! ### Date and Time //! -//! Chrono provides a -//! [**`DateTime`**](./struct.DateTime.html) -//! type to represent a date and a time in a timezone. +//! Chrono provides a [`DateTime`] 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. +//! For more abstract moment-in-time tracking such as internal timekeeping that is unconcerned with +//! timezones, consider [`std::time::SystemTime`], which tracks your system clock, or +//! [`std::time::Instant`], which is an opaque but monotonically-increasing representation of a +//! moment in time. //! -//! `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: +//! [`DateTime`] is timezone-aware and must be constructed from a [`TimeZone`] 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/struct.Utc.html) specifies the UTC time zone. It is most efficient. +//! * [`Utc`] specifies the UTC time zone. It is most efficient. //! -//! * [**`Local`**](./offset/struct.Local.html) specifies the system local time zone. +//! * [`Local`] specifies the system local time zone. //! -//! * [**`FixedOffset`**](./offset/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. +//! * [`FixedOffset`] 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`](./struct.DateTime.html#method.with_timezone) method. +//! [`DateTime`]s with different [`TimeZone`] types are distinct and do not mix, but can be +//! converted to each other using the [`DateTime::with_timezone`] method. //! -//! You can get the current date and time in the UTC time zone -//! ([`Utc::now()`](./offset/struct.Utc.html#method.now)) -//! or in the local time zone -//! ([`Local::now()`](./offset/struct.Local.html#method.now)). +//! You can get the current date and time in the UTC time zone ([`Utc::now()`]) or in the local time +//! zone ([`Local::now()`]). //! //! ``` //! # #[cfg(feature = "now")] { @@ -125,9 +120,9 @@ //! # } //! ``` //! -//! 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. +//! 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::offset::MappedLocalTime; @@ -202,9 +197,8 @@ //! # doctest().unwrap(); //! ``` //! -//! Various properties are available to the date and time, and can be altered individually. -//! Most of them are defined in the traits [`Datelike`](./trait.Datelike.html) and -//! [`Timelike`](./trait.Timelike.html) which you should `use` before. +//! 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: //! @@ -268,20 +262,18 @@ //! //! ### Formatting and Parsing //! -//! Formatting is done via the [`format`](./struct.DateTime.html#method.format) method, -//! which format is equivalent to the familiar `strftime` format. +//! Formatting is done via the [`format`](DateTime::format()) method, which format is equivalent to +//! the familiar `strftime` format. //! -//! See [`format::strftime`](./format/strftime/index.html#specifiers) -//! documentation for full syntax and list of specifiers. +//! See [`format::strftime`](format::strftime#specifiers) documentation for full syntax and list of +//! specifiers. //! //! The default `to_string` method and `{:?}` specifier also give a reasonable representation. -//! Chrono also provides [`to_rfc2822`](./struct.DateTime.html#method.to_rfc2822) and -//! [`to_rfc3339`](./struct.DateTime.html#method.to_rfc3339) methods -//! for well-known formats. +//! Chrono also provides [`to_rfc2822`](DateTime::to_rfc2822) and +//! [`to_rfc3339`](DateTime::to_rfc3339) methods for well-known formats. //! -//! Chrono now also provides date formatting in almost any language without the -//! help of an additional C library. This functionality is under the feature -//! `unstable-locales`: +//! Chrono now also provides date formatting in almost any language without the help of an +//! additional C library. This functionality is under the feature `unstable-locales`: //! //! ```toml //! chrono = { version = "0.4", features = ["unstable-locales"] } @@ -326,24 +318,18 @@ //! //! Parsing can be done with two methods: //! -//! 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`, `DateTime` and -//! `DateTime` 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. +//! 1. The standard [`FromStr`](std::str::FromStr) trait (and [`parse`](str::parse) method on a +//! string) can be used for parsing `DateTime`, `DateTime` and +//! `DateTime` values. This parses what the `{:?}` ([`std::fmt::Debug`] format specifier +//! prints, and requires the offset to be present. //! -//! 2. [`DateTime::parse_from_str`](./struct.DateTime.html#method.parse_from_str) parses -//! a date and time with offsets and returns `DateTime`. -//! 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_rfc2822`](./struct.DateTime.html#method.parse_from_rfc2822) -//! and -//! [`DateTime::parse_from_rfc3339`](./struct.DateTime.html#method.parse_from_rfc3339) -//! are similar but for well-known formats. +//! 2. [`DateTime::parse_from_str`] parses a date and time with offsets and returns +//! `DateTime`. 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_rfc2822`] and [`DateTime::parse_from_rfc3339`] are similar but for +//! well-known formats. //! -//! More detailed control over the parsing process is available via -//! [`format`](./format/index.html) module. +//! More detailed control over the parsing process is available via [`format`](mod@format) module. //! //! ```rust //! use chrono::prelude::*; @@ -375,8 +361,8 @@ //! assert!(DateTime::parse_from_str("Sat Nov 28 12:00:09 2014", "%a %b %e %T %Y").is_err()); //! ``` //! -//! Again : See [`format::strftime`](./format/strftime/index.html#specifiers) -//! documentation for full syntax and list of specifiers. +//! Again: See [`format::strftime`](format::strftime#specifiers) documentation for full syntax and +//! list of specifiers. //! //! ### Conversion from and to EPOCH timestamps //! @@ -406,20 +392,16 @@ //! //! ### Naive date and time //! -//! Chrono provides naive counterparts to `Date`, (non-existent) `Time` and `DateTime` -//! as [**`NaiveDate`**](./naive/struct.NaiveDate.html), -//! [**`NaiveTime`**](./naive/struct.NaiveTime.html) and -//! [**`NaiveDateTime`**](./naive/struct.NaiveDateTime.html) respectively. +//! Chrono provides naive counterparts to `Date`, (non-existent) `Time` and `DateTime` as +//! [`NaiveDate`], [`NaiveTime`] and [`NaiveDateTime`] 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. +//! 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`](./struct.DateTime.html#method.naive_local) returns -//! a view to the naive local time, -//! and [`naive_utc`](./struct.DateTime.html#method.naive_utc) returns -//! a view to the naive UTC time. +//! [`naive_local`](DateTime::naive_local) returns a view to the naive local time, +//! and [`naive_utc`](DateTime::naive_utc) returns a view to the naive UTC time. //! //! ## Limitations //! @@ -427,7 +409,7 @@ //! * Date types are limited to about +/- 262,000 years from the common epoch. //! * Time types are limited to nanosecond accuracy. //! * Leap seconds can be represented, but Chrono does not fully support them. -//! See [Leap Second Handling](https://docs.rs/chrono/latest/chrono/naive/struct.NaiveTime.html#leap-second-handling). +//! See [Leap Second Handling](NaiveTime#leap-second-handling). //! //! ## Rust version requirements //!