Struct icu_datetime::time_zone::TimeZoneFormatter

pub struct TimeZoneFormatter {
    pub(crate) locale: DataLocale,
    pub(crate) data_payloads: TimeZoneDataPayloads,
    pub(crate) format_units: SmallVec<[TimeZoneFormatterUnit; 3]>,
    pub(crate) fallback_unit: FallbackTimeZoneFormatterUnit,
}

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

impl TimeZoneFormatter

pub(crate) fn try_new_for_pattern<ZP>( zone_provider: &ZP, locale: &DataLocale, patterns: DataPayload<PatternPluralsFromPatternsV1Marker>, options: &TimeZoneFormatterOptions, ) -> Result<Self, DateTimeError>

where ZP: DataProvider<TimeZoneFormatsV1Marker> + DataProvider<ExemplarCitiesV1Marker> + DataProvider<MetazoneGenericNamesLongV1Marker> + DataProvider<MetazoneGenericNamesShortV1Marker> + DataProvider<MetazoneSpecificNamesLongV1Marker> + DataProvider<MetazoneSpecificNamesShortV1Marker> + ?Sized,

Constructor that selectively loads data based on what is required to format the given pattern into the given locale.

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.

📚 Help choosing a constructor

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.

📚 Help choosing a constructor

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.

📚 Help choosing a constructor

pub fn try_new_unstable<P>( provider: &P, locale: &DataLocale, options: TimeZoneFormatterOptions, ) -> Result<Self, DateTimeError>

where P: DataProvider<TimeZoneFormatsV1Marker> + ?Sized,

A version of Self::try_new that uses custom data provided by a DataProvider.

📚 Help choosing a constructor

⚠️ The bounds on provider may change over time, including in SemVer minor releases.

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”.

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”.

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”.

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”.

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”.

pub fn include_localized_gmt_format( &mut self, ) -> Result<&mut TimeZoneFormatter, DateTimeError>

Include localized-GMT format for timezone. For example, “GMT-07:00”.

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”.

pub fn load_generic_non_location_long<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>

where ZP: DataProvider<MetazoneGenericNamesLongV1Marker> + ?Sized,

Load generic-non-location-long format for timezone. For example, “Pacific Time”.

pub fn load_generic_non_location_short<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>

where ZP: DataProvider<MetazoneGenericNamesShortV1Marker> + ?Sized,

Load generic-non-location-short format for timezone. For example, “PT”.

pub fn load_specific_non_location_long<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>

where ZP: DataProvider<MetazoneSpecificNamesLongV1Marker> + ?Sized,

Load specific-non-location-long format for timezone. For example, “Pacific Standard Time”.

pub fn load_specific_non_location_short<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>

where ZP: DataProvider<MetazoneSpecificNamesShortV1Marker> + ?Sized,

Load specific-non-location-short format for timezone. For example, “PDT”.

pub fn load_generic_location_format<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>

where ZP: DataProvider<ExemplarCitiesV1Marker> + ?Sized,

Load generic-location format for timezone. For example, “Los Angeles Time”.

fn load_exemplar_city_format<ZP>( &mut self, zone_provider: &ZP, ) -> Result<&mut TimeZoneFormatter, DateTimeError>

where ZP: DataProvider<ExemplarCitiesV1Marker> + ?Sized,

Load exemplar-city format for timezone. For example, “Los Angeles”.

pub fn load_localized_gmt_format( &mut self, ) -> Result<&mut TimeZoneFormatter, DateTimeError>

👎Deprecated since 1.3.0: renamed to include_localized_gmt_format

Alias to TimeZoneFormatter::include_localized_gmt_format.

pub 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

Alias to TimeZoneFormatter::include_iso_8601_format.

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");

pub fn format_to_string(&self, value: &impl TimeZoneInput) -> String

Takes a TimeZoneInput implementer and returns a string with the formatted value.

Trait Implementations

impl Debug for TimeZoneFormatter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.