Struct icu::datetime::pattern::DateTimePattern

pub struct DateTimePattern { /* private fields */ }

A pattern for formatting a datetime in a calendar.

❗ This type forgoes most internationalization functionality of the datetime crate. It assumes that the pattern is already localized for the customer’s locale. Most clients should use DateTimeFormatter instead of directly formatting with patterns.

There are two ways to make one of these:

1. From a custom pattern string: DateTimePattern::try_from_pattern_str
2. From a formatted datetime: FormattedDateTime::pattern

Things you can do with one of these:

1. Use it to directly format a datetime via TypedDateTimeNames
2. Convert it to a string pattern via Writeable
3. Get the resolved components

📏 This item has a stack size of 32 bytes on the stable toolchain at release date.

Examples

Create a pattern from a custom string and compare it to one from data, then check the resolved components:

use icu::calendar::Date;
use icu::calendar::Gregorian;
use icu::datetime::fields::components;
use icu::datetime::fieldsets::YMD;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::FixedCalendarDateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

// Create the pattern from a string:
let pattern_str = "d MMM y";
let custom_pattern =
    DateTimePattern::try_from_pattern_str(pattern_str).unwrap();
assert_writeable_eq!(custom_pattern, pattern_str);

// Load data that resolves to the same pattern:
let data_pattern = FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
    locale!("es-MX").into(),
    YMD::medium(),
)
.unwrap()
// The pattern can depend on the datetime being formatted.
.format(
    &Date::try_new_iso(2024, 1, 1)
        .unwrap()
        .to_calendar(Gregorian),
)
.pattern();
assert_writeable_eq!(data_pattern, pattern_str);
assert_eq!(custom_pattern, data_pattern);

// Check the resolved components:
let mut expected_components_bag = components::Bag::default();
expected_components_bag.year = Some(components::Year::Numeric);
expected_components_bag.month = Some(components::Month::Short);
expected_components_bag.day = Some(components::Day::NumericDayOfMonth);
let actual_components_bag = components::Bag::from(&data_pattern);
assert_eq!(actual_components_bag, expected_components_bag);

Check the hour cycle of a resolved pattern:

use icu::calendar::Time;
use icu::datetime::fields::components;
use icu::datetime::fieldsets::T;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::TimeFormatter;
use icu::locale::locale;
use icu::locale::preferences::extensions::unicode::keywords::HourCycle;
use writeable::assert_writeable_eq;

let pattern = TimeFormatter::try_new(
    locale!("es-MX").into(),
    T::medium(),
)
.unwrap()
// The pattern can depend on the datetime being formatted.
.format(&Time::try_new(12, 0, 0, 0).unwrap())
.pattern();

assert_writeable_eq!(pattern, "hh:mm:ss a");

// Get the hour cycle from the resolved components:
let components = components::Bag::from(&pattern);
assert_eq!(components.hour_cycle, Some(HourCycle::H12));

Implementations

impl DateTimePattern

pub fn try_from_pattern_str( pattern_str: &str, ) -> Result<DateTimePattern, PatternError>

Creates a DateTimePattern from a pattern string.

For more details on the syntax, see UTS 35: https://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns

impl DateTimePattern

pub fn to_string(&self) -> String

Converts the given value to a String.

Under the hood, this uses an efficient Writeable implementation. However, in order to avoid allocating a string, it is more efficient to use Writeable directly.

Trait Implementations

impl Debug for DateTimePattern

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for DateTimePattern

This trait is implemented for compatibility with fmt!. To create a string, Writeable::write_to_string is usually more efficient.

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<&DateTimePattern> for Bag

fn from(value: &DateTimePattern) -> Bag

Converts to this type from the input type.

impl FromStr for DateTimePattern

type Err = PatternError

The associated error which can be returned from parsing.

fn from_str( s: &str, ) -> Result<DateTimePattern, <DateTimePattern as FromStr>::Err>

Parses a string s to return a value of this type.

impl PartialEq for DateTimePattern

fn eq(&self, other: &DateTimePattern) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Writeable for DateTimePattern

fn write_to<W>(&self, sink: &mut W) -> Result<(), Error>

where W: Write + ?Sized,

Writes a string to the given sink. Errors from the sink are bubbled up. The default implementation delegates to write_to_parts, and discards any Part annotations.

fn write_to_parts<S>(&self, sink: &mut S) -> Result<(), Error>

where S: PartsWrite + ?Sized,

Write bytes and Part annotations to the given sink. Errors from the sink are bubbled up. The default implementation delegates to write_to, and doesn’t produce any Part annotations.

fn writeable_length_hint(&self) -> LengthHint

Returns a hint for the number of UTF-8 bytes that will be written to the sink.

fn write_to_string(&self) -> Cow<'_, str>

Creates a new String with the data from this Writeable. Like ToString, but smaller and faster.

impl Eq for DateTimePattern