Struct icu_datetime::TypedDateFormatter

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

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.

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 TypedDateFormatter, and then fast formatting of DateInput data using the instance.

Examples

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

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

let date = Date::try_new_gregorian_date(2020, 9, 1)
    .expect("Failed to construct Date.");

assert_writeable_eq!(df.format(&date), "Tuesday, September 1, 2020");

This model replicates that of ICU and ECMA402.

Implementations

impl<C: CldrCalendar> TypedDateFormatter<C>

pub fn try_new_with_length_unstable<D>(
    data_provider: &D,
    locale: &DataLocale,
    length: Date
) -> Result<Self, DateTimeError>where
    D: DataProvider<<C as CldrCalendar>::DateSymbolsV1Marker> + DataProvider<<C as CldrCalendar>::DateLengthsV1Marker> + 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::Date;
use icu::calendar::Gregorian;
use icu::datetime::{options::length, TypedDateFormatter};
use icu::locid::locale;
use writeable::assert_writeable_eq;

let formatter =
    TypedDateFormatter::<Gregorian>::try_new_with_length_unstable(
        &icu_testdata::unstable(),
        &locale!("en").into(),
        length::Date::Full,
    )
    .unwrap();

assert_writeable_eq!(
    formatter.format(&Date::try_new_gregorian_date(2022, 8, 29).unwrap()),
    "Monday, August 29, 2022",
);

If the locale has a calendar keyword, the keyword is ignored in favor of the type parameter on the TypedDateFormatter. To obey the calendar keyword, use DateFormatter instead.

use icu::calendar::indian::Indian;
use icu::calendar::Date;
use icu::datetime::{options::length, TypedDateFormatter};
use icu::locid::locale;
use writeable::assert_writeable_eq;

let formatter = TypedDateFormatter::<Indian>::try_new_with_length_unstable(
    &icu_testdata::unstable(),
    &locale!("en-u-ca-japanese").into(),
    length::Date::Full,
)
.unwrap();

// Indian format from type wins over locale keyword
assert_writeable_eq!(
    formatter.format(&Date::try_new_indian_date(1944, 6, 7).unwrap()),
    "Monday, Bhadra 7, 1944 Saka",
);

pub fn try_new_with_length_with_any_provider(
    provider: &impl AnyProvider + ?Sized,
    locale: &DataLocale,
    length: Date
) -> Result<Self, DateTimeError>

Creates a new instance using an AnyProvider.

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

📚 Help choosing a constructor

pub fn try_new_with_length_with_buffer_provider(
    provider: &impl BufferProvider + ?Sized,
    locale: &DataLocale,
    length: Date
) -> 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_with_length_unstable

📚 Help choosing a constructor

pub fn format<'l, T>(&'l self, value: &T) -> FormattedDateTime<'l>where
    T: DateInput<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::{Date, Gregorian};
use icu::datetime::{options::length, TypedDateFormatter};
use icu::locid::locale;
use writeable::assert_writeable_eq;
let df = TypedDateFormatter::<Gregorian>::try_new_with_length_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    length::Date::Full,
)
.expect("Failed to create TypedDateFormatter instance.");

let date = Date::try_new_gregorian_date(2020, 9, 1)
    .expect("Failed to construct Date.");

assert_writeable_eq!(df.format(&date), "Tuesday, September 1, 2020");

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

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

Examples

use icu::calendar::{Date, Gregorian};
use icu::datetime::{options::length, TypedDateFormatter};
use icu::locid::locale;
let df = TypedDateFormatter::<Gregorian>::try_new_with_length_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    length::Date::Short,
)
.expect("Failed to create TypedDateTimeFormatter instance.");

let date = Date::try_new_gregorian_date(2020, 9, 1)
    .expect("Failed to construct Date.");

assert_eq!(df.format_to_string(&date), "9/1/20");