Crate icu_datetime

icu_datetime is one of the ICU4X components.

This API provides necessary functionality for formatting date and time to user readable textual representation.

DateTimeFormat is the main structure of the component. It accepts a set of arguments which allow it to collect necessary data from the DataProvider, and once instantiated, can be used to quickly format any date and time provided.

Examples

use icu::locid::Locale;
use icu::locid::macros::langid;
use icu::calendar::Gregorian;
use icu::datetime::{DateTimeFormat, DateTimeFormatOptions, mock::parse_gregorian_from_str, options::length};

let provider = icu_testdata::get_provider();

let locale: Locale = langid!("en").into();

// See the next code example for a more ergonomic example with .into().
let options = DateTimeFormatOptions::Length(length::Bag {
    date: Some(length::Date::Medium),
    time: Some(length::Time::Short),
    ..Default::default()
});

let dtf = DateTimeFormat::<Gregorian>::try_new(locale, &provider, &options)
    .expect("Failed to create DateTimeFormat instance.");


let date = parse_gregorian_from_str("2020-09-12T12:35:00")
    .expect("Failed to parse date.");

let formatted_date = dtf.format(&date);
assert_eq!(formatted_date.to_string(), "Sep 12, 2020, 12:35 PM");

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

use icu::locid::Locale;
use icu::locid::macros::langid;
use icu::calendar::Gregorian;
use icu::datetime::{DateTimeFormat, DateTimeFormatOptions, options::length};
let options = length::Bag {
    date: Some(length::Date::Medium),
    time: Some(length::Time::Short),
    ..Default::default()
}.into();

let dtf = DateTimeFormat::<Gregorian>::try_new(locale, &provider, &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.

Notice: Rust at the moment does not have a canonical way to represent date and time. We use DateTime as an example of the data necessary for ICU DateTimeFormat to work, and we hope to work with the community to develop core date and time APIs that will work as an input for this component. DateTime additionally has support for non-Gregorian calendars, which this module will eventually be able to format.

Re-exports

pub use datetime::DateTimeFormat;

pub use options::DateTimeFormatOptions;

pub use time_zone::TimeZoneFormat;

pub use time_zone::TimeZoneFormatConfig;

pub use zoned_datetime::ZonedDateTimeFormat;

Modules

date

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

datetime

The collection of code that is needed for handling formatting operations for DateTimes. Central to this is the DateTimeFormat.

mock

A collection of temporary structs and utilities to input data for tests, benchmarks, and examples.

options

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

provider

Data provider struct definitions for this ICU4X component.

time_zone

zoned_datetime

Structs

FormattedDateTime

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

FormattedTimeZone

FormattedZonedDateTime

Enums

DateTimeFormatError

A list of possible error outcomes for the DateTimeFormat struct.

Traits

CldrCalendar

A calendar that can be found in CLDR