Struct icu_datetime::DateFormatter

pub struct 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.

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

Examples

use icu::calendar::{any_calendar::AnyCalendar, Date, Gregorian};
use icu::datetime::{options::length, DateFormatter};
use icu::locid::Locale;
use std::str::FromStr;

let provider = icu_testdata::get_provider();

let length = length::Date::Medium;

let df = DateFormatter::try_new_with_buffer_provider(&provider, &Locale::from_str("en-u-ca-gregory").unwrap().into(), length)
    .expect("Failed to create TypedDateFormatter instance.");

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

let value = df.format_to_string(&any_date).expect("calendars should match");
assert_eq!(value, "Sep 1, 2020");

This model replicates that of ICU and ECMA402.

Implementations

impl DateFormatter

pub fn try_new_with_any_provider<P>(
    data_provider: &P,
    locale: &DataLocale,
    length: Date
) -> Result<Self, DateTimeFormatterError> where
    P: AnyProvider, 

Construct a new DateFormatter from a data provider that implements AnyProvider.

The provider must be able to provide data for the following keys: datetime/symbols@1, datetime/timelengths@1, datetime/timelengths@1, datetime/symbols@1, datetime/skeletons@1, datetime/week_data@1, and plurals/ordinals@1.

Furthermore, based on the type of calendar used, one of the following data keys may be necessary:

• u-ca-japanese (Japanese calendar): calendar/japanese@1

pub fn try_new_with_buffer_provider<P>(
    data_provider: &P,
    locale: &DataLocale,
    length: Date
) -> Result<Self, DateTimeFormatterError> where
    P: BufferProvider, 

Construct a new DateFormatter from a data provider that implements BufferProvider.

The provider must be able to provide data for the following keys: datetime/symbols@1, datetime/datelengths@1, datetime/timelengths@1, datetime/symbols@1, datetime/skeletons@1, datetime/week_data@1, and plurals/ordinals@1.

Furthermore, based on the type of calendar used, one of the following data keys may be necessary:

• u-ca-japanese (Japanese calendar): calendar/japanese@1

Examples

use icu::calendar::{any_calendar::AnyCalendar, Date, Gregorian};
use icu::datetime::{options::length, DateFormatter};
use icu::locid::Locale;
use icu_provider::any::DynamicDataProviderAnyMarkerWrap;
use std::str::FromStr;

let provider = icu_testdata::get_provider();

let length = length::Date::Medium;
let locale = Locale::from_str("en-u-ca-gregory").unwrap();

let df = DateFormatter::try_new_with_buffer_provider(&provider, &locale.into(), length)
    .expect("Failed to create TypedDateFormatter instance.");

let datetime = Date::new_gregorian_date(2020, 9, 1)
    .expect("Failed to construct Date.");
let any_datetime = datetime.to_any();

let value = df.format_to_string(&any_datetime).expect("calendars should match");
assert_eq!(value, "Sep 1, 2020");

pub fn try_new_unstable<P>(
    data_provider: &P,
    locale: &DataLocale,
    length: Date
) -> Result<Self, DateTimeFormatterError> where
    P: DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<DateSkeletonPatternsV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<GregorianDateLengthsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<JapaneseDateLengthsV1Marker> + DataProvider<JapaneseExtendedDateLengthsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<IndianDateLengthsV1Marker> + DataProvider<EthiopicDateLengthsV1Marker> + DataProvider<GregorianDateSymbolsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<JapaneseDateSymbolsV1Marker> + DataProvider<JapaneseExtendedDateSymbolsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<IndianDateSymbolsV1Marker> + DataProvider<EthiopicDateSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + DataProvider<JapaneseExtendedErasV1Marker> + ?Sized, 

Construct a new DateFormatter from a data provider that can provide all of the requested data.

This method is unstable, more bounds may be added in the future as calendar support is added. It is preferable to use a provider that implements DataProvider<D> for all D, and ensure data is loaded as appropriate. The Self::try_new_with_buffer_provider(), Self::try_new_with_any_provider() constructors may also be used if compile stability is desired.

Examples

use icu::calendar::{any_calendar::AnyCalendar, Date, Gregorian};
use icu::datetime::{options::length, DateFormatter};
use icu::locid::Locale;
use icu_provider::any::DynamicDataProviderAnyMarkerWrap;
use std::str::FromStr;

let provider = icu_testdata::get_provider();

let length = length::Date::Medium;
let locale = Locale::from_str("en-u-ca-gregory").unwrap();

let df = DateFormatter::try_new_unstable(&provider, &locale.into(), length)
    .expect("Failed to create TypedDateFormatter instance.");

let datetime = Date::new_gregorian_date(2020, 9, 1)
    .expect("Failed to construct Date.");
let any_datetime = datetime.to_any();

let value = df.format_to_string(&any_datetime).expect("calendars should match");
assert_eq!(value, "Sep 1, 2020");

pub fn format<'l, T>(
    &'l self,
    value: &T
) -> Result<FormattedDateTime<'l>, DateTimeFormatterError> where
    T: DateInput<Calendar = AnyCalendar>, 

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

This function will fail if the date passed in uses a different calendar than that of the AnyCalendar. Please convert dates before passing them in if necessary. This function will automatically convert and format dates that are associated with the ISO calendar.

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

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

This function will fail if the date passed in uses a different calendar than that of the AnyCalendar. Please convert dates before passing them in if necessary. This function will automatically convert and format dates that are associated with the ISO calendar.

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

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

This function will fail if the date passed in uses a different calendar than that of the AnyCalendar. Please convert dates before passing them in if necessary. This function will automatically convert and format dates that are associated with the ISO calendar.