Crate icu_datetime

Expand description

Localized formatting of dates, times, and time zones.

This module is published as its own crate (icu_datetime) and as part of the icu crate. See the latter for more details on the ICU4X project.

ICU4X datetime formatting follows the Unicode UTS 35 standard for Semantic Skeletons. First you choose a field set, then you configure the formatting options to your desired context.

Field Sets: icu::datetime::fieldsets
Options: icu::datetime::options

ICU4X supports formatting in over one dozen calendar systems, including Gregorian, Buddhist, Hijri, and more. The calendar system is usually derived from the locale, but it can also be specified explicitly.

The main formatter in this crate is DateTimeFormatter, which supports all field sets, options, and calendar systems. Additional formatter types are available to developers in resource-constrained environments.

The formatters accept input types from the calendar and timezone crates (Also reexported from the input module of this crate):

Not all inputs are valid for all field sets.

§Examples

use icu::datetime::fieldsets;
use icu::datetime::input::Date;
use icu::datetime::input::{DateTime, Time};
use icu::datetime::DateTimeFormatter;
use icu::locale::{locale, Locale};
use writeable::assert_writeable_eq;

// Field set for year, month, day, hour, and minute with a medium length:
let field_set_with_options = fieldsets::YMD::medium().with_time_hm();

// Create a formatter for Argentinian Spanish:
let locale = locale!("es-AR");
let dtf = DateTimeFormatter::try_new(locale.into(), field_set_with_options)
    .unwrap();

// Format something:
let datetime = DateTime {
    date: Date::try_new_iso(2025, 1, 15).unwrap(),
    time: Time::try_new(16, 9, 35, 0).unwrap(),
};
let formatted_date = dtf.format(&datetime);

assert_writeable_eq!(formatted_date, "15 de ene de 2025, 4:09 p. m.");

§Binary Size Considerations

§Avoid linking unnecessary field sets data

There are two APIs for fieldsets:

“static” field sets, like fieldsets::YMD, where each field set is a type.
“dynamic” field sets, like fieldsets::enums::CompositeFieldSet, where each field set is a value.

While dynamic fields sets may offer a more powerful API, using them in constructors links data for all possible values, i.e. all patterns, that the dynamic field set can represent, even if they are unreachable in code.

Static field sets on the other hand leverage the type system to let the compiler drop unneeded data.

§Example

use icu::datetime::DateTimeFormatter;
use icu::datetime::fieldsets::YMD;
use icu::datetime::fieldsets::enums::{CompositeFieldSet, DateFieldSet};

// This constructor only links data required for YMD
let a: DateTimeFormatter<YMD> =
    DateTimeFormatter::try_new(Default::default(), YMD::medium()).unwrap();

// This constructor links data for *all possible field sets*, even though we only use YMD
let b: DateTimeFormatter<CompositeFieldSet> =
    DateTimeFormatter::try_new(Default::default(), CompositeFieldSet::Date(DateFieldSet::YMD(YMD::medium()))).unwrap();

// If a DateTimeFormatter<CompositeFieldSet> is required, cast after construction instead:
let c: DateTimeFormatter<CompositeFieldSet> =  a.cast_into_fset::<CompositeFieldSet>();

§Avoid linking unnecessary calendar data

All field sets that contain dates use different data for each calendar system when used with DateTimeFormatter. This is good i18n practice, as in general the calendar system should be derived from the user locale, not fixed in code. However, there are legitimate use cases where only one calendar system is supported, in which case DateTimeFormatter would link unused data. In this case FixedCalendarDateTimeFormatter can be used, which is generic in a calendar type and only links the data for that calendar.

Using FixedCalendarDateTimeFormatter also avoids linking code that converts inputs to the user’s calendar. For field sets that don’t contain dates, this can also be achieved using NoCalendarFormatter.

Modules§

fieldsets: All available field sets for datetime formatting.
input: Types that can be fed to DateTimeFormatter/FixedCalendarDateTimeFormatter.
options: Options types for date/time formatting.
parts: Parts of a formatted date/time.
pattern: Lower-level, power-user APIs for formatting datetimes with pattern strings.
preferences: Locale preferences used by this crate
provider: 🚧 [Unstable] Data provider struct definitions for this ICU4X component.
scaffold: Scaffolding traits and types for the datetime crate.
unchecked: Datetime formatting without static checking of invariants.

Structs§

DateTimeFormatter: DateTimeFormatter is a formatter capable of formatting dates and/or times from a calendar selected at runtime.
DateTimeFormatterPreferences: The user locale preferences for datetime formatting.
FixedCalendarDateTimeFormatter: FixedCalendarDateTimeFormatter is a formatter capable of formatting dates and/or times from a calendar selected at compile time.
FormattedDateTime: An intermediate type during a datetime formatting operation.
MismatchedCalendarError: An error from mixing calendar types in a formatter.

Enums§

DateTimeFormatterLoadError: An error from constructing a formatter.

Type Aliases§

NoCalendarFormatter: A formatter optimized for time and time zone formatting, when a calendar is not needed.