Struct FixedCalendarDateTimeNames

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

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 312 bytes on the stable toolchain at release date.

Type parameters:

1. The calendar chosen at compile time for additional type safety
2. 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::datetime::input::Date;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::MonthNameLength;
use icu::datetime::pattern::WeekdayNameLength;
use icu::datetime::pattern::DayPeriodNameLength;
use icu::locale::locale;
use icu::datetime::input::{DateTime, Time};
use writeable::assert_try_writeable_eq;

// Create an instance that can format abbreviated month, weekday, and day period names:
let mut names: FixedCalendarDateTimeNames<Gregorian> =
    FixedCalendarDateTimeNames::try_new(locale!("uk").into()).unwrap();
names
    .include_month_names(MonthNameLength::Abbreviated)
    .unwrap()
    .include_weekday_names(WeekdayNameLength::Abbreviated)
    .unwrap()
    .include_day_period_names(DayPeriodNameLength::Abbreviated)
    .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 { date: Date::try_new_gregorian(2023, 11, 20).unwrap(), time: Time::try_new(12, 35, 3, 0).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::datetime::input::Date;
use icu::datetime::DateTimeWriteError;
use icu::datetime::parts;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::pattern::{DateTimePattern, PatternLoadError};
use icu::datetime::fieldsets::enums::CompositeFieldSet;
use icu::locale::locale;
use icu::time::zone::{IanaParser, VariantOffsetsCalculator};
use icu::datetime::input::{Time, TimeZoneInfo, ZonedDateTime};
use icu_provider_adapters::empty::EmptyDataProvider;
use writeable::{Part, assert_try_writeable_parts_eq};

// Unstable API used only for error construction below
use icu::datetime::provider::fields::{Field, FieldLength, FieldSymbol, Weekday};

// Create an instance that can format all fields (CompositeFieldSet):
let mut names: FixedCalendarDateTimeNames<Gregorian, CompositeFieldSet> =
    FixedCalendarDateTimeNames::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 = ZonedDateTime::try_from_str("2023-11-20T11:35:03+00:00[Europe/London]", Gregorian, IanaParser::new(), VariantOffsetsCalculator::new()).unwrap();

// 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 }.into())),
    [
        (7, 10, Part::ERROR), // mon
        (7, 10, parts::WEEKDAY), // mon
        (11, 14, Part::ERROR), // M11
        (11, 14, parts::MONTH), // M11
        (15, 17, icu::decimal::parts::INTEGER), // 20
        (15, 17, parts::DAY), // 20
        (18, 22, icu::decimal::parts::INTEGER), // 2023
        (18, 22, parts::YEAR), // 2023
        (23, 25, Part::ERROR), // CE
        (23, 25, parts::ERA), // CE
        (29, 31, icu::decimal::parts::INTEGER), // 11
        (29, 31, parts::HOUR), // 11
        (32, 34, icu::decimal::parts::INTEGER), // 35
        (32, 34, parts::MINUTE), // 35
        (35, 41, parts::SECOND), // 03.000
        (35, 37, icu::decimal::parts::INTEGER), // 03
        (37, 38, icu::decimal::parts::DECIMAL), // .
        (38, 41, icu::decimal::parts::FRACTION), // 000
        (42, 44, Part::ERROR), // AM
        (42, 44, parts::DAY_PERIOD), // AM
        (45, 50, Part::ERROR), // +0000
        (45, 50, parts::TIME_ZONE_NAME), // +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(_, _)),
));

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

use icu::calendar::Gregorian;
use icu::datetime::DateTimeWriteError;
use icu::datetime::parts;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::fieldsets::zone::LocalizedOffsetLong;
use icu::locale::locale;
use icu::datetime::input::{DateTime, 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: FixedCalendarDateTimeNames<Gregorian, LocalizedOffsetLong> =
    FixedCalendarDateTimeNames::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 `FixedCalendarDateTimeNames` 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}
        (7, 10, parts::WEEKDAY), // {E}
        (11, 14, Part::ERROR), // {M}
        (11, 14, parts::MONTH), // {M}
        (15, 18, Part::ERROR), // {d}
        (15, 18, parts::DAY), // {d}
        (19, 22, Part::ERROR), // {y}
        (19, 22, parts::YEAR), // {y}
        (23, 26, Part::ERROR), // {G}
        (23, 26, parts::ERA), // {G}
        (30, 33, Part::ERROR), // {h}
        (30, 33, parts::HOUR), // {h}
        (34, 37, Part::ERROR), // {m}
        (34, 37, parts::MINUTE), // {m}
        (38, 41, Part::ERROR), // {s}
        (38, 41, parts::SECOND), // {s}
        (42, 45, Part::ERROR), // {a}
        (42, 45, parts::DAY_PERIOD), // {a}
        (46, 49, Part::ERROR), // {z}
        (46, 49, parts::TIME_ZONE_NAME), // {z}
    ]
);

When loading data for time zones, currently only one type can be loaded; see: https://github.com/unicode-org/icu4x/issues/6063

use icu::datetime::input::Date;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::fieldsets::enums::ZoneFieldSet;
use icu::locale::locale;
use icu::datetime::input::{DateTime, Time};
use writeable::assert_try_writeable_eq;

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

// Load the names for generic short:
names.include_time_zone_essentials().unwrap();
names.include_time_zone_generic_short_names().unwrap();
names.include_time_zone_location_names().unwrap();

// The same functions can be called a second time (nothing will happen):
names.include_time_zone_essentials().unwrap();
names.include_time_zone_generic_short_names().unwrap();
names.include_time_zone_location_names().unwrap();

// But loading names for a different zone style does not currently work:
names.include_time_zone_specific_short_names().unwrap_err();

Implementations

impl<C, FSet> FixedCalendarDateTimeNames<C, FSet>

where FSet: DateTimeNamesMarker,

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

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

For an example, see FixedCalendarDateTimeNames.

✨ Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

pub fn try_new_unstable<P>( provider: &P, prefs: DateTimeFormatterPreferences, ) -> Result<FixedCalendarDateTimeNames<C, FSet>, DataError>

where P: DataProvider<DecimalSymbolsV1> + DataProvider<DecimalDigitsV1> + ?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.

pub fn try_new_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), prefs: DateTimeFormatterPreferences, ) -> Result<FixedCalendarDateTimeNames<C, FSet>, DataError>

A version of [Self :: try_new] that uses custom data provided by a BufferProvider.

✨ Enabled with the serde feature.

📚 Help choosing a constructor

pub fn new_without_number_formatting( prefs: DateTimeFormatterPreferences, ) -> FixedCalendarDateTimeNames<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::datetime::input::Date;
use icu::datetime::parts;
use icu::datetime::DateTimeWriteError;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
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: FixedCalendarDateTimeNames<Gregorian, DateFieldSet> =
    FixedCalendarDateTimeNames::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::DecimalFormatterNotLoaded),
    [
        (7, 11, Part::ERROR), // 2024
        (7, 11, parts::YEAR), // 2024
        (12, 14, Part::ERROR), // 07
        (12, 14, parts::MONTH), // 07
        (15, 17, Part::ERROR), // 01
        (15, 17, parts::DAY), // 01
    ]
);

impl<C, FSet> FixedCalendarDateTimeNames<C, FSet>

where C: CldrCalendar, FSet: DateTimeNamesMarker,

pub fn from_formatter( prefs: DateTimeFormatterPreferences, formatter: FixedCalendarDateTimeFormatter<C, FSet>, ) -> FixedCalendarDateTimeNames<C, FSet>

Creates an instance with the names loaded in a FixedCalendarDateTimeFormatter.

This function requires passing in the DateTimeFormatterPreferences because it is not retained in the formatter. Pass the same value or else unexpected behavior may occur.

Examples

use icu::datetime::input::Date;
use icu::datetime::input::{DateTime, Time};
use icu::datetime::FixedCalendarDateTimeFormatter;
use icu::datetime::fieldsets::{YMD, YMDT};
use icu::datetime::pattern::{FixedCalendarDateTimeNames, DayPeriodNameLength};
use icu::locale::locale;
use writeable::assert_writeable_eq;

let prefs = locale!("es-MX").into();

let formatter =
    FixedCalendarDateTimeFormatter::try_new(
        prefs,
        YMD::long(),
    )
    .unwrap();

assert_writeable_eq!(
    formatter.format(&Date::try_new_gregorian(2025, 2, 13).unwrap()),
    "13 de febrero de 2025"
);

// Change the YMD formatter to a YMDT formatter, after loading day period names.
// This assumes that the locale uses Abbreviated names for the given semantic skeleton!
let mut names = FixedCalendarDateTimeNames::from_formatter(prefs, formatter).cast_into_fset::<YMDT>();
names.include_day_period_names(DayPeriodNameLength::Abbreviated).unwrap();
let formatter = names.try_into_formatter(YMDT::long().hm()).unwrap();

assert_writeable_eq!(
    formatter.format(&DateTime {
        date: Date::try_new_gregorian(2025, 2, 13).unwrap(),
        time: Time::midnight(),
    }),
    "13 de febrero de 2025, 12:00 a.m."
);

impl<C, FSet> FixedCalendarDateTimeNames<C, FSet>

where C: CldrCalendar, FSet: DateTimeMarkers + GetField<CompositeFieldSet>, <FSet as DateTimeMarkers>::D: TypedDateDataMarkers<C>, <FSet as DateTimeMarkers>::T: TimeMarkers, <FSet as DateTimeMarkers>::Z: ZoneMarkers,

pub fn try_into_formatter( self, field_set: FSet, ) -> Result<FixedCalendarDateTimeFormatter<C, FSet>, (DateTimeFormatterLoadError, FixedCalendarDateTimeNames<C, FSet>)>

where Baked: AllFixedCalendarPatternDataMarkers<C, FSet>,

Loads a pattern for the given field set and returns a FixedCalendarDateTimeFormatter.

The names in the current FixedCalendarDateTimeNames must be sufficient for the field set. If not, the input object will be returned with an error.

Examples

use icu::datetime::fieldsets::T;
use icu::datetime::input::Time;
use icu::datetime::pattern::{
    DayPeriodNameLength, FixedCalendarDateTimeNames,
};
use icu::locale::locale;
use writeable::assert_writeable_eq;

let names =
    FixedCalendarDateTimeNames::<(), _>::new_without_number_formatting(
        locale!("es-MX").into(),
    );

let field_set = T::long().hm();

// Cannot convert yet: no names are loaded
let mut names = names.try_into_formatter(field_set).unwrap_err().1;

// Load the data we need:
names
    .include_day_period_names(DayPeriodNameLength::Abbreviated)
    .unwrap();
names.include_decimal_formatter().unwrap();

// Now the conversion is successful:
let formatter = names.try_into_formatter(field_set).unwrap();

assert_writeable_eq!(formatter.format(&Time::midnight()), "12:00 a.m.");

pub fn try_into_formatter_unstable<P>( self, provider: &P, field_set: FSet, ) -> Result<FixedCalendarDateTimeFormatter<C, FSet>, (DateTimeFormatterLoadError, FixedCalendarDateTimeNames<C, FSet>)>

where P: AllFixedCalendarPatternDataMarkers<C, FSet> + ?Sized,

A version of Self::try_into_formatter 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.

pub fn try_into_formatter_with_buffer_provider<P>( self, provider: &P, field_set: FSet, ) -> Result<FixedCalendarDateTimeFormatter<C, FSet>, (DateTimeFormatterLoadError, FixedCalendarDateTimeNames<C, FSet>)>

where P: BufferProvider + ?Sized,

A version of Self::try_into_formatter that uses custom data provided by a BufferProvider.

✨ Enabled with the serde feature.

📚 Help choosing a constructor

impl<C, FSet> FixedCalendarDateTimeNames<C, FSet>

where C: CldrCalendar, FSet: DateTimeNamesMarker,

pub fn load_year_names<P>( &mut self, provider: &P, length: YearNameLength, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<<C as CldrCalendar>::YearNamesV1> + ?Sized,

Loads year (era or cycle) names for the specified length.

Does not support multiple field symbols or lengths. See #4337

pub fn include_year_names( &mut self, length: YearNameLength, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where Baked: DataProvider<<C as CldrCalendar>::YearNamesV1>,

Includes year (era or cycle) names for the specified length.

Does not support multiple field symbols or lengths. See #4337

Examples

use icu::calendar::Gregorian;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::pattern::PatternLoadError;
use icu::datetime::pattern::YearNameLength;
use icu::locale::locale;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian>::try_new(locale!("und").into())
        .unwrap();

// First length is successful:
names.include_year_names(YearNameLength::Wide).unwrap();

// Attempting to load the first length a second time will succeed:
names.include_year_names(YearNameLength::Wide).unwrap();

// But loading a new length fails:
assert!(matches!(
    names.include_year_names(YearNameLength::Abbreviated),
    Err(PatternLoadError::ConflictingField(_))
));

pub fn load_month_names<P>( &mut self, provider: &P, length: MonthNameLength, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<<C as CldrCalendar>::MonthNamesV1> + ?Sized,

Loads month names for the specified symbol and length.

Does not support multiple field symbols or lengths. See #4337

pub fn include_month_names( &mut self, length: MonthNameLength, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where Baked: DataProvider<<C as CldrCalendar>::MonthNamesV1>,

Includes month names for the specified symbol and length.

Does not support multiple field symbols or lengths. See #4337

Examples

use icu::calendar::Gregorian;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::pattern::MonthNameLength;
use icu::datetime::pattern::PatternLoadError;
use icu::locale::locale;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian>::try_new(locale!("und").into())
        .unwrap();

// First length is successful:
names.include_month_names(MonthNameLength::Wide).unwrap();

// Attempting to load the first length a second time will succeed:
names.include_month_names(MonthNameLength::Wide).unwrap();

// But loading a new symbol or length fails:
assert!(matches!(
    names.include_month_names(MonthNameLength::StandaloneWide),
    Err(PatternLoadError::ConflictingField(_))
));
assert!(matches!(
    names.include_month_names(MonthNameLength::Abbreviated),
    Err(PatternLoadError::ConflictingField(_))
));

impl<C, FSet> FixedCalendarDateTimeNames<C, FSet>

where FSet: DateTimeNamesMarker,

pub fn load_day_period_names<P>( &mut self, provider: &P, length: DayPeriodNameLength, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<DayPeriodNamesV1> + ?Sized,

Loads day period names for the specified length.

Does not support multiple field symbols or lengths. See #4337

pub fn include_day_period_names( &mut self, length: DayPeriodNameLength, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

Includes day period names for the specified length.

Does not support multiple field symbols or lengths. See #4337

Examples

use icu::calendar::Gregorian;
use icu::datetime::pattern::DayPeriodNameLength;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::pattern::PatternLoadError;
use icu::locale::locale;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian>::try_new(locale!("und").into())
        .unwrap();

// First length is successful:
names
    .include_day_period_names(DayPeriodNameLength::Wide)
    .unwrap();

// Attempting to load the first length a second time will succeed:
names
    .include_day_period_names(DayPeriodNameLength::Wide)
    .unwrap();

// But loading a new length fails:
assert!(matches!(
    names.include_day_period_names(DayPeriodNameLength::Abbreviated),
    Err(PatternLoadError::ConflictingField(_))
));

pub fn load_weekday_names<P>( &mut self, provider: &P, length: WeekdayNameLength, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<WeekdayNamesV1> + ?Sized,

Loads weekday names for the specified symbol and length.

Does not support multiple field symbols or lengths. See #4337

pub fn include_weekday_names( &mut self, length: WeekdayNameLength, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

Includes weekday names for the specified symbol and length.

Does not support multiple field symbols or lengths. See #4337

Examples

use icu::calendar::Gregorian;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::pattern::PatternLoadError;
use icu::datetime::pattern::WeekdayNameLength;
use icu::locale::locale;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian>::try_new(locale!("und").into())
        .unwrap();

// First length is successful:
names
    .include_weekday_names(WeekdayNameLength::Wide)
    .unwrap();

// Attempting to load the first length a second time will succeed:
names
    .include_weekday_names(WeekdayNameLength::Wide)
    .unwrap();

// But loading a new symbol or length fails:
assert!(matches!(
    names.include_weekday_names(WeekdayNameLength::StandaloneWide),
    Err(PatternLoadError::ConflictingField(_))
));
assert!(matches!(
    names.include_weekday_names(WeekdayNameLength::Abbreviated),
    Err(PatternLoadError::ConflictingField(_))
));

pub fn load_time_zone_essentials<P>( &mut self, provider: &P, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<TimeZoneEssentialsV1> + ?Sized,

Loads shared essential patterns for time zone formatting.

pub fn include_time_zone_essentials( &mut self, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

Includes shared essential patterns for time zone formatting.

This data should always be loaded when performing time zone formatting. By itself, it allows localized offset formats.

Examples

use icu::calendar::Gregorian;
use icu::datetime::fieldsets::enums::ZoneFieldSet;
use icu::datetime::input::ZonedDateTime;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::locale::locale;
use icu::time::zone::{IanaParser, VariantOffsetsCalculator};
use writeable::assert_try_writeable_eq;

let mut zone_london_winter = ZonedDateTime::try_from_str(
    "2024-01-01T00:00:00+00:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;
let mut zone_london_summer = ZonedDateTime::try_from_str(
    "2024-07-01T00:00:00+01:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian, ZoneFieldSet>::try_new(
        locale!("en-GB").into(),
    )
    .unwrap();

names.include_time_zone_essentials().unwrap();

// Create a pattern with symbol `OOOO`:
let pattern_str = "'Your time zone is:' OOOO";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: GMT+00:00",
);
assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_summer),
    "Your time zone is: GMT+01:00",
);

// Now try `V`:
let pattern_str = "'Your time zone is:' V";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: gblon",
);

// Now try `Z`:
let pattern_str = "'Your time zone is:' Z";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: +0000",
);

// Now try `ZZZZZ`:
let pattern_str = "'Your time zone is:' ZZZZZ";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: Z",
);
assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_summer),
    "Your time zone is: +01:00",
);

pub fn load_time_zone_location_names<P>( &mut self, provider: &P, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<LocationsV1> + DataProvider<LocationsRootV1> + ?Sized,

Loads location names for time zone formatting.

pub fn include_time_zone_location_names( &mut self, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

Includes location names for time zone formatting.

Important: When performing manual time zone data loading, in addition to the specific time zone format data, also call either:

• FixedCalendarDateTimeNames::include_time_zone_essentials
• FixedCalendarDateTimeNames::load_time_zone_essentials

Examples

use icu::calendar::Gregorian;
use icu::datetime::fieldsets::enums::ZoneFieldSet;
use icu::datetime::input::ZonedDateTime;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::locale::locale;
use icu::time::zone::{IanaParser, VariantOffsetsCalculator};
use writeable::assert_try_writeable_eq;

let mut zone_london_winter = ZonedDateTime::try_from_str(
    "2024-01-01T00:00:00+00:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian, ZoneFieldSet>::try_new(
        locale!("en-GB").into(),
    )
    .unwrap();

names.include_time_zone_essentials().unwrap();
names.include_time_zone_location_names().unwrap();

// Try `VVVV`:
let pattern_str = "'Your time zone is:' VVVV";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: UK Time",
);

pub fn load_time_zone_exemplar_city_names<P>( &mut self, provider: &P, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<ExemplarCitiesV1> + DataProvider<ExemplarCitiesRootV1> + ?Sized,

Loads exemplar city names for time zone formatting.

pub fn include_time_zone_exemplar_city_names( &mut self, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

Includes exemplar city names for time zone formatting.

Important: The VVV format requires location data in addition to exemplar city data. Also call either:

• FixedCalendarDateTimeNames::include_time_zone_location_names
• FixedCalendarDateTimeNames::load_time_zone_location_names

Examples

use icu::calendar::Gregorian;
use icu::datetime::fieldsets::enums::ZoneFieldSet;
use icu::datetime::input::ZonedDateTime;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::locale::locale;
use icu::time::zone::{IanaParser, VariantOffsetsCalculator};
use writeable::assert_try_writeable_eq;

let mut zone_london_winter = ZonedDateTime::try_from_str(
    "2024-01-01T00:00:00+00:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian, ZoneFieldSet>::try_new(
        locale!("en-GB").into(),
    )
    .unwrap();

names.include_time_zone_location_names().unwrap();
names.include_time_zone_exemplar_city_names().unwrap();

// Try `VVVV`:
let pattern_str = "'Your time zone is:' VVV";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: London",
);

pub fn load_time_zone_generic_long_names<P>( &mut self, provider: &P, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<MetazoneGenericNamesLongV1> + DataProvider<MetazoneStandardNamesLongV1> + DataProvider<MetazonePeriodV1> + ?Sized,

Loads generic non-location long time zone names.

pub fn include_time_zone_generic_long_names( &mut self, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

Includes generic non-location long time zone names.

Important: When performing manual time zone data loading, in addition to the specific time zone format data, also call either:

• FixedCalendarDateTimeNames::include_time_zone_essentials
• FixedCalendarDateTimeNames::load_time_zone_essentials

Examples

use icu::calendar::Gregorian;
use icu::datetime::fieldsets::enums::ZoneFieldSet;
use icu::datetime::input::ZonedDateTime;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::locale::locale;
use icu::time::zone::{IanaParser, VariantOffsetsCalculator};
use writeable::assert_try_writeable_eq;

let mut zone_london_winter = ZonedDateTime::try_from_str(
    "2024-01-01T00:00:00+00:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;
let mut zone_london_summer = ZonedDateTime::try_from_str(
    "2024-07-01T00:00:00+01:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian, ZoneFieldSet>::try_new(
        locale!("en-GB").into(),
    )
    .unwrap();

names.include_time_zone_essentials().unwrap();
names.include_time_zone_generic_long_names().unwrap();

// Create a pattern with symbol `vvvv`:
let pattern_str = "'Your time zone is:' vvvv";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: Greenwich Mean Time",
);
assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_summer),
    "Your time zone is: Greenwich Mean Time", // TODO
);

pub fn load_time_zone_generic_short_names<P>( &mut self, provider: &P, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<MetazoneGenericNamesShortV1> + DataProvider<MetazonePeriodV1> + ?Sized,

Loads generic non-location short time zone names.

pub fn include_time_zone_generic_short_names( &mut self, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

Includes generic non-location short time zone names.

Important: When performing manual time zone data loading, in addition to the specific time zone format data, also call either:

• FixedCalendarDateTimeNames::include_time_zone_essentials
• FixedCalendarDateTimeNames::load_time_zone_essentials

Examples

use icu::calendar::Gregorian;
use icu::datetime::fieldsets::enums::ZoneFieldSet;
use icu::datetime::input::ZonedDateTime;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::locale::locale;
use icu::time::zone::{IanaParser, VariantOffsetsCalculator};
use writeable::assert_try_writeable_eq;

let mut zone_london_winter = ZonedDateTime::try_from_str(
    "2024-01-01T00:00:00+00:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;
let mut zone_london_summer = ZonedDateTime::try_from_str(
    "2024-07-01T00:00:00+01:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian, ZoneFieldSet>::try_new(
        locale!("en-GB").into(),
    )
    .unwrap();

names.include_time_zone_essentials().unwrap();
names.include_time_zone_generic_short_names().unwrap();

// Create a pattern with symbol `v`:
let pattern_str = "'Your time zone is:' v";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: GMT",
);
assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_summer),
    "Your time zone is: GMT", // TODO
);

pub fn load_time_zone_specific_long_names<P>( &mut self, provider: &P, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<MetazoneSpecificNamesLongV1> + DataProvider<MetazoneStandardNamesLongV1> + DataProvider<MetazonePeriodV1> + ?Sized,

Loads specific non-location long time zone names.

pub fn include_time_zone_specific_long_names( &mut self, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

Includes specific non-location long time zone names.

Important: When performing manual time zone data loading, in addition to the specific time zone format data, also call either:

• FixedCalendarDateTimeNames::include_time_zone_essentials
• FixedCalendarDateTimeNames::load_time_zone_essentials

Examples

use icu::calendar::Gregorian;
use icu::datetime::fieldsets::enums::ZoneFieldSet;
use icu::datetime::input::ZonedDateTime;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::locale::locale;
use icu::time::zone::{IanaParser, VariantOffsetsCalculator};
use writeable::assert_try_writeable_eq;

let mut zone_london_winter = ZonedDateTime::try_from_str(
    "2024-01-01T00:00:00+00:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;
let mut zone_london_summer = ZonedDateTime::try_from_str(
    "2024-07-01T00:00:00+01:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian, ZoneFieldSet>::try_new(
        locale!("en-GB").into(),
    )
    .unwrap();

names.include_time_zone_essentials().unwrap();
names.include_time_zone_specific_long_names().unwrap();

// Create a pattern with symbol `zzzz`:
let pattern_str = "'Your time zone is:' zzzz";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: Greenwich Mean Time",
);
assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_summer),
    "Your time zone is: British Summer Time",
);

pub fn load_time_zone_specific_short_names<P>( &mut self, provider: &P, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

where P: DataProvider<MetazoneSpecificNamesShortV1> + DataProvider<MetazonePeriodV1> + ?Sized,

Loads specific non-location short time zone names.

pub fn include_time_zone_specific_short_names( &mut self, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, PatternLoadError>

Includes specific non-location short time zone names.

Important: When performing manual time zone data loading, in addition to the specific time zone format data, also call either:

• FixedCalendarDateTimeNames::include_time_zone_essentials
• FixedCalendarDateTimeNames::load_time_zone_essentials

Examples

use icu::calendar::Gregorian;
use icu::datetime::fieldsets::enums::ZoneFieldSet;
use icu::datetime::input::ZonedDateTime;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::locale::locale;
use icu::time::zone::{IanaParser, VariantOffsetsCalculator};
use writeable::assert_try_writeable_eq;

let mut zone_london_winter = ZonedDateTime::try_from_str(
    "2024-01-01T00:00:00+00:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;
let mut zone_london_summer = ZonedDateTime::try_from_str(
    "2024-07-01T00:00:00+01:00[Europe/London]",
    Gregorian,
    IanaParser::new(),
    VariantOffsetsCalculator::new(),
)
.unwrap()
.zone;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian, ZoneFieldSet>::try_new(
        locale!("en-GB").into(),
    )
    .unwrap();

names.include_time_zone_essentials().unwrap();
names.include_time_zone_specific_short_names().unwrap();

// Create a pattern with symbol `z`:
let pattern_str = "'Your time zone is:' z";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_winter),
    "Your time zone is: GMT",
);
assert_try_writeable_eq!(
    names
        .with_pattern_unchecked(&pattern)
        .format(&zone_london_summer),
    "Your time zone is: BST",
);

pub fn load_decimal_formatter<P>( &mut self, provider: &P, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, DataError>

where P: DataProvider<DecimalSymbolsV1> + DataProvider<DecimalDigitsV1> + ?Sized,

Loads a DecimalFormatter from a data provider.

pub fn include_decimal_formatter( &mut self, ) -> Result<&mut FixedCalendarDateTimeNames<C, FSet>, DataError>

Loads a DecimalFormatter with compiled data.

Examples

use icu::datetime::fieldsets::enums::TimeFieldSet;
use icu::datetime::input::Time;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::locale::locale;
use writeable::assert_try_writeable_eq;

let mut names = FixedCalendarDateTimeNames::<(), TimeFieldSet>::try_new(
    locale!("bn").into(),
)
.unwrap();
names.include_decimal_formatter();

// Create a pattern for the time, which is all numbers
let pattern_str = "'The current 24-hour time is:' HH:mm";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

let time = Time::try_new(6, 40, 33, 0).unwrap();

assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&time),
    "The current 24-hour time is: ০৬:৪০",
);

impl<C, FSet> FixedCalendarDateTimeNames<C, FSet>

where C: CldrCalendar, FSet: DateTimeNamesMarker,

pub fn with_pattern_unchecked<'l>( &'l self, pattern: &'l DateTimePattern, ) -> DateTimePatternFormatter<'l, C, FSet>

Associates this FixedCalendarDateTimeNames with a pattern without checking that all necessary data is loaded.

pub fn load_for_pattern<'l, P>( &'l mut self, provider: &P, pattern: &'l DateTimePattern, ) -> Result<DateTimePatternFormatter<'l, C, FSet>, PatternLoadError>

where P: DataProvider<<C as CldrCalendar>::YearNamesV1> + DataProvider<<C as CldrCalendar>::MonthNamesV1> + DataProvider<WeekdayNamesV1> + DataProvider<DayPeriodNamesV1> + DataProvider<TimeZoneEssentialsV1> + DataProvider<LocationsV1> + DataProvider<LocationsRootV1> + DataProvider<ExemplarCitiesV1> + DataProvider<ExemplarCitiesRootV1> + DataProvider<MetazoneGenericNamesLongV1> + DataProvider<MetazoneGenericNamesShortV1> + DataProvider<MetazoneStandardNamesLongV1> + DataProvider<MetazoneSpecificNamesLongV1> + DataProvider<MetazoneSpecificNamesShortV1> + DataProvider<MetazonePeriodV1> + DataProvider<DecimalSymbolsV1> + DataProvider<DecimalDigitsV1> + ?Sized,

Associates this FixedCalendarDateTimeNames with a datetime pattern and loads all data required for that pattern.

Does not duplicate textual field symbols. See #4337

pub fn include_for_pattern<'l>( &'l mut self, pattern: &'l DateTimePattern, ) -> Result<DateTimePatternFormatter<'l, C, FSet>, PatternLoadError>

where Baked: DataProvider<<C as CldrCalendar>::YearNamesV1> + DataProvider<<C as CldrCalendar>::MonthNamesV1>,

Associates this FixedCalendarDateTimeNames with a pattern and includes all data required for that pattern.

Does not support duplicate textual field symbols. See #4337

Examples

use icu::calendar::Gregorian;
use icu::datetime::input::Date;
use icu::datetime::input::{DateTime, Time};
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::locale::locale;
use writeable::assert_try_writeable_eq;

let mut names =
    FixedCalendarDateTimeNames::<Gregorian>::try_new(locale!("en").into())
        .unwrap();

// Create a pattern from a pattern string:
let pattern_str = "MMM d (EEEE) 'of year' y G 'at' h:mm a";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

// Load data for the pattern and format:
let datetime = DateTime {
    date: Date::try_new_gregorian(2023, 12, 5).unwrap(),
    time: Time::try_new(17, 43, 12, 0).unwrap(),
};
assert_try_writeable_eq!(
    names
        .include_for_pattern(&pattern)
        .unwrap()
        .format(&datetime),
    "Dec 5 (Tuesday) of year 2023 AD at 5:43 PM"
);

impl<C, FSet> FixedCalendarDateTimeNames<C, FSet>

where FSet: DateTimeNamesMarker,

pub fn cast_into_fset<FSet2>(self) -> FixedCalendarDateTimeNames<C, FSet2>

where FSet2: DateTimeNamesFrom<FSet>,

Maps a FixedCalendarDateTimeNames of a specific FSet to a more general FSet.

For example, this can transform a formatter for DateFieldSet to one for CompositeDateTimeFieldSet.

Examples

use icu::calendar::Gregorian;
use icu::datetime::fieldsets::enums::{
    CompositeDateTimeFieldSet, DateFieldSet,
};
use icu::datetime::input::Date;
use icu::datetime::input::{DateTime, Time};
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::pattern::MonthNameLength;
use icu::locale::locale;
use writeable::assert_try_writeable_eq;

// Create an instance that can format abbreviated month names:
let mut names: FixedCalendarDateTimeNames<Gregorian, DateFieldSet> =
    FixedCalendarDateTimeNames::try_new(locale!("uk").into()).unwrap();
names
    .include_month_names(MonthNameLength::Abbreviated)
    .unwrap();

// Test it with a pattern:
let pattern_str = "MMM d y";
let pattern: DateTimePattern = pattern_str.parse().unwrap();
let datetime = DateTime {
    date: Date::try_new_gregorian(2023, 11, 20).unwrap(),
    time: Time::midnight(),
};
assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&datetime),
    "лист. 20 2023"
);

// Convert the field set to `CompositeDateTimeFieldSet`:
let composite_names = names.cast_into_fset::<CompositeDateTimeFieldSet>();

// It should still work:
assert_try_writeable_eq!(
    composite_names
        .with_pattern_unchecked(&pattern)
        .format(&datetime),
    "лист. 20 2023"
);

Converting into a narrower type is not supported:

use icu::calendar::Gregorian;
use icu::datetime::pattern::FixedCalendarDateTimeNames;
use icu::datetime::fieldsets::enums::{DateFieldSet, CompositeDateTimeFieldSet};

let composite_names: FixedCalendarDateTimeNames<Gregorian, CompositeDateTimeFieldSet> = todo!();

// error[E0277]: the trait bound `(): From<DataPayloadWithVariables<DayPeriodNamesV1, FieldLength>>` is not satisfied
let narrow_names = composite_names.cast_into_fset::<DateFieldSet>();

Trait Implementations

impl<FSet> AsMut<FixedCalendarDateTimeNames<(), FSet>> for DateTimeNames<FSet>

where FSet: DateTimeNamesMarker,

fn as_mut(&mut self) -> &mut FixedCalendarDateTimeNames<(), FSet>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<FSet> AsRef<FixedCalendarDateTimeNames<(), FSet>> for DateTimeNames<FSet>

where FSet: DateTimeNamesMarker,

fn as_ref(&self) -> &FixedCalendarDateTimeNames<(), FSet>

Converts this type into a shared reference of the (usually inferred) input type.

impl<C, FSet> Clone for FixedCalendarDateTimeNames<C, FSet>

where C: Clone, FSet: Clone + DateTimeNamesMarker,

fn clone(&self) -> FixedCalendarDateTimeNames<C, FSet>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<C, FSet> Debug for FixedCalendarDateTimeNames<C, FSet>

where C: Debug, FSet: Debug + DateTimeNamesMarker,

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

Formats the value using the given formatter.