/src/chrono/src/format/mod.rs

Source (jump to first uncovered line)
// This is a part of Chrono.
// See README.md and LICENSE.txt for details.

//! Formatting (and parsing) utilities for date and time.
//!
//! This module provides the common types and routines to implement,
//! for example, [`DateTime::format`](../struct.DateTime.html#method.format) or
//! [`DateTime::parse_from_str`](../struct.DateTime.html#method.parse_from_str) methods.
//! For most cases you should use these high-level interfaces.
//!
//! Internally the formatting and parsing shares the same abstract **formatting items**,
//! which are just an [`Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html) of
//! the [`Item`](./enum.Item.html) type.
//! They are generated from more readable **format strings**;
//! currently Chrono supports a built-in syntax closely resembling
//! C's `strftime` format. The available options can be found [here](./strftime/index.html).
//!
//! # Example
//! ```
//! # #[cfg(feature = "alloc")] {
//! use chrono::{NaiveDateTime, TimeZone, Utc};
//!
//! let date_time = Utc.with_ymd_and_hms(2020, 11, 10, 0, 1, 32).unwrap();
//!
//! let formatted = format!("{}", date_time.format("%Y-%m-%d %H:%M:%S"));
//! assert_eq!(formatted, "2020-11-10 00:01:32");
//!
//! let parsed = NaiveDateTime::parse_from_str(&formatted, "%Y-%m-%d %H:%M:%S")?.and_utc();
//! assert_eq!(parsed, date_time);
//! # }
//! # Ok::<(), chrono::ParseError>(())
//! ```

#[cfg(all(feature = "alloc", not(feature = "std"), not(test)))]
use alloc::boxed::Box;
use core::fmt;
use core::str::FromStr;
#[cfg(feature = "std")]
use std::error::Error;

use crate::{Month, ParseMonthError, ParseWeekdayError, Weekday};

mod formatting;
mod parsed;

// due to the size of parsing routines, they are in separate modules.
mod parse;
pub(crate) mod scan;

pub mod strftime;

#[allow(unused)]
// TODO: remove '#[allow(unused)]' once we use this module for parsing or something else that does
// not require `alloc`.
pub(crate) mod locales;

pub use formatting::SecondsFormat;
pub(crate) use formatting::write_hundreds;
#[cfg(feature = "alloc")]
pub(crate) use formatting::write_rfc2822;
#[cfg(any(feature = "alloc", feature = "serde"))]
pub(crate) use formatting::write_rfc3339;
#[cfg(feature = "alloc")]
#[allow(deprecated)]
pub use formatting::{DelayedFormat, format, format_item};
#[cfg(feature = "unstable-locales")]
pub use locales::Locale;
pub(crate) use parse::parse_rfc3339;
pub use parse::{parse, parse_and_remainder};
pub use parsed::Parsed;
pub use strftime::StrftimeItems;

/// An uninhabited type used for `InternalNumeric` and `InternalFixed` below.
#[derive(Clone, PartialEq, Eq, Hash)]
enum Void {}

/// Padding characters for numeric items.
#[derive(Copy, Clone, PartialEq, Eq, Debug, Hash)]
pub enum Pad {
    /// No padding.
    None,
    /// Zero (`0`) padding.
    Zero,
    /// Space padding.
    Space,
}

/// Numeric item types.
/// They have associated formatting width (FW) and parsing width (PW).
///
/// The **formatting width** is the minimal width to be formatted.
/// If the number is too short, and the padding is not [`Pad::None`](./enum.Pad.html#variant.None),
/// then it is left-padded.
/// If the number is too long or (in some cases) negative, it is printed as is.
///
/// The **parsing width** is the maximal width to be scanned.
/// The parser only tries to consume from one to given number of digits (greedily).
/// It also trims the preceding whitespace if any.
/// It cannot parse the negative number, so some date and time cannot be formatted then
/// parsed with the same formatting items.
#[non_exhaustive]
#[derive(Clone, PartialEq, Eq, Debug, Hash)]
pub enum Numeric {
    /// Full Gregorian year (FW=4, PW=∞).
    /// May accept years before 1 BCE or after 9999 CE, given an initial sign (+/-).
    Year,
    /// Gregorian year divided by 100 (century number; FW=PW=2). Implies the non-negative year.
    YearDiv100,
    /// Gregorian year modulo 100 (FW=PW=2). Cannot be negative.
    YearMod100,
    /// Year in the ISO week date (FW=4, PW=∞).
    /// May accept years before 1 BCE or after 9999 CE, given an initial sign.
    IsoYear,
    /// Year in the ISO week date, divided by 100 (FW=PW=2). Implies the non-negative year.
    IsoYearDiv100,
    /// Year in the ISO week date, modulo 100 (FW=PW=2). Cannot be negative.
    IsoYearMod100,
    /// Quarter (FW=PW=1).
    Quarter,
    /// Month (FW=PW=2).
    Month,
    /// Day of the month (FW=PW=2).
    Day,
    /// Week number, where the week 1 starts at the first Sunday of January (FW=PW=2).
    WeekFromSun,
    /// Week number, where the week 1 starts at the first Monday of January (FW=PW=2).
    WeekFromMon,
    /// Week number in the ISO week date (FW=PW=2).
    IsoWeek,
    /// Day of the week, where Sunday = 0 and Saturday = 6 (FW=PW=1).
    NumDaysFromSun,
    /// Day of the week, where Monday = 1 and Sunday = 7 (FW=PW=1).
    WeekdayFromMon,
    /// Day of the year (FW=PW=3).
    Ordinal,
    /// Hour number in the 24-hour clocks (FW=PW=2).
    Hour,
    /// Hour number in the 12-hour clocks (FW=PW=2).
    Hour12,
    /// The number of minutes since the last whole hour (FW=PW=2).
    Minute,
    /// The number of seconds since the last whole minute (FW=PW=2).
    Second,
    /// The number of nanoseconds since the last whole second (FW=PW=9).
    /// Note that this is *not* left-aligned;
    /// see also [`Fixed::Nanosecond`](./enum.Fixed.html#variant.Nanosecond).
    Nanosecond,
    /// The number of non-leap seconds since the midnight UTC on January 1, 1970 (FW=1, PW=∞).
    /// For formatting, it assumes UTC upon the absence of time zone offset.
    Timestamp,

    /// Internal uses only.
    ///
    /// This item exists so that one can add additional internal-only formatting
    /// without breaking major compatibility (as enum variants cannot be selectively private).
    Internal(InternalNumeric),
}

/// An opaque type representing numeric item types for internal uses only.
#[derive(Clone, Eq, Hash, PartialEq)]
pub struct InternalNumeric {
    _dummy: Void,
}

impl fmt::Debug for InternalNumeric {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "<InternalNumeric>")
    }
}

/// Fixed-format item types.
///
/// They have their own rules of formatting and parsing.
/// Otherwise noted, they print in the specified cases but parse case-insensitively.
#[non_exhaustive]
#[derive(Clone, PartialEq, Eq, Debug, Hash)]
pub enum Fixed {
    /// Abbreviated month names.
    ///
    /// Prints a three-letter-long name in the title case, reads the same name in any case.
    ShortMonthName,
    /// Full month names.
    ///
    /// Prints a full name in the title case, reads either a short or full name in any case.
    LongMonthName,
    /// Abbreviated day of the week names.
    ///
    /// Prints a three-letter-long name in the title case, reads the same name in any case.
    ShortWeekdayName,
    /// Full day of the week names.
    ///
    /// Prints a full name in the title case, reads either a short or full name in any case.
    LongWeekdayName,
    /// AM/PM.
    ///
    /// Prints in lower case, reads in any case.
    LowerAmPm,
    /// AM/PM.
    ///
    /// Prints in upper case, reads in any case.
    UpperAmPm,
    /// An optional dot plus one or more digits for left-aligned nanoseconds.
    /// May print nothing, 3, 6 or 9 digits according to the available accuracy.
    /// See also [`Numeric::Nanosecond`](./enum.Numeric.html#variant.Nanosecond).
    Nanosecond,
    /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 3.
    Nanosecond3,
    /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 6.
    Nanosecond6,
    /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 9.
    Nanosecond9,
    /// Timezone name.
    ///
    /// It does not support parsing, its use in the parser is an immediate failure.
    TimezoneName,
    /// Offset from the local time to UTC (`+09:00` or `-04:00` or `+00:00`).
    ///
    /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace.
    /// The offset is limited from `-24:00` to `+24:00`,
    /// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
    TimezoneOffsetColon,
    /// Offset from the local time to UTC with seconds (`+09:00:00` or `-04:00:00` or `+00:00:00`).
    ///
    /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace.
    /// The offset is limited from `-24:00:00` to `+24:00:00`,
    /// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
    TimezoneOffsetDoubleColon,
    /// Offset from the local time to UTC without minutes (`+09` or `-04` or `+00`).
    ///
    /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace.
    /// The offset is limited from `-24` to `+24`,
    /// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
    TimezoneOffsetTripleColon,
    /// Offset from the local time to UTC (`+09:00` or `-04:00` or `Z`).
    ///
    /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace,
    /// and `Z` can be either in upper case or in lower case.
    /// The offset is limited from `-24:00` to `+24:00`,
    /// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
    TimezoneOffsetColonZ,
    /// Same as [`TimezoneOffsetColon`](#variant.TimezoneOffsetColon) but prints no colon.
    /// Parsing allows an optional colon.
    TimezoneOffset,
    /// Same as [`TimezoneOffsetColonZ`](#variant.TimezoneOffsetColonZ) but prints no colon.
    /// Parsing allows an optional colon.
    TimezoneOffsetZ,
    /// RFC 2822 date and time syntax. Commonly used for email and MIME date and time.
    RFC2822,
    /// RFC 3339 & ISO 8601 date and time syntax.
    RFC3339,

    /// Internal uses only.
    ///
    /// This item exists so that one can add additional internal-only formatting
    /// without breaking major compatibility (as enum variants cannot be selectively private).
    Internal(InternalFixed),
}

/// An opaque type representing fixed-format item types for internal uses only.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct InternalFixed {
    val: InternalInternal,
}

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
enum InternalInternal {
    /// Same as [`TimezoneOffsetColonZ`](#variant.TimezoneOffsetColonZ), but
    /// allows missing minutes (per [ISO 8601][iso8601]).
    ///
    /// # Panics
    ///
    /// If you try to use this for printing.
    ///
    /// [iso8601]: https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
    TimezoneOffsetPermissive,
    /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 3 and there is no leading dot.
    Nanosecond3NoDot,
    /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 6 and there is no leading dot.
    Nanosecond6NoDot,
    /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 9 and there is no leading dot.
    Nanosecond9NoDot,
}

/// Type for specifying the format of UTC offsets.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
pub struct OffsetFormat {
    /// See `OffsetPrecision`.
    pub precision: OffsetPrecision,
    /// Separator between hours, minutes and seconds.
    pub colons: Colons,
    /// Represent `+00:00` as `Z`.
    pub allow_zulu: bool,
    /// Pad the hour value to two digits.
    pub padding: Pad,
}

/// The precision of an offset from UTC formatting item.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
pub enum OffsetPrecision {
    /// Format offset from UTC as only hours. Not recommended, it is not uncommon for timezones to
    /// have an offset of 30 minutes, 15 minutes, etc.
    /// Any minutes and seconds get truncated.
    Hours,
    /// Format offset from UTC as hours and minutes.
    /// Any seconds will be rounded to the nearest minute.
    Minutes,
    /// Format offset from UTC as hours, minutes and seconds.
    Seconds,
    /// Format offset from UTC as hours, and optionally with minutes.
    /// Any seconds will be rounded to the nearest minute.
    OptionalMinutes,
    /// Format offset from UTC as hours and minutes, and optionally seconds.
    OptionalSeconds,
    /// Format offset from UTC as hours and optionally minutes and seconds.
    OptionalMinutesAndSeconds,
}

/// The separator between hours and minutes in an offset.
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
pub enum Colons {
    /// No separator
    None,
    /// Colon (`:`) as separator
    Colon,
    /// No separator when formatting, colon allowed when parsing.
    Maybe,
}

/// A single formatting item. This is used for both formatting and parsing.
#[derive(Clone, PartialEq, Eq, Debug, Hash)]
pub enum Item<'a> {
    /// A literally printed and parsed text.
    Literal(&'a str),
    /// Same as `Literal` but with the string owned by the item.
    #[cfg(feature = "alloc")]
    OwnedLiteral(Box<str>),
    /// Whitespace. Prints literally but reads zero or more whitespace.
    Space(&'a str),
    /// Same as `Space` but with the string owned by the item.
    #[cfg(feature = "alloc")]
    OwnedSpace(Box<str>),
    /// Numeric item. Can be optionally padded to the maximal length (if any) when formatting;
    /// the parser simply ignores any padded whitespace and zeroes.
    Numeric(Numeric, Pad),
    /// Fixed-format item.
    Fixed(Fixed),
    /// Issues a formatting error. Used to signal an invalid format string.
    Error,
}

const fn num(numeric: Numeric) -> Item<'static> {
    Item::Numeric(numeric, Pad::None)
}

const fn num0(numeric: Numeric) -> Item<'static> {
    Item::Numeric(numeric, Pad::Zero)
}

const fn nums(numeric: Numeric) -> Item<'static> {
    Item::Numeric(numeric, Pad::Space)
}

const fn fixed(fixed: Fixed) -> Item<'static> {
    Item::Fixed(fixed)
}

const fn internal_fixed(val: InternalInternal) -> Item<'static> {
    Item::Fixed(Fixed::Internal(InternalFixed { val }))
}

impl Item<'_> {
    /// Convert items that contain a reference to the format string into an owned variant.
    #[cfg(any(feature = "alloc", feature = "std"))]
    pub fn to_owned(self) -> Item<'static> {
        match self {
            Item::Literal(s) => Item::OwnedLiteral(Box::from(s)),
            Item::Space(s) => Item::OwnedSpace(Box::from(s)),
            Item::Numeric(n, p) => Item::Numeric(n, p),
            Item::Fixed(f) => Item::Fixed(f),
            Item::OwnedLiteral(l) => Item::OwnedLiteral(l),
            Item::OwnedSpace(s) => Item::OwnedSpace(s),
            Item::Error => Item::Error,
        }
    }
}

/// An error from the `parse` function.
#[derive(Debug, Clone, PartialEq, Eq, Copy, Hash)]
pub struct ParseError(ParseErrorKind);

impl ParseError {
    /// The category of parse error
    pub const fn kind(&self) -> ParseErrorKind {
        self.0
    }
}

/// The category of parse error
#[allow(clippy::manual_non_exhaustive)]
#[derive(Debug, Clone, PartialEq, Eq, Copy, Hash)]
pub enum ParseErrorKind {
    /// Given field is out of permitted range.
    OutOfRange,

    /// There is no possible date and time value with given set of fields.
    ///
    /// This does not include the out-of-range conditions, which are trivially invalid.
    /// It includes the case that there are one or more fields that are inconsistent to each other.
    Impossible,

    /// Given set of fields is not enough to make a requested date and time value.
    ///
    /// Note that there *may* be a case that given fields constrain the possible values so much
    /// that there is a unique possible value. Chrono only tries to be correct for
    /// most useful sets of fields however, as such constraint solving can be expensive.
    NotEnough,

    /// The input string has some invalid character sequence for given formatting items.
    Invalid,

    /// The input string has been prematurely ended.
    TooShort,

    /// All formatting items have been read but there is a remaining input.
    TooLong,

    /// There was an error on the formatting string, or there were non-supported formatting items.
    BadFormat,

    // TODO: Change this to `#[non_exhaustive]` (on the enum) with the next breaking release.
    #[doc(hidden)]
    __Nonexhaustive,
}

/// Same as `Result<T, ParseError>`.
pub type ParseResult<T> = Result<T, ParseError>;

impl fmt::Display for ParseError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self.0 {
            ParseErrorKind::OutOfRange => write!(f, "input is out of range"),
            ParseErrorKind::Impossible => write!(f, "no possible date and time matching input"),
            ParseErrorKind::NotEnough => write!(f, "input is not enough for unique date and time"),
            ParseErrorKind::Invalid => write!(f, "input contains invalid characters"),
            ParseErrorKind::TooShort => write!(f, "premature end of input"),
            ParseErrorKind::TooLong => write!(f, "trailing input"),
            ParseErrorKind::BadFormat => write!(f, "bad or unsupported format string"),
            _ => unreachable!(),
        }
    }
}

#[cfg(feature = "std")]
impl Error for ParseError {
    #[allow(deprecated)]
    fn description(&self) -> &str {
        "parser error, see to_string() for details"
    }
}

// to be used in this module and submodules
pub(crate) const OUT_OF_RANGE: ParseError = ParseError(ParseErrorKind::OutOfRange);
const IMPOSSIBLE: ParseError = ParseError(ParseErrorKind::Impossible);
const NOT_ENOUGH: ParseError = ParseError(ParseErrorKind::NotEnough);
const INVALID: ParseError = ParseError(ParseErrorKind::Invalid);
const TOO_SHORT: ParseError = ParseError(ParseErrorKind::TooShort);
pub(crate) const TOO_LONG: ParseError = ParseError(ParseErrorKind::TooLong);
const BAD_FORMAT: ParseError = ParseError(ParseErrorKind::BadFormat);

// this implementation is here only because we need some private code from `scan`

/// Parsing a `str` into a `Weekday` uses the format [`%A`](./format/strftime/index.html).
///
/// # Example
///
/// ```
/// use chrono::Weekday;
///
/// assert_eq!("Sunday".parse::<Weekday>(), Ok(Weekday::Sun));
/// assert!("any day".parse::<Weekday>().is_err());
/// ```
///
/// The parsing is case-insensitive.
///
/// ```
/// # use chrono::Weekday;
/// assert_eq!("mON".parse::<Weekday>(), Ok(Weekday::Mon));
/// ```
///
/// Only the shortest form (e.g. `sun`) and the longest form (e.g. `sunday`) is accepted.
///
/// ```
/// # use chrono::Weekday;
/// assert!("thurs".parse::<Weekday>().is_err());
/// ```
impl FromStr for Weekday {
    type Err = ParseWeekdayError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if let Ok(("", w)) = scan::short_or_long_weekday(s) {
            Ok(w)
        } else {
            Err(ParseWeekdayError { _dummy: () })
        }
    }
}

/// Parsing a `str` into a `Month` uses the format [`%B`](./format/strftime/index.html).
///
/// # Example
///
/// ```
/// use chrono::Month;
///
/// assert_eq!("January".parse::<Month>(), Ok(Month::January));
/// assert!("any day".parse::<Month>().is_err());
/// ```
///
/// The parsing is case-insensitive.
///
/// ```
/// # use chrono::Month;
/// assert_eq!("fEbruARy".parse::<Month>(), Ok(Month::February));
/// ```
///
/// Only the shortest form (e.g. `jan`) and the longest form (e.g. `january`) is accepted.
///
/// ```
/// # use chrono::Month;
/// assert!("septem".parse::<Month>().is_err());
/// assert!("Augustin".parse::<Month>().is_err());
/// ```
impl FromStr for Month {
    type Err = ParseMonthError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if let Ok(("", w)) = scan::short_or_long_month0(s) {
            match w {
                0 => Ok(Month::January),
                1 => Ok(Month::February),
                2 => Ok(Month::March),
                3 => Ok(Month::April),
                4 => Ok(Month::May),
                5 => Ok(Month::June),
                6 => Ok(Month::July),
                7 => Ok(Month::August),
                8 => Ok(Month::September),
                9 => Ok(Month::October),
                10 => Ok(Month::November),
                11 => Ok(Month::December),
                _ => Err(ParseMonthError { _dummy: () }),
            }
        } else {
            Err(ParseMonthError { _dummy: () })
        }
    }
}

Coverage Report

Created: 2025-08-26 06:32

Line	Count	Source (jump to first uncovered line)
1		// This is a part of Chrono.
2		// See README.md and LICENSE.txt for details.
3
4		//! Formatting (and parsing) utilities for date and time.
5		//!
6		//! This module provides the common types and routines to implement,
7		//! for example, [`DateTime::format`](../struct.DateTime.html#method.format) or
8		//! [`DateTime::parse_from_str`](../struct.DateTime.html#method.parse_from_str) methods.
9		//! For most cases you should use these high-level interfaces.
10		//!
11		//! Internally the formatting and parsing shares the same abstract formatting items,
12		//! which are just an [`Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html) of
13		//! the [`Item`](./enum.Item.html) type.
14		//! They are generated from more readable format strings;
15		//! currently Chrono supports a built-in syntax closely resembling
16		//! C's `strftime` format. The available options can be found [here](./strftime/index.html).
17		//!
18		//! # Example
19		//! ```
20		//! # #[cfg(feature = "alloc")] {
21		//! use chrono::{NaiveDateTime, TimeZone, Utc};
22		//!
23		//! let date_time = Utc.with_ymd_and_hms(2020, 11, 10, 0, 1, 32).unwrap();
24		//!
25		//! let formatted = format!("{}", date_time.format("%Y-%m-%d %H:%M:%S"));
26		//! assert_eq!(formatted, "2020-11-10 00:01:32");
27		//!
28		//! let parsed = NaiveDateTime::parse_from_str(&formatted, "%Y-%m-%d %H:%M:%S")?.and_utc();
29		//! assert_eq!(parsed, date_time);
30		//! # }
31		//! # Ok::<(), chrono::ParseError>(())
32		//! ```
33
34		#[cfg(all(feature = "alloc", not(feature = "std"), not(test)))]
35		use alloc::boxed::Box;
36		use core::fmt;
37		use core::str::FromStr;
38		#[cfg(feature = "std")]
39		use std::error::Error;
40
41		use crate::{Month, ParseMonthError, ParseWeekdayError, Weekday};
42
43		mod formatting;
44		mod parsed;
45
46		// due to the size of parsing routines, they are in separate modules.
47		mod parse;
48		pub(crate) mod scan;
49
50		pub mod strftime;
51
52		#[allow(unused)]
53		// TODO: remove '#[allow(unused)]' once we use this module for parsing or something else that does
54		// not require `alloc`.
55		pub(crate) mod locales;
56
57		pub use formatting::SecondsFormat;
58		pub(crate) use formatting::write_hundreds;
59		#[cfg(feature = "alloc")]
60		pub(crate) use formatting::write_rfc2822;
61		#[cfg(any(feature = "alloc", feature = "serde"))]
62		pub(crate) use formatting::write_rfc3339;
63		#[cfg(feature = "alloc")]
64		#[allow(deprecated)]
65		pub use formatting::{DelayedFormat, format, format_item};
66		#[cfg(feature = "unstable-locales")]
67		pub use locales::Locale;
68		pub(crate) use parse::parse_rfc3339;
69		pub use parse::{parse, parse_and_remainder};
70		pub use parsed::Parsed;
71		pub use strftime::StrftimeItems;
72
73		/// An uninhabited type used for `InternalNumeric` and `InternalFixed` below.
74		#[derive(Clone, PartialEq, Eq, Hash)]
75		enum Void {}
76
77		/// Padding characters for numeric items.
78		#[derive(Copy, Clone, PartialEq, Eq, Debug, Hash)]
79		pub enum Pad {
80		/// No padding.
81		None,
82		/// Zero (`0`) padding.
83		Zero,
84		/// Space padding.
85		Space,
86		}
87
88		/// Numeric item types.
89		/// They have associated formatting width (FW) and parsing width (PW).
90		///
91		/// The formatting width is the minimal width to be formatted.
92		/// If the number is too short, and the padding is not [`Pad::None`](./enum.Pad.html#variant.None),
93		/// then it is left-padded.
94		/// If the number is too long or (in some cases) negative, it is printed as is.
95		///
96		/// The parsing width is the maximal width to be scanned.
97		/// The parser only tries to consume from one to given number of digits (greedily).
98		/// It also trims the preceding whitespace if any.
99		/// It cannot parse the negative number, so some date and time cannot be formatted then
100		/// parsed with the same formatting items.
101		#[non_exhaustive]
102		#[derive(Clone, PartialEq, Eq, Debug, Hash)]
103		pub enum Numeric {
104		/// Full Gregorian year (FW=4, PW=∞).
105		/// May accept years before 1 BCE or after 9999 CE, given an initial sign (+/-).
106		Year,
107		/// Gregorian year divided by 100 (century number; FW=PW=2). Implies the non-negative year.
108		YearDiv100,
109		/// Gregorian year modulo 100 (FW=PW=2). Cannot be negative.
110		YearMod100,
111		/// Year in the ISO week date (FW=4, PW=∞).
112		/// May accept years before 1 BCE or after 9999 CE, given an initial sign.
113		IsoYear,
114		/// Year in the ISO week date, divided by 100 (FW=PW=2). Implies the non-negative year.
115		IsoYearDiv100,
116		/// Year in the ISO week date, modulo 100 (FW=PW=2). Cannot be negative.
117		IsoYearMod100,
118		/// Quarter (FW=PW=1).
119		Quarter,
120		/// Month (FW=PW=2).
121		Month,
122		/// Day of the month (FW=PW=2).
123		Day,
124		/// Week number, where the week 1 starts at the first Sunday of January (FW=PW=2).
125		WeekFromSun,
126		/// Week number, where the week 1 starts at the first Monday of January (FW=PW=2).
127		WeekFromMon,
128		/// Week number in the ISO week date (FW=PW=2).
129		IsoWeek,
130		/// Day of the week, where Sunday = 0 and Saturday = 6 (FW=PW=1).
131		NumDaysFromSun,
132		/// Day of the week, where Monday = 1 and Sunday = 7 (FW=PW=1).
133		WeekdayFromMon,
134		/// Day of the year (FW=PW=3).
135		Ordinal,
136		/// Hour number in the 24-hour clocks (FW=PW=2).
137		Hour,
138		/// Hour number in the 12-hour clocks (FW=PW=2).
139		Hour12,
140		/// The number of minutes since the last whole hour (FW=PW=2).
141		Minute,
142		/// The number of seconds since the last whole minute (FW=PW=2).
143		Second,
144		/// The number of nanoseconds since the last whole second (FW=PW=9).
145		/// Note that this is not left-aligned;
146		/// see also [`Fixed::Nanosecond`](./enum.Fixed.html#variant.Nanosecond).
147		Nanosecond,
148		/// The number of non-leap seconds since the midnight UTC on January 1, 1970 (FW=1, PW=∞).
149		/// For formatting, it assumes UTC upon the absence of time zone offset.
150		Timestamp,
151
152		/// Internal uses only.
153		///
154		/// This item exists so that one can add additional internal-only formatting
155		/// without breaking major compatibility (as enum variants cannot be selectively private).
156		Internal(InternalNumeric),
157		}
158
159		/// An opaque type representing numeric item types for internal uses only.
160		#[derive(Clone, Eq, Hash, PartialEq)]
161		pub struct InternalNumeric {
162		_dummy: Void,
163		}
164
165		impl fmt::Debug for InternalNumeric {
166	0	fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
167	0	write!(f, "<InternalNumeric>")
168	0	}
169		}
170
171		/// Fixed-format item types.
172		///
173		/// They have their own rules of formatting and parsing.
174		/// Otherwise noted, they print in the specified cases but parse case-insensitively.
175		#[non_exhaustive]
176		#[derive(Clone, PartialEq, Eq, Debug, Hash)]
177		pub enum Fixed {
178		/// Abbreviated month names.
179		///
180		/// Prints a three-letter-long name in the title case, reads the same name in any case.
181		ShortMonthName,
182		/// Full month names.
183		///
184		/// Prints a full name in the title case, reads either a short or full name in any case.
185		LongMonthName,
186		/// Abbreviated day of the week names.
187		///
188		/// Prints a three-letter-long name in the title case, reads the same name in any case.
189		ShortWeekdayName,
190		/// Full day of the week names.
191		///
192		/// Prints a full name in the title case, reads either a short or full name in any case.
193		LongWeekdayName,
194		/// AM/PM.
195		///
196		/// Prints in lower case, reads in any case.
197		LowerAmPm,
198		/// AM/PM.
199		///
200		/// Prints in upper case, reads in any case.
201		UpperAmPm,
202		/// An optional dot plus one or more digits for left-aligned nanoseconds.
203		/// May print nothing, 3, 6 or 9 digits according to the available accuracy.
204		/// See also [`Numeric::Nanosecond`](./enum.Numeric.html#variant.Nanosecond).
205		Nanosecond,
206		/// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 3.
207		Nanosecond3,
208		/// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 6.
209		Nanosecond6,
210		/// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 9.
211		Nanosecond9,
212		/// Timezone name.
213		///
214		/// It does not support parsing, its use in the parser is an immediate failure.
215		TimezoneName,
216		/// Offset from the local time to UTC (`+09:00` or `-04:00` or `+00:00`).
217		///
218		/// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace.
219		/// The offset is limited from `-24:00` to `+24:00`,
220		/// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
221		TimezoneOffsetColon,
222		/// Offset from the local time to UTC with seconds (`+09:00:00` or `-04:00:00` or `+00:00:00`).
223		///
224		/// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace.
225		/// The offset is limited from `-24:00:00` to `+24:00:00`,
226		/// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
227		TimezoneOffsetDoubleColon,
228		/// Offset from the local time to UTC without minutes (`+09` or `-04` or `+00`).
229		///
230		/// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace.
231		/// The offset is limited from `-24` to `+24`,
232		/// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
233		TimezoneOffsetTripleColon,
234		/// Offset from the local time to UTC (`+09:00` or `-04:00` or `Z`).
235		///
236		/// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace,
237		/// and `Z` can be either in upper case or in lower case.
238		/// The offset is limited from `-24:00` to `+24:00`,
239		/// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
240		TimezoneOffsetColonZ,
241		/// Same as [`TimezoneOffsetColon`](#variant.TimezoneOffsetColon) but prints no colon.
242		/// Parsing allows an optional colon.
243		TimezoneOffset,
244		/// Same as [`TimezoneOffsetColonZ`](#variant.TimezoneOffsetColonZ) but prints no colon.
245		/// Parsing allows an optional colon.
246		TimezoneOffsetZ,
247		/// RFC 2822 date and time syntax. Commonly used for email and MIME date and time.
248		RFC2822,
249		/// RFC 3339 & ISO 8601 date and time syntax.
250		RFC3339,
251
252		/// Internal uses only.
253		///
254		/// This item exists so that one can add additional internal-only formatting
255		/// without breaking major compatibility (as enum variants cannot be selectively private).
256		Internal(InternalFixed),
257		}
258
259		/// An opaque type representing fixed-format item types for internal uses only.
260		#[derive(Debug, Clone, PartialEq, Eq, Hash)]
261		pub struct InternalFixed {
262		val: InternalInternal,
263		}
264
265		#[derive(Debug, Clone, PartialEq, Eq, Hash)]
266		enum InternalInternal {
267		/// Same as [`TimezoneOffsetColonZ`](#variant.TimezoneOffsetColonZ), but
268		/// allows missing minutes (per [ISO 8601][iso8601]).
269		///
270		/// # Panics
271		///
272		/// If you try to use this for printing.
273		///
274		/// [iso8601]: https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
275		TimezoneOffsetPermissive,
276		/// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 3 and there is no leading dot.
277		Nanosecond3NoDot,
278		/// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 6 and there is no leading dot.
279		Nanosecond6NoDot,
280		/// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 9 and there is no leading dot.
281		Nanosecond9NoDot,
282		}
283
284		/// Type for specifying the format of UTC offsets.
285		#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
286		pub struct OffsetFormat {
287		/// See `OffsetPrecision`.
288		pub precision: OffsetPrecision,
289		/// Separator between hours, minutes and seconds.
290		pub colons: Colons,
291		/// Represent `+00:00` as `Z`.
292		pub allow_zulu: bool,
293		/// Pad the hour value to two digits.
294		pub padding: Pad,
295		}
296
297		/// The precision of an offset from UTC formatting item.
298		#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
299		pub enum OffsetPrecision {
300		/// Format offset from UTC as only hours. Not recommended, it is not uncommon for timezones to
301		/// have an offset of 30 minutes, 15 minutes, etc.
302		/// Any minutes and seconds get truncated.
303		Hours,
304		/// Format offset from UTC as hours and minutes.
305		/// Any seconds will be rounded to the nearest minute.
306		Minutes,
307		/// Format offset from UTC as hours, minutes and seconds.
308		Seconds,
309		/// Format offset from UTC as hours, and optionally with minutes.
310		/// Any seconds will be rounded to the nearest minute.
311		OptionalMinutes,
312		/// Format offset from UTC as hours and minutes, and optionally seconds.
313		OptionalSeconds,
314		/// Format offset from UTC as hours and optionally minutes and seconds.
315		OptionalMinutesAndSeconds,
316		}
317
318		/// The separator between hours and minutes in an offset.
319		#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
320		pub enum Colons {
321		/// No separator
322		None,
323		/// Colon (`:`) as separator
324		Colon,
325		/// No separator when formatting, colon allowed when parsing.
326		Maybe,
327		}
328
329		/// A single formatting item. This is used for both formatting and parsing.
330		#[derive(Clone, PartialEq, Eq, Debug, Hash)]
331		pub enum Item<'a> {
332		/// A literally printed and parsed text.
333		Literal(&'a str),
334		/// Same as `Literal` but with the string owned by the item.
335		#[cfg(feature = "alloc")]
336		OwnedLiteral(Box<str>),
337		/// Whitespace. Prints literally but reads zero or more whitespace.
338		Space(&'a str),
339		/// Same as `Space` but with the string owned by the item.
340		#[cfg(feature = "alloc")]
341		OwnedSpace(Box<str>),
342		/// Numeric item. Can be optionally padded to the maximal length (if any) when formatting;
343		/// the parser simply ignores any padded whitespace and zeroes.
344		Numeric(Numeric, Pad),
345		/// Fixed-format item.
346		Fixed(Fixed),
347		/// Issues a formatting error. Used to signal an invalid format string.
348		Error,
349		}
350
351	4.05k	const fn num(numeric: Numeric) -> Item<'static> {
352	4.05k	Item::Numeric(numeric, Pad::None)
353	4.05k	}
354
355	13.0k	const fn num0(numeric: Numeric) -> Item<'static> {
356	13.0k	Item::Numeric(numeric, Pad::Zero)
357	13.0k	}
358
359	589	const fn nums(numeric: Numeric) -> Item<'static> {
360	589	Item::Numeric(numeric, Pad::Space)
361	589	}
362
363	69.7k	const fn fixed(fixed: Fixed) -> Item<'static> {
364	69.7k	Item::Fixed(fixed)
365	69.7k	}
366
367	2.63k	const fn internal_fixed(val: InternalInternal) -> Item<'static> {
368	2.63k	Item::Fixed(Fixed::Internal(InternalFixed { val }))
369	2.63k	}
370
371		impl Item<'_> {
372		/// Convert items that contain a reference to the format string into an owned variant.
373		#[cfg(any(feature = "alloc", feature = "std"))]
374	0	pub fn to_owned(self) -> Item<'static> {
375	0	match self {
376	0	Item::Literal(s) => Item::OwnedLiteral(Box::from(s)),
377	0	Item::Space(s) => Item::OwnedSpace(Box::from(s)),
378	0	Item::Numeric(n, p) => Item::Numeric(n, p),
379	0	Item::Fixed(f) => Item::Fixed(f),
380	0	Item::OwnedLiteral(l) => Item::OwnedLiteral(l),
381	0	Item::OwnedSpace(s) => Item::OwnedSpace(s),
382	0	Item::Error => Item::Error,
383		}
384	0	}
385		}
386
387		/// An error from the `parse` function.
388		#[derive(Debug, Clone, PartialEq, Eq, Copy, Hash)]
389		pub struct ParseError(ParseErrorKind);
390
391		impl ParseError {
392		/// The category of parse error
393	0	pub const fn kind(&self) -> ParseErrorKind {
394	0	self.0
395	0	}
396		}
397
398		/// The category of parse error
399		#[allow(clippy::manual_non_exhaustive)]
400		#[derive(Debug, Clone, PartialEq, Eq, Copy, Hash)]
401		pub enum ParseErrorKind {
402		/// Given field is out of permitted range.
403		OutOfRange,
404
405		/// There is no possible date and time value with given set of fields.
406		///
407		/// This does not include the out-of-range conditions, which are trivially invalid.
408		/// It includes the case that there are one or more fields that are inconsistent to each other.
409		Impossible,
410
411		/// Given set of fields is not enough to make a requested date and time value.
412		///
413		/// Note that there may be a case that given fields constrain the possible values so much
414		/// that there is a unique possible value. Chrono only tries to be correct for
415		/// most useful sets of fields however, as such constraint solving can be expensive.
416		NotEnough,
417
418		/// The input string has some invalid character sequence for given formatting items.
419		Invalid,
420
421		/// The input string has been prematurely ended.
422		TooShort,
423
424		/// All formatting items have been read but there is a remaining input.
425		TooLong,
426
427		/// There was an error on the formatting string, or there were non-supported formatting items.
428		BadFormat,
429
430		// TODO: Change this to `#[non_exhaustive]` (on the enum) with the next breaking release.
431		#[doc(hidden)]
432		__Nonexhaustive,
433		}
434
435		/// Same as `Result<T, ParseError>`.
436		pub type ParseResult<T> = Result<T, ParseError>;
437
438		impl fmt::Display for ParseError {
439	0	fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
440	0	match self.0 {
441	0	ParseErrorKind::OutOfRange => write!(f, "input is out of range"),
442	0	ParseErrorKind::Impossible => write!(f, "no possible date and time matching input"),
443	0	ParseErrorKind::NotEnough => write!(f, "input is not enough for unique date and time"),
444	0	ParseErrorKind::Invalid => write!(f, "input contains invalid characters"),
445	0	ParseErrorKind::TooShort => write!(f, "premature end of input"),
446	0	ParseErrorKind::TooLong => write!(f, "trailing input"),
447	0	ParseErrorKind::BadFormat => write!(f, "bad or unsupported format string"),
448	0	_ => unreachable!(),
449		}
450	0	}
451		}
452
453		#[cfg(feature = "std")]
454		impl Error for ParseError {
455		#[allow(deprecated)]
456	0	fn description(&self) -> &str {
457	0	"parser error, see to_string() for details"
458	0	}
459		}
460
461		// to be used in this module and submodules
462		pub(crate) const OUT_OF_RANGE: ParseError = ParseError(ParseErrorKind::OutOfRange);
463		const IMPOSSIBLE: ParseError = ParseError(ParseErrorKind::Impossible);
464		const NOT_ENOUGH: ParseError = ParseError(ParseErrorKind::NotEnough);
465		const INVALID: ParseError = ParseError(ParseErrorKind::Invalid);
466		const TOO_SHORT: ParseError = ParseError(ParseErrorKind::TooShort);
467		pub(crate) const TOO_LONG: ParseError = ParseError(ParseErrorKind::TooLong);
468		const BAD_FORMAT: ParseError = ParseError(ParseErrorKind::BadFormat);
469
470		// this implementation is here only because we need some private code from `scan`
471
472		/// Parsing a `str` into a `Weekday` uses the format [`%A`](./format/strftime/index.html).
473		///
474		/// # Example
475		///
476		/// ```
477		/// use chrono::Weekday;
478		///
479		/// assert_eq!("Sunday".parse::<Weekday>(), Ok(Weekday::Sun));
480		/// assert!("any day".parse::<Weekday>().is_err());
481		/// ```
482		///
483		/// The parsing is case-insensitive.
484		///
485		/// ```
486		/// # use chrono::Weekday;
487		/// assert_eq!("mON".parse::<Weekday>(), Ok(Weekday::Mon));
488		/// ```
489		///
490		/// Only the shortest form (e.g. `sun`) and the longest form (e.g. `sunday`) is accepted.
491		///
492		/// ```
493		/// # use chrono::Weekday;
494		/// assert!("thurs".parse::<Weekday>().is_err());
495		/// ```
496		impl FromStr for Weekday {
497		type Err = ParseWeekdayError;
498
499	0	fn from_str(s: &str) -> Result<Self, Self::Err> {
500	0	if let Ok(("", w)) = scan::short_or_long_weekday(s) {
501	0	Ok(w)
502		} else {
503	0	Err(ParseWeekdayError { _dummy: () })
504		}
505	0	}
506		}
507
508		/// Parsing a `str` into a `Month` uses the format [`%B`](./format/strftime/index.html).
509		///
510		/// # Example
511		///
512		/// ```
513		/// use chrono::Month;
514		///
515		/// assert_eq!("January".parse::<Month>(), Ok(Month::January));
516		/// assert!("any day".parse::<Month>().is_err());
517		/// ```
518		///
519		/// The parsing is case-insensitive.
520		///
521		/// ```
522		/// # use chrono::Month;
523		/// assert_eq!("fEbruARy".parse::<Month>(), Ok(Month::February));
524		/// ```
525		///
526		/// Only the shortest form (e.g. `jan`) and the longest form (e.g. `january`) is accepted.
527		///
528		/// ```
529		/// # use chrono::Month;
530		/// assert!("septem".parse::<Month>().is_err());
531		/// assert!("Augustin".parse::<Month>().is_err());
532		/// ```
533		impl FromStr for Month {
534		type Err = ParseMonthError;
535
536		fn from_str(s: &str) -> Result<Self, Self::Err> {
537		if let Ok(("", w)) = scan::short_or_long_month0(s) {
538		match w {
539		0 => Ok(Month::January),
540		1 => Ok(Month::February),
541		2 => Ok(Month::March),
542		3 => Ok(Month::April),
543		4 => Ok(Month::May),
544		5 => Ok(Month::June),
545		6 => Ok(Month::July),
546		7 => Ok(Month::August),
547		8 => Ok(Month::September),
548		9 => Ok(Month::October),
549		10 => Ok(Month::November),
550		11 => Ok(Month::December),
551		_ => Err(ParseMonthError { _dummy: () }),
552		}
553		} else {
554		Err(ParseMonthError { _dummy: () })
555		}
556		}
557		}