Struct icu::datetime::pattern::TypedDateTimeNames

source ·

pub struct TypedDateTimeNames<C, FSet = CompositeDateTimeFieldSet>where
    C: CldrCalendar,
    FSet: DateTimeNamesMarker,
{ /* private fields */ }

Expand description

A low-level type that formats datetime patterns with localized names. The calendar should be chosen at compile time.

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

Type parameters:

The calendar chosen at compile time for additional type safety
A components object type containing the fields that might be formatted

By default, the components object is set to CompositeDateTimeFieldSet, meaning that dates and times, but not time zones, are supported. A smaller components object results in smaller stack size.

To support all fields including time zones, use CompositeFieldSet.

§Examples

use icu::calendar::Gregorian;
use icu::calendar::DateTime;
use icu::datetime::pattern::TypedDateTimeNames;
use icu::datetime::fields::FieldLength;
use icu::datetime::fields;
use icu::datetime::pattern::DateTimePattern;
use icu::locale::locale;
use writeable::assert_try_writeable_eq;

// Create an instance that can format abbreviated month, weekday, and day period names:
let mut names: TypedDateTimeNames<Gregorian> =
    TypedDateTimeNames::try_new(locale!("uk").into()).unwrap();
names
    .include_month_names(fields::Month::Format, FieldLength::Three)
    .unwrap()
    .include_weekday_names(fields::Weekday::Format, FieldLength::Three)
    .unwrap()
    .include_day_period_names(FieldLength::Three)
    .unwrap();

// Create a pattern from a pattern string (note: K is the hour with h11 hour cycle):
let pattern_str = "E MMM d y -- K:mm a";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

// Test it:
let datetime = DateTime::try_new_gregorian(2023, 11, 20, 12, 35, 3).unwrap();
assert_try_writeable_eq!(names.with_pattern_unchecked(&pattern).format(&datetime), "пн лист. 20 2023 -- 0:35 пп");

If the correct data is not loaded, and error will occur:

use icu::calendar::Gregorian;
use icu::calendar::{Date, Time};
use icu::datetime::DateTimeWriteError;
use icu::datetime::pattern::TypedDateTimeNames;
use icu::datetime::fields::{Field, FieldLength, FieldSymbol, Weekday};
use icu::datetime::pattern::{DateTimePattern, PatternLoadError};
use icu::datetime::fieldsets::enums::CompositeFieldSet;
use icu::locale::locale;
use icu::timezone::{TimeZoneInfo, IxdtfParser};
use icu_provider_adapters::empty::EmptyDataProvider;
use writeable::{Part, assert_try_writeable_parts_eq};

// Create an instance that can format all fields (CompositeFieldSet):
let mut names: TypedDateTimeNames<Gregorian, CompositeFieldSet> =
    TypedDateTimeNames::try_new(locale!("en").into()).unwrap();

// Create a pattern from a pattern string:
let pattern_str = "'It is:' E MMM d y G 'at' h:mm:ssSSS a zzzz";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

// The pattern string contains lots of symbols including "E", "MMM", and "a",
// but we did not load any data!

let mut dtz = IxdtfParser::new().try_from_str("2023-11-20T11:35:03+00:00[Europe/London]").unwrap().to_calendar(Gregorian);

// Missing data is filled in on a best-effort basis, and an error is signaled.
assert_try_writeable_parts_eq!(
    names.with_pattern_unchecked(&pattern).format(&dtz),
    "It is: mon M11 20 2023 CE at 11:35:03.000 AM +0000",
    Err(DateTimeWriteError::NamesNotLoaded(Field { symbol: FieldSymbol::Weekday(Weekday::Format), length: FieldLength::One })),
    [
        (7, 10, Part::ERROR), // mon
        (11, 14, Part::ERROR), // M11
        (23, 25, Part::ERROR), // CE
        (42, 44, Part::ERROR), // AM
        (45, 50, Part::ERROR), // +0000
    ]
);

// To make the error occur sooner, one can use an EmptyDataProvider:
let empty = EmptyDataProvider::new();
assert!(matches!(
    names.load_for_pattern(&empty, &pattern),
    Err(PatternLoadError::Data(_, Field { symbol: FieldSymbol::Weekday(_), .. })),
));

If the pattern contains fields inconsistent with the receiver, an error will occur:

use icu::calendar::Gregorian;
use icu::calendar::DateTime;
use icu::datetime::DateTimeWriteError;
use icu::datetime::pattern::TypedDateTimeNames;
use icu::datetime::fields::{Field, FieldLength, FieldSymbol, Weekday};
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::fieldsets::O;
use icu::locale::locale;
use icu::timezone::TimeZoneInfo;
use writeable::{Part, assert_try_writeable_parts_eq};

// Create an instance that can format abbreviated month, weekday, and day period names:
let mut names: TypedDateTimeNames<Gregorian, O> =
    TypedDateTimeNames::try_new(locale!("en").into()).unwrap();

// Create a pattern from a pattern string:
let pattern_str = "'It is:' E MMM d y G 'at' h:mm:ssSSS a zzzz";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

// The pattern string contains lots of symbols including "E", "MMM", and "a",
// but the `TypedDateTimeNames` is configured to format only time zones!
// Further, the time zone we provide doesn't contain any offset into!
// Missing data is filled in on a best-effort basis, and an error is signaled.
assert_try_writeable_parts_eq!(
    names.with_pattern_unchecked(&pattern).format(&TimeZoneInfo::unknown()),
    "It is: {E} {M} {d} {y} {G} at {h}:{m}:{s} {a} {z}",
    Err(DateTimeWriteError::MissingInputField("iso_weekday")),
    [
        (7, 10, Part::ERROR), // {E}
        (11, 14, Part::ERROR), // {M}
        (15, 18, Part::ERROR), // {d}
        (19, 22, Part::ERROR), // {y}
        (23, 26, Part::ERROR), // {G}
        (30, 33, Part::ERROR), // {h}
        (34, 37, Part::ERROR), // {m}
        (38, 41, Part::ERROR), // {s}
        (42, 45, Part::ERROR), // {a}
        (46, 49, Part::ERROR), // {z}
    ]
);

Implementations§

source §

impl<C, FSet> TypedDateTimeNames<C, FSet>
where C: CldrCalendar, FSet: DateTimeNamesMarker,

source

pub fn try_new( prefs: DateTimeFormatterPreferences, ) -> Result<TypedDateTimeNames<C, FSet>, DataError>

Constructor that takes a selected locale and creates an empty instance.

For an example, see TypedDateTimeNames.

✨ Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

source

pub fn try_new_unstable( provider: &P, prefs: DateTimeFormatterPreferences, ) -> Result<TypedDateTimeNames<C, FSet>, DataError>
where P: DataProvider<DecimalSymbolsV2Marker> + DataProvider<DecimalDigitsV1Marker> + ?Sized,

A version of Self::try_new that uses custom data provided by a DataProvider.

📚 Help choosing a constructor

⚠️ The bounds on provider may change over time, including in SemVer minor releases.

source

pub fn new_without_number_formatting( prefs: DateTimeFormatterPreferences, ) -> TypedDateTimeNames<C, FSet>

Creates a completely empty instance, not even with number formatting.

§Examples

Errors occur if a number formatter is not loaded but one is required:

use icu::calendar::Gregorian;
use icu::calendar::Date;
use icu::datetime::DateTimeWriteError;
use icu::datetime::pattern::TypedDateTimeNames;
use icu::datetime::fields::{Field, FieldLength, FieldSymbol, Weekday};
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::fieldsets::enums::DateFieldSet;
use icu::locale::locale;
use writeable::{Part, assert_try_writeable_parts_eq};

// Create an instance that can format only date fields:
let names: TypedDateTimeNames<Gregorian, DateFieldSet> =
    TypedDateTimeNames::new_without_number_formatting(locale!("en").into());

// Create a pattern from a pattern string:
let pattern_str = "'It is:' y-MM-dd";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

// The pattern string contains lots of numeric symbols,
// but we did not load any data!

let date = Date::try_new_gregorian(2024, 7, 1).unwrap();

// Missing data is filled in on a best-effort basis, and an error is signaled.
// (note that the padding is ignored in this fallback mode)
assert_try_writeable_parts_eq!(
    names.with_pattern_unchecked(&pattern).format(&date),
    "It is: 2024-07-01",
    Err(DateTimeWriteError::FixedDecimalFormatterNotLoaded),
    [
        (7, 11, Part::ERROR), // 2024
        (12, 14, Part::ERROR), // 07
        (15, 17, Part::ERROR), // 01
    ]
);

source