Crate icu_datetime

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.

1. Field Sets: icu::datetime::fieldsets
2. 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:

1. Date
2. DateTime
3. Time
4. UtcOffset
5. TimeZoneInfo
6. CustomZonedDateTime

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_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.format_any_calendar(&datetime);

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

Re-exports

• pub use options::Length;

Modules

• fields
  Enums representing the fields in a date pattern, including the field’s type, length and symbol.
• fieldsets
  All available field sets for datetime formatting.
• input
  A collection of utilities for representing and working with dates as an input to formatting operations.
• neo_pattern
  Temporary module for neo datetime patterns
• 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.
• 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.
• 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.
• DateTimeWriteError
  Error for TryWriteable implementations

Type Aliases

• TimeFormatter
  A formatter optimized for time and time zone formatting.