Struct icu_datetime::zoned_datetime::ZonedDateTimeFormat

pub struct ZonedDateTimeFormat<'d> { /* fields omitted */ }

The composition of DateTimeFormat and TimeZoneFormat.

ZonedDateTimeFormat uses data from the DataProviders, 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, TimeZoneFormat will pull in only the resources it needs to format that pattern that is derived from the provided DateTimeFormatOptions.

For that reason, one should think of the process of formatting a zoned datetime in two steps: first, a computationally heavy construction of ZonedDateTimeFormat, and then fast formatting of the data using the instance.

Examples

use icu::locid::Locale;
use icu::locid::macros::langid;
use icu::datetime::{ZonedDateTimeFormat, options::length};
use icu::datetime::mock::zoned_datetime::MockZonedDateTime;
use icu_provider::inv::InvariantDataProvider;

let locale: Locale = langid!("en").into();

let date_provider = InvariantDataProvider;
let zone_provider = InvariantDataProvider;

let options = length::Bag {
    date: Some(length::Date::Medium),
    time: Some(length::Time::Short),
    ..Default::default()
};
let zdtf = ZonedDateTimeFormat::try_new(locale, &date_provider, &zone_provider, &options.into())
    .expect("Failed to create DateTimeFormat instance.");


let zoned_datetime: MockZonedDateTime = "2021-04-08T16:12:37.000-07:00"
    .parse()
    .expect("Failed to parse zoned datetime");

let value = zdtf.format_to_string(&zoned_datetime);

Implementations

impl<'d> ZonedDateTimeFormat<'d>

pub fn try_new<L, DP: ?Sized, ZP: ?Sized>(
    locale: L,
    date_provider: &DP,
    zone_provider: &ZP,
    options: &DateTimeFormatOptions
) -> Result<Self, DateTimeFormatError> where
    L: Into<Locale>,
    DP: DataProvider<'d, DatesV1>,
    ZP: DataProvider<'d, TimeZoneFormatsV1<'d>> + DataProvider<'d, ExemplarCitiesV1<'d>> + DataProvider<'d, MetaZoneGenericNamesLongV1<'d>> + DataProvider<'d, MetaZoneGenericNamesShortV1<'d>> + DataProvider<'d, MetaZoneSpecificNamesLongV1<'d>> + DataProvider<'d, MetaZoneSpecificNamesShortV1<'d>>, 

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

Examples

use icu::locid::Locale;
use icu::locid::macros::langid;
use icu::datetime::{ZonedDateTimeFormat, DateTimeFormatOptions};
use icu::datetime::mock::zoned_datetime::MockZonedDateTime;
use icu_provider::inv::InvariantDataProvider;

let locale: Locale = langid!("en").into();

let date_provider = InvariantDataProvider;
let zone_provider = InvariantDataProvider;

let options = DateTimeFormatOptions::default();

let zdtf = ZonedDateTimeFormat::try_new(locale, &date_provider, &zone_provider, &options);

assert_eq!(zdtf.is_ok(), true);

pub fn format<'l: 'd, T>(
    &'l self,
    value: &'l T
) -> FormattedZonedDateTime<'l, T> where
    T: ZonedDateTimeInput, 

Takes a ZonedDateTimeInput implementer 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::locid::Locale;
use icu::locid::macros::langid;
use icu::datetime::{ZonedDateTimeFormat, DateTimeFormatOptions};
use icu::datetime::mock::zoned_datetime::MockZonedDateTime;
use icu_provider::inv::InvariantDataProvider;
let zdtf = ZonedDateTimeFormat::try_new(locale, &date_provider, &zone_provider, &options)
    .expect("Failed to create ZonedDateTimeFormat instance.");

let zoned_datetime: MockZonedDateTime = "2021-04-08T16:12:37.000-07:00"
    .parse()
    .expect("Failed to parse zoned datetime");

let formatted_date = zdtf.format(&zoned_datetime);

let _ = format!("Date: {}", formatted_date);

At the moment, there’s little value in using that over one of the other format methods, but FormattedZonedDateTime will grow with methods for iterating over fields, extracting information about formatted date and so on.

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

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

Examples

use icu::locid::Locale;
use icu::locid::macros::langid;
use icu::datetime::{ZonedDateTimeFormat, DateTimeFormatOptions};
use icu::datetime::mock::zoned_datetime::MockZonedDateTime;
use icu_provider::inv::InvariantDataProvider;
let zdtf = ZonedDateTimeFormat::try_new(locale, &date_provider, &zone_provider, &options.into())
    .expect("Failed to create ZonedDateTimeFormat instance.");

let zoned_datetime: MockZonedDateTime = "2021-04-08T16:12:37.000-07:00"
    .parse()
    .expect("Failed to parse zoned datetime");

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

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

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

Takes a ZonedDateTimeInput implementer and returns it formatted as a string.

Examples

use icu::locid::Locale;
use icu::locid::macros::langid;
use icu::datetime::{ZonedDateTimeFormat, DateTimeFormatOptions};
use icu::datetime::mock::zoned_datetime::MockZonedDateTime;
use icu_provider::inv::InvariantDataProvider;
let zdtf = ZonedDateTimeFormat::try_new(locale, &date_provider, &zone_provider, &options.into())
    .expect("Failed to create ZonedDateTimeFormat instance.");

let zoned_datetime: MockZonedDateTime = "2021-04-08T16:12:37.000-07:00"
    .parse()
    .expect("Failed to parse zoned datetime");

let _ = zdtf.format_to_string(&zoned_datetime);