Crate icu_datetime

Help

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.

§Binary Size Tradeoffs

The datetime crate has been engineered with a focus on giving developers the ability to tune binary size to their needs. The table illustrates the two main tradeoffs, field sets and calendar systems:

Factor	Static (Lower Binary Size)	Dynamic (Greater Binary Size)
Field Sets	Specific `fieldsets` types	Enumerations from `fieldsets::enums`
Calendar Systems	`FixedCalendarDateTimeFormatter`	`DateTimeFormatter`

If formatting times and time zones without dates, consider using NoCalendarFormatter.

§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 = 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).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.");

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.

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.
DateTimeInputUnchecked: An input bag with all possible datetime input fields.
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.
FormattedDateTimeUnchecked: An intermediate type during a datetime formatting operation with dynamic input.
MismatchedCalendarError: An error from mixing calendar types in a formatter.
UnsupportedCalendarError: Error returned from constructors that map from AnyCalendar to a formatter.

Enums§

DateTimeFormatterLoadError: An error from constructing a formatter.
DateTimeWriteError: Error for TryWriteable implementations

Type Aliases§

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