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, Islamic, 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:
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 TimeFormatter
.
§Examples
use icu::calendar::DateTime;
use icu::datetime::fieldsets;
use icu::datetime::DateTimeFormatter;
use icu::locale::{locale, Locale};
use writeable::assert_try_writeable_eq;
// Field set for year, month, day, hour, and minute with a medium length:
let field_set = fieldsets::YMDT::medium().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::try_new_iso(2025, 1, 15, 16, 9, 35).unwrap();
let formatted_date = dtf.convert_and_format(&datetime);
assert_try_writeable_eq!(formatted_date, "15 de ene de 2025, 4:09 p. m.");
Modules§
- Enums representing the fields in a date pattern, including the field’s type, length and symbol.
- All available field sets for datetime formatting.
- A collection of utilities for representing and working with dates as an input to formatting operations.
- Temporary module for neo datetime patterns
- Options types for date/time formatting.
- Lower-level, power-user APIs for formatting datetimes with pattern strings.
- 🚧 [Unstable] Data provider struct definitions for this ICU4X component.
- Scaffolding traits and types for the datetime crate.
Structs§
DateTimeFormatter
is a formatter capable of formatting dates and/or times from a calendar selected at runtime.- The prefs for datetime formatting.
FixedCalendarDateTimeFormatter
is a formatter capable of formatting dates and/or times from a calendar selected at compile time.- An intermediate type during a datetime formatting operation.
- An error from mixing calendar types in a formatter.
Enums§
- An error from constructing a formatter.
- Error for
TryWriteable
implementations - The length of a formatted date/time string.
Type Aliases§
- A formatter optimized for time and time zone formatting.