Struct icu_datetime::ZonedDateTimeFormatter
source · [−]pub struct ZonedDateTimeFormatter(_, _);
Expand description
ZonedDateTimeFormatter
is a formatter capable of formatting
date/times with timezones from any calendar, selected at runtime. For the difference between this and TypedZonedDateTimeFormatter
,
please read the crate root docs.
This is equivalently the composition of
DateTimeFormatter
and TimeZoneFormatter
.
ZonedDateTimeFormatter
uses data from the [data provider]s, the selected DataLocale
, 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 ZonedDateTimeFormatter
, and then fast formatting
of the data using the instance.
Examples
use icu::calendar::{DateTime, Gregorian};
use icu::timezone::CustomTimeZone;
use icu::datetime::{options::length, ZonedDateTimeFormatter};
use icu::locid::locale;
use icu_datetime::TimeZoneFormatterOptions;
let provider = icu_testdata::get_provider();
let options = length::Bag::from_date_time_style(length::Date::Medium, length::Time::Long);
let zdtf = ZonedDateTimeFormatter::try_new_with_buffer_provider(
&provider,
&locale!("en").into(),
options.into(),
TimeZoneFormatterOptions::default(),
)
.expect("Failed to create TypedDateTimeFormatter instance.");
let datetime = DateTime::new_gregorian_datetime(2020, 9, 1, 12, 34, 28)
.expect("Failed to construct DateTime.");
let any_datetime = datetime.to_any();
let time_zone: CustomTimeZone = "+05:00".parse().expect("Timezone should parse");
let value = zdtf.format_to_string(&any_datetime, &time_zone).expect("calendars should match");
assert_eq!(value, "Sep 1, 2020, 12:34:28 PM GMT+05:00");
Implementations
sourceimpl ZonedDateTimeFormatter
impl ZonedDateTimeFormatter
sourcepub fn try_new_unstable<P>(
provider: &P,
locale: &DataLocale,
date_time_format_options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions
) -> Result<Self, DateTimeFormatterError> where
P: 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<GregorianDateLengthsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<JapaneseDateLengthsV1Marker> + DataProvider<JapaneseExtendedDateLengthsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<IndianDateLengthsV1Marker> + DataProvider<EthiopicDateLengthsV1Marker> + DataProvider<GregorianDateSymbolsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<JapaneseDateSymbolsV1Marker> + DataProvider<JapaneseExtendedDateSymbolsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<IndianDateSymbolsV1Marker> + DataProvider<EthiopicDateSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + DataProvider<JapaneseExtendedErasV1Marker> + ?Sized,
pub fn try_new_unstable<P>(
provider: &P,
locale: &DataLocale,
date_time_format_options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions
) -> Result<Self, DateTimeFormatterError> where
P: 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<GregorianDateLengthsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<JapaneseDateLengthsV1Marker> + DataProvider<JapaneseExtendedDateLengthsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<IndianDateLengthsV1Marker> + DataProvider<EthiopicDateLengthsV1Marker> + DataProvider<GregorianDateSymbolsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<JapaneseDateSymbolsV1Marker> + DataProvider<JapaneseExtendedDateSymbolsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<IndianDateSymbolsV1Marker> + DataProvider<EthiopicDateSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + DataProvider<JapaneseExtendedErasV1Marker> + ?Sized,
Constructor that takes a selected DataLocale
, a reference to a data provider for
dates, a data provider for time zones, a data provider for calendars, and a list of DateTimeFormatterOptions
.
It collects all data necessary to format zoned datetime values into the given locale.
This method is unstable, more bounds may be added in the future as calendar support is added. It is
preferable to use a provider that implements DataProvider<D>
for all D
, and ensure data is loaded as
appropriate. The Self::try_new_with_buffer_provider()
, Self::try_new_with_any_provider()
constructors
may also be used if compile stability is desired.
Examples
use icu::calendar::Gregorian;
use icu::datetime::options::length;
use icu::datetime::mock::parse_zoned_gregorian_from_str;
use icu::datetime::{DateTimeFormatterOptions, ZonedDateTimeFormatter};
use icu::locid::Locale;
use icu::datetime::TimeZoneFormatterOptions;
use std::str::FromStr;
let provider = icu_testdata::get_provider();
let options = length::Bag::from_date_time_style(length::Date::Medium, length::Time::Long).into();
let locale = Locale::from_str("en-u-ca-gregory").unwrap();
let zdtf = ZonedDateTimeFormatter::try_new_unstable(
&provider,
&locale.into(),
options,
TimeZoneFormatterOptions::default(),
).expect("Construction should succeed");
let (datetime, time_zone) = parse_zoned_gregorian_from_str("2021-04-08T16:12:37.000-07:00")
.expect("Failed to parse zoned datetime");
let any_datetime = datetime.to_any();
assert_eq!(zdtf.format_to_string(&any_datetime, &time_zone).unwrap(), "Apr 8, 2021, 4:12:37 PM GMT-07:00");
sourcepub fn try_new_with_any_provider<P>(
data_provider: &P,
locale: &DataLocale,
options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions
) -> Result<Self, DateTimeFormatterError> where
P: AnyProvider,
pub fn try_new_with_any_provider<P>(
data_provider: &P,
locale: &DataLocale,
options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions
) -> Result<Self, DateTimeFormatterError> where
P: AnyProvider,
Construct a new ZonedDateTimeFormatter
from a data provider that implements
AnyProvider
.
The provider must be able to provide data for the following keys: datetime/symbols@1
, datetime/timelengths@1
,
datetime/timelengths@1
, datetime/symbols@1
, datetime/skeletons@1
, datetime/week_data@1
, plurals/ordinals@1
,
time_zone/formats@1
, time_zone/exemplar_cities@1
, time_zone/generic_long@1
, time_zone/generic_short@1
,
time_zone/specific_long@1
, time_zone/specific_short@1
, time_zone/metazone_period@1
.
Furthermore, based on the type of calendar used, one of the following data keys may be necessary:
u-ca-japanese
(Japanese calendar):calendar/japanese@1
Test will currently fail due to https://github.com/unicode-org/icu4x/issues/2188,
since these functions currently must be given a fallback-enabled provider and
we do not have one in icu_testdata
use icu::calendar::Gregorian;
use icu::datetime::options::length;
use icu::datetime::mock::parse_zoned_gregorian_from_str;
use icu::datetime::{DateTimeFormatterOptions, ZonedDateTimeFormatter};
use icu::locid::Locale;
use icu::datetime::TimeZoneFormatterOptions;
use std::str::FromStr;
let provider = icu_testdata::get_baked_provider();
let options = length::Bag::from_date_time_style(length::Date::Medium, length::Time::Long).into();
let locale = Locale::from_str("en-u-ca-gregory").unwrap();
let zdtf = ZonedDateTimeFormatter::try_new_with_any_provider(
&provider,
&locale.into(),
options,
TimeZoneFormatterOptions::default(),
).expect("Construction should succeed");
let (datetime, time_zone) = parse_zoned_gregorian_from_str("2021-04-08T16:12:37.000-07:00")
.expect("Failed to parse zoned datetime");
let any_datetime = datetime.to_any();
assert_eq!(zdtf.format_to_string(&any_datetime, &time_zone).unwrap(), "Apr 8, 2021, 4:12:37 PM GMT-07:00");
sourcepub fn try_new_with_buffer_provider<P>(
data_provider: &P,
locale: &DataLocale,
options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions
) -> Result<Self, DateTimeFormatterError> where
P: BufferProvider,
pub fn try_new_with_buffer_provider<P>(
data_provider: &P,
locale: &DataLocale,
options: DateTimeFormatterOptions,
time_zone_format_options: TimeZoneFormatterOptions
) -> Result<Self, DateTimeFormatterError> where
P: BufferProvider,
Construct a new ZonedDateTimeFormatter
from a data provider that implements
BufferProvider
.
The provider must be able to provide data for the following keys: datetime/symbols@1
, datetime/timelengths@1
,
datetime/timelengths@1
, datetime/symbols@1
, datetime/skeletons@1
, datetime/week_data@1
, plurals/ordinals@1
,
time_zone/formats@1
, time_zone/exemplar_cities@1
, time_zone/generic_long@1
, time_zone/generic_short@1
,
time_zone/specific_long@1
, time_zone/specific_short@1
, time_zone/metazone_period@1
.
Furthermore, based on the type of calendar used, one of the following data keys may be necessary:
u-ca-japanese
(Japanese calendar):calendar/japanese@1
use icu::calendar::Gregorian;
use icu::datetime::options::length;
use icu::datetime::mock::parse_zoned_gregorian_from_str;
use icu::datetime::{DateTimeFormatterOptions, ZonedDateTimeFormatter};
use icu::locid::Locale;
use icu::datetime::TimeZoneFormatterOptions;
use std::str::FromStr;
let provider = icu_testdata::get_provider();
let options = length::Bag::from_date_time_style(length::Date::Medium, length::Time::Long).into();
let locale = Locale::from_str("en").unwrap();
let zdtf = ZonedDateTimeFormatter::try_new_with_buffer_provider(
&provider,
&locale.into(),
options,
TimeZoneFormatterOptions::default(),
).expect("Construction should succeed");
let (datetime, time_zone) = parse_zoned_gregorian_from_str("2021-04-08T16:12:37.000-07:00")
.expect("Failed to parse zoned datetime");
let any_datetime = datetime.to_any();
assert_eq!(zdtf.format_to_string(&any_datetime, &time_zone).unwrap(), "Apr 8, 2021, 4:12:37 PM GMT-07:00");
sourcepub fn format<'l, T>(
&'l self,
date: &impl DateTimeInput<Calendar = AnyCalendar>,
time_zone: &impl TimeZoneInput
) -> Result<FormattedZonedDateTime<'l>, DateTimeFormatterError>
pub fn format<'l, T>(
&'l self,
date: &impl DateTimeInput<Calendar = AnyCalendar>,
time_zone: &impl TimeZoneInput
) -> Result<FormattedZonedDateTime<'l>, DateTimeFormatterError>
Takes a DateTimeInput
and a TimeZoneInput
and returns an instance of a FormattedZonedDateTime
that contains all information necessary to display a formatted date and operate on it.
This function will fail if the date passed in uses a different calendar than that of the AnyCalendar. Please convert dates before passing them in if necessary. This function will automatically convert and format dates that are associated with the ISO calendar.
sourcepub fn format_to_write(
&self,
w: &mut impl Write,
date: &impl DateTimeInput<Calendar = AnyCalendar>,
time_zone: &impl TimeZoneInput
) -> Result<(), DateTimeFormatterError>
pub fn format_to_write(
&self,
w: &mut impl Write,
date: &impl DateTimeInput<Calendar = AnyCalendar>,
time_zone: &impl TimeZoneInput
) -> Result<(), DateTimeFormatterError>
Takes a mutable reference to anything that implements Write
trait
and a DateTimeInput
and a TimeZoneInput
and populates the buffer with a formatted value.
This function will fail if the date passed in uses a different calendar than that of the AnyCalendar. Please convert dates before passing them in if necessary. This function will automatically convert and format dates that are associated with the ISO calendar.
sourcepub fn format_to_string(
&self,
date: &impl DateTimeInput<Calendar = AnyCalendar>,
time_zone: &impl TimeZoneInput
) -> Result<String, DateTimeFormatterError>
pub fn format_to_string(
&self,
date: &impl DateTimeInput<Calendar = AnyCalendar>,
time_zone: &impl TimeZoneInput
) -> Result<String, DateTimeFormatterError>
Takes a DateTimeInput
and a TimeZoneInput
and returns it formatted as a string.
This function will fail if the date passed in uses a different calendar than that of the AnyCalendar. Please convert dates before passing them in if necessary. This function will automatically convert and format dates that are associated with the ISO calendar.
Auto Trait Implementations
impl RefUnwindSafe for ZonedDateTimeFormatter
impl Send for ZonedDateTimeFormatter
impl Sync for ZonedDateTimeFormatter
impl Unpin for ZonedDateTimeFormatter
impl UnwindSafe for ZonedDateTimeFormatter
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more