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.
FixedCalendarDateTimeFormatter
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.
These formatters work with types from the calendar
module, like Date
, DateTime
, and Time
,
and timezone::TimeZoneInfo
, however other types may be used provided they implement the traits from the input
module.
Each instance of a date-related formatter 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 FixedCalendarDateTimeFormatter<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 neo::DateTimeFormatter
with the calendar specified in the locale, and use it with
DateTime<AnyCalendar>
(see 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::fieldset::YMDT;
use icu::datetime::{DateTimeFormatter, FixedCalendarDateTimeFormatter};
use icu::locale::{locale, Locale};
use writeable::assert_try_writeable_eq;
// You can work with a formatter that can select the calendar at runtime:
let locale = Locale::try_from_str("en-u-ca-gregory").unwrap();
let dtf = DateTimeFormatter::try_new(&locale.into(), YMDT::medium().hm())
.expect("should successfully create DateTimeFormatter instance");
// Or one that selects a calendar at compile time:
let typed_dtf = FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
&locale!("en").into(),
YMDT::medium().hm(),
)
.expect(
"should successfully create FixedCalendarDateTimeFormatter instance",
);
let typed_date =
DateTime::try_new_gregorian(2020, 9, 12, 12, 34, 28).unwrap();
// prefer using ISO dates with DateTimeFormatter
let date = typed_date.to_iso();
let formatted_date = dtf.convert_and_format(&date);
let typed_formatted_date = typed_dtf.format(&typed_date);
assert_try_writeable_eq!(formatted_date, "Sep 12, 2020, 12:34 PM");
assert_try_writeable_eq!(typed_formatted_date, "Sep 12, 2020, 12:34 PM");
Modules§
- Enums representing the fields in a date pattern, including the field’s type, length and symbol.
- All available field sets for datetime formatting.
- A collection of utilities for representing and working with dates as an input to formatting operations.
- Temporary module for neo datetime patterns
- Temporary module for neo datetime skeletons (Semantic Skeleta)
DateTimeFormatterOptions
is a bag of options which, together withLocale
, defines how dates will be formatted.- 🚧 [Unstable] Data provider struct definitions for this ICU4X component.
- Scaffolding traits and types for the datetime crate.
Structs§
DateTimeFormatter
is a formatter capable of formatting dates and/or times from a calendar selected at runtime.FixedCalendarDateTimeFormatter
is a formatter capable of formatting dates and/or times from a calendar selected at compile time.- A pattern that has been interpolated and implements
TryWriteable
. - An intermediate type during a datetime formatting operation.
- An error from mixing calendar types in a formatter.
- A low-level type that formats datetime patterns with localized names. The calendar should be chosen at compile time.
Enums§
- Error for
TryWriteable
implementations - A specification for the length of a date or component of a date.
- Error returned from
TypedDateTimeNames
’s pattern load methods.