Crate icu_datetime
source ·Expand description
Formatting date and time.
This module is published as its own crate (icu_datetime
)
and as part of the icu
crate. See the latter for more details on the ICU4X project.
TypedDateTimeFormatter
and DateTimeFormatter
are the main types of the component. They accepts a set of arguments which
allow it to collect necessary data from the data provider, and once instantiated, can be
used to quickly format any date and time provided. There are variants of these types that can format greater or fewer components,
including TypedDateFormatter
& DateFormatter
, TypedZonedDateTimeFormatter
& ZonedDateTimeFormatter
, TimeFormatter
,
and TimeZoneFormatter
These formatters work with types from the calendar
module, like Date
, DateTime
, and Time
,
and timezone::CustomTimeZone
, however other types may be used provided they implement the traits from the input
module.
Each instance of a date-related formatter (i.e. not TimeFormatter
or TimeZoneFormatter
is associated with a particular Calendar
.
The “Typed” vs untyped formatter distinction is to help with this. For example, if you know at compile time that you
will only be formatting Gregorian dates, you can use TypedDateTimeFormatter<Gregorian>
and the
APIs will make sure that only Gregorian DateTime
s are used with the calendar. On the other hand, if you want to be able to select
the calendar at runtime, you can use DateTimeFormatter
with the calendar specified in the locale, and use it with
DateTime
,AnyCalendar
. These formatters still require dates associated
with the appropriate calendar (though they will convert ISO dates to the calendar if provided), they just do not force the
programmer to pick the calendar at compile time.
§Examples
use icu::calendar::{DateTime, Gregorian};
use icu::datetime::{
options::length, DateTimeFormatter, DateTimeFormatterOptions,
TypedDateTimeFormatter,
};
use icu::locid::{locale, Locale};
use std::str::FromStr;
use writeable::assert_writeable_eq;
// See the next code example for a more ergonomic example with .into().
let options =
DateTimeFormatterOptions::Length(length::Bag::from_date_time_style(
length::Date::Medium,
length::Time::Short,
));
// You can work with a formatter that can select the calendar at runtime:
let locale = Locale::from_str("en-u-ca-gregory").unwrap();
let dtf = DateTimeFormatter::try_new(&locale.into(), options.clone())
.expect("Failed to create DateTimeFormatter instance.");
// Or one that selects a calendar at compile time:
let typed_dtf = TypedDateTimeFormatter::<Gregorian>::try_new(
&locale!("en").into(),
options,
)
.expect("Failed to create TypedDateTimeFormatter instance.");
let typed_date =
DateTime::try_new_gregorian_datetime(2020, 9, 12, 12, 34, 28).unwrap();
// prefer using ISO dates with DateTimeFormatter
let date = typed_date.to_iso().to_any();
let formatted_date = dtf.format(&date).expect("Calendars should match");
let typed_formatted_date = typed_dtf.format(&typed_date);
assert_writeable_eq!(formatted_date, "Sep 12, 2020, 12:34 PM");
assert_writeable_eq!(typed_formatted_date, "Sep 12, 2020, 12:34 PM");
let formatted_date_string =
dtf.format_to_string(&date).expect("Calendars should match");
let typed_formatted_date_string = typed_dtf.format_to_string(&typed_date);
assert_eq!(formatted_date_string, "Sep 12, 2020, 12:34 PM");
assert_eq!(typed_formatted_date_string, "Sep 12, 2020, 12:34 PM");
The options can be created more ergonomically using the Into
trait to automatically
convert a options::length::Bag
into a DateTimeFormatterOptions::Length
.
use icu::calendar::Gregorian;
use icu::datetime::{
options::length, DateTimeFormatterOptions, TypedDateTimeFormatter,
};
use icu::locid::locale;
let options = length::Bag::from_date_time_style(
length::Date::Medium,
length::Time::Short,
)
.into();
let dtf = TypedDateTimeFormatter::<Gregorian>::try_new(
&locale!("en").into(),
options,
);
At the moment, the crate provides only options using the Length
bag, but in the future,
we expect to add more ways to customize the output, like skeletons, and components.
Re-exports§
pub use options::DateTimeFormatterOptions;
pub use DateTimeError as Error;
Modules§
- any 🔒This module contains the untyped
AnyCalendar
-basedTypedDateTimeFormatter
APIs that are capable of formatting dates from any calendar - calendar 🔒
- datetime 🔒The collection of code that is needed for handling formatting operations for DateTimes. Central to this is the
TypedDateTimeFormatter
. - error 🔒
- Enums representing the fields in a date pattern, including the field’s type, length and symbol.
- format 🔒
- helpers 🔒
- A collection of utilities for representing and working with dates as an input to formatting operations.
DateTimeFormatterOptions
is a bag of options which, together withLocale
, defines how dates will be formatted with aTypedDateTimeFormatter
instance.- 🚧 [Unstable] Data provider struct definitions for this ICU4X component.
- raw 🔒
- A formatter specifically for the time zone.
Structs§
DateFormatter
is a formatter capable of formatting dates from any calendar, selected at runtime. For the difference between this andTypedDateFormatter
, please read the crate root docs.DateTimeFormatter
is a formatter capable of formatting date/times from any calendar, selected at runtime. For the difference between this andTypedDateTimeFormatter
, please read the crate root docs.FormattedDateTime
is a intermediate structure which can be retrieved as an output fromTypedDateTimeFormatter
.FormattedTimeZone
is a intermediate structure which can be retrieved as an output fromTimeZoneFormatter
.FormattedTimeZone
is a intermediate structure which can be retrieved as an output fromZonedDateTimeFormatter
.- An error from mixing calendar types in
DateTimeFormatter
TimeFormatter
is a structure of theicu::datetime
component that provides time formatting only. When constructed, it uses data from the data provider, selected locale and provided preferences to collect all data necessary to format any time into that locale.TypedDateFormatter
is a formatter capable of formatting dates from a calendar selected at compile time. For the difference between this andDateFormatter
, please read the crate root docs.TypedDateTimeFormatter
is a formatter capable of formatting date/times from a calendar selected at compile time. For the difference between this andDateTimeFormatter
, please read the crate root docs.- The composition of
TypedDateTimeFormatter
andTimeZoneFormatter
. ZonedDateTimeFormatter
is a formatter capable of formatting date/times with time zones from any calendar, selected at runtime. For the difference between this andTypedZonedDateTimeFormatter
, please read the crate root docs.
Enums§
- A list of error outcomes for various operations in this module.
Traits§
- A calendar that can be found in CLDR