Module icu::datetime::options::components

🚧 [Experimental] Options for constructing DateTimeFormatter objects by each component style.

✨ Enabled with the experimental Cargo feature.

🚧 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

Implementation status

This module is available by enabling the "experimental" Cargo feature. It may change in breaking ways, including across minor releases.

This is currently only a partial implementation of the UTS-35 skeleton matching algorithm.

Algorithm step	Status
Match skeleton fields according to a ranking	Implemented
Adjust the matched pattern to have certain widths	Implemented
Match date and times separately, and them combine them	Implemented
Use appendItems to fill in a pattern with missing fields	Not yet, and may not be fully implemented. See issue #586

Description

A components::Bag is a model of encoding information on how to format date and time by specifying a list of components the user wants to be visible in the formatted string and how each field should be displayed.

This model closely corresponds to ECMA402 API and allows for high level of customization compared to Length model.

Additionally, the bag contains an optional set of Preferences which represent user preferred adjustments that can be applied onto the pattern right before formatting.

Pattern Selection

The components::Bag is a way for the developer to describe which components should be included in in a datetime, and how they should be displayed. There is not a strict guarantee in how the final date will be displayed to the end user. The user’s preferences and locale information can override the developer preferences.

The fields in the components::Bag are matched against available patterns in the CLDR locale data. A best fit is found, and presented to the user. This means that in certain situations, and component combinations, fields will not have a match, or the match will have a different type of presentation for a given locale.

Examples

use icu::datetime::options::components;
use icu::datetime::options::DateTimeFormatterOptions;

let mut bag = components::Bag::default();
bag.year = Some(components::Year::Numeric);
bag.month = Some(components::Month::Long);
bag.day = Some(components::Day::NumericDayOfMonth);

bag.hour = Some(components::Numeric::TwoDigit);
bag.minute = Some(components::Numeric::TwoDigit);

// The options can be created manually.
let options = DateTimeFormatterOptions::Components(bag);

Or the options can be inferred through the .into() trait.

use icu::datetime::options::components;
use icu::datetime::options::DateTimeFormatterOptions;
let options: DateTimeFormatterOptions = components::Bag::default().into();

Note: The exact formatted result is a subject to change over time. Formatted result should be treated as opaque and displayed to the user as-is, and it is strongly recommended to never write tests that expect a particular formatted output.

Structs

• Bag
  See the module-level docs for more information.

Enums

• Day
  Options for displaying the current day of the month or year.
• Month
  Options for displaying a Month for the components::Bag.
• Numeric
  A numeric component for the components::Bag. It is used for the year, day, hour, minute, and second.
• Text
  A text component for the components::Bag. It is used for the era and weekday.
• TimeZoneName
  Options for displaying a time zone for the components::Bag.
• Week
  Options for displaying the current week number for the components::Bag.
• Year
  Options for displaying a Year for the components::Bag.