diff options
Diffstat (limited to 'vendor/chrono/README.md')
| -rw-r--r-- | vendor/chrono/README.md | 85 |
1 files changed, 53 insertions, 32 deletions
diff --git a/vendor/chrono/README.md b/vendor/chrono/README.md index ad9591889..639a09144 100644 --- a/vendor/chrono/README.md +++ b/vendor/chrono/README.md @@ -1,4 +1,4 @@ -[Chrono][docsrs]: Date and Time for Rust +[Chrono][docsrs]: Timezone-aware date and time handling ======================================== [![Chrono GitHub Actions][gh-image]][gh-checks] @@ -15,45 +15,66 @@ [gitter-image]: https://badges.gitter.im/chrono-rs/chrono.svg [gitter]: https://gitter.im/chrono-rs/chrono -It aims to be a feature-complete superset of -the [time](https://github.com/rust-lang-deprecated/time) library. -In particular, +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 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. +* The [`DateTime`](https://docs.rs/chrono/latest/chrono/struct.DateTime.html) 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 + [`LocalResult`](https://docs.rs/chrono/latest/chrono/offset/enum.LocalResult.html). +* Configurable parsing and formatting with an `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. +* Types and operations are implemented to be reasonably efficient. -There were several previous attempts to bring a good date and time library to Rust, -which Chrono builds upon and should acknowledge: +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. -* [Initial research on - the wiki](https://github.com/rust-lang/rust-wiki-backup/blob/master/Lib-datetime.md) -* Dietrich Epp's [datetime-rs](https://github.com/depp/datetime-rs) -* Luis de Bethencourt's [rust-datetime](https://github.com/luisbg/rust-datetime) +## Documentation + +See [docs.rs](https://docs.rs/chrono/latest/chrono/) for the API reference. ## 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. +* Only the proleptic Gregorian calendar (i.e. extended to support older dates) is supported. +* 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). + +## Crate features + +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. +* `clock`: Enables reading the system time (`now`) and local timezone (`Local`). +* `wasmbind`: Interface with the JS Date API for the `wasm32` target. + +Optional features: + +* `serde`: Enable serialization/deserialization via serde. +* `rkyv`: Enable serialization/deserialization via rkyv. +* `rustc-serialize`: Enable serialization/deserialization via rustc-serialize (deprecated). +* `old_time`: compatability with the `Duration` type of the `time` 0.1 crate (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. + +## Rust version requirements + +The Minimum Supported Rust Version (MSRV) is currently **Rust 1.56.0**. -Date types are limited in about +/- 262,000 years from the common epoch. -Time types are limited in the nanosecond accuracy. +The MSRV is explicitly tested in CI. It may be bumped in minor releases, but this is not done +lightly. -[Leap seconds are supported in the representation but -Chrono doesn't try to make use of them](https://docs.rs/chrono/0.4/chrono/naive/struct.NaiveTime.html#leap-second-handling). -(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 -if you want. +## License -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 -and consequently `Utc.ymd_opt(2014, 1, 30).unwrap().with_month(2)` returns `None`. +This project is licensed under either of -Non ISO week handling is not yet supported. -For now you can use the [chrono_ext](https://crates.io/crates/chrono_ext) -crate ([sources](https://github.com/bcourtine/chrono-ext/)). +* [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) +* [MIT License](https://opensource.org/licenses/MIT) -Advanced time zone handling is not yet supported. -For now you can try the [Chrono-tz](https://github.com/chronotope/chrono-tz/) crate instead. +at your option. |