Struct icu_datetime::TypedDateTimeFormatter

pub struct TypedDateTimeFormatter<C>(_, _);

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.

When constructed, it uses data from the data provider, selected locale and provided options to collect all data necessary to format any dates into that locale.

For that reason, one should think of the process of formatting a date in two steps - first, a computational heavy construction of TypedDateTimeFormatter, and then fast formatting of DateInput data using the instance.

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::{options::length, TypedDateTimeFormatter};
use icu::locid::locale;
use writeable::assert_writeable_eq;

let mut options = length::Bag::from_date_time_style(
    length::Date::Medium,
    length::Time::Short,
);

let dtf = TypedDateTimeFormatter::<Gregorian>::try_new_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    options.into(),
)
.expect("Failed to create TypedDateTimeFormatter instance.");

let datetime = DateTime::try_new_gregorian_datetime(2020, 9, 1, 12, 34, 28)
    .expect("Failed to construct DateTime.");

assert_writeable_eq!(dtf.format(&datetime), "Sep 1, 2020, 12:34 PM");

This model replicates that of ICU and ECMA402.

Implementations

impl<C: CldrCalendar> TypedDateTimeFormatter<C>

pub fn try_from_date_and_time(
    date: TypedDateFormatter<C>,
    time: TimeFormatter
) -> Result<Self, DateTimeError>

Constructor that takes a TimeFormatter and TypedDateFormatter and combines them into a TypedDateTimeFormatter.

Examples

use icu::calendar::Gregorian;
use icu::datetime::{
    options::length, TimeFormatter, TypedDateFormatter,
    TypedDateTimeFormatter,
};
use icu::locid::locale;

let tf = TimeFormatter::try_new_with_length_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    length::Time::Short,
)
.expect("Failed to create TimeFormatter instance.");
let df = TypedDateFormatter::<Gregorian>::try_new_with_length_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    length::Date::Short,
)
.expect("Failed to create TypedDateFormatter instance.");

TypedDateTimeFormatter::<Gregorian>::try_from_date_and_time(df, tf)
    .unwrap();

pub fn try_new_experimental_unstable<D>(
    data_provider: &D,
    locale: &DataLocale,
    options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>where
    D: DataProvider<<C as CldrCalendar>::DateSymbolsV1Marker> + DataProvider<<C as CldrCalendar>::DateLengthsV1Marker> + DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<DateSkeletonPatternsV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<WeekDataV1Marker> + ?Sized,

Constructor that supports experimental options.

🚧 This code is experimental; it may change at any time, in breaking or non-breaking ways, including in SemVer minor releases. It can be enabled with the "experimental" feature of the icu meta-crate. Use with caution. #1317

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::{options::components, TypedDateTimeFormatter};
use icu::locid::locale;
use icu_provider::AsDeserializingBufferProvider;
use writeable::assert_writeable_eq;

let mut options = components::Bag::default();
options.year = Some(components::Year::Numeric);
options.month = Some(components::Month::Long);

let dtf =
    TypedDateTimeFormatter::<Gregorian>::try_new_experimental_unstable(
        &icu_testdata::buffer().as_deserializing(),
        &locale!("en").into(),
        options.into(),
    )
    .unwrap();

let datetime =
    DateTime::try_new_gregorian_datetime(2022, 8, 31, 1, 2, 3).unwrap();

assert_writeable_eq!(dtf.format(&datetime), "August 2022");

pub fn try_new_unstable<D>(
    data_provider: &D,
    locale: &DataLocale,
    options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>where
    D: DataProvider<<C as CldrCalendar>::DateSymbolsV1Marker> + DataProvider<<C as CldrCalendar>::DateLengthsV1Marker> + DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<WeekDataV1Marker> + ?Sized,

Constructor that takes a selected locale, reference to a data provider and a list of options, then collects all data necessary to format date and time values into the given locale.

📚 Help choosing a constructor

⚠️ The bounds on this function may change over time, including in SemVer minor releases.

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::{options::length, TypedDateTimeFormatter};
use icu::locid::locale;
use writeable::assert_writeable_eq;

let options = length::Bag::from_date_time_style(
    length::Date::Medium,
    length::Time::Medium,
);

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

let datetime =
    DateTime::try_new_gregorian_datetime(2022, 8, 31, 1, 2, 3).unwrap();

assert_writeable_eq!(dtf.format(&datetime), "Aug 31, 2022, 1:02:03 AM");

pub fn try_new_with_any_provider(
    provider: &impl AnyProvider + ?Sized,
    locale: &DataLocale,
    options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>

Creates a new instance using an AnyProvider.

For details on the behavior of this function, see: Self::try_new_unstable

📚 Help choosing a constructor

pub fn try_new_with_buffer_provider(
    provider: &impl BufferProvider + ?Sized,
    locale: &DataLocale,
    options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>

✨ Enabled with the "serde" feature.

Creates a new instance using a BufferProvider.

For details on the behavior of this function, see: Self::try_new_unstable

📚 Help choosing a constructor

pub fn format<'l, T>(&'l self, value: &T) -> FormattedDateTime<'l>where
    T: DateTimeInput<Calendar = C>,

Takes a DateTimeInput implementer and returns an instance of a FormattedDateTime that contains all information necessary to display a formatted date and operate on it.

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::TypedDateTimeFormatter;
use writeable::assert_writeable_eq;
use icu::locid::locale;
let dtf = TypedDateTimeFormatter::<Gregorian>::try_new_unstable(&icu_testdata::unstable(), &locale!("en").into(), options.into())
    .expect("Failed to create TypedDateTimeFormatter instance.");

let datetime = DateTime::try_new_gregorian_datetime(2020, 9, 1, 12, 34, 28)
    .expect("Failed to construct DateTime.");

assert_writeable_eq!(dtf.format(&datetime), "12:34:28 PM");

pub fn format_to_string(
    &self,
    value: &impl DateTimeInput<Calendar = C>
) -> String

Takes a DateTimeInput implementer and returns it formatted as a string.

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::TypedDateTimeFormatter;
use icu::locid::locale;
let dtf = TypedDateTimeFormatter::<Gregorian>::try_new_unstable(&icu_testdata::unstable(), &locale!("en").into(), options.into())
    .expect("Failed to create TypedDateTimeFormatter instance.");

let datetime = DateTime::try_new_gregorian_datetime(2020, 9, 1, 12, 34, 28)
    .expect("Failed to construct DateTime.");

assert_eq!(dtf.format_to_string(&datetime), "12:34:28 PM");

pub fn resolve_components(&self) -> Bag

Returns a components::Bag that represents the resolved components for the options that were provided to the TypedDateTimeFormatter. The developer may request a certain set of options for a TypedDateTimeFormatter but the locale and resolution algorithm may change certain details of what actually gets resolved.

Examples

use icu::calendar::Gregorian;
use icu::datetime::{
    options::{components, length},
    DateTimeFormatterOptions, TypedDateTimeFormatter,
};
use icu::locid::locale;

let options = length::Bag::from_date_style(length::Date::Medium).into();
let dtf = TypedDateTimeFormatter::<Gregorian>::try_new_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    options,
)
.expect("Failed to create TypedDateTimeFormatter instance.");

let mut expected_components_bag = components::Bag::default();
expected_components_bag.year = Some(components::Year::Numeric);
expected_components_bag.month = Some(components::Month::Short);
expected_components_bag.day = Some(components::Day::NumericDayOfMonth);

assert_eq!(dtf.resolve_components(), expected_components_bag);