Struct icu::datetime::DateTimeFormatter
source · pub struct DateTimeFormatter<FSet>where
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 512 bytes on the stable toolchain at release date.
Implementations§
source§impl<FSet> DateTimeFormatter<FSet>where
FSet: DateTimeMarkers + GetField<CompositeFieldSet>,
<FSet as DateTimeMarkers>::D: DateDataMarkers,
<FSet as DateTimeMarkers>::T: TimeMarkers,
<FSet as DateTimeMarkers>::Z: ZoneMarkers,
impl<FSet> DateTimeFormatter<FSet>where
FSet: DateTimeMarkers + GetField<CompositeFieldSet>,
<FSet as DateTimeMarkers>::D: DateDataMarkers,
<FSet as DateTimeMarkers>::T: TimeMarkers,
<FSet as DateTimeMarkers>::Z: ZoneMarkers,
sourcepub fn try_new(
locale: &DataLocale,
field_set: FSet,
) -> Result<DateTimeFormatter<FSet>, PatternLoadError>where
Baked: AllAnyCalendarFormattingDataMarkers<FSet>,
pub fn try_new(
locale: &DataLocale,
field_set: FSet,
) -> Result<DateTimeFormatter<FSet>, PatternLoadError>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::fieldset::YMD;
use icu::datetime::DateTimeFormatter;
use icu::locale::locale;
use std::str::FromStr;
use writeable::assert_try_writeable_eq;
let locale = locale!("en-u-ca-hebrew");
let formatter =
DateTimeFormatter::try_new(&locale.into(), YMD::medium()).unwrap();
let datetime = DateTime::try_new_iso(2024, 5, 8, 0, 0, 0).unwrap();
assert_try_writeable_eq!(
formatter.convert_and_format(&datetime),
"30 Nisan 5784"
);
sourcepub fn try_new_with_any_provider<P>(
provider: &P,
locale: &DataLocale,
field_set: FSet,
) -> Result<DateTimeFormatter<FSet>, PatternLoadError>where
P: AnyProvider + ?Sized,
pub fn try_new_with_any_provider<P>(
provider: &P,
locale: &DataLocale,
field_set: FSet,
) -> Result<DateTimeFormatter<FSet>, PatternLoadError>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,
locale: &DataLocale,
field_set: FSet,
) -> Result<DateTimeFormatter<FSet>, PatternLoadError>where
P: BufferProvider + ?Sized,
pub fn try_new_with_buffer_provider<P>(
provider: &P,
locale: &DataLocale,
field_set: FSet,
) -> Result<DateTimeFormatter<FSet>, PatternLoadError>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,
locale: &DataLocale,
field_set: FSet,
) -> Result<DateTimeFormatter<FSet>, PatternLoadError>
pub fn try_new_unstable<P>( provider: &P, locale: &DataLocale, field_set: FSet, ) -> Result<DateTimeFormatter<FSet>, PatternLoadError>
A version of Self::try_new
that uses custom data provided by a DataProvider
.
source§impl<FSet> DateTimeFormatter<FSet>where
FSet: DateTimeMarkers,
<FSet as DateTimeMarkers>::D: DateInputMarkers,
<FSet as DateTimeMarkers>::T: TimeMarkers,
<FSet as DateTimeMarkers>::Z: ZoneMarkers,
impl<FSet> DateTimeFormatter<FSet>where
FSet: DateTimeMarkers,
<FSet as DateTimeMarkers>::D: DateInputMarkers,
<FSet as DateTimeMarkers>::T: TimeMarkers,
<FSet as DateTimeMarkers>::Z: ZoneMarkers,
sourcepub fn strict_format<I>(
&self,
datetime: &I,
) -> Result<FormattedNeoDateTime<'_>, MismatchedCalendarError>
pub fn strict_format<I>( &self, datetime: &I, ) -> Result<FormattedNeoDateTime<'_>, 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::fieldset::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.strict_format(&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::fieldset::YMD;
use icu::locale::locale;
let formatter = DateTimeFormatter::try_new(
&locale!("es-MX").into(),
NeoSkeletonLength::Long.into(),
)
.unwrap();
// the trait `GetField<AnyCalendarKind>`
// is not implemented for `icu::icu_calendar::Time`
formatter.strict_format(&Time::try_new(0, 0, 0, 0).unwrap());
sourcepub fn convert_and_format<'a, I>(
&'a self,
datetime: &I,
) -> FormattedNeoDateTime<'a>where
I: ConvertCalendar + ?Sized,
<I as ConvertCalendar>::Converted<'a>: Sized + AllInputMarkers<FSet>,
pub fn convert_and_format<'a, I>(
&'a self,
datetime: &I,
) -> FormattedNeoDateTime<'a>where
I: ConvertCalendar + ?Sized,
<I as ConvertCalendar>::Converted<'a>: Sized + AllInputMarkers<FSet>,
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::fieldset::YMD;
use icu::datetime::DateTimeFormatter;
use icu::datetime::MismatchedCalendarError;
use icu::locale::locale;
use writeable::assert_try_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_try_writeable_eq!(
formatter.convert_and_format(&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::fieldset::YMD;
use icu::locale::locale;
let formatter = DateTimeFormatter::try_new(
&locale!("es-MX").into(),
NeoSkeletonLength::Long.into(),
)
.unwrap();
// the trait `GetField<AnyCalendarKind>`
// is not implemented for `icu::icu_calendar::Time`
formatter.convert_and_format(&Time::try_new(0, 0, 0, 0).unwrap());
source§impl<FSet> DateTimeFormatter<FSet>where
FSet: DateTimeMarkers,
impl<FSet> DateTimeFormatter<FSet>where
FSet: DateTimeMarkers,
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::fieldset::YMD;
use icu::datetime::DateTimeFormatter;
use icu::locale::locale;
use writeable::assert_try_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_try_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::fieldset::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 { .. })));
Trait Implementations§
Auto Trait Implementations§
impl<FSet> Freeze for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as DateTimeNamesHolderTrait<YearNamesV1Marker>>::Container<FieldLength>: Freeze,
<<FSet as DateTimeNamesMarker>::MonthNames as DateTimeNamesHolderTrait<MonthNamesV1Marker>>::Container<(Month, FieldLength)>: Freeze,
<<FSet as DateTimeNamesMarker>::WeekdayNames as DateTimeNamesHolderTrait<WeekdayNamesV1Marker>>::Container<(Weekday, FieldLength)>: Freeze,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as DateTimeNamesHolderTrait<DayPeriodNamesV1Marker>>::Container<FieldLength>: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as DateTimeNamesHolderTrait<TimeZoneEssentialsV1Marker>>::Container<()>: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneLocations as DateTimeNamesHolderTrait<LocationsV1Marker>>::Container<()>: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as DateTimeNamesHolderTrait<MetazoneGenericNamesLongV1Marker>>::Container<()>: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as DateTimeNamesHolderTrait<MetazoneGenericNamesShortV1Marker>>::Container<()>: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as DateTimeNamesHolderTrait<MetazoneSpecificNamesLongV1Marker>>::Container<()>: Freeze,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as DateTimeNamesHolderTrait<MetazoneSpecificNamesShortV1Marker>>::Container<()>: Freeze,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as DateTimeNamesHolderTrait<MetazonePeriodV1Marker>>::Container<()>: Freeze,
impl<FSet> RefUnwindSafe for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as DateTimeNamesHolderTrait<YearNamesV1Marker>>::Container<FieldLength>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::MonthNames as DateTimeNamesHolderTrait<MonthNamesV1Marker>>::Container<(Month, FieldLength)>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::WeekdayNames as DateTimeNamesHolderTrait<WeekdayNamesV1Marker>>::Container<(Weekday, FieldLength)>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as DateTimeNamesHolderTrait<DayPeriodNamesV1Marker>>::Container<FieldLength>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as DateTimeNamesHolderTrait<TimeZoneEssentialsV1Marker>>::Container<()>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneLocations as DateTimeNamesHolderTrait<LocationsV1Marker>>::Container<()>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as DateTimeNamesHolderTrait<MetazoneGenericNamesLongV1Marker>>::Container<()>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as DateTimeNamesHolderTrait<MetazoneGenericNamesShortV1Marker>>::Container<()>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as DateTimeNamesHolderTrait<MetazoneSpecificNamesLongV1Marker>>::Container<()>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as DateTimeNamesHolderTrait<MetazoneSpecificNamesShortV1Marker>>::Container<()>: RefUnwindSafe,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as DateTimeNamesHolderTrait<MetazonePeriodV1Marker>>::Container<()>: RefUnwindSafe,
FSet: RefUnwindSafe,
impl<FSet> Send for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as DateTimeNamesHolderTrait<YearNamesV1Marker>>::Container<FieldLength>: Send,
<<FSet as DateTimeNamesMarker>::MonthNames as DateTimeNamesHolderTrait<MonthNamesV1Marker>>::Container<(Month, FieldLength)>: Send,
<<FSet as DateTimeNamesMarker>::WeekdayNames as DateTimeNamesHolderTrait<WeekdayNamesV1Marker>>::Container<(Weekday, FieldLength)>: Send,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as DateTimeNamesHolderTrait<DayPeriodNamesV1Marker>>::Container<FieldLength>: Send,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as DateTimeNamesHolderTrait<TimeZoneEssentialsV1Marker>>::Container<()>: Send,
<<FSet as DateTimeNamesMarker>::ZoneLocations as DateTimeNamesHolderTrait<LocationsV1Marker>>::Container<()>: Send,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as DateTimeNamesHolderTrait<MetazoneGenericNamesLongV1Marker>>::Container<()>: Send,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as DateTimeNamesHolderTrait<MetazoneGenericNamesShortV1Marker>>::Container<()>: Send,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as DateTimeNamesHolderTrait<MetazoneSpecificNamesLongV1Marker>>::Container<()>: Send,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as DateTimeNamesHolderTrait<MetazoneSpecificNamesShortV1Marker>>::Container<()>: Send,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as DateTimeNamesHolderTrait<MetazonePeriodV1Marker>>::Container<()>: Send,
FSet: Send,
impl<FSet> Sync for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as DateTimeNamesHolderTrait<YearNamesV1Marker>>::Container<FieldLength>: Sync,
<<FSet as DateTimeNamesMarker>::MonthNames as DateTimeNamesHolderTrait<MonthNamesV1Marker>>::Container<(Month, FieldLength)>: Sync,
<<FSet as DateTimeNamesMarker>::WeekdayNames as DateTimeNamesHolderTrait<WeekdayNamesV1Marker>>::Container<(Weekday, FieldLength)>: Sync,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as DateTimeNamesHolderTrait<DayPeriodNamesV1Marker>>::Container<FieldLength>: Sync,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as DateTimeNamesHolderTrait<TimeZoneEssentialsV1Marker>>::Container<()>: Sync,
<<FSet as DateTimeNamesMarker>::ZoneLocations as DateTimeNamesHolderTrait<LocationsV1Marker>>::Container<()>: Sync,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as DateTimeNamesHolderTrait<MetazoneGenericNamesLongV1Marker>>::Container<()>: Sync,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as DateTimeNamesHolderTrait<MetazoneGenericNamesShortV1Marker>>::Container<()>: Sync,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as DateTimeNamesHolderTrait<MetazoneSpecificNamesLongV1Marker>>::Container<()>: Sync,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as DateTimeNamesHolderTrait<MetazoneSpecificNamesShortV1Marker>>::Container<()>: Sync,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as DateTimeNamesHolderTrait<MetazonePeriodV1Marker>>::Container<()>: Sync,
FSet: Sync,
impl<FSet> Unpin for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as DateTimeNamesHolderTrait<YearNamesV1Marker>>::Container<FieldLength>: Unpin,
<<FSet as DateTimeNamesMarker>::MonthNames as DateTimeNamesHolderTrait<MonthNamesV1Marker>>::Container<(Month, FieldLength)>: Unpin,
<<FSet as DateTimeNamesMarker>::WeekdayNames as DateTimeNamesHolderTrait<WeekdayNamesV1Marker>>::Container<(Weekday, FieldLength)>: Unpin,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as DateTimeNamesHolderTrait<DayPeriodNamesV1Marker>>::Container<FieldLength>: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as DateTimeNamesHolderTrait<TimeZoneEssentialsV1Marker>>::Container<()>: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneLocations as DateTimeNamesHolderTrait<LocationsV1Marker>>::Container<()>: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as DateTimeNamesHolderTrait<MetazoneGenericNamesLongV1Marker>>::Container<()>: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as DateTimeNamesHolderTrait<MetazoneGenericNamesShortV1Marker>>::Container<()>: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as DateTimeNamesHolderTrait<MetazoneSpecificNamesLongV1Marker>>::Container<()>: Unpin,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as DateTimeNamesHolderTrait<MetazoneSpecificNamesShortV1Marker>>::Container<()>: Unpin,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as DateTimeNamesHolderTrait<MetazonePeriodV1Marker>>::Container<()>: Unpin,
FSet: Unpin,
impl<FSet> UnwindSafe for DateTimeFormatter<FSet>where
<<FSet as DateTimeNamesMarker>::YearNames as DateTimeNamesHolderTrait<YearNamesV1Marker>>::Container<FieldLength>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::MonthNames as DateTimeNamesHolderTrait<MonthNamesV1Marker>>::Container<(Month, FieldLength)>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::WeekdayNames as DateTimeNamesHolderTrait<WeekdayNamesV1Marker>>::Container<(Weekday, FieldLength)>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::DayPeriodNames as DateTimeNamesHolderTrait<DayPeriodNamesV1Marker>>::Container<FieldLength>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneEssentials as DateTimeNamesHolderTrait<TimeZoneEssentialsV1Marker>>::Container<()>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneLocations as DateTimeNamesHolderTrait<LocationsV1Marker>>::Container<()>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneGenericLong as DateTimeNamesHolderTrait<MetazoneGenericNamesLongV1Marker>>::Container<()>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneGenericShort as DateTimeNamesHolderTrait<MetazoneGenericNamesShortV1Marker>>::Container<()>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneSpecificLong as DateTimeNamesHolderTrait<MetazoneSpecificNamesLongV1Marker>>::Container<()>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::ZoneSpecificShort as DateTimeNamesHolderTrait<MetazoneSpecificNamesShortV1Marker>>::Container<()>: UnwindSafe,
<<FSet as DateTimeNamesMarker>::MetazoneLookup as DateTimeNamesHolderTrait<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