Struct icu::datetime::TypedZonedDateTimeFormatter

pub struct TypedZonedDateTimeFormatter<C>(_, _);

The composition of TypedDateTimeFormatter and TimeZoneFormatter.

TypedZonedDateTimeFormatter is a formatter capable of formatting date/times with time zones from a calendar selected at compile time. For the difference between this and DateTimeFormatter, please read the crate root docs.

TypedZonedDateTimeFormatter uses data from the [data provider]s, the selected locale, 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 TypedZonedDateTimeFormatter, and then fast formatting of the data using the instance.

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::time_zone::TimeZoneFormatterOptions;
use icu::datetime::{options::length, TypedZonedDateTimeFormatter};
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 zdtf = TypedZonedDateTimeFormatter::<Gregorian>::try_new_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    options.into(),
    TimeZoneFormatterOptions::default(),
)
.expect("Failed to create TypedDateTimeFormatter instance.");

let datetime =
    DateTime::try_new_gregorian_datetime(2020, 9, 12, 12, 34, 28).unwrap();
let time_zone = CustomTimeZone::from_str("-07:00").unwrap();

let formatted_date = zdtf.format(&datetime, &time_zone);

assert_writeable_eq!(formatted_date, "Sep 12, 2020, 12:34:28 PM GMT-07:00");

Implementations

impl<C> TypedZonedDateTimeFormatter<C> where
    C: CldrCalendar, 

pub fn try_new_experimental_unstable<P>(
    provider: &P,
    locale: &DataLocale,
    date_time_format_options: DateTimeFormatterOptions,
    time_zone_format_options: TimeZoneFormatterOptions
) -> Result<TypedZonedDateTimeFormatter<C>, DateTimeError> where
    P: DataProvider<<C as CldrCalendar>::DateSymbolsV1Marker> + DataProvider<<C as CldrCalendar>::DateLengthsV1Marker> + DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<DateSkeletonPatternsV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<TimeZoneFormatsV1Marker> + DataProvider<ExemplarCitiesV1Marker> + DataProvider<MetazoneGenericNamesLongV1Marker> + DataProvider<MetazoneGenericNamesShortV1Marker> + DataProvider<MetazoneSpecificNamesLongV1Marker> + DataProvider<MetazoneSpecificNamesShortV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + ?Sized, 

Constructor that takes a selected locale, a reference to a data provider for dates, a data provider for time zones, and a list of DateTimeFormatterOptions. It collects all data necessary to format zoned datetime values into the given locale.

🚧 This code is experimental; it may change at any time, in breaking or non-breaking ways, including in SemVer minor releases. It can be enabled with the "experimental" Cargo feature of the icu meta-crate. Use with caution. #1317

Examples

use icu::calendar::{Gregorian, DateTime};
use icu::datetime::{options::components, TypedZonedDateTimeFormatter};
use icu::locid::locale;
use icu::datetime::time_zone::TimeZoneFormatterOptions;
use icu::timezone::CustomTimeZone;
use icu_provider::AsDeserializingBufferProvider;
use writeable::assert_writeable_eq;

let mut options = components::Bag::default();
options.year = Some(components::Year::Numeric);
options.month = Some(components::Month::Long);
options.hour = Some(components::Numeric::Numeric);
options.minute = Some(components::Numeric::Numeric);
options.time_zone_name = Some(components::TimeZoneName::GmtOffset);

let zdtf = TypedZonedDateTimeFormatter::<Gregorian>::try_new_experimental_unstable(
    &icu_testdata::buffer().as_deserializing(),
    &locale!("en").into(),
    options.into(),
    TimeZoneFormatterOptions::default(),
).unwrap();

let datetime = DateTime::try_new_gregorian_datetime(2022, 8, 31, 1, 2, 3).unwrap();

assert_writeable_eq!(
    zdtf.format(&datetime, &CustomTimeZone::utc()),
    "August 2022, 01:02 GMT",
);

pub fn try_new_unstable<P>(
    provider: &P,
    locale: &DataLocale,
    date_time_format_options: DateTimeFormatterOptions,
    time_zone_format_options: TimeZoneFormatterOptions
) -> Result<TypedZonedDateTimeFormatter<C>, DateTimeError> where
    P: DataProvider<<C as CldrCalendar>::DateSymbolsV1Marker> + DataProvider<<C as CldrCalendar>::DateLengthsV1Marker> + DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<TimeZoneFormatsV1Marker> + DataProvider<ExemplarCitiesV1Marker> + DataProvider<MetazoneGenericNamesLongV1Marker> + DataProvider<MetazoneGenericNamesShortV1Marker> + DataProvider<MetazoneSpecificNamesLongV1Marker> + DataProvider<MetazoneSpecificNamesShortV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + ?Sized, 

Constructor that takes a selected locale, a reference to a data provider for dates, a data provider for time zones, and a list of DateTimeFormatterOptions. It collects all data necessary to format zoned datetime values into the given locale.

📚 Help choosing a constructor

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

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::time_zone::TimeZoneFormatterOptions;
use icu::datetime::{options::length, TypedZonedDateTimeFormatter};
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 = TypedZonedDateTimeFormatter::<Gregorian>::try_new_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    options.into(),
    TimeZoneFormatterOptions::default(),
)
.unwrap();

let datetime =
    DateTime::try_new_gregorian_datetime(2022, 8, 31, 1, 2, 3).unwrap();

assert_writeable_eq!(
    zdtf.format(&datetime, &CustomTimeZone::utc()),
    "Aug 31, 2022, 1:02:03 AM GMT",
);

pub fn try_new_with_any_provider(
    provider: &impl AnyProvider,
    locale: &DataLocale,
    date_time_format_options: DateTimeFormatterOptions,
    time_zone_format_options: TimeZoneFormatterOptions
) -> Result<TypedZonedDateTimeFormatter<C>, 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,
    date_time_format_options: DateTimeFormatterOptions,
    time_zone_format_options: TimeZoneFormatterOptions
) -> Result<TypedZonedDateTimeFormatter<C>, 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 format(
    &'l self,
    date: &impl DateTimeInput<Calendar = C>,
    time_zone: &impl TimeZoneInput
) -> FormattedZonedDateTime<'l>

Takes a DateTimeInput and a TimeZoneInput and returns an instance of a FormattedZonedDateTime that contains all information necessary to display a formatted zoned datetime and operate on it.

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::{options::length, TypedZonedDateTimeFormatter};
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 zdtf = TypedZonedDateTimeFormatter::<Gregorian>::try_new_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    options.into(),
    Default::default(),
)
.expect("Failed to create TypedZonedDateTimeFormatter instance.");

let datetime =
    DateTime::try_new_gregorian_datetime(2020, 9, 12, 12, 34, 28).unwrap();
let time_zone = CustomTimeZone::from_str("-07:00").unwrap();

let formatted_date = zdtf.format(&datetime, &time_zone);

assert_writeable_eq!(formatted_date, "Sep 12, 2020, 12:34:28 PM GMT-07:00");

pub fn format_to_string(
    &self,
    date: &impl DateTimeInput<Calendar = C>,
    time_zone: &impl TimeZoneInput
) -> String

Takes a DateTimeInput and a TimeZoneInput and returns it formatted as a string.

Examples

use icu::calendar::{DateTime, Gregorian};
use icu::datetime::{options::length, TypedZonedDateTimeFormatter};
use icu::locid::locale;
use icu::timezone::CustomTimeZone;
use std::str::FromStr;

let options = length::Bag::from_date_time_style(
    length::Date::Medium,
    length::Time::Long,
);

let zdtf = TypedZonedDateTimeFormatter::<Gregorian>::try_new_unstable(
    &icu_testdata::unstable(),
    &locale!("en").into(),
    options.into(),
    Default::default(),
)
.expect("Failed to create TypedZonedDateTimeFormatter instance.");

let datetime =
    DateTime::try_new_gregorian_datetime(2020, 9, 12, 12, 34, 28).unwrap();
let time_zone = CustomTimeZone::from_str("-07:00").unwrap();

let formatted_string = zdtf.format_to_string(&datetime, &time_zone);

assert_eq!(formatted_string, "Sep 12, 2020, 12:34:28 PM GMT-07:00");