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