Crate icu_datetime

Formatting date and time.

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.

TypedDateTimeFormatter and DateTimeFormatter are the main types of the component. They accepts a set of arguments which allow it to collect necessary data from the data provider, and once instantiated, can be used to quickly format any date and time provided. There are variants of these types that can format greater or fewer components, including TypedDateFormatter & DateFormatter, TypedZonedDateTimeFormatter & ZonedDateTimeFormatter, TimeFormatter, and TimeZoneFormatter

These formatters work with types from the calendar module, like Date, DateTime, and Time, and timezone::CustomTimeZone, however other types may be used provided they implement the traits from the input module.

Each instance of a date-related formatter (i.e. not TimeFormatter or TimeZoneFormatter is associated with a particular Calendar. The “Typed” vs untyped formatter distinction is to help with this. For example, if you know at compile time that you will only be formatting Gregorian dates, you can use TypedDateTimeFormatter<Gregorian> and the APIs will make sure that only Gregorian DateTimes are used with the calendar. On the other hand, if you want to be able to select the calendar at runtime, you can use DateTimeFormatter with the calendar specified in the locale, and use it with DateTime,AnyCalendar. These formatters still require dates associated with the appropriate calendar (though they will convert ISO dates to the calendar if provided), they just do not force the programmer to pick the calendar at compile time.

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::{
    options::length, DateTimeFormatter, DateTimeFormatterOptions,
    TypedDateTimeFormatter,
};
use icu::locid::{locale, Locale};
use std::str::FromStr;
use writeable::assert_writeable_eq;

// See the next code example for a more ergonomic example with .into().
let options =
    DateTimeFormatterOptions::Length(length::Bag::from_date_time_style(
        length::Date::Medium,
        length::Time::Short,
    ));

// You can work with a formatter that can select the calendar at runtime:
let locale = Locale::from_str("en-u-ca-gregory").unwrap();
let dtf = DateTimeFormatter::try_new(&locale.into(), options.clone())
    .expect("Failed to create DateTimeFormatter instance.");

// Or one that selects a calendar at compile time:
let typed_dtf = TypedDateTimeFormatter::<Gregorian>::try_new(
    &locale!("en").into(),
    options,
)
.expect("Failed to create TypedDateTimeFormatter instance.");

let typed_date =
    DateTime::try_new_gregorian_datetime(2020, 9, 12, 12, 34, 28).unwrap();
// prefer using ISO dates with DateTimeFormatter
let date = typed_date.to_iso().to_any();

let formatted_date = dtf.format(&date).expect("Calendars should match");
let typed_formatted_date = typed_dtf.format(&typed_date);

assert_writeable_eq!(formatted_date, "Sep 12, 2020, 12:34 PM");
assert_writeable_eq!(typed_formatted_date, "Sep 12, 2020, 12:34 PM");

let formatted_date_string =
    dtf.format_to_string(&date).expect("Calendars should match");
let typed_formatted_date_string = typed_dtf.format_to_string(&typed_date);

assert_eq!(formatted_date_string, "Sep 12, 2020, 12:34 PM");
assert_eq!(typed_formatted_date_string, "Sep 12, 2020, 12:34 PM");

The options can be created more ergonomically using the Into trait to automatically convert a options::length::Bag into a DateTimeFormatterOptions::Length.

use icu::calendar::Gregorian;
use icu::datetime::{
    options::length, DateTimeFormatterOptions, TypedDateTimeFormatter,
};
use icu::locid::locale;
let options = length::Bag::from_date_time_style(
    length::Date::Medium,
    length::Time::Short,
)
.into();

let dtf = TypedDateTimeFormatter::<Gregorian>::try_new(
    &locale!("en").into(),
    options,
);

At the moment, the crate provides only options using the Length bag, but in the future, we expect to add more ways to customize the output, like skeletons, and components.

Re-exports

pub use options::DateTimeFormatterOptions;

pub use DateTimeError as Error;

Modules

fields

Enums representing the fields in a date pattern, including the field’s type, length and symbol.

input

A collection of utilities for representing and working with dates as an input to formatting operations.

neo

High-level entrypoints for Neo DateTime Formatter

neo_marker

Temporary module for neo formatter markers.

neo_pattern

Temporary module for neo datetime patterns

neo_skeleton

Temporary module for neo datetime skeletons (Semantic Skeleta)

options

DateTimeFormatterOptions is a bag of options which, together with Locale, defines how dates will be formatted with a TypedDateTimeFormatter instance.

provider

🚧 [Unstable] Data provider struct definitions for this ICU4X component.

time_zone

A formatter specifically for the time zone.

Structs

DateFormatter

DateFormatter is a formatter capable of formatting dates from any calendar, selected at runtime. For the difference between this and TypedDateFormatter, please read the crate root docs.

DateTimeFormatter

DateTimeFormatter is a formatter capable of formatting date/times from any calendar, selected at runtime. For the difference between this and TypedDateTimeFormatter, please read the crate root docs.

FormattedDateTime

FormattedDateTime is a intermediate structure which can be retrieved as an output from TypedDateTimeFormatter.

FormattedDateTimePattern

A pattern that has been interpolated and implements TryWriteable.

FormattedTimeZone

FormattedTimeZone is a intermediate structure which can be retrieved as an output from TimeZoneFormatter.

FormattedZonedDateTime

FormattedTimeZone is a intermediate structure which can be retrieved as an output from ZonedDateTimeFormatter.

MismatchedCalendarError

An error from mixing calendar types in DateTimeFormatter

TimeFormatter

TimeFormatter is a structure of the icu::datetime component that provides time formatting only. When constructed, it uses data from the data provider, selected locale and provided preferences to collect all data necessary to format any time into that locale.

TypedDateFormatter

TypedDateFormatter is a formatter capable of formatting dates from a calendar selected at compile time. For the difference between this and DateFormatter, please read the crate root docs.

TypedDateTimeFormatter

TypedDateTimeFormatter is a formatter capable of formatting date/times from a calendar selected at compile time. For the difference between this and DateTimeFormatter, please read the crate root docs.

TypedDateTimeNames

A low-level type that formats datetime patterns with localized symbols. The calendar should be chosen at compile time. 📏 This item has a stack size of 488 bytes on the stable toolchain at release date.

TypedZonedDateTimeFormatter

The composition of TypedDateTimeFormatter and TimeZoneFormatter.

ZonedDateTimeFormatter

ZonedDateTimeFormatter is a formatter capable of formatting date/times with time zones from any calendar, selected at runtime. For the difference between this and TypedZonedDateTimeFormatter, please read the crate root docs.

Enums

DateTimeError

A list of error outcomes for various operations in this module.

DateTimeWriteError

Error for TryWriteable implementations

LoadError

Error returned from TypedDateTimeNames’s pattern load methods.

NeverCalendar

A calendar that can never exist.

SingleLoadError

Error returned from TypedDateTimeNames’s load methods.

Traits

CldrCalendar

A calendar that can be found in CLDR

InternalCldrCalendar

The CldrCalendar trait is sealed except when the "experimental" Cargo feature is enabled. If implementing CldrCalendar, you must also implement UnstableCldrCalendar and acknowledge the stability policy.