Struct icu_datetime::time_zone::TimeZoneFormatter
source · pub struct TimeZoneFormatter {
pub(crate) locale: DataLocale,
pub(crate) data_payloads: TimeZoneDataPayloads,
pub(crate) format_units: SmallVec<[TimeZoneFormatterUnit; 3]>,
pub(crate) fallback_unit: FallbackTimeZoneFormatterUnit,
}
Expand description
TimeZoneFormatter
is available for users who need to separately control the formatting of time
zones. Note: most users might prefer ZonedDateTimeFormatter
, which includes default time zone
formatting according to the calendar.
TimeZoneFormatter
uses data from the data provider and the selected locale
to format time zones into that locale.
The various time-zone configs specified in UTS-35 require different sets of data for
formatting. As such,TimeZoneFormatter
will pull in only the resources needed to format the
config that it is given upon construction.
For that reason, one should think of the process of formatting a time zone in two steps:
first, a computationally heavy construction of TimeZoneFormatter
, and then fast formatting
of the time-zone data using the instance.
CustomTimeZone
can be used as formatting input.
§Examples
Here, we configure the TimeZoneFormatter
to first look for time zone formatting symbol
data for generic_non_location_short
, and if it does not exist, to subsequently check
for generic_non_location_long
data.
use icu::calendar::DateTime;
use icu::timezone::{CustomTimeZone, MetazoneCalculator, TimeZoneIdMapper};
use icu::datetime::{DateTimeError, time_zone::TimeZoneFormatter};
use icu::locid::locale;
use tinystr::tinystr;
use writeable::assert_writeable_eq;
// Set up the time zone. Note: the inputs here are
// 1. The GMT offset
// 2. The IANA time zone ID
// 3. A datetime (for metazone resolution)
// 4. Note: we do not need the zone variant because of `load_generic_*()`
// Set up the Metazone calculator, time zone ID mapper,
// and the DateTime to use in calculation
let mzc = MetazoneCalculator::new();
let mapper = TimeZoneIdMapper::new();
let datetime = DateTime::try_new_iso_datetime(2022, 8, 29, 0, 0, 0)
.unwrap();
// Set up the formatter
let mut tzf = TimeZoneFormatter::try_new(
&locale!("en").into(),
Default::default(),
)
.unwrap();
tzf.include_generic_non_location_short()?
.include_generic_non_location_long()?;
// "uschi" - has metazone symbol data for generic_non_location_short
let mut time_zone = "-0600".parse::<CustomTimeZone>().unwrap();
time_zone.time_zone_id = mapper.as_borrowed().iana_to_bcp47("America/Chicago");
time_zone.maybe_calculate_metazone(&mzc, &datetime);
assert_writeable_eq!(
tzf.format(&time_zone),
"CT"
);
// "ushnl" - has time zone override symbol data for generic_non_location_short
let mut time_zone = "-1000".parse::<CustomTimeZone>().unwrap();
time_zone.time_zone_id = Some(tinystr!(8, "ushnl").into());
time_zone.maybe_calculate_metazone(&mzc, &datetime);
assert_writeable_eq!(
tzf.format(&time_zone),
"HST"
);
// "frpar" - does not have symbol data for generic_non_location_short, so falls
// back to generic_non_location_long
let mut time_zone = "+0100".parse::<CustomTimeZone>().unwrap();
time_zone.time_zone_id = Some(tinystr!(8, "frpar").into());
time_zone.maybe_calculate_metazone(&mzc, &datetime);
assert_writeable_eq!(
tzf.format(&time_zone),
"Central European Time"
);
// GMT with offset - used when metazone is not available
let mut time_zone = "+0530".parse::<CustomTimeZone>().unwrap();
assert_writeable_eq!(
tzf.format(&time_zone),
"GMT+05:30"
);
Fields§
§locale: DataLocale
§data_payloads: TimeZoneDataPayloads
§format_units: SmallVec<[TimeZoneFormatterUnit; 3]>
§fallback_unit: FallbackTimeZoneFormatterUnit
Implementations§
source§impl TimeZoneFormatter
impl TimeZoneFormatter
sourcepub(crate) fn try_new_for_pattern<ZP>(
zone_provider: &ZP,
locale: &DataLocale,
patterns: DataPayload<PatternPluralsFromPatternsV1Marker>,
options: &TimeZoneFormatterOptions,
) -> Result<Self, DateTimeError>
pub(crate) fn try_new_for_pattern<ZP>( zone_provider: &ZP, locale: &DataLocale, patterns: DataPayload<PatternPluralsFromPatternsV1Marker>, options: &TimeZoneFormatterOptions, ) -> Result<Self, DateTimeError>
Constructor that selectively loads data based on what is required to format the given pattern into the given locale.
sourcepub fn try_new(
locale: &DataLocale,
options: TimeZoneFormatterOptions,
) -> Result<Self, DateTimeError>
pub fn try_new( locale: &DataLocale, options: TimeZoneFormatterOptions, ) -> Result<Self, DateTimeError>
Creates a new TimeZoneFormatter
with a GMT or ISO format using compiled data.
To enable other time zone styles, use one of the with
(compiled data) or load
(runtime
data provider) methods.
✨ Enabled with the compiled_data
Cargo feature.
§Examples
Default format is Localized GMT:
use icu::datetime::time_zone::{
TimeZoneFormatter, TimeZoneFormatterOptions,
};
use icu::locid::locale;
use icu::timezone::CustomTimeZone;
use writeable::assert_writeable_eq;
let tzf = TimeZoneFormatter::try_new(
&locale!("es").into(),
TimeZoneFormatterOptions::default(),
)
.unwrap();
let time_zone = "-0700".parse::<CustomTimeZone>().unwrap();
assert_writeable_eq!(tzf.format(&time_zone), "GMT-07:00");
✨ Enabled with the compiled_data
Cargo feature.
sourcepub fn try_new_with_any_provider(
provider: &(impl AnyProvider + ?Sized),
locale: &DataLocale,
options: TimeZoneFormatterOptions,
) -> Result<Self, DateTimeError>
pub fn try_new_with_any_provider( provider: &(impl AnyProvider + ?Sized), locale: &DataLocale, options: TimeZoneFormatterOptions, ) -> Result<Self, DateTimeError>
A version of [Self :: try_new
] that uses custom data provided by an AnyProvider
.
sourcepub fn try_new_unstable<P>(
provider: &P,
locale: &DataLocale,
options: TimeZoneFormatterOptions,
) -> Result<Self, DateTimeError>
pub fn try_new_unstable<P>( provider: &P, locale: &DataLocale, options: TimeZoneFormatterOptions, ) -> Result<Self, DateTimeError>
A version of Self::try_new
that uses custom data provided by a DataProvider
.
sourcepub fn include_generic_non_location_long(
&mut self,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn include_generic_non_location_long( &mut self, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Include generic-non-location-long format for timezone from compiled data. For example, “Pacific Time”.
sourcepub fn include_generic_non_location_short(
&mut self,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn include_generic_non_location_short( &mut self, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Include generic-non-location-short format for timezone from compiled data. For example, “PT”.
sourcepub fn include_specific_non_location_long(
&mut self,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn include_specific_non_location_long( &mut self, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Include specific-non-location-long format for timezone from compiled data. For example, “Pacific Standard Time”.
sourcepub fn include_specific_non_location_short(
&mut self,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn include_specific_non_location_short( &mut self, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Include specific-non-location-short format for timezone from compiled data. For example, “PDT”.
sourcepub fn include_generic_location_format(
&mut self,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn include_generic_location_format( &mut self, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Include generic-location format for timezone from compiled data. For example, “Los Angeles Time”.
sourcepub fn include_localized_gmt_format(
&mut self,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn include_localized_gmt_format( &mut self, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Include localized-GMT format for timezone. For example, “GMT-07:00”.
sourcepub fn include_iso_8601_format(
&mut self,
format: IsoFormat,
minutes: IsoMinutes,
seconds: IsoSeconds,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn include_iso_8601_format( &mut self, format: IsoFormat, minutes: IsoMinutes, seconds: IsoSeconds, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Include ISO-8601 format for timezone. For example, “-07:00”.
sourcepub fn load_generic_non_location_long<ZP>(
&mut self,
zone_provider: &ZP,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn load_generic_non_location_long<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Load generic-non-location-long format for timezone. For example, “Pacific Time”.
sourcepub fn load_generic_non_location_short<ZP>(
&mut self,
zone_provider: &ZP,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn load_generic_non_location_short<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Load generic-non-location-short format for timezone. For example, “PT”.
sourcepub fn load_specific_non_location_long<ZP>(
&mut self,
zone_provider: &ZP,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn load_specific_non_location_long<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Load specific-non-location-long format for timezone. For example, “Pacific Standard Time”.
sourcepub fn load_specific_non_location_short<ZP>(
&mut self,
zone_provider: &ZP,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn load_specific_non_location_short<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Load specific-non-location-short format for timezone. For example, “PDT”.
sourcepub fn load_generic_location_format<ZP>(
&mut self,
zone_provider: &ZP,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
pub fn load_generic_location_format<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Load generic-location format for timezone. For example, “Los Angeles Time”.
sourcefn load_exemplar_city_format<ZP>(
&mut self,
zone_provider: &ZP,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
fn load_exemplar_city_format<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
Load exemplar-city format for timezone. For example, “Los Angeles”.
sourcepub fn load_localized_gmt_format(
&mut self,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
👎Deprecated since 1.3.0: renamed to include_localized_gmt_format
pub fn load_localized_gmt_format( &mut self, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
include_localized_gmt_format
sourcepub fn load_iso_8601_format(
&mut self,
format: IsoFormat,
minutes: IsoMinutes,
seconds: IsoSeconds,
) -> Result<&mut TimeZoneFormatter, DateTimeError>
👎Deprecated since 1.3.0: renamed to include_iso_8601_format
pub fn load_iso_8601_format( &mut self, format: IsoFormat, minutes: IsoMinutes, seconds: IsoSeconds, ) -> Result<&mut TimeZoneFormatter, DateTimeError>
include_iso_8601_format
sourcepub fn format<'l, T>(&'l self, value: &'l T) -> FormattedTimeZone<'l, T>where
T: TimeZoneInput,
pub fn format<'l, T>(&'l self, value: &'l T) -> FormattedTimeZone<'l, T>where
T: TimeZoneInput,
Takes a TimeZoneInput
implementer and returns an instance of a FormattedTimeZone
that contains all information necessary to display a formatted time zone and operate on it.
§Examples
use icu::datetime::time_zone::{
TimeZoneFormatter, TimeZoneFormatterOptions,
};
use icu::locid::locale;
use icu::timezone::CustomTimeZone;
use writeable::assert_writeable_eq;
let tzf = TimeZoneFormatter::try_new(
&locale!("en").into(),
TimeZoneFormatterOptions::default(),
)
.expect("Failed to create TimeZoneFormatter");
let time_zone = CustomTimeZone::utc();
assert_writeable_eq!(tzf.format(&time_zone), "GMT");
sourcepub fn format_to_string(&self, value: &impl TimeZoneInput) -> String
pub fn format_to_string(&self, value: &impl TimeZoneInput) -> String
Takes a TimeZoneInput
implementer and returns a string with the formatted value.
Trait Implementations§
Auto Trait Implementations§
impl Freeze for TimeZoneFormatter
impl RefUnwindSafe for TimeZoneFormatter
impl !Send for TimeZoneFormatter
impl !Sync for TimeZoneFormatter
impl Unpin for TimeZoneFormatter
impl UnwindSafe for TimeZoneFormatter
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