time/lib.rs
1//! # Feature flags
2//!
3//! This crate exposes a number of features. These can be enabled or disabled as shown
4//! [in Cargo's documentation](https://doc.rust-lang.org/cargo/reference/features.html). Features
5//! are _disabled_ by default unless otherwise noted.
6//!
7//! Reliance on a given feature is always indicated alongside the item definition.
8//!
9//! - `std` (_enabled by default, implicitly enables `alloc`_)
10//!
11//! This enables a number of features that depend on the standard library.
12//!
13//! - `alloc` (_enabled by default via `std`_)
14//!
15//! Enables a number of features that require the ability to dynamically allocate memory.
16//!
17//! - `macros`
18//!
19//! Enables macros that provide compile-time verification of values and intuitive syntax.
20//!
21//! - `formatting` (_implicitly enables `std`_)
22//!
23//! Enables formatting of most structs.
24//!
25//! - `parsing`
26//!
27//! Enables parsing of most structs.
28//!
29//! - `local-offset` (_implicitly enables `std`_)
30//!
31//! This feature enables a number of methods that allow obtaining the system's UTC offset.
32//!
33//! - `large-dates`
34//!
35//! By default, only years within the ±9999 range (inclusive) are supported. If you need support
36//! for years outside this range, consider enabling this feature; the supported range will be
37//! increased to ±999,999.
38//!
39//! Note that enabling this feature has some costs, as it means forgoing some optimizations.
40//! Ambiguities may be introduced when parsing that would not otherwise exist.
41//!
42//! - `serde`
43//!
44//! Enables [`serde`](https://docs.rs/serde) support for all types.
45//!
46//! - `serde-human-readable` (_implicitly enables `serde`, `formatting`, and `parsing`_)
47//!
48//! Allows `serde` representations to use a human-readable format. This is determined by the
49//! serializer, not the user. If this feature is not enabled or if the serializer requests a
50//! non-human-readable format, a format optimized for binary representation will be used.
51//!
52//! Libraries should never enable this feature, as the decision of what format to use should be up
53//! to the user.
54//!
55//! - `rand` (_implicitly enables `rand08` and `rand09`_)
56//!
57//! Previously, this would enable support for `rand` 0.8. Since the release of `rand` 0.9, the
58//! feature has been split into `rand08` and `rand09` to allow support for both versions. For
59//! backwards compatibility and simplicity, this feature enables support for _both_ series.
60//!
61//! It is strongly recommended to enable `rand08` or `rand09` directly, as enabling `rand` will
62//! needlessly pull in both versions.
63//!
64//! - `rand08`
65//!
66//! Enables [`rand` 0.8](https://docs.rs/rand/0.8) support for all types.
67//!
68//! - `rand09`
69//!
70//! Enables [`rand` 0.9](https://docs.rs/rand/0.9) support for all types.
71//!
72//! - `quickcheck` (_implicitly enables `alloc`_)
73//!
74//! Enables [quickcheck](https://docs.rs/quickcheck) support for all types.
75//!
76//! - `wasm-bindgen`
77//!
78//! Enables [`wasm-bindgen`](https://github.com/rustwasm/wasm-bindgen) support for converting
79//! [JavaScript dates](https://rustwasm.github.io/wasm-bindgen/api/js_sys/struct.Date.html), as
80//! well as obtaining the UTC offset from JavaScript.
81
82#![doc(html_playground_url = "https://play.rust-lang.org")]
83#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_notable_trait))]
84#![no_std]
85#![doc(html_favicon_url = "https://avatars0.githubusercontent.com/u/55999857")]
86#![doc(html_logo_url = "https://avatars0.githubusercontent.com/u/55999857")]
87#![doc(test(attr(deny(warnings))))]
88
89#[allow(unused_extern_crates)]
90#[cfg(feature = "alloc")]
91extern crate alloc;
92
93#[cfg(feature = "std")]
94extern crate std;
95
96mod date;
97mod duration;
98pub mod error;
99pub mod ext;
100#[cfg(any(feature = "formatting", feature = "parsing"))]
101pub mod format_description;
102#[cfg(feature = "formatting")]
103pub mod formatting;
104mod hint;
105#[cfg(feature = "std")]
106mod instant;
107mod internal_macros;
108mod interop;
109#[cfg(feature = "macros")]
110pub mod macros;
111mod month;
112mod offset_date_time;
113#[cfg(feature = "parsing")]
114pub mod parsing;
115mod primitive_date_time;
116#[cfg(feature = "quickcheck")]
117mod quickcheck;
118#[cfg(feature = "rand08")]
119mod rand08;
120#[cfg(feature = "rand09")]
121mod rand09;
122#[cfg(feature = "serde")]
123pub mod serde;
124mod sys;
125#[cfg(test)]
126mod tests;
127mod time;
128mod utc_date_time;
129mod utc_offset;
130pub mod util;
131mod weekday;
132
133pub use time_core::convert;
134
135pub use crate::date::Date;
136pub use crate::duration::Duration;
137pub use crate::error::Error;
138#[doc(hidden)]
139#[cfg(feature = "std")]
140#[expect(deprecated)]
141pub use crate::instant::Instant;
142pub use crate::month::Month;
143pub use crate::offset_date_time::OffsetDateTime;
144pub use crate::primitive_date_time::PrimitiveDateTime;
145pub use crate::time::Time;
146pub use crate::utc_date_time::UtcDateTime;
147pub use crate::utc_offset::UtcOffset;
148pub use crate::weekday::Weekday;
149
150/// An alias for [`std::result::Result`] with a generic error from the time crate.
151pub type Result<T> = core::result::Result<T, Error>;
152
153/// This is a separate function to reduce the code size of `expect_opt!`.
154#[inline(never)]
155#[cold]
156#[track_caller]
157const fn expect_failed(message: &str) -> ! {
158 panic!("{}", message)
159}
160
161/// Returns the size of the pointed-to value in bytes.
162///
163/// This is a `const fn` in the standard library starting in Rust 1.85. When MSRV is at least that,
164/// this can be removed.
165#[inline]
166const fn size_of_val<T>(_: &T) -> usize {
167 size_of::<T>()
168}