Struct icu_datetime::ZonedDateTimeFormatter
source · pub struct ZonedDateTimeFormatter(ZonedDateTimeFormatter, AnyCalendar);
Expand description
ZonedDateTimeFormatter
is a formatter capable of formatting
date/times with time zones from any calendar, selected at runtime. For the difference between this and TypedZonedDateTimeFormatter
,
please read the crate root docs.
This is equivalently the composition of
DateTimeFormatter
and TimeZoneFormatter
.
ZonedDateTimeFormatter
uses data from the [data provider]s, the selected DataLocale
, and the
provided pattern to collect all data necessary to format a datetime with time zones into that locale.
The various pattern symbols specified in UTS-35 require different sets of data for formatting.
As such, TimeZoneFormatter
will pull in only the resources it needs to format that pattern
that is derived from the provided DateTimeFormatterOptions
.
For that reason, one should think of the process of formatting a zoned datetime in two steps:
first, a computationally heavy construction of ZonedDateTimeFormatter
, and then fast formatting
of the data using the instance.
📏 This item has a stack size of 6248 bytes on the stable toolchain at release date.
§Examples
Using a GMT time zone:
use icu::calendar::DateTime;
use icu::datetime::{options::length, ZonedDateTimeFormatter};
use icu::locid::locale;
use icu::timezone::CustomTimeZone;
use writeable::assert_writeable_eq;
let options = length::Bag::from_date_time_style(
length::Date::Medium,
length::Time::Long,
);
let zdtf = ZonedDateTimeFormatter::try_new(
&locale!("en").into(),
options.into(),
Default::default(),
)
.expect("Failed to create ZonedDateTimeFormatter 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();
let time_zone = CustomTimeZone::utc();
assert_writeable_eq!(
zdtf.format(&any_datetime, &time_zone)
.expect("Calendars should match"),
"Sep 1, 2020, 12:34:28 PM GMT"
);
Using a non-GMT time zone, specified by id:
use icu::calendar::DateTime;
use icu::datetime::{options::length, ZonedDateTimeFormatter};
use icu::locid::locale;
use icu::timezone::{CustomTimeZone, GmtOffset, MetazoneCalculator, ZoneVariant};
use tinystr::TinyAsciiStr;
use writeable::assert_writeable_eq;
let options = length::Bag::from_date_time_style(
length::Date::Medium,
length::Time::Full,
);
let zdtf = ZonedDateTimeFormatter::try_new(
&locale!("en").into(),
options.into(),
Default::default(),
)
.expect("Failed to create ZonedDateTimeFormatter instance.");
// Create a DateTime at September 1, 2020 at 12:34:28 PM
let datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
.expect("Failed to construct DateTime.");
let any_datetime = datetime.to_any();
// Create a time zone for America/Chicago at GMT-6:
let mut time_zone = CustomTimeZone::new_empty();
time_zone.gmt_offset = "-06:00".parse::<GmtOffset>().ok();
time_zone.time_zone_id = "uschi".parse::<TinyAsciiStr<8>>().ok().map(Into::into);
time_zone.zone_variant = Some(ZoneVariant::daylight());
// Compute the metazone during `datetime` (September 1, 2020 at 12:34:28 PM):
let mzc = MetazoneCalculator::new();
time_zone.maybe_calculate_metazone(&mzc, &datetime);
assert_writeable_eq!(
zdtf
.format(&any_datetime, &time_zone)
.expect("Calendars should match"),
"Sep 1, 2020, 12:34:28 PM Central Daylight Time");
Tuple Fields§
§0: ZonedDateTimeFormatter
§1: AnyCalendar
Implementations§
source§impl ZonedDateTimeFormatter
impl ZonedDateTimeFormatter
sourcepub fn try_new(
locale: &DataLocale,
date_time_format_options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions,
) -> Result<Self, DateTimeError>
pub fn try_new( locale: &DataLocale, date_time_format_options: DateTimeFormatterOptions, time_zone_format_options: TimeZoneFormatterOptions, ) -> Result<Self, DateTimeError>
Constructor that takes a selected DataLocale
and a list of DateTimeFormatterOptions
and uses compiled data.
It collects all data necessary to format zoned datetime values into the given locale.
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;
use icu::datetime::time_zone::TimeZoneFormatterOptions;
use icu::datetime::ZonedDateTimeFormatter;
use icu::locid::locale;
use icu::timezone::CustomTimeZone;
use std::str::FromStr;
use writeable::assert_writeable_eq;
let options = length::Bag::from_date_time_style(
length::Date::Medium,
length::Time::Long,
);
let locale = locale!("en-u-ca-gregory").into();
let zdtf = ZonedDateTimeFormatter::try_new(
&locale,
options.into(),
TimeZoneFormatterOptions::default(),
)
.expect("Construction should succeed");
let datetime =
DateTime::try_new_iso_datetime(2021, 04, 08, 16, 12, 37).unwrap();
let time_zone = CustomTimeZone::from_str("-07:00").unwrap();
let any_datetime = datetime.to_any();
assert_writeable_eq!(
zdtf.format(&any_datetime, &time_zone).unwrap(),
"Apr 8, 2021, 4:12:37 PM GMT-07:00"
);
sourcepub fn try_new_unstable<P>(
provider: &P,
locale: &DataLocale,
date_time_format_options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions,
) -> Result<Self, DateTimeError>where
P: DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<TimeZoneFormatsV1Marker> + DataProvider<ExemplarCitiesV1Marker> + DataProvider<MetazoneGenericNamesLongV1Marker> + DataProvider<MetazoneGenericNamesShortV1Marker> + DataProvider<MetazoneSpecificNamesLongV1Marker> + DataProvider<MetazoneSpecificNamesShortV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<ChineseCacheV1Marker> + DataProvider<ChineseDateLengthsV1Marker> + DataProvider<ChineseDateSymbolsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<DangiCacheV1Marker> + 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<IslamicObservationalCacheV1Marker> + DataProvider<IslamicUmmAlQuraCacheV1Marker> + 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,
date_time_format_options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions,
) -> Result<Self, DateTimeError>where
P: DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<TimeZoneFormatsV1Marker> + DataProvider<ExemplarCitiesV1Marker> + DataProvider<MetazoneGenericNamesLongV1Marker> + DataProvider<MetazoneGenericNamesShortV1Marker> + DataProvider<MetazoneSpecificNamesLongV1Marker> + DataProvider<MetazoneSpecificNamesShortV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<ChineseCacheV1Marker> + DataProvider<ChineseDateLengthsV1Marker> + DataProvider<ChineseDateSymbolsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<DangiCacheV1Marker> + 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<IslamicObservationalCacheV1Marker> + DataProvider<IslamicUmmAlQuraCacheV1Marker> + 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_new_with_any_provider(
provider: &impl AnyProvider,
locale: &DataLocale,
options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions,
) -> Result<Self, DateTimeError>
pub fn try_new_with_any_provider( provider: &impl AnyProvider, locale: &DataLocale, options: DateTimeFormatterOptions, time_zone_format_options: TimeZoneFormatterOptions, ) -> Result<Self, DateTimeError>
A version of Self::try_new
that uses custom data provided by an AnyProvider
.
sourcepub fn format<'l>(
&'l self,
date: &impl DateTimeInput<Calendar = AnyCalendar>,
time_zone: &impl TimeZoneInput,
) -> Result<FormattedZonedDateTime<'l>, DateTimeError>
pub fn format<'l>( &'l self, date: &impl DateTimeInput<Calendar = AnyCalendar>, time_zone: &impl TimeZoneInput, ) -> Result<FormattedZonedDateTime<'l>, DateTimeError>
Takes a DateTimeInput
and a TimeZoneInput
and returns an instance of a FormattedZonedDateTime
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,
date: &impl DateTimeInput<Calendar = AnyCalendar>,
time_zone: &impl TimeZoneInput,
) -> Result<String, DateTimeError>
pub fn format_to_string( &self, date: &impl DateTimeInput<Calendar = AnyCalendar>, time_zone: &impl TimeZoneInput, ) -> Result<String, DateTimeError>
Takes a DateTimeInput
and a TimeZoneInput
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.
sourcefn convert_if_necessary(
&self,
value: &impl DateTimeInput<Calendar = AnyCalendar>,
) -> Result<Option<ExtractedDateTimeInput>, DateTimeError>
fn convert_if_necessary( &self, value: &impl DateTimeInput<Calendar = AnyCalendar>, ) -> Result<Option<ExtractedDateTimeInput>, DateTimeError>
Converts a date to the correct calendar if necessary
Returns Err
if the date is not ISO or compatible with the current calendar, returns Ok(None)
if the date is compatible with the current calendar and doesn’t need conversion
Trait Implementations§
Auto Trait Implementations§
impl Freeze for ZonedDateTimeFormatter
impl RefUnwindSafe for ZonedDateTimeFormatter
impl !Send for ZonedDateTimeFormatter
impl !Sync for ZonedDateTimeFormatter
impl Unpin for ZonedDateTimeFormatter
impl UnwindSafe for ZonedDateTimeFormatter
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