icu_datetime/
lib.rs

1// This file is part of ICU4X. For terms of use, please see the file
2// called LICENSE at the top level of the ICU4X source tree
3// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
4
5//! Localized formatting of dates, times, and time zones.
6//!
7//! This module is published as its own crate ([`icu_datetime`](https://docs.rs/icu_datetime/latest/icu_datetime/))
8//! and as part of the [`icu`](https://docs.rs/icu/latest/icu/) crate. See the latter for more details on the ICU4X project.
9//!
10//! ICU4X datetime formatting follows the Unicode UTS 35 standard for [Semantic Skeletons](https://unicode.org/reports/tr35/tr35-dates.html#Semantic_Skeletons).
11//! First you choose a _field set_, then you configure the formatting _options_ to your desired context.
12//!
13//! 1. Field Sets: [`icu::datetime::fieldsets`](fieldsets)
14//! 2. Options: [`icu::datetime::options`](options)
15//!
16//! ICU4X supports formatting in over one dozen _calendar systems_, including Gregorian, Buddhist,
17//! Hijri, and more. The calendar system is usually derived from the locale, but it can also be
18//! specified explicitly.
19//!
20//! The main formatter in this crate is [`DateTimeFormatter`], which supports all field sets,
21//! options, and calendar systems. Additional formatter types are available to developers in
22//! resource-constrained environments.
23//!
24//! The formatters accept input types from the [`calendar`](icu_calendar) and
25//! [`timezone`](icu_time) crates (Also reexported from the [`input`] module of this crate):
26//!
27//! 1. [`Date`](icu_calendar::Date)
28//! 2. [`DateTime`](icu_time::DateTime)
29//! 3. [`Time`](icu_time::Time)
30//! 4. [`UtcOffset`](icu_time::zone::UtcOffset)
31//! 5. [`TimeZoneInfo`](icu_time::TimeZoneInfo)
32//! 6. [`ZonedDateTime`](icu_time::ZonedDateTime)
33//!
34//! Not all inputs are valid for all field sets.
35//!
36//! # Binary Size Tradeoffs
37//!
38//! The datetime crate has been engineered with a focus on giving developers the ability to
39//! tune binary size to their needs. The table illustrates the two main tradeoffs, field sets
40//! and calendar systems:
41//!
42//! | Factor | Static (Lower Binary Size) | Dynamic (Greater Binary Size) |
43//! |---|---|---|
44//! | Field Sets | Specific [`fieldsets`] types | Enumerations from [`fieldsets::enums`] |
45//! | Calendar Systems | [`FixedCalendarDateTimeFormatter`] | [`DateTimeFormatter`] |
46//!
47//! If formatting times and time zones without dates, consider using [`NoCalendarFormatter`].
48//!
49//! # Examples
50//!
51//! ```
52//! use icu::datetime::fieldsets;
53//! use icu::datetime::input::Date;
54//! use icu::datetime::input::{DateTime, Time};
55//! use icu::datetime::DateTimeFormatter;
56//! use icu::locale::{locale, Locale};
57//! use writeable::assert_writeable_eq;
58//!
59//! // Field set for year, month, day, hour, and minute with a medium length:
60//! let field_set_with_options = fieldsets::YMD::medium().with_time_hm();
61//!
62//! // Create a formatter for Argentinian Spanish:
63//! let locale = locale!("es-AR");
64//! let dtf = DateTimeFormatter::try_new(locale.into(), field_set_with_options)
65//!     .unwrap();
66//!
67//! // Format something:
68//! let datetime = DateTime {
69//!     date: Date::try_new_iso(2025, 1, 15).unwrap(),
70//!     time: Time::try_new(16, 9, 35, 0).unwrap(),
71//! };
72//! let formatted_date = dtf.format(&datetime);
73//!
74//! assert_writeable_eq!(formatted_date, "15 de ene de 2025, 4:09 p. m.");
75//! ```
76
77// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
78#![cfg_attr(not(any(test, doc)), no_std)]
79#![cfg_attr(
80    not(test),
81    deny(
82        clippy::indexing_slicing,
83        clippy::unwrap_used,
84        clippy::expect_used,
85        clippy::panic,
86        clippy::exhaustive_structs,
87        clippy::exhaustive_enums,
88        clippy::trivially_copy_pass_by_ref,
89        missing_debug_implementations,
90    )
91)]
92#![warn(missing_docs)]
93
94extern crate alloc;
95
96mod combo;
97mod error;
98mod external_loaders;
99pub mod fieldsets;
100mod format;
101mod neo;
102pub mod options;
103pub mod parts;
104pub mod pattern;
105pub mod provider;
106pub(crate) mod raw;
107pub mod scaffold;
108pub(crate) mod size_test_macro;
109pub mod unchecked;
110
111pub use error::{DateTimeFormatterLoadError, MismatchedCalendarError};
112
113pub use neo::DateTimeFormatter;
114pub use neo::DateTimeFormatterPreferences;
115pub use neo::FixedCalendarDateTimeFormatter;
116pub use neo::FormattedDateTime;
117pub use neo::NoCalendarFormatter;
118
119/// Locale preferences used by this crate
120pub mod preferences {
121    /// **This is a reexport of a type in [`icu::locale`](icu_locale_core::preferences::extensions::unicode::keywords)**.
122    #[doc = "\n"] // prevent autoformatting
123    pub use icu_locale_core::preferences::extensions::unicode::keywords::CalendarAlgorithm;
124    /// **This is a reexport of a type in [`icu::locale`](icu_locale_core::preferences::extensions::unicode::keywords)**.
125    #[doc = "\n"] // prevent autoformatting
126    pub use icu_locale_core::preferences::extensions::unicode::keywords::HijriCalendarAlgorithm;
127    /// **This is a reexport of a type in [`icu::locale`](icu_locale_core::preferences::extensions::unicode::keywords)**.
128    #[doc = "\n"] // prevent autoformatting
129    pub use icu_locale_core::preferences::extensions::unicode::keywords::HourCycle;
130    /// **This is a reexport of a type in [`icu::locale`](icu_locale_core::preferences::extensions::unicode::keywords)**.
131    #[doc = "\n"] // prevent autoformatting
132    pub use icu_locale_core::preferences::extensions::unicode::keywords::NumberingSystem;
133}
134
135/// Types that can be fed to [`DateTimeFormatter`]/[`FixedCalendarDateTimeFormatter`].
136///
137/// This module contains re-exports from the [`icu_calendar`] and [`icu_time`] crates.
138pub mod input {
139    pub use icu_calendar::Date;
140    pub use icu_time::zone::UtcOffset;
141    pub use icu_time::DateTime;
142    pub use icu_time::Time;
143    pub use icu_time::TimeZone;
144    pub use icu_time::TimeZoneInfo;
145    pub use icu_time::ZonedDateTime;
146}
icu_datetime/lib.rs

icu_datetime/
lib.rs
