Struct icu_datetime::DateTimeFormatter
source · pub struct DateTimeFormatter(/* private fields */);
Expand description
DateTimeFormatter
is a formatter capable of formatting
date/times from any calendar, selected at runtime. For the difference between this and TypedDateTimeFormatter
,
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 DateTimeFormatter
, and then fast formatting of DateTime
data using the instance.
Examples
use icu::calendar::DateTime;
use icu::datetime::{options::length, DateTimeFormatter};
use icu::locid::locale;
use std::str::FromStr;
use writeable::assert_writeable_eq;
let mut options = length::Bag::from_date_time_style(
length::Date::Medium,
length::Time::Short,
);
let dtf = DateTimeFormatter::try_new(
&locale!("en-u-ca-gregory").into(),
options.into(),
)
.expect("Failed to create DateTimeFormatter instance.");
let datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
.expect("Failed to construct DateTime.");
let any_datetime = datetime.to_any();
assert_writeable_eq!(
dtf.format(&any_datetime).expect("Calendars should match"),
"Sep 1, 2020, 12:34 PM"
);
Since this works with AnyCalendar
, you can use DateTime
with AnyCalendar
to have a date in a runtime-selected calendar:
use icu::calendar::{AnyCalendar, AnyCalendarKind, DateTime, types::Time};
use icu::datetime::{options::length, DateTimeFormatter};
use icu::locid::locale;
use writeable::assert_writeable_eq;
let locale = locale!("en-u-ca-japanese").into(); // English with the Japanese calendar
let calendar = AnyCalendar::new_for_locale(&locale);
let calendar = Rc::new(calendar); // Avoid cloning it
// manually construct a datetime in this calendar
let manual_time = Time::try_new(12, 33, 12, 0).expect("failed to construct Time");
// construct from era code, year, month code, day, time, and a calendar
// This is March 28, 15 Heisei
let manual_datetime = DateTime::try_new_from_codes("heisei".parse().unwrap(), 15, "M03".parse().unwrap(), 28,
manual_time, calendar.clone())
.expect("Failed to construct DateTime manually");
// construct another datetime by converting from ISO
let iso_datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
.expect("Failed to construct ISO DateTime.");
let iso_converted = iso_datetime.to_calendar(calendar);
let options = length::Bag::from_date_time_style(length::Date::Medium, length::Time::Short);
let dtf = DateTimeFormatter::try_new(&locale, options.into())
.expect("Failed to create DateTimeFormatter instance.");
let manual_value = dtf.format(&manual_datetime).expect("Calendars should match");
assert_writeable_eq!(manual_value, "Mar 28, 15 Heisei, 12:33 PM");
let converted_value = dtf.format(&iso_converted).expect("Calendars should match");
assert_writeable_eq!(converted_value, "Sep 1, 2 Reiwa, 12:34 PM");
This model replicates that of ICU
and ECMA402
.
Implementations§
source§impl DateTimeFormatter
impl DateTimeFormatter
sourcepub fn try_new(
locale: &DataLocale,
options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>
pub fn try_new( locale: &DataLocale, options: DateTimeFormatterOptions ) -> Result<Self, DateTimeError>
Construct a new DateTimeFormatter
from compiled data.
This method will pick the calendar off of the locale; and if unspecified or unknown will fall back to the default
calendar for the locale. See AnyCalendarKind
for a list of supported calendars.
✨ Enabled with the compiled_data
Cargo feature.
Examples
use icu::calendar::DateTime;
use icu::datetime::{options::length, DateTimeFormatter};
use icu::locid::locale;
use icu_provider::any::DynamicDataProviderAnyMarkerWrap;
use std::str::FromStr;
use writeable::assert_writeable_eq;
let options = length::Bag::from_date_time_style(
length::Date::Medium,
length::Time::Short,
);
let locale = locale!("en-u-ca-gregory");
let dtf = DateTimeFormatter::try_new(&locale.into(), options.into())
.expect("Failed to create TypedDateTimeFormatter instance.");
let datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
.expect("Failed to construct DateTime.");
let any_datetime = datetime.to_any();
assert_writeable_eq!(
dtf.format(&any_datetime).expect("Calendars should match"),
"Sep 1, 2020, 12:34 PM"
);
✨ Enabled with the compiled_data
Cargo feature.
sourcepub fn try_new_with_any_provider(
provider: &impl AnyProvider,
locale: &DataLocale,
options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>
pub fn try_new_with_any_provider( provider: &impl AnyProvider, locale: &DataLocale, options: DateTimeFormatterOptions ) -> Result<Self, DateTimeError>
A version of Self::try_new
that uses custom data provided by an AnyProvider
.
sourcepub fn try_new_with_buffer_provider(
provider: &impl BufferProvider,
locale: &DataLocale,
options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>
pub fn try_new_with_buffer_provider( provider: &impl BufferProvider, locale: &DataLocale, options: DateTimeFormatterOptions ) -> Result<Self, DateTimeError>
A version of Self::try_new
that uses custom data provided by a BufferProvider
.
✨ Enabled with the serde
feature.
sourcepub fn try_new_experimental_unstable<P>(
provider: &P,
locale: &DataLocale,
options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>where
P: DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<DateSkeletonPatternsV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<ChineseDateLengthsV1Marker> + DataProvider<ChineseDateSymbolsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<DangiDateLengthsV1Marker> + DataProvider<DangiDateSymbolsV1Marker> + DataProvider<EthiopianDateLengthsV1Marker> + DataProvider<EthiopianDateSymbolsV1Marker> + DataProvider<GregorianDateLengthsV1Marker> + DataProvider<GregorianDateSymbolsV1Marker> + DataProvider<HebrewDateLengthsV1Marker> + DataProvider<HebrewDateSymbolsV1Marker> + DataProvider<IndianDateLengthsV1Marker> + DataProvider<IndianDateSymbolsV1Marker> + DataProvider<IslamicDateLengthsV1Marker> + DataProvider<IslamicDateSymbolsV1Marker> + DataProvider<JapaneseDateLengthsV1Marker> + DataProvider<JapaneseDateSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + DataProvider<JapaneseExtendedDateLengthsV1Marker> + DataProvider<JapaneseExtendedDateSymbolsV1Marker> + DataProvider<JapaneseExtendedErasV1Marker> + DataProvider<PersianDateLengthsV1Marker> + DataProvider<PersianDateSymbolsV1Marker> + DataProvider<RocDateLengthsV1Marker> + DataProvider<RocDateSymbolsV1Marker> + ?Sized,
pub fn try_new_experimental_unstable<P>( provider: &P, locale: &DataLocale, options: DateTimeFormatterOptions ) -> Result<Self, DateTimeError>where P: DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<DateSkeletonPatternsV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<ChineseDateLengthsV1Marker> + DataProvider<ChineseDateSymbolsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<DangiDateLengthsV1Marker> + DataProvider<DangiDateSymbolsV1Marker> + DataProvider<EthiopianDateLengthsV1Marker> + DataProvider<EthiopianDateSymbolsV1Marker> + DataProvider<GregorianDateLengthsV1Marker> + DataProvider<GregorianDateSymbolsV1Marker> + DataProvider<HebrewDateLengthsV1Marker> + DataProvider<HebrewDateSymbolsV1Marker> + DataProvider<IndianDateLengthsV1Marker> + DataProvider<IndianDateSymbolsV1Marker> + DataProvider<IslamicDateLengthsV1Marker> + DataProvider<IslamicDateSymbolsV1Marker> + DataProvider<JapaneseDateLengthsV1Marker> + DataProvider<JapaneseDateSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + DataProvider<JapaneseExtendedDateLengthsV1Marker> + DataProvider<JapaneseExtendedDateSymbolsV1Marker> + DataProvider<JapaneseExtendedErasV1Marker> + DataProvider<PersianDateLengthsV1Marker> + DataProvider<PersianDateSymbolsV1Marker> + DataProvider<RocDateLengthsV1Marker> + DataProvider<RocDateSymbolsV1Marker> + ?Sized,
A version of Self::try_new_experimental
that uses custom data provided by a DataProvider
.
sourcepub fn try_new_experimental(
locale: &DataLocale,
options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>
pub fn try_new_experimental( locale: &DataLocale, options: DateTimeFormatterOptions ) -> Result<Self, DateTimeError>
Constructor that supports experimental options with compiled data.
✨ Enabled with the compiled_data
and experimental
Cargo features.
Examples
use icu::calendar::DateTime;
use icu::datetime::{options::components, DateTimeFormatter};
use icu::locid::locale;
use icu_provider::any::DynamicDataProviderAnyMarkerWrap;
use icu_provider::AsDeserializingBufferProvider;
use std::str::FromStr;
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 = DateTimeFormatter::try_new_experimental(
&locale!("en-u-ca-gregory").into(),
options.into(),
)
.expect("Failed to create TypedDateTimeFormatter instance.");
let datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
.expect("Failed to construct DateTime.");
let any_datetime = datetime.to_any();
assert_writeable_eq!(
dtf.format(&any_datetime).expect("Calendars should match"),
"September 2020"
);
sourcepub fn try_new_unstable<P>(
provider: &P,
locale: &DataLocale,
options: DateTimeFormatterOptions
) -> Result<Self, DateTimeError>where
P: DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<ChineseDateLengthsV1Marker> + DataProvider<ChineseDateSymbolsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<DangiDateLengthsV1Marker> + DataProvider<DangiDateSymbolsV1Marker> + DataProvider<EthiopianDateLengthsV1Marker> + DataProvider<EthiopianDateSymbolsV1Marker> + DataProvider<GregorianDateLengthsV1Marker> + DataProvider<GregorianDateSymbolsV1Marker> + DataProvider<HebrewDateLengthsV1Marker> + DataProvider<HebrewDateSymbolsV1Marker> + DataProvider<IndianDateLengthsV1Marker> + DataProvider<IndianDateSymbolsV1Marker> + DataProvider<IslamicDateLengthsV1Marker> + DataProvider<IslamicDateSymbolsV1Marker> + DataProvider<JapaneseDateLengthsV1Marker> + DataProvider<JapaneseDateSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + DataProvider<JapaneseExtendedDateLengthsV1Marker> + DataProvider<JapaneseExtendedDateSymbolsV1Marker> + DataProvider<JapaneseExtendedErasV1Marker> + DataProvider<PersianDateLengthsV1Marker> + DataProvider<PersianDateSymbolsV1Marker> + DataProvider<RocDateLengthsV1Marker> + DataProvider<RocDateSymbolsV1Marker> + ?Sized,
pub fn try_new_unstable<P>( provider: &P, locale: &DataLocale, options: DateTimeFormatterOptions ) -> Result<Self, DateTimeError>where P: DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<ChineseDateLengthsV1Marker> + DataProvider<ChineseDateSymbolsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<DangiDateLengthsV1Marker> + DataProvider<DangiDateSymbolsV1Marker> + DataProvider<EthiopianDateLengthsV1Marker> + DataProvider<EthiopianDateSymbolsV1Marker> + DataProvider<GregorianDateLengthsV1Marker> + DataProvider<GregorianDateSymbolsV1Marker> + DataProvider<HebrewDateLengthsV1Marker> + DataProvider<HebrewDateSymbolsV1Marker> + DataProvider<IndianDateLengthsV1Marker> + DataProvider<IndianDateSymbolsV1Marker> + DataProvider<IslamicDateLengthsV1Marker> + DataProvider<IslamicDateSymbolsV1Marker> + DataProvider<JapaneseDateLengthsV1Marker> + DataProvider<JapaneseDateSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + DataProvider<JapaneseExtendedDateLengthsV1Marker> + DataProvider<JapaneseExtendedDateSymbolsV1Marker> + DataProvider<JapaneseExtendedErasV1Marker> + DataProvider<PersianDateLengthsV1Marker> + DataProvider<PersianDateSymbolsV1Marker> + DataProvider<RocDateLengthsV1Marker> + DataProvider<RocDateSymbolsV1Marker> + ?Sized,
A version of Self::try_new
that uses custom data provided by a DataProvider
.
sourcepub fn try_from_date_and_time(
date: DateFormatter,
time: TimeFormatter
) -> Result<Self, DateTimeError>
pub fn try_from_date_and_time( date: DateFormatter, time: TimeFormatter ) -> Result<Self, DateTimeError>
Constructor that takes a TimeFormatter
and DateFormatter
and combines them into a DateTimeFormatter
.
Prefer using one of the other constructors if possible.
Examples
use icu::calendar::DateTime;
use icu::datetime::{
options::length, DateFormatter, DateTimeFormatter, TimeFormatter,
};
use icu::locid::locale;
use icu_provider::any::DynamicDataProviderAnyMarkerWrap;
use std::str::FromStr;
use writeable::assert_writeable_eq;
let length = length::Date::Medium;
let locale = locale!("en-u-ca-gregory");
let df = DateFormatter::try_new_with_length(&locale.into(), length)
.expect("Failed to create TypedDateFormatter instance.");
let tf = TimeFormatter::try_new_with_length(
&locale!("en").into(),
length::Time::Short,
)
.expect("Failed to create TimeFormatter instance.");
let dtf = DateTimeFormatter::try_from_date_and_time(df, tf).unwrap();
let datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
.expect("Failed to construct DateTime.");
let any_datetime = datetime.to_any();
assert_writeable_eq!(
dtf.format(&any_datetime).expect("Calendars should match"),
"Sep 1, 2020, 12:34 PM"
);
sourcepub fn format<'l, T>(
&'l self,
value: &T
) -> Result<FormattedDateTime<'l>, DateTimeError>where
T: DateTimeInput<Calendar = AnyCalendar>,
pub fn format<'l, T>( &'l self, value: &T ) -> Result<FormattedDateTime<'l>, DateTimeError>where T: DateTimeInput<Calendar = AnyCalendar>,
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.
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.
sourcepub fn format_to_string(
&self,
value: &impl DateTimeInput<Calendar = AnyCalendar>
) -> Result<String, DateTimeError>
pub fn format_to_string( &self, value: &impl DateTimeInput<Calendar = AnyCalendar> ) -> Result<String, DateTimeError>
Takes a DateTimeInput
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.
sourcepub fn resolve_components(&self) -> Bag
pub fn resolve_components(&self) -> Bag
Returns a components::Bag
that represents the resolved components for the
options that were provided to the DateTimeFormatter
. The developer may request
a certain set of options for a DateTimeFormatter
but the locale and resolution
algorithm may change certain details of what actually gets resolved.
✨ Enabled with the experimental
Cargo feature.
Examples
use icu::calendar::Gregorian;
use icu::datetime::{
options::{components, length},
DateTimeFormatter, DateTimeFormatterOptions,
};
use icu::locid::locale;
use std::str::FromStr;
let options = length::Bag::from_date_style(length::Date::Medium).into();
let dtf =
DateTimeFormatter::try_new(&locale!("en-u-ca-gregory").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);