time/format_description/
mod.rs

1//! Description of how types should be formatted and parsed.
2//!
3//! The formatted value will be output to the provided writer. Format descriptions can be
4//! [well-known](crate::format_description::well_known) or obtained by using the
5//! [`format_description!`](crate::macros::format_description) macro or a function listed below.
6//!
7//! For examples, see the implementors of [Formattable](crate::formatting::Formattable),
8//! e.g. [`well_known::Rfc3339`].
9
10mod borrowed_format_item;
11mod component;
12pub(crate) mod format_description_v3;
13pub mod modifier;
14#[cfg(feature = "alloc")]
15mod owned_format_item;
16#[cfg(feature = "alloc")]
17mod parse;
18
19/// Well-known formats, typically standards.
20pub mod well_known {
21    pub mod iso8601;
22    mod rfc2822;
23    mod rfc3339;
24
25    #[doc(inline)]
26    pub use iso8601::Iso8601;
27    pub use rfc2822::Rfc2822;
28    pub use rfc3339::Rfc3339;
29}
30
31/// Re-exports of internal types for use in macros.
32///
33/// Do not rely on the existence of this module for any reason. It, in its entirety, is not
34/// considered public API, is not subject to semantic versioning, and may be changed or removed at
35/// any point.
36#[doc(hidden)]
37pub mod __private {
38    pub use super::format_description_v3::{Component, FormatDescriptionV3Inner};
39}
40
41pub use borrowed_format_item::BorrowedFormatItem;
42#[doc(hidden)]
43#[deprecated(since = "0.3.37", note = "use `BorrowedFormatItem` for clarity")]
44pub use borrowed_format_item::BorrowedFormatItem as FormatItem;
45#[cfg(feature = "alloc")]
46pub use owned_format_item::OwnedFormatItem;
47
48pub use self::component::Component;
49pub use self::format_description_v3::FormatDescriptionV3;
50#[cfg(feature = "alloc")]
51#[expect(deprecated, reason = "backwards compatibility")]
52pub use self::parse::parse;
53#[cfg(feature = "alloc")]
54pub use self::parse::{parse_borrowed, parse_owned, parse_strftime_borrowed, parse_strftime_owned};
55
56/// The type output by the [`format_description!`](crate::macros::format_description) macro.
57pub type StaticFormatDescription = &'static [BorrowedFormatItem<'static>];
58
59/// Indicate whether the hour is "am" or "pm".
60#[derive(Debug, Clone, Copy, PartialEq, Eq)]
61pub(crate) enum Period {
62    #[allow(clippy::missing_docs_in_private_items)]
63    Am,
64    #[allow(clippy::missing_docs_in_private_items)]
65    Pm,
66}
67
68/// The version of a format description.
69#[allow(clippy::missing_docs_in_private_items, reason = "self-explanatory")]
70#[derive(Debug, Clone, Copy)]
71pub(crate) enum FormatDescriptionVersion {
72    V1,
73    V2,
74    V3,
75}
76
77impl FormatDescriptionVersion {
78    #[inline]
79    const fn is_v1(self) -> bool {
80        match self {
81            Self::V1 => true,
82            Self::V2 | Self::V3 => false,
83        }
84    }
85
86    #[inline]
87    const fn is_at_least_v2(self) -> bool {
88        match self {
89            Self::V1 => false,
90            Self::V2 | Self::V3 => true,
91        }
92    }
93
94    #[inline]
95    const fn is_at_least_v3(self) -> bool {
96        match self {
97            Self::V1 | Self::V2 => false,
98            Self::V3 => true,
99        }
100    }
101}
time/format_description/mod.rs

time/format_description/
mod.rs
