Struct icu_datetime::datetime::DateTimeFormat

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

DateTimeFormat is the main structure of the icu_datetime component. When constructed, it uses data from the DataProvider, 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 DateTimeFormat, and then fast formatting of DateTimeInput data using the instance.

Examples

use icu::locid::Locale;
use icu::locid::macros::langid;
use icu::datetime::{DateTimeFormat, options::length};
use icu::calendar::{DateTime, Gregorian};
use icu_provider::inv::InvariantDataProvider;

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

let provider = InvariantDataProvider;

let options = length::Bag {
    date: Some(length::Date::Medium),
    time: Some(length::Time::Short),
    ..Default::default()
};
let dtf = DateTimeFormat::<Gregorian>::try_new(locale, &provider, &options.into())
    .expect("Failed to create DateTimeFormat instance.");


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

let value = dtf.format_to_string(&datetime);

This model replicates that of ICU and ECMA402. In the future this will become even more pronounced when we introduce asynchronous DataProvider and corresponding asynchronous constructor.

Implementations

impl<C: CldrCalendar> DateTimeFormat<C>

pub fn try_new<T: Into<Locale>, D>(
    locale: T,
    data_provider: &D,
    options: &DateTimeFormatOptions
) -> Result<Self, DateTimeFormatError> where
    D: DataProvider<DateSymbolsV1Marker> + DataProvider<DatePatternsV1Marker> + DataProvider<DateSkeletonPatternsV1Marker> + DataProvider<PluralRulesV1Marker>, 

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

Examples

use icu::locid::Locale;
use icu::locid::macros::langid;
use icu::calendar::Gregorian;
use icu::datetime::{DateTimeFormat, DateTimeFormatOptions};
use icu_provider::inv::InvariantDataProvider;

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

let provider = InvariantDataProvider;

let options = DateTimeFormatOptions::default();

let dtf = DateTimeFormat::<Gregorian>::try_new(locale, &provider, &options);

assert_eq!(dtf.is_ok(), true);

pub fn format<'l, T>(&'l self, value: &'l T) -> FormattedDateTime<'l, T> 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::locid::Locale;
use icu::locid::macros::langid;
use icu::datetime::{DateTimeFormat, DateTimeFormatOptions};
use icu::calendar::{DateTime, Gregorian};
use icu_provider::inv::InvariantDataProvider;
let dtf = DateTimeFormat::<Gregorian>::try_new(locale, &provider, &options)
    .expect("Failed to create DateTimeFormat instance.");

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

let formatted_date = dtf.format(&datetime);

let _ = format!("Date: {}", formatted_date);

At the moment, there’s little value in using that over one of the other format methods, but FormattedDateTime will grow with methods for iterating over fields, extracting information about formatted date and so on.

pub fn format_to_write(
    &self,
    w: &mut impl Write,
    value: &impl DateTimeInput<Calendar = C>
) -> Result

Takes a mutable reference to anything that implements Write trait and a DateTimeInput implementer and populates the buffer with a formatted value.

Examples

use icu::locid::Locale;
use icu::locid::macros::langid;
use icu::datetime::{DateTimeFormat, DateTimeFormatOptions};
use icu::calendar::{DateTime, Gregorian};
use icu_provider::inv::InvariantDataProvider;
let dtf = DateTimeFormat::<Gregorian>::try_new(locale, &provider, &options.into())
    .expect("Failed to create DateTimeFormat instance.");

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

let mut buffer = String::new();
dtf.format_to_write(&mut buffer, &datetime)
    .expect("Failed to write to a buffer.");

let _ = format!("Date: {}", buffer);

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::locid::Locale;
use icu::locid::macros::langid;
use icu::datetime::{DateTimeFormat, DateTimeFormatOptions};
use icu::calendar::{DateTime, Gregorian};
use icu_provider::inv::InvariantDataProvider;
let dtf = DateTimeFormat::<Gregorian>::try_new(locale, &provider, &options.into())
    .expect("Failed to create DateTimeFormat instance.");

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

let _ = dtf.format_to_string(&datetime);

pub fn resolve_components(&self) -> Bag

Returns a components::Bag that represents the resolved components for the options that were provided to the DateTimeFormat. The developer may request a certain set of options for a DateTimeFormat 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},
    DateTimeFormat, DateTimeFormatOptions,
};
use icu::locid::macros::langid;
use icu::locid::Locale;

let options = DateTimeFormatOptions::Length(length::Bag {
    date: Some(length::Date::Medium),
    time: None,
    preferences: None,
});

let locale: Locale = langid!("en").into();
let provider = icu_testdata::get_provider();
let dtf = DateTimeFormat::<Gregorian>::try_new(locale, &provider, &options)
    .expect("Failed to create DateTimeFormat instance.");

assert_eq!(
    dtf.resolve_components(),
    components::Bag {
        year: Some(components::Year::Numeric),
        month: Some(components::Month::Short),
        day: Some(components::Numeric::Numeric),
        ..Default::default()
    }
);