Struct icu::datetime::time_zone::TimeZoneFormatter

pub struct TimeZoneFormatter { /* private fields */ }

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};
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 BCP-47 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 and the DateTime to use in calculation
let mzc = MetazoneCalculator::try_new_unstable(&icu_testdata::unstable())
    .unwrap();
let datetime = DateTime::try_new_iso_datetime(2022, 8, 29, 0, 0, 0)
    .unwrap();

// Set up the formatter
let mut tzf = TimeZoneFormatter::try_new_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    Default::default(),
)
.unwrap();
tzf.load_generic_non_location_short(&icu_testdata::unstable())?
    .load_generic_non_location_long(&icu_testdata::unstable())?;

// "uschi" - has metazone symbol data for generic_non_location_short
let mut time_zone = "-0600".parse::<CustomTimeZone>().unwrap();
time_zone.time_zone_id = Some(tinystr!(8, "uschi").into());
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"
);

Implementations

impl TimeZoneFormatter

pub fn try_new_unstable<P>(
    provider: &P,
    locale: &DataLocale,
    options: TimeZoneFormatterOptions
) -> Result<TimeZoneFormatter, DateTimeError> where
    P: DataProvider<TimeZoneFormatsV1Marker> + ?Sized, 

Creates a new TimeZoneFormatter with a GMT or ISO format.

To enable other time zone styles, use one of the load methods.

📚 Help choosing a constructor

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

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_unstable(
    &icu_testdata::unstable(),
    &locale!("es").into(),
    TimeZoneFormatterOptions::default(),
)
.unwrap();

let time_zone = "-0700".parse::<CustomTimeZone>().unwrap();

assert_writeable_eq!(tzf.format(&time_zone), "GMT-07:00");

pub fn try_new_with_any_provider(
    provider: &impl AnyProvider,
    locale: &DataLocale,
    options: TimeZoneFormatterOptions
) -> Result<TimeZoneFormatter, DateTimeError>

Creates a new instance using an AnyProvider.

For details on the behavior of this function, see: Self::try_new_unstable

📚 Help choosing a constructor

pub fn try_new_with_buffer_provider(
    provider: &impl BufferProvider,
    locale: &DataLocale,
    options: TimeZoneFormatterOptions
) -> Result<TimeZoneFormatter, DateTimeError>

✨ Enabled with the "serde" feature.

Creates a new instance using a BufferProvider.

For details on the behavior of this function, see: Self::try_new_unstable

📚 Help choosing a constructor

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.

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

Load localized GMT format for timezone. For example, GMT-07:00.

pub fn load_iso_8601_format(
    &mut self,
    format: IsoFormat,
    minutes: IsoMinutes,
    seconds: IsoSeconds
) -> Result<&mut TimeZoneFormatter, DateTimeError>

Load Iso8601 format for timezone. For example, -07:00.

pub fn format<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_unstable(
    &icu_testdata::unstable(),
    &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.