Crate icu::datetime

source ·
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.

  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:

FactorStatic (Lower Binary Size)Dynamic (Greater Binary Size)
Field SetsSpecific fieldsets typesEnumerations from fieldsets::enums
Calendar SystemsFixedCalendarDateTimeFormatterDateTimeFormatter

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§

Enums§

Type Aliases§

  • A formatter optimized for time and time zone formatting.