| 1 |
[Chrono][docsrs]: Timezone-aware date and time handling |
| 2 |
======================================== |
| 3 |
|
| 4 |
[![Chrono GitHub Actions][gh-image]][gh-checks] |
| 5 |
[![Chrono on crates.io][cratesio-image]][cratesio] |
| 6 |
[![Chrono on docs.rs][docsrs-image]][docsrs] |
| 7 |
[![Chat][discord-image]][discord] |
| 8 |
[![codecov.io][codecov-img]][codecov-link] |
| 9 |
|
| 10 |
[gh-image]: https://github.com/chronotope/chrono/actions/workflows/test.yml/badge.svg?branch=main |
| 11 |
[gh-checks]: https://github.com/chronotope/chrono/actions/workflows/test.yml?query=branch%3Amain |
| 12 |
[cratesio-image]: https://img.shields.io/crates/v/chrono.svg |
| 13 |
[cratesio]: https://crates.io/crates/chrono |
| 14 |
[docsrs-image]: https://docs.rs/chrono/badge.svg |
| 15 |
[docsrs]: https://docs.rs/chrono |
| 16 |
[discord-image]: https://img.shields.io/discord/976380008299917365?logo=discord |
| 17 |
[discord]: https://discord.gg/sXpav4PS7M |
| 18 |
[codecov-img]: https://img.shields.io/codecov/c/github/chronotope/chrono?logo=codecov |
| 19 |
[codecov-link]: https://codecov.io/gh/chronotope/chrono |
| 20 |
|
| 21 |
Chrono aims to provide all functionality needed to do correct operations on dates and times in the |
| 22 |
[proleptic Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar): |
| 23 |
|
| 24 |
* The [`DateTime`](https://docs.rs/chrono/latest/chrono/struct.DateTime.html) type is timezone-aware |
| 25 |
by default, with separate timezone-naive types. |
| 26 |
* Operations that may produce an invalid or ambiguous date and time return `Option` or |
| 27 |
[`MappedLocalTime`](https://docs.rs/chrono/latest/chrono/offset/enum.MappedLocalTime.html). |
| 28 |
* Configurable parsing and formatting with an `strftime` inspired date and time formatting syntax. |
| 29 |
* The [`Local`](https://docs.rs/chrono/latest/chrono/offset/struct.Local.html) timezone works with |
| 30 |
the current timezone of the OS. |
| 31 |
* Types and operations are implemented to be reasonably efficient. |
| 32 |
|
| 33 |
Timezone data is not shipped with chrono by default to limit binary sizes. Use the companion crate |
| 34 |
[Chrono-TZ](https://crates.io/crates/chrono-tz) or [`tzfile`](https://crates.io/crates/tzfile) for |
| 35 |
full timezone support. |
| 36 |
|
| 37 |
## Documentation |
| 38 |
|
| 39 |
See [docs.rs](https://docs.rs/chrono/latest/chrono/) for the API reference. |
| 40 |
|
| 41 |
## Limitations |
| 42 |
|
| 43 |
* Only the proleptic Gregorian calendar (i.e. extended to support older dates) is supported. |
| 44 |
* Date types are limited to about +/- 262,000 years from the common epoch. |
| 45 |
* Time types are limited to nanosecond accuracy. |
| 46 |
* Leap seconds can be represented, but Chrono does not fully support them. |
| 47 |
See [Leap Second Handling](https://docs.rs/chrono/latest/chrono/naive/struct.NaiveTime.html#leap-second-handling). |
| 48 |
|
| 49 |
## Crate features |
| 50 |
|
| 51 |
Default features: |
| 52 |
|
| 53 |
* `alloc`: Enable features that depend on allocation (primarily string formatting). |
| 54 |
* `std`: Enables functionality that depends on the standard library. This is a superset of `alloc` |
| 55 |
and adds interoperation with standard library types and traits. |
| 56 |
* `clock`: Enables reading the local timezone (`Local`). This is a superset of `now`. |
| 57 |
* `now`: Enables reading the system time (`now`). |
| 58 |
* `wasmbind`: Interface with the JS Date API for the `wasm32` target. |
| 59 |
|
| 60 |
Optional features: |
| 61 |
|
| 62 |
* `serde`: Enable serialization/deserialization via [serde]. |
| 63 |
* `rkyv`: Deprecated, use the `rkyv-*` features. |
| 64 |
* `rkyv-16`: Enable serialization/deserialization via [rkyv], using 16-bit integers for integral `*size` types. |
| 65 |
* `rkyv-32`: Enable serialization/deserialization via [rkyv], using 32-bit integers for integral `*size` types. |
| 66 |
* `rkyv-64`: Enable serialization/deserialization via [rkyv], using 64-bit integers for integral `*size` types. |
| 67 |
* `rkyv-validation`: Enable rkyv validation support using `bytecheck`. |
| 68 |
* `arbitrary`: Construct arbitrary instances of a type with the Arbitrary crate. |
| 69 |
* `unstable-locales`: Enable localization. This adds various methods with a `_localized` suffix. |
| 70 |
The implementation and API may change or even be removed in a patch release. Feedback welcome. |
| 71 |
* `oldtime`: This feature no longer has any effect; it used to offer compatibility with the `time` 0.1 crate. |
| 72 |
|
| 73 |
Note: The `rkyv{,-16,-32,-64}` features are mutually exclusive. |
| 74 |
|
| 75 |
[serde]: https://github.com/serde-rs/serde |
| 76 |
[rkyv]: https://github.com/rkyv/rkyv |
| 77 |
|
| 78 |
## Rust version requirements |
| 79 |
|
| 80 |
The Minimum Supported Rust Version (MSRV) is currently **Rust 1.61.0**. |
| 81 |
|
| 82 |
The MSRV is explicitly tested in CI. It may be bumped in minor releases, but this is not done |
| 83 |
lightly. |
| 84 |
|
| 85 |
## License |
| 86 |
|
| 87 |
This project is licensed under either of |
| 88 |
|
| 89 |
* [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) |
| 90 |
* [MIT License](https://opensource.org/licenses/MIT) |
| 91 |
|
| 92 |
at your option. |