Struct icu_datetime::DateTimeFormatter
source · pub struct DateTimeFormatter<FSet: DateTimeNamesMarker> { /* private fields */ }
Expand description
DateTimeFormatter
is a formatter capable of formatting dates and/or times from
a calendar selected at runtime.
For more details, please read the crate root docs.
📏 This item has a stack size of 400 bytes on the stable toolchain at release date.
Implementations§
source§impl<FSet> DateTimeFormatter<FSet>where
FSet::D: DateDataMarkers,
FSet::T: TimeMarkers,
FSet::Z: ZoneMarkers,
FSet: GetField<CompositeFieldSet> + DateTimeMarkers,
impl<FSet> DateTimeFormatter<FSet>where
FSet::D: DateDataMarkers,
FSet::T: TimeMarkers,
FSet::Z: ZoneMarkers,
FSet: GetField<CompositeFieldSet> + DateTimeMarkers,
sourcepub fn try_new(
prefs: DateTimeFormatterPreferences,
field_set: FSet,
) -> Result<Self, DateTimeFormatterLoadError>where
Baked: AllAnyCalendarFormattingDataMarkers<FSet>,
pub fn try_new(
prefs: DateTimeFormatterPreferences,
field_set: FSet,
) -> Result<Self, DateTimeFormatterLoadError>where
Baked: AllAnyCalendarFormattingDataMarkers<FSet>,
Creates a new DateTimeFormatter
from compiled data with
datetime components specified at build time.
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.
Use this constructor for optimal data size and memory use
if you know the required datetime components at build time.
If you do not know the datetime components until runtime,
use a with_components
constructor.
✨ Enabled with the compiled_data
Cargo feature.
§Examples
Basic usage:
use icu::calendar::{any_calendar::AnyCalendar, DateTime};
use icu::datetime::fieldsets::YMD;
use icu::datetime::DateTimeFormatter;
use icu::locale::locale;
use std::str::FromStr;
use writeable::assert_writeable_eq;
let formatter = DateTimeFormatter::try_new(
locale!("en-u-ca-hebrew").into(),
YMD::medium(),
)
.unwrap();
let datetime = DateTime::try_new_iso(2024, 5, 8, 0, 0, 0).unwrap();
assert_writeable_eq!(
formatter.format_any_calendar(&datetime),
"30 Nisan 5784"
);
sourcepub fn try_new_with_any_provider<P>(
provider: &P,
prefs: DateTimeFormatterPreferences,
field_set: FSet,
) -> Result<Self, DateTimeFormatterLoadError>where
P: AnyProvider + ?Sized,
pub fn try_new_with_any_provider<P>(
provider: &P,
prefs: DateTimeFormatterPreferences,
field_set: FSet,
) -> Result<Self, DateTimeFormatterLoadError>where
P: AnyProvider + ?Sized,
A version of [Self :: try_new
] that uses custom data provided by an AnyProvider
.
sourcepub fn try_new_with_buffer_provider<P>(
provider: &P,
prefs: DateTimeFormatterPreferences,
field_set: FSet,
) -> Result<Self, DateTimeFormatterLoadError>where
P: BufferProvider + ?Sized,
pub fn try_new_with_buffer_provider<P>(
provider: &P,
prefs: DateTimeFormatterPreferences,
field_set: FSet,
) -> Result<Self, DateTimeFormatterLoadError>where
P: BufferProvider + ?Sized,
A version of [Self :: try_new
] that uses custom data provided by a BufferProvider
.
✨ Enabled with the serde
feature.
sourcepub fn try_new_unstable<P>(
provider: &P,
prefs: DateTimeFormatterPreferences,
field_set: FSet,
) -> Result<Self, DateTimeFormatterLoadError>
pub fn try_new_unstable<P>( provider: &P, prefs: DateTimeFormatterPreferences, field_set: FSet, ) -> Result<Self, DateTimeFormatterLoadError>
A version of Self::try_new
that uses custom data provided by a DataProvider
.
source§impl<FSet: DateTimeMarkers> DateTimeFormatter<FSet>
impl<FSet: DateTimeMarkers> DateTimeFormatter<FSet>
sourcepub fn format_same_calendar<I>(
&self,
datetime: &I,
) -> Result<FormattedDateTime<'_>, MismatchedCalendarError>
pub fn format_same_calendar<I>( &self, datetime: &I, ) -> Result<FormattedDateTime<'_>, MismatchedCalendarError>
Formats a datetime, checking that the calendar system is correct.
If the datetime is not in the same calendar system as the formatter, an error is returned.
§Examples
Mismatched calendars will return an error:
use icu::calendar::Date;
use icu::datetime::fieldsets::YMD;
use icu::datetime::DateTimeFormatter;
use icu::datetime::MismatchedCalendarError;
use icu::locale::locale;
let formatter = DateTimeFormatter::try_new(
locale!("en-u-ca-hebrew").into(),
YMD::long(),
)
.unwrap();
let date = Date::try_new_gregorian(2023, 12, 20).unwrap();
assert!(matches!(
formatter.format_same_calendar(&date),
Err(MismatchedCalendarError { .. })
));
A time cannot be passed into the formatter when a date is expected:
use icu::calendar::Time;
use icu::datetime::DateTimeFormatter;
use icu::datetime::fieldsets::YMD;
use icu::locale::locale;
let formatter = DateTimeFormatter::try_new(
locale!("es-MX").into(),
Length::Long.into(),
)
.unwrap();
// the trait `GetField<AnyCalendarKind>`
// is not implemented for `icu::icu_calendar::Time`
formatter.format_same_calendar(&Time::try_new(0, 0, 0, 0).unwrap());
sourcepub fn format_any_calendar<'a, I>(
&'a self,
datetime: &I,
) -> FormattedDateTime<'a>
pub fn format_any_calendar<'a, I>( &'a self, datetime: &I, ) -> FormattedDateTime<'a>
Formats a datetime after first converting it to the formatter’s calendar.
§Examples
Mismatched calendars convert and format automatically:
use icu::calendar::Date;
use icu::datetime::fieldsets::YMD;
use icu::datetime::DateTimeFormatter;
use icu::datetime::MismatchedCalendarError;
use icu::locale::locale;
use writeable::assert_writeable_eq;
let formatter = DateTimeFormatter::try_new(
locale!("en-u-ca-hebrew").into(),
YMD::long(),
)
.unwrap();
let date = Date::try_new_roc(113, 5, 8).unwrap();
assert_writeable_eq!(formatter.format_any_calendar(&date), "30 Nisan 5784");
A time cannot be passed into the formatter when a date is expected:
use icu::calendar::Time;
use icu::datetime::DateTimeFormatter;
use icu::datetime::fieldsets::YMD;
use icu::locale::locale;
let formatter = DateTimeFormatter::try_new(
locale!("es-MX").into(),
Length::Long.into(),
)
.unwrap();
// the trait `GetField<AnyCalendarKind>`
// is not implemented for `icu::icu_calendar::Time`
formatter.format_any_calendar(&Time::try_new(0, 0, 0, 0).unwrap());
source§impl<FSet: DateTimeMarkers> DateTimeFormatter<FSet>
impl<FSet: DateTimeMarkers> DateTimeFormatter<FSet>
sourcepub fn try_into_typed_formatter<C>(
self,
) -> Result<FixedCalendarDateTimeFormatter<C, FSet>, MismatchedCalendarError>where
C: CldrCalendar + IntoAnyCalendar,
pub fn try_into_typed_formatter<C>(
self,
) -> Result<FixedCalendarDateTimeFormatter<C, FSet>, MismatchedCalendarError>where
C: CldrCalendar + IntoAnyCalendar,
Attempt to convert this DateTimeFormatter
into one with a specific calendar.
Returns an error if the type parameter does not match the inner calendar.
§Examples
use icu::calendar::cal::Hebrew;
use icu::calendar::Date;
use icu::datetime::fieldsets::YMD;
use icu::datetime::DateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;
let formatter = DateTimeFormatter::try_new(
locale!("en-u-ca-hebrew").into(),
YMD::long(),
)
.unwrap()
.try_into_typed_formatter::<Hebrew>()
.unwrap();
let date = Date::try_new_hebrew(5785, 1, 12).unwrap();
assert_writeable_eq!(formatter.format(&date), "12 Tishri 5785");
An error occurs if the calendars don’t match:
use icu::calendar::cal::Hebrew;
use icu::calendar::Date;
use icu::datetime::fieldsets::YMD;
use icu::datetime::DateTimeFormatter;
use icu::datetime::MismatchedCalendarError;
use icu::locale::locale;
let result = DateTimeFormatter::try_new(
locale!("en-u-ca-buddhist").into(),
YMD::long(),
)
.unwrap()
.try_into_typed_formatter::<Hebrew>();
assert!(matches!(result, Err(MismatchedCalendarError { .. })));
sourcepub fn with_fset<FSet2: DateTimeNamesFrom<FSet>>(
self,
) -> DateTimeFormatter<FSet2>
pub fn with_fset<FSet2: DateTimeNamesFrom<FSet>>( self, ) -> DateTimeFormatter<FSet2>
Maps a DateTimeFormatter
of a specific FSet
to a more general FSet
.
For example, this can transform a formatter for YMD
to one for DateFieldSet
.
§Examples
use icu::calendar::Gregorian;
use icu::calendar::DateTime;
use icu::datetime::DateTimeFormatter;
use icu::datetime::fieldsets::{YMD, enums::DateFieldSet};
use icu::locale::locale;
use writeable::assert_writeable_eq;
let specific_formatter = DateTimeFormatter::try_new(
locale!("fr").into(),
YMD::medium(),
)
.unwrap();
// Test that the specific formatter works:
let datetime = DateTime::try_new_gregorian(2024, 12, 20, 14, 30, 0).unwrap();
assert_writeable_eq!(
specific_formatter.format_any_calendar(&datetime),
"20 déc. 2024"
);
// Make a more general formatter:
let general_formatter = specific_formatter.with_fset::<DateFieldSet>();
// Test that it still works:
assert_writeable_eq!(
general_formatter.format_any_calendar(&datetime),
"20 déc. 2024"
);
sourcepub fn calendar_kind(&self) -> AnyCalendarKind
pub fn calendar_kind(&self) -> AnyCalendarKind
Returns the calendar system used in this formatter.
§Examples
use icu::calendar::AnyCalendarKind;
use icu::calendar::Date;
use icu::datetime::fieldsets::YMD;
use icu::datetime::DateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;
let formatter = DateTimeFormatter::try_new(
locale!("th").into(),
YMD::long(),
)
.unwrap();
assert_writeable_eq!(
formatter.format_any_calendar(&Date::try_new_iso(2024, 12, 16).unwrap()),
"16 ธันวาคม 2567"
);
assert_eq!(formatter.calendar_kind(), AnyCalendarKind::Buddhist);
assert_eq!(formatter.calendar_kind().as_bcp47_string(), "buddhist");
Trait Implementations§
Auto Trait Implementations§
impl<FSet> Freeze for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as NamesContainer<YearNamesV1Marker, FieldLength>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::MonthNames as NamesContainer<MonthNamesV1Marker, (Month, FieldLength)>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::WeekdayNames as NamesContainer<WeekdayNamesV1Marker, (Weekday, FieldLength)>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as NamesContainer<DayPeriodNamesV1Marker, FieldLength>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as NamesContainer<TimeZoneEssentialsV1Marker, ()>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneLocations as NamesContainer<LocationsV1Marker, ()>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as NamesContainer<MetazoneGenericNamesLongV1Marker, ()>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as NamesContainer<MetazoneGenericNamesShortV1Marker, ()>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as NamesContainer<MetazoneSpecificNamesLongV1Marker, ()>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as NamesContainer<MetazoneSpecificNamesShortV1Marker, ()>>::Container: Freeze,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as NamesContainer<MetazonePeriodV1Marker, ()>>::Container: Freeze,
impl<FSet> RefUnwindSafe for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as NamesContainer<YearNamesV1Marker, FieldLength>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::MonthNames as NamesContainer<MonthNamesV1Marker, (Month, FieldLength)>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::WeekdayNames as NamesContainer<WeekdayNamesV1Marker, (Weekday, FieldLength)>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as NamesContainer<DayPeriodNamesV1Marker, FieldLength>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as NamesContainer<TimeZoneEssentialsV1Marker, ()>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneLocations as NamesContainer<LocationsV1Marker, ()>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as NamesContainer<MetazoneGenericNamesLongV1Marker, ()>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as NamesContainer<MetazoneGenericNamesShortV1Marker, ()>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as NamesContainer<MetazoneSpecificNamesLongV1Marker, ()>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as NamesContainer<MetazoneSpecificNamesShortV1Marker, ()>>::Container: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as NamesContainer<MetazonePeriodV1Marker, ()>>::Container: RefUnwindSafe,
FSet: RefUnwindSafe,
impl<FSet> Send for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as NamesContainer<YearNamesV1Marker, FieldLength>>::Container: Send,
<<FSet as DateTimeNamesMarker>::MonthNames as NamesContainer<MonthNamesV1Marker, (Month, FieldLength)>>::Container: Send,
<<FSet as DateTimeNamesMarker>::WeekdayNames as NamesContainer<WeekdayNamesV1Marker, (Weekday, FieldLength)>>::Container: Send,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as NamesContainer<DayPeriodNamesV1Marker, FieldLength>>::Container: Send,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as NamesContainer<TimeZoneEssentialsV1Marker, ()>>::Container: Send,
<<FSet as DateTimeNamesMarker>::ZoneLocations as NamesContainer<LocationsV1Marker, ()>>::Container: Send,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as NamesContainer<MetazoneGenericNamesLongV1Marker, ()>>::Container: Send,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as NamesContainer<MetazoneGenericNamesShortV1Marker, ()>>::Container: Send,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as NamesContainer<MetazoneSpecificNamesLongV1Marker, ()>>::Container: Send,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as NamesContainer<MetazoneSpecificNamesShortV1Marker, ()>>::Container: Send,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as NamesContainer<MetazonePeriodV1Marker, ()>>::Container: Send,
FSet: Send,
impl<FSet> Sync for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as NamesContainer<YearNamesV1Marker, FieldLength>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::MonthNames as NamesContainer<MonthNamesV1Marker, (Month, FieldLength)>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::WeekdayNames as NamesContainer<WeekdayNamesV1Marker, (Weekday, FieldLength)>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as NamesContainer<DayPeriodNamesV1Marker, FieldLength>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as NamesContainer<TimeZoneEssentialsV1Marker, ()>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::ZoneLocations as NamesContainer<LocationsV1Marker, ()>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as NamesContainer<MetazoneGenericNamesLongV1Marker, ()>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as NamesContainer<MetazoneGenericNamesShortV1Marker, ()>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as NamesContainer<MetazoneSpecificNamesLongV1Marker, ()>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as NamesContainer<MetazoneSpecificNamesShortV1Marker, ()>>::Container: Sync,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as NamesContainer<MetazonePeriodV1Marker, ()>>::Container: Sync,
FSet: Sync,
impl<FSet> Unpin for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as NamesContainer<YearNamesV1Marker, FieldLength>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::MonthNames as NamesContainer<MonthNamesV1Marker, (Month, FieldLength)>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::WeekdayNames as NamesContainer<WeekdayNamesV1Marker, (Weekday, FieldLength)>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as NamesContainer<DayPeriodNamesV1Marker, FieldLength>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as NamesContainer<TimeZoneEssentialsV1Marker, ()>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneLocations as NamesContainer<LocationsV1Marker, ()>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as NamesContainer<MetazoneGenericNamesLongV1Marker, ()>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as NamesContainer<MetazoneGenericNamesShortV1Marker, ()>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as NamesContainer<MetazoneSpecificNamesLongV1Marker, ()>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as NamesContainer<MetazoneSpecificNamesShortV1Marker, ()>>::Container: Unpin,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as NamesContainer<MetazonePeriodV1Marker, ()>>::Container: Unpin,
FSet: Unpin,
impl<FSet> UnwindSafe for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as NamesContainer<YearNamesV1Marker, FieldLength>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::MonthNames as NamesContainer<MonthNamesV1Marker, (Month, FieldLength)>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::WeekdayNames as NamesContainer<WeekdayNamesV1Marker, (Weekday, FieldLength)>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as NamesContainer<DayPeriodNamesV1Marker, FieldLength>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as NamesContainer<TimeZoneEssentialsV1Marker, ()>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneLocations as NamesContainer<LocationsV1Marker, ()>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as NamesContainer<MetazoneGenericNamesLongV1Marker, ()>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as NamesContainer<MetazoneGenericNamesShortV1Marker, ()>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as NamesContainer<MetazoneSpecificNamesLongV1Marker, ()>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as NamesContainer<MetazoneSpecificNamesShortV1Marker, ()>>::Container: UnwindSafe,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as NamesContainer<MetazonePeriodV1Marker, ()>>::Container: UnwindSafe,
FSet: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more