Struct icu_datetime::time_zone::TimeZoneFormat

pub struct TimeZoneFormat { /* private fields */ }

TimeZoneFormat uses data from the data provider, the selected Locale, and the provided TimeZoneFormatConfig to collect all data necessary 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,TimeZoneFormat 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 TimeZoneFormat, and then fast formatting of the time-zone data using the instance.

Examples

use icu_locid::locale;
use icu_datetime::{TimeZoneFormat, TimeZoneFormatConfig, TimeZoneFormatOptions};
use icu_datetime::date::GmtOffset;
use icu_datetime::mock::time_zone::MockTimeZone;
use icu_provider::inv::InvariantDataProvider;

let provider = InvariantDataProvider;

let tzf = TimeZoneFormat::try_from_config(locale!("en"), TimeZoneFormatConfig::GenericNonLocationLong, &provider, &TimeZoneFormatOptions::default())
    .expect("Failed to create TimeZoneFormat");

let time_zone = MockTimeZone::new(
       GmtOffset::default(),
       None,
       None,
       None,
);

let value = tzf.format_to_string(&time_zone);

Implementations

impl TimeZoneFormat

pub fn try_from_config<L, ZP>(
    locale: L,
    config: TimeZoneFormatConfig,
    zone_provider: &ZP,
    options: &TimeZoneFormatOptions
) -> Result<Self, DateTimeFormatError> where
    L: Into<Locale>,
    ZP: ResourceProvider<TimeZoneFormatsV1Marker> + ResourceProvider<ExemplarCitiesV1Marker> + ResourceProvider<MetaZoneGenericNamesLongV1Marker> + ResourceProvider<MetaZoneGenericNamesShortV1Marker> + ResourceProvider<MetaZoneSpecificNamesLongV1Marker> + ResourceProvider<MetaZoneSpecificNamesShortV1Marker> + ?Sized, 

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

Examples

use icu_locid::locale;
use icu_datetime::{TimeZoneFormat, TimeZoneFormatConfig, TimeZoneFormatOptions};
use icu_datetime::mock::time_zone::MockTimeZone;
use icu_provider::inv::InvariantDataProvider;

let provider = InvariantDataProvider;

let tzf = TimeZoneFormat::try_from_config(locale!("en"), TimeZoneFormatConfig::LocalizedGMT, &provider, &TimeZoneFormatOptions::default());

assert!(tzf.is_ok());

pub fn load_generic_non_location_long<ZP>(
    &mut self,
    zone_provider: &ZP
) -> Result<&mut TimeZoneFormat, DateTimeFormatError> where
    ZP: ResourceProvider<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 TimeZoneFormat, DateTimeFormatError> where
    ZP: ResourceProvider<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 TimeZoneFormat, DateTimeFormatError> where
    ZP: ResourceProvider<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 TimeZoneFormat, DateTimeFormatError> where
    ZP: ResourceProvider<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 TimeZoneFormat, DateTimeFormatError> where
    ZP: ResourceProvider<ExemplarCitiesV1Marker> + ?Sized, 

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

pub fn load_localized_gmt_format(
    &mut self
) -> Result<&mut TimeZoneFormat, DateTimeFormatError>

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 TimeZoneFormat, DateTimeFormatError>

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

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_locid::locale;
use icu_datetime::{TimeZoneFormat, TimeZoneFormatConfig, TimeZoneFormatOptions};
use icu_datetime::date::GmtOffset;
use icu_datetime::mock::time_zone::MockTimeZone;
use icu_provider::inv::InvariantDataProvider;

let provider = InvariantDataProvider;

let tzf = TimeZoneFormat::try_from_config(locale!("en"), TimeZoneFormatConfig::LocalizedGMT, &provider, &TimeZoneFormatOptions::default())
    .expect("Failed to create TimeZoneFormat");

let time_zone = MockTimeZone::new(
       GmtOffset::default(),
       None,
       None,
       None,
);

let _ = tzf.format(&time_zone);

pub fn format_to_write(
    &self,
    w: &mut impl Write,
    value: &impl TimeZoneInput
) -> Result

Takes a mutable reference to anything that implements the Write trait and a TimeZoneInput implementer that populates the buffer with a formatted value.

Examples

use icu_locid::locale;
use icu_datetime::{TimeZoneFormat, TimeZoneFormatConfig, TimeZoneFormatOptions};
use icu_datetime::date::GmtOffset;
use icu_datetime::mock::time_zone::MockTimeZone;
use icu_provider::inv::InvariantDataProvider;

let provider = InvariantDataProvider;

let tzf = TimeZoneFormat::try_from_config(locale!("en"), TimeZoneFormatConfig::LocalizedGMT, &provider, &TimeZoneFormatOptions::default())
    .expect("Failed to create TimeZoneFormat");

let time_zone = MockTimeZone::new(
       GmtOffset::default(),
       None,
       None,
       None,
);

let mut buffer = String::new();
tzf.format_to_write(&mut buffer, &time_zone)
    .expect("Failed to write to a buffer.");

let _ = format!("Time Zone: {}", buffer);

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

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

Examples

use icu_locid::locale;
use icu_datetime::{TimeZoneFormat, TimeZoneFormatConfig, TimeZoneFormatOptions};
use icu_datetime::date::GmtOffset;
use icu_datetime::mock::time_zone::MockTimeZone;
use icu_provider::inv::InvariantDataProvider;

let provider = InvariantDataProvider;

let tzf = TimeZoneFormat::try_from_config(locale!("en"), TimeZoneFormatConfig::LocalizedGMT, &provider, &TimeZoneFormatOptions::default())
    .expect("Failed to create TimeZoneFormat");

let time_zone = MockTimeZone::new(
       GmtOffset::default(),
       None,
       None,
       None,
);

let _ = tzf.format_to_string(&time_zone);