13958601093

Committed 19 Mar 2025 04:17PM UTC coverage: 74.164% (-1.5%) from 75.71%

Build # 13958601093

Build Type

push

github

Committed by

web-flow

Commit Message

Clean up properties docs (#6315)

Run Details

58056 of 78281 relevant lines covered (74.16%)

819371.32 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

24.3

/components/datetime/src/options/mod.rs

// This file is part of ICU4X. For terms of use, please see the file
// called LICENSE at the top level of the ICU4X source tree
// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).

//! Options types for date/time formatting.

use icu_time::scaffold::IntoOption;

/// The length of a formatted date/time string.
///
/// Length settings are always a hint, not a guarantee. For example, certain locales and
/// calendar systems do not define numeric names, so spelled-out names could occur even if a
/// short length was requested, and likewise with numeric names with a medium or long length.
///
/// # Examples
///
/// ```
/// use icu::calendar::Gregorian;
/// use icu::datetime::fieldsets::YMD;
/// use icu::datetime::input::Date;
/// use icu::datetime::FixedCalendarDateTimeFormatter;
/// use icu::locale::locale;
/// use writeable::assert_writeable_eq;
///
/// let short_formatter = FixedCalendarDateTimeFormatter::try_new(
///     locale!("en-US").into(),
///     YMD::short(),
/// )
/// .unwrap();
///
/// let medium_formatter = FixedCalendarDateTimeFormatter::try_new(
///     locale!("en-US").into(),
///     YMD::medium(),
/// )
/// .unwrap();
///
/// let long_formatter = FixedCalendarDateTimeFormatter::try_new(
///     locale!("en-US").into(),
///     YMD::long(),
/// )
/// .unwrap();
///
/// assert_writeable_eq!(
///     short_formatter.format(&Date::try_new_gregorian(2000, 1, 1).unwrap()),
///     "1/1/00"
/// );
///
/// assert_writeable_eq!(
///     medium_formatter.format(&Date::try_new_gregorian(2000, 1, 1).unwrap()),
///     "Jan 1, 2000"
/// );
///
/// assert_writeable_eq!(
///     long_formatter.format(&Date::try_new_gregorian(2000, 1, 1).unwrap()),
///     "January 1, 2000"
/// );
/// ```
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Default)]
#[cfg_attr(
    all(feature = "serde", feature = "experimental"),
    derive(serde::Serialize, serde::Deserialize)
)]
#[cfg_attr(
    all(feature = "serde", feature = "experimental"),
    serde(rename_all = "lowercase")
)]
#[repr(u8)] // discriminants come from symbol count in UTS 35
#[non_exhaustive]
pub enum Length {
    /// A long date; typically spelled-out, as in “January 1, 2000”.
    Long = 4,
    /// A medium-sized date; typically abbreviated, as in “Jan. 1, 2000”.
    ///
    /// This is the default.
    #[default]
    Medium = 3,
    /// A short date; typically numeric, as in “1/1/2000”.
    Short = 1,
}

impl IntoOption<Length> for Length {
    #[inline]
    fn into_option(self) -> Option<Self> {
        Some(self)
    }
}

/// The alignment context of the formatted string.
///
/// By default, datetimes are formatted for a variable-width context. You can
/// give a hint that the strings will be displayed in a column-like context,
/// which will coerce numerics to be padded with zeros.
///
/// # Examples
///
/// ```
/// use icu::calendar::Gregorian;
/// use icu::datetime::fieldsets::YMD;
/// use icu::datetime::input::Date;
/// use icu::datetime::options::Alignment;
/// use icu::datetime::FixedCalendarDateTimeFormatter;
/// use icu::locale::locale;
/// use writeable::assert_writeable_eq;
///
/// let plain_formatter =
///     FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
///         locale!("en-US").into(),
///         YMD::short(),
///     )
///     .unwrap();
///
/// let column_formatter =
///     FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
///         locale!("en-US").into(),
///         YMD::short().with_alignment(Alignment::Column),
///     )
///     .unwrap();
///
/// // By default, en-US does not pad the month and day with zeros.
/// assert_writeable_eq!(
///     plain_formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
///     "1/1/25"
/// );
///
/// // The column alignment option hints that they should be padded.
/// assert_writeable_eq!(
///     column_formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
///     "01/01/25"
/// );
/// ```
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Default)]
#[cfg_attr(
    all(feature = "serde", feature = "experimental"),
    derive(serde::Serialize, serde::Deserialize)
)]
#[cfg_attr(
    all(feature = "serde", feature = "experimental"),
    serde(rename_all = "lowercase")
)]
#[non_exhaustive]
pub enum Alignment {
    /// Align fields as the locale specifies them to be aligned.
    ///
    /// This is the default option.
    #[default]
    Auto,
    /// Align fields as appropriate for a column layout. For example:
    ///
    /// | US Holiday   | Date       |
    /// |--------------|------------|
    /// | Memorial Day | 05/26/2025 |
    /// | Labor Day    | 09/01/2025 |
    /// | Veterans Day | 11/11/2025 |
    ///
    /// This option causes numeric fields to be padded when necessary. It does
    /// not impact whether a numeric or spelled-out field is chosen.
    Column,
}

impl IntoOption<Alignment> for Alignment {
    #[inline]
    fn into_option(self) -> Option<Self> {
        Some(self)
    }
}

/// A specification of how to render the year and the era.
///
/// The choices may grow over time; to follow along and offer feedback, see
/// <https://github.com/unicode-org/icu4x/issues/6010>.
///
/// # Examples
///
/// ```
/// use icu::calendar::Gregorian;
/// use icu::datetime::fieldsets::YMD;
/// use icu::datetime::input::Date;
/// use icu::datetime::options::YearStyle;
/// use icu::datetime::FixedCalendarDateTimeFormatter;
/// use icu::locale::locale;
/// use writeable::assert_writeable_eq;
///
/// let formatter = FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
///     locale!("en-US").into(),
///     YMD::short().with_year_style(YearStyle::Auto),
/// )
/// .unwrap();
///
/// // Era displayed when needed for disambiguation,
/// // such as years before year 0 and small year numbers:
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(-1000, 1, 1).unwrap()),
///     "1/1/1001 BC"
/// );
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(77, 1, 1).unwrap()),
///     "1/1/77 AD"
/// );
/// // Era elided for modern years:
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(1900, 1, 1).unwrap()),
///     "1/1/1900"
/// );
/// // Era and century both elided for nearby years:
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
///     "1/1/25"
/// );
///
/// let formatter = FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
///     locale!("en-US").into(),
///     YMD::short().with_year_style(YearStyle::Full),
/// )
/// .unwrap();
///
/// // Era still displayed in cases with ambiguity:
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(-1000, 1, 1).unwrap()),
///     "1/1/1001 BC"
/// );
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(77, 1, 1).unwrap()),
///     "1/1/77 AD"
/// );
/// // Era elided for modern years:
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(1900, 1, 1).unwrap()),
///     "1/1/1900"
/// );
/// // But now we always get a full-precision year:
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
///     "1/1/2025"
/// );
///
/// let formatter = FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
///     locale!("en-US").into(),
///     YMD::short().with_year_style(YearStyle::WithEra),
/// )
/// .unwrap();
///
/// // Era still displayed in cases with ambiguity:
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(-1000, 1, 1).unwrap()),
///     "1/1/1001 BC"
/// );
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(77, 1, 1).unwrap()),
///     "1/1/77 AD"
/// );
/// // But now it is shown even on modern years:
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(1900, 1, 1).unwrap()),
///     "1/1/1900 AD"
/// );
/// assert_writeable_eq!(
///     formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
///     "1/1/2025 AD"
/// );
/// ```
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Default)]
#[cfg_attr(
    all(feature = "serde", feature = "experimental"),
    derive(serde::Serialize, serde::Deserialize)
)]
#[cfg_attr(
    all(feature = "serde", feature = "experimental"),
    serde(rename_all = "camelCase")
)]
#[non_exhaustive]
pub enum YearStyle {
    /// Display the century and/or era when needed to disambiguate the year,
    /// based on locale preferences.
    ///
    /// This is the default option.
    ///
    /// Examples:
    ///
    /// - `1000 BC`
    /// - `77 AD`
    /// - `1900`
    /// - `'24`
    #[default]
    Auto,
    /// Always display the century, and display the era when needed to
    /// disambiguate the year, based on locale preferences.
    ///
    /// Examples:
    ///
    /// - `1000 BC`
    /// - `77 AD`
    /// - `1900`
    /// - `2024`
    Full,
    /// Always display the century and era.
    ///
    /// Examples:
    ///
    /// - `1000 BC`
    /// - `77 AD`
    /// - `1900 AD`
    /// - `2024 AD`
    WithEra,
}

impl IntoOption<YearStyle> for YearStyle {
    #[inline]
    fn into_option(self) -> Option<Self> {
        Some(self)
    }
}

/// A specification for how precisely to display the time of day.
///
/// The time can be displayed with hour, minute, or second precision, and
/// zero-valued fields can be automatically hidden.
///
/// The examples in the discriminants are based on the following inputs and hour cycles:
///
/// 1. 11 o'clock with 12-hour time
/// 2. 16:20 (4:20 pm) with 24-hour time
/// 3. 7:15:01.85 with 24-hour time
///
/// Fractional second digits can be displayed with a fixed precision. If you would like
/// additional options for fractional second digit display, please leave a comment in
/// <https://github.com/unicode-org/icu4x/issues/6008>.
///
/// # Examples
///
/// ```
/// use icu::datetime::input::Time;
/// use icu::datetime::fieldsets::T;
/// use icu::datetime::options::SubsecondDigits;
/// use icu::datetime::options::TimePrecision;
/// use icu::datetime::FixedCalendarDateTimeFormatter;
/// use icu::locale::locale;
/// use writeable::assert_writeable_eq;
///
/// let formatters = [
///     TimePrecision::Hour,
///     TimePrecision::Minute,
///     TimePrecision::Second,
///     TimePrecision::Subsecond(SubsecondDigits::S2),
///     TimePrecision::MinuteOptional,
/// ]
/// .map(|time_precision| {
///     FixedCalendarDateTimeFormatter::<(), _>::try_new(
///         locale!("en-US").into(),
///         T::short().with_time_precision(time_precision),
///     )
///     .unwrap()
/// });
///
/// let times = [
///     Time::try_new(7, 0, 0, 0).unwrap(),
///     Time::try_new(7, 0, 10, 0).unwrap(),
///     Time::try_new(7, 12, 20, 543_200_000).unwrap(),
/// ];
///
/// let expected_value_table = [
///     // 7:00:00, 7:00:10, 7:12:20.5432
///     ["7 AM", "7 AM", "7 AM"],                            // Hour
///     ["7:00 AM", "7:00 AM", "7:12 AM"],                   // Minute
///     ["7:00:00 AM", "7:00:10 AM", "7:12:20 AM"],          // Second
///     ["7:00:00.00 AM", "7:00:10.00 AM", "7:12:20.54 AM"], // Subsecond(F2)
///     ["7 AM", "7 AM", "7:12 AM"],                         // MinuteOptional
/// ];
///
/// for (expected_value_row, formatter) in
///     expected_value_table.iter().zip(formatters.iter())
/// {
///     for (expected_value, time) in
///         expected_value_row.iter().zip(times.iter())
///     {
///         assert_writeable_eq!(
///             formatter.format(time),
///             *expected_value,
///             "{formatter:?} @ {time:?}"
///         );
///     }
/// }
/// ```
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Default)]
#[cfg_attr(
    all(feature = "serde", feature = "experimental"),
    derive(serde::Serialize, serde::Deserialize)
)]
#[cfg_attr(
    all(feature = "serde", feature = "experimental"),
    serde(from = "TimePrecisionSerde", into = "TimePrecisionSerde")
)]
#[non_exhaustive]
pub enum TimePrecision {
    /// Display the hour. Hide all other time fields.
    ///
    /// Examples:
    ///
    /// 1. `11 am`
    /// 2. `16h`
    /// 3. `07h`
    Hour,
    /// Display the hour and minute. Hide the second.
    ///
    /// Examples:
    ///
    /// 1. `11:00 am`
    /// 2. `16:20`
    /// 3. `07:15`
    Minute,
    /// Display the hour, minute, and second. Hide fractional seconds.
    ///
    /// This is currently the default, but the default is subject to change.
    ///
    /// Examples:
    ///
    /// 1. `11:00:00 am`
    /// 2. `16:20:00`
    /// 3. `07:15:01`
    #[default]
    Second,
    /// Display the hour, minute, and second with the given number of
    /// fractional second digits.
    ///
    /// Examples with [`SubsecondDigits::S1`]:
    ///
    /// 1. `11:00:00.0 am`
    /// 2. `16:20:00.0`
    /// 3. `07:15:01.8`
    Subsecond(SubsecondDigits),
    /// Display the hour; display the minute if nonzero. Hide the second.
    ///
    /// Examples:
    ///
    /// 1. `11 am`
    /// 2. `16:20`
    /// 3. `07:15`
    MinuteOptional,
}

impl IntoOption<TimePrecision> for TimePrecision {
    #[inline]
    fn into_option(self) -> Option<Self> {
        Some(self)
    }
}

#[cfg(all(feature = "serde", feature = "experimental"))]
#[derive(Copy, Clone, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
enum TimePrecisionSerde {
    Hour,
    Minute,
    Second,
    Subsecond1,
    Subsecond2,
    Subsecond3,
    Subsecond4,
    Subsecond5,
    Subsecond6,
    Subsecond7,
    Subsecond8,
    Subsecond9,
    MinuteOptional,
}

#[cfg(all(feature = "serde", feature = "experimental"))]
impl From<TimePrecision> for TimePrecisionSerde {
    fn from(value: TimePrecision) -> Self {
        match value {
            TimePrecision::Hour => TimePrecisionSerde::Hour,
            TimePrecision::Minute => TimePrecisionSerde::Minute,
            TimePrecision::Second => TimePrecisionSerde::Second,
            TimePrecision::Subsecond(SubsecondDigits::S1) => TimePrecisionSerde::Subsecond1,
            TimePrecision::Subsecond(SubsecondDigits::S2) => TimePrecisionSerde::Subsecond2,
            TimePrecision::Subsecond(SubsecondDigits::S3) => TimePrecisionSerde::Subsecond3,
            TimePrecision::Subsecond(SubsecondDigits::S4) => TimePrecisionSerde::Subsecond4,
            TimePrecision::Subsecond(SubsecondDigits::S5) => TimePrecisionSerde::Subsecond5,
            TimePrecision::Subsecond(SubsecondDigits::S6) => TimePrecisionSerde::Subsecond6,
            TimePrecision::Subsecond(SubsecondDigits::S7) => TimePrecisionSerde::Subsecond7,
            TimePrecision::Subsecond(SubsecondDigits::S8) => TimePrecisionSerde::Subsecond8,
            TimePrecision::Subsecond(SubsecondDigits::S9) => TimePrecisionSerde::Subsecond9,
            TimePrecision::MinuteOptional => TimePrecisionSerde::MinuteOptional,
        }
    }
}

#[cfg(all(feature = "serde", feature = "experimental"))]
impl From<TimePrecisionSerde> for TimePrecision {
    fn from(value: TimePrecisionSerde) -> Self {
        match value {
            TimePrecisionSerde::Hour => TimePrecision::Hour,
            TimePrecisionSerde::Minute => TimePrecision::Minute,
            TimePrecisionSerde::Second => TimePrecision::Second,
            TimePrecisionSerde::Subsecond1 => TimePrecision::Subsecond(SubsecondDigits::S1),
            TimePrecisionSerde::Subsecond2 => TimePrecision::Subsecond(SubsecondDigits::S2),
            TimePrecisionSerde::Subsecond3 => TimePrecision::Subsecond(SubsecondDigits::S3),
            TimePrecisionSerde::Subsecond4 => TimePrecision::Subsecond(SubsecondDigits::S4),
            TimePrecisionSerde::Subsecond5 => TimePrecision::Subsecond(SubsecondDigits::S5),
            TimePrecisionSerde::Subsecond6 => TimePrecision::Subsecond(SubsecondDigits::S6),
            TimePrecisionSerde::Subsecond7 => TimePrecision::Subsecond(SubsecondDigits::S7),
            TimePrecisionSerde::Subsecond8 => TimePrecision::Subsecond(SubsecondDigits::S8),
            TimePrecisionSerde::Subsecond9 => TimePrecision::Subsecond(SubsecondDigits::S9),
            TimePrecisionSerde::MinuteOptional => TimePrecision::MinuteOptional,
        }
    }
}

/// A specification for how many fractional second digits to display.
///
/// For example, to display the time with millisecond precision, use
/// [`SubsecondDigits::S3`].
///
/// Lower-precision digits will be truncated.
///
/// # Examples
///
/// Times can be displayed with a custom number of fractional digits from 0-9:
///
/// ```
/// use icu::calendar::Gregorian;
/// use icu::datetime::fieldsets::T;
/// use icu::datetime::input::Time;
/// use icu::datetime::options::SubsecondDigits;
/// use icu::datetime::options::TimePrecision;
/// use icu::datetime::FixedCalendarDateTimeFormatter;
/// use icu::locale::locale;
/// use writeable::assert_writeable_eq;
///
/// let formatter = FixedCalendarDateTimeFormatter::<(), _>::try_new(
///     locale!("en-US").into(),
///     T::short()
///         .with_time_precision(TimePrecision::Subsecond(SubsecondDigits::S2)),
/// )
/// .unwrap();
///
/// assert_writeable_eq!(
///     formatter.format(&Time::try_new(16, 12, 20, 543200000).unwrap()),
///     "4:12:20.54 PM"
/// );
/// ```
#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum SubsecondDigits {
    /// One fractional digit (tenths of a second).
    S1 = 1,
    /// Two fractional digits (hundredths of a second).
    S2 = 2,
    /// Three fractional digits (milliseconds).
    S3 = 3,
    /// Four fractional digits.
    S4 = 4,
    /// Five fractional digits.
    S5 = 5,
    /// Six fractional digits (microseconds).
    S6 = 6,
    /// Seven fractional digits.
    S7 = 7,
    /// Eight fractional digits.
    S8 = 8,
    /// Nine fractional digits (nanoseconds)
    S9 = 9,
}

/// An error from constructing [`SubsecondDigits`].
#[derive(Debug, Copy, Clone, PartialEq, Eq, displaydoc::Display)]
#[non_exhaustive]
pub enum SubsecondError {
    /// The provided value is out of range (0-9).
    OutOfRange,
}

impl core::error::Error for SubsecondError {}

impl From<SubsecondDigits> for u8 {
    fn from(value: SubsecondDigits) -> u8 {
        use SubsecondDigits::*;
        match value {
            S1 => 1,
            S2 => 2,
            S3 => 3,
            S4 => 4,
            S5 => 5,
            S6 => 6,
            S7 => 7,
            S8 => 8,
            S9 => 9,
        }
    }
}

impl TryFrom<u8> for SubsecondDigits {
    type Error = SubsecondError;
    fn try_from(value: u8) -> Result<Self, Self::Error> {
        use SubsecondDigits::*;
        match value {
            1 => Ok(S1),
            2 => Ok(S2),
            3 => Ok(S3),
            4 => Ok(S4),
            5 => Ok(S5),
            6 => Ok(S6),
            7 => Ok(S7),
            8 => Ok(S8),
            9 => Ok(S9),
            _ => Err(SubsecondError::OutOfRange),
        }
    }
}

1	// This file is part of ICU4X. For terms of use, please see the file
2	// called LICENSE at the top level of the ICU4X source tree
3	// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
4
5	//! Options types for date/time formatting.
6
7	use icu_time::scaffold::IntoOption;
8
9	/// The length of a formatted date/time string.
10	///
11	/// Length settings are always a hint, not a guarantee. For example, certain locales and
12	/// calendar systems do not define numeric names, so spelled-out names could occur even if a
13	/// short length was requested, and likewise with numeric names with a medium or long length.
14	///
15	/// # Examples
16	///
17	/// ```
18	/// use icu::calendar::Gregorian;
19	/// use icu::datetime::fieldsets::YMD;
20	/// use icu::datetime::input::Date;
21	/// use icu::datetime::FixedCalendarDateTimeFormatter;
22	/// use icu::locale::locale;
23	/// use writeable::assert_writeable_eq;
24	///
25	/// let short_formatter = FixedCalendarDateTimeFormatter::try_new(
26	/// locale!("en-US").into(),
27	/// YMD::short(),
28	/// )
29	/// .unwrap();
30	///
31	/// let medium_formatter = FixedCalendarDateTimeFormatter::try_new(
32	/// locale!("en-US").into(),
33	/// YMD::medium(),
34	/// )
35	/// .unwrap();
36	///
37	/// let long_formatter = FixedCalendarDateTimeFormatter::try_new(
38	/// locale!("en-US").into(),
39	/// YMD::long(),
40	/// )
41	/// .unwrap();
42	///
43	/// assert_writeable_eq!(
44	/// short_formatter.format(&Date::try_new_gregorian(2000, 1, 1).unwrap()),
45	/// "1/1/00"
46	/// );
47	///
48	/// assert_writeable_eq!(
49	/// medium_formatter.format(&Date::try_new_gregorian(2000, 1, 1).unwrap()),
50	/// "Jan 1, 2000"
51	/// );
52	///
53	/// assert_writeable_eq!(
54	/// long_formatter.format(&Date::try_new_gregorian(2000, 1, 1).unwrap()),
55	/// "January 1, 2000"
56	/// );
57	/// ```
58	#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Default)]	1,885✔
59	#[cfg_attr(
60	all(feature = "serde", feature = "experimental"),
61	derive(serde::Serialize, serde::Deserialize)	×
62	)]
63	#[cfg_attr(
64	all(feature = "serde", feature = "experimental"),
65	serde(rename_all = "lowercase")
66	)]
67	#[repr(u8)] // discriminants come from symbol count in UTS 35
68	#[non_exhaustive]
69	pub enum Length {	×
70	/// A long date; typically spelled-out, as in “January 1, 2000”.
71	Long = 4,	×
72	/// A medium-sized date; typically abbreviated, as in “Jan. 1, 2000”.
73	///
74	/// This is the default.
75	#[default]
76	Medium = 3,	939✔
77	/// A short date; typically numeric, as in “1/1/2000”.
78	Short = 1,	×
79	}
80
81	impl IntoOption<Length> for Length {
82	#[inline]
83	fn into_option(self) -> Option<Self> {	×
84	Some(self)	×
85	}	×
86	}
87
88	/// The alignment context of the formatted string.
89	///
90	/// By default, datetimes are formatted for a variable-width context. You can
91	/// give a hint that the strings will be displayed in a column-like context,
92	/// which will coerce numerics to be padded with zeros.
93	///
94	/// # Examples
95	///
96	/// ```
97	/// use icu::calendar::Gregorian;
98	/// use icu::datetime::fieldsets::YMD;
99	/// use icu::datetime::input::Date;
100	/// use icu::datetime::options::Alignment;
101	/// use icu::datetime::FixedCalendarDateTimeFormatter;
102	/// use icu::locale::locale;
103	/// use writeable::assert_writeable_eq;
104	///
105	/// let plain_formatter =
106	/// FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
107	/// locale!("en-US").into(),
108	/// YMD::short(),
109	/// )
110	/// .unwrap();
111	///
112	/// let column_formatter =
113	/// FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
114	/// locale!("en-US").into(),
115	/// YMD::short().with_alignment(Alignment::Column),
116	/// )
117	/// .unwrap();
118	///
119	/// // By default, en-US does not pad the month and day with zeros.
120	/// assert_writeable_eq!(
121	/// plain_formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
122	/// "1/1/25"
123	/// );
124	///
125	/// // The column alignment option hints that they should be padded.
126	/// assert_writeable_eq!(
127	/// column_formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
128	/// "01/01/25"
129	/// );
130	/// ```
131	#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Default)]	15,814✔
132	#[cfg_attr(
133	all(feature = "serde", feature = "experimental"),
134	derive(serde::Serialize, serde::Deserialize)	×
135	)]
136	#[cfg_attr(
137	all(feature = "serde", feature = "experimental"),
138	serde(rename_all = "lowercase")
139	)]
140	#[non_exhaustive]
141	pub enum Alignment {	×
142	/// Align fields as the locale specifies them to be aligned.
143	///
144	/// This is the default option.
145	#[default]
146	Auto,	7,905✔
147	/// Align fields as appropriate for a column layout. For example:
148	///
149	/// \| US Holiday \| Date \|
150	/// \|--------------\|------------\|
151	/// \| Memorial Day \| 05/26/2025 \|
152	/// \| Labor Day \| 09/01/2025 \|
153	/// \| Veterans Day \| 11/11/2025 \|
154	///
155	/// This option causes numeric fields to be padded when necessary. It does
156	/// not impact whether a numeric or spelled-out field is chosen.
157	Column,	×
158	}
159
160	impl IntoOption<Alignment> for Alignment {
161	#[inline]
162	fn into_option(self) -> Option<Self> {	×
163	Some(self)	×
164	}	×
165	}
166
167	/// A specification of how to render the year and the era.
168	///
169	/// The choices may grow over time; to follow along and offer feedback, see
170	/// <https://github.com/unicode-org/icu4x/issues/6010>.
171	///
172	/// # Examples
173	///
174	/// ```
175	/// use icu::calendar::Gregorian;
176	/// use icu::datetime::fieldsets::YMD;
177	/// use icu::datetime::input::Date;
178	/// use icu::datetime::options::YearStyle;
179	/// use icu::datetime::FixedCalendarDateTimeFormatter;
180	/// use icu::locale::locale;
181	/// use writeable::assert_writeable_eq;
182	///
183	/// let formatter = FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
184	/// locale!("en-US").into(),
185	/// YMD::short().with_year_style(YearStyle::Auto),
186	/// )
187	/// .unwrap();
188	///
189	/// // Era displayed when needed for disambiguation,
190	/// // such as years before year 0 and small year numbers:
191	/// assert_writeable_eq!(
192	/// formatter.format(&Date::try_new_gregorian(-1000, 1, 1).unwrap()),
193	/// "1/1/1001 BC"
194	/// );
195	/// assert_writeable_eq!(
196	/// formatter.format(&Date::try_new_gregorian(77, 1, 1).unwrap()),
197	/// "1/1/77 AD"
198	/// );
199	/// // Era elided for modern years:
200	/// assert_writeable_eq!(
201	/// formatter.format(&Date::try_new_gregorian(1900, 1, 1).unwrap()),
202	/// "1/1/1900"
203	/// );
204	/// // Era and century both elided for nearby years:
205	/// assert_writeable_eq!(
206	/// formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
207	/// "1/1/25"
208	/// );
209	///
210	/// let formatter = FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
211	/// locale!("en-US").into(),
212	/// YMD::short().with_year_style(YearStyle::Full),
213	/// )
214	/// .unwrap();
215	///
216	/// // Era still displayed in cases with ambiguity:
217	/// assert_writeable_eq!(
218	/// formatter.format(&Date::try_new_gregorian(-1000, 1, 1).unwrap()),
219	/// "1/1/1001 BC"
220	/// );
221	/// assert_writeable_eq!(
222	/// formatter.format(&Date::try_new_gregorian(77, 1, 1).unwrap()),
223	/// "1/1/77 AD"
224	/// );
225	/// // Era elided for modern years:
226	/// assert_writeable_eq!(
227	/// formatter.format(&Date::try_new_gregorian(1900, 1, 1).unwrap()),
228	/// "1/1/1900"
229	/// );
230	/// // But now we always get a full-precision year:
231	/// assert_writeable_eq!(
232	/// formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
233	/// "1/1/2025"
234	/// );
235	///
236	/// let formatter = FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
237	/// locale!("en-US").into(),
238	/// YMD::short().with_year_style(YearStyle::WithEra),
239	/// )
240	/// .unwrap();
241	///
242	/// // Era still displayed in cases with ambiguity:
243	/// assert_writeable_eq!(
244	/// formatter.format(&Date::try_new_gregorian(-1000, 1, 1).unwrap()),
245	/// "1/1/1001 BC"
246	/// );
247	/// assert_writeable_eq!(
248	/// formatter.format(&Date::try_new_gregorian(77, 1, 1).unwrap()),
249	/// "1/1/77 AD"
250	/// );
251	/// // But now it is shown even on modern years:
252	/// assert_writeable_eq!(
253	/// formatter.format(&Date::try_new_gregorian(1900, 1, 1).unwrap()),
254	/// "1/1/1900 AD"
255	/// );
256	/// assert_writeable_eq!(
257	/// formatter.format(&Date::try_new_gregorian(2025, 1, 1).unwrap()),
258	/// "1/1/2025 AD"
259	/// );
260	/// ```
261	#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Default)]	465✔
262	#[cfg_attr(
263	all(feature = "serde", feature = "experimental"),
264	derive(serde::Serialize, serde::Deserialize)	×
265	)]
266	#[cfg_attr(
267	all(feature = "serde", feature = "experimental"),
268	serde(rename_all = "camelCase")
269	)]
270	#[non_exhaustive]
271	pub enum YearStyle {	×
272	/// Display the century and/or era when needed to disambiguate the year,
273	/// based on locale preferences.
274	///
275	/// This is the default option.
276	///
277	/// Examples:
278	///
279	/// - `1000 BC`
280	/// - `77 AD`
281	/// - `1900`
282	/// - `'24`
283	#[default]
284	Auto,	231✔
285	/// Always display the century, and display the era when needed to
286	/// disambiguate the year, based on locale preferences.
287	///
288	/// Examples:
289	///
290	/// - `1000 BC`
291	/// - `77 AD`
292	/// - `1900`
293	/// - `2024`
294	Full,	×
295	/// Always display the century and era.
296	///
297	/// Examples:
298	///
299	/// - `1000 BC`
300	/// - `77 AD`
301	/// - `1900 AD`
302	/// - `2024 AD`
303	WithEra,	×
304	}
305
306	impl IntoOption<YearStyle> for YearStyle {
307	#[inline]
308	fn into_option(self) -> Option<Self> {	×
309	Some(self)	×
310	}	×
311	}
312
313	/// A specification for how precisely to display the time of day.
314	///
315	/// The time can be displayed with hour, minute, or second precision, and
316	/// zero-valued fields can be automatically hidden.
317	///
318	/// The examples in the discriminants are based on the following inputs and hour cycles:
319	///
320	/// 1. 11 o'clock with 12-hour time
321	/// 2. 16:20 (4:20 pm) with 24-hour time
322	/// 3. 7:15:01.85 with 24-hour time
323	///
324	/// Fractional second digits can be displayed with a fixed precision. If you would like
325	/// additional options for fractional second digit display, please leave a comment in
326	/// <https://github.com/unicode-org/icu4x/issues/6008>.
327	///
328	/// # Examples
329	///
330	/// ```
331	/// use icu::datetime::input::Time;
332	/// use icu::datetime::fieldsets::T;
333	/// use icu::datetime::options::SubsecondDigits;
334	/// use icu::datetime::options::TimePrecision;
335	/// use icu::datetime::FixedCalendarDateTimeFormatter;
336	/// use icu::locale::locale;
337	/// use writeable::assert_writeable_eq;
338	///
339	/// let formatters = [
340	/// TimePrecision::Hour,
341	/// TimePrecision::Minute,
342	/// TimePrecision::Second,
343	/// TimePrecision::Subsecond(SubsecondDigits::S2),
344	/// TimePrecision::MinuteOptional,
345	/// ]
346	/// .map(\|time_precision\| {
347	/// FixedCalendarDateTimeFormatter::<(), _>::try_new(
348	/// locale!("en-US").into(),
349	/// T::short().with_time_precision(time_precision),
350	/// )
351	/// .unwrap()
352	/// });
353	///
354	/// let times = [
355	/// Time::try_new(7, 0, 0, 0).unwrap(),
356	/// Time::try_new(7, 0, 10, 0).unwrap(),
357	/// Time::try_new(7, 12, 20, 543_200_000).unwrap(),
358	/// ];
359	///
360	/// let expected_value_table = [
361	/// // 7:00:00, 7:00:10, 7:12:20.5432
362	/// ["7 AM", "7 AM", "7 AM"], // Hour
363	/// ["7:00 AM", "7:00 AM", "7:12 AM"], // Minute
364	/// ["7:00:00 AM", "7:00:10 AM", "7:12:20 AM"], // Second
365	/// ["7:00:00.00 AM", "7:00:10.00 AM", "7:12:20.54 AM"], // Subsecond(F2)
366	/// ["7 AM", "7 AM", "7:12 AM"], // MinuteOptional
367	/// ];
368	///
369	/// for (expected_value_row, formatter) in
370	/// expected_value_table.iter().zip(formatters.iter())
371	/// {
372	/// for (expected_value, time) in
373	/// expected_value_row.iter().zip(times.iter())
374	/// {
375	/// assert_writeable_eq!(
376	/// formatter.format(time),
377	/// *expected_value,
378	/// "{formatter:?} @ {time:?}"
379	/// );
380	/// }
381	/// }
382	/// ```
383	#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Default)]	1,266✔
384	#[cfg_attr(
385	all(feature = "serde", feature = "experimental"),
386	derive(serde::Serialize, serde::Deserialize)	492✔
387	)]
388	#[cfg_attr(
389	all(feature = "serde", feature = "experimental"),
390	serde(from = "TimePrecisionSerde", into = "TimePrecisionSerde")
391	)]
392	#[non_exhaustive]
393	pub enum TimePrecision {
394	/// Display the hour. Hide all other time fields.
395	///
396	/// Examples:
397	///
398	/// 1. `11 am`
399	/// 2. `16h`
400	/// 3. `07h`
401	Hour,
402	/// Display the hour and minute. Hide the second.
403	///
404	/// Examples:
405	///
406	/// 1. `11:00 am`
407	/// 2. `16:20`
408	/// 3. `07:15`
409	Minute,
410	/// Display the hour, minute, and second. Hide fractional seconds.
411	///
412	/// This is currently the default, but the default is subject to change.
413	///
414	/// Examples:
415	///
416	/// 1. `11:00:00 am`
417	/// 2. `16:20:00`
418	/// 3. `07:15:01`
419	#[default]
420	Second,	41✔
421	/// Display the hour, minute, and second with the given number of
422	/// fractional second digits.
423	///
424	/// Examples with [`SubsecondDigits::S1`]:
425	///
426	/// 1. `11:00:00.0 am`
427	/// 2. `16:20:00.0`
428	/// 3. `07:15:01.8`
429	Subsecond(SubsecondDigits),	1✔
430	/// Display the hour; display the minute if nonzero. Hide the second.
431	///
432	/// Examples:
433	///
434	/// 1. `11 am`
435	/// 2. `16:20`
436	/// 3. `07:15`
437	MinuteOptional,
438	}
439
440	impl IntoOption<TimePrecision> for TimePrecision {
441	#[inline]
442	fn into_option(self) -> Option<Self> {	×
443	Some(self)	×
444	}	×
445	}
446
447	#[cfg(all(feature = "serde", feature = "experimental"))]
448	#[derive(Copy, Clone, serde::Serialize, serde::Deserialize)]	1,181✔
449	#[serde(rename_all = "camelCase")]
450	enum TimePrecisionSerde {	197✔
451	Hour,	99✔
452	Minute,	99✔
453	Second,	×
454	Subsecond1,	×
455	Subsecond2,	×
456	Subsecond3,	×
457	Subsecond4,	×
458	Subsecond5,	×
459	Subsecond6,	×
460	Subsecond7,	×
461	Subsecond8,	×
462	Subsecond9,	×
463	MinuteOptional,	×
464	}
465
466	#[cfg(all(feature = "serde", feature = "experimental"))]
467	impl From<TimePrecision> for TimePrecisionSerde {
468	fn from(value: TimePrecision) -> Self {	295✔
469	match value {	295✔
470	TimePrecision::Hour => TimePrecisionSerde::Hour,	×
471	TimePrecision::Minute => TimePrecisionSerde::Minute,	295✔
472	TimePrecision::Second => TimePrecisionSerde::Second,	×
473	TimePrecision::Subsecond(SubsecondDigits::S1) => TimePrecisionSerde::Subsecond1,	×
474	TimePrecision::Subsecond(SubsecondDigits::S2) => TimePrecisionSerde::Subsecond2,	×
475	TimePrecision::Subsecond(SubsecondDigits::S3) => TimePrecisionSerde::Subsecond3,	×
476	TimePrecision::Subsecond(SubsecondDigits::S4) => TimePrecisionSerde::Subsecond4,	×
477	TimePrecision::Subsecond(SubsecondDigits::S5) => TimePrecisionSerde::Subsecond5,	×
478	TimePrecision::Subsecond(SubsecondDigits::S6) => TimePrecisionSerde::Subsecond6,	×
479	TimePrecision::Subsecond(SubsecondDigits::S7) => TimePrecisionSerde::Subsecond7,	×
480	TimePrecision::Subsecond(SubsecondDigits::S8) => TimePrecisionSerde::Subsecond8,	×
481	TimePrecision::Subsecond(SubsecondDigits::S9) => TimePrecisionSerde::Subsecond9,	×
482	TimePrecision::MinuteOptional => TimePrecisionSerde::MinuteOptional,	×
483	}
484	}	295✔
485	}
486
487	#[cfg(all(feature = "serde", feature = "experimental"))]
488	impl From<TimePrecisionSerde> for TimePrecision {
489	fn from(value: TimePrecisionSerde) -> Self {	230✔
490	match value {	230✔
491	TimePrecisionSerde::Hour => TimePrecision::Hour,	6✔
492	TimePrecisionSerde::Minute => TimePrecision::Minute,	210✔
493	TimePrecisionSerde::Second => TimePrecision::Second,	13✔
494	TimePrecisionSerde::Subsecond1 => TimePrecision::Subsecond(SubsecondDigits::S1),	×
495	TimePrecisionSerde::Subsecond2 => TimePrecision::Subsecond(SubsecondDigits::S2),	×
496	TimePrecisionSerde::Subsecond3 => TimePrecision::Subsecond(SubsecondDigits::S3),	×
497	TimePrecisionSerde::Subsecond4 => TimePrecision::Subsecond(SubsecondDigits::S4),	×
498	TimePrecisionSerde::Subsecond5 => TimePrecision::Subsecond(SubsecondDigits::S5),	×
499	TimePrecisionSerde::Subsecond6 => TimePrecision::Subsecond(SubsecondDigits::S6),	×
500	TimePrecisionSerde::Subsecond7 => TimePrecision::Subsecond(SubsecondDigits::S7),	×
501	TimePrecisionSerde::Subsecond8 => TimePrecision::Subsecond(SubsecondDigits::S8),	×
502	TimePrecisionSerde::Subsecond9 => TimePrecision::Subsecond(SubsecondDigits::S9),	1✔
503	TimePrecisionSerde::MinuteOptional => TimePrecision::MinuteOptional,	×
504	}
505	}	230✔
506	}
507
508	/// A specification for how many fractional second digits to display.
509	///
510	/// For example, to display the time with millisecond precision, use
511	/// [`SubsecondDigits::S3`].
512	///
513	/// Lower-precision digits will be truncated.
514	///
515	/// # Examples
516	///
517	/// Times can be displayed with a custom number of fractional digits from 0-9:
518	///
519	/// ```
520	/// use icu::calendar::Gregorian;
521	/// use icu::datetime::fieldsets::T;
522	/// use icu::datetime::input::Time;
523	/// use icu::datetime::options::SubsecondDigits;
524	/// use icu::datetime::options::TimePrecision;
525	/// use icu::datetime::FixedCalendarDateTimeFormatter;
526	/// use icu::locale::locale;
527	/// use writeable::assert_writeable_eq;
528	///
529	/// let formatter = FixedCalendarDateTimeFormatter::<(), _>::try_new(
530	/// locale!("en-US").into(),
531	/// T::short()
532	/// .with_time_precision(TimePrecision::Subsecond(SubsecondDigits::S2)),
533	/// )
534	/// .unwrap();
535	///
536	/// assert_writeable_eq!(
537	/// formatter.format(&Time::try_new(16, 12, 20, 543200000).unwrap()),
538	/// "4:12:20.54 PM"
539	/// );
540	/// ```
541	#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]	2✔
542	#[non_exhaustive]
543	pub enum SubsecondDigits {
544	/// One fractional digit (tenths of a second).
545	S1 = 1,
546	/// Two fractional digits (hundredths of a second).
547	S2 = 2,
548	/// Three fractional digits (milliseconds).
549	S3 = 3,
550	/// Four fractional digits.
551	S4 = 4,
552	/// Five fractional digits.
553	S5 = 5,
554	/// Six fractional digits (microseconds).
555	S6 = 6,
556	/// Seven fractional digits.
557	S7 = 7,
558	/// Eight fractional digits.
559	S8 = 8,
560	/// Nine fractional digits (nanoseconds)
561	S9 = 9,
562	}
563
564	/// An error from constructing [`SubsecondDigits`].
565	#[derive(Debug, Copy, Clone, PartialEq, Eq, displaydoc::Display)]	×
566	#[non_exhaustive]
567	pub enum SubsecondError {
568	/// The provided value is out of range (0-9).
569	OutOfRange,
570	}
571
572	impl core::error::Error for SubsecondError {}
573
574	impl From<SubsecondDigits> for u8 {
575	fn from(value: SubsecondDigits) -> u8 {	×
576	use SubsecondDigits::*;
577	match value {	×
578	S1 => 1,	×
579	S2 => 2,	×
580	S3 => 3,	×
581	S4 => 4,	×
582	S5 => 5,	×
583	S6 => 6,	×
584	S7 => 7,	×
585	S8 => 8,	×
586	S9 => 9,	×
587	}
588	}	×
589	}
590
591	impl TryFrom<u8> for SubsecondDigits {
592	type Error = SubsecondError;
593	fn try_from(value: u8) -> Result<Self, Self::Error> {	×
594	use SubsecondDigits::*;
595	match value {	×
596	1 => Ok(S1),	×
597	2 => Ok(S2),	×
598	3 => Ok(S3),	×
599	4 => Ok(S4),	×
600	5 => Ok(S5),	×
601	6 => Ok(S6),	×
602	7 => Ok(S7),	×
603	8 => Ok(S8),	×
604	9 => Ok(S9),	×
605	_ => Err(SubsecondError::OutOfRange),	×
606	}
607	}	×
608	}

zbraniecki / icu4x / 13958601093

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous