icu_calendar/
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//! Types for dealing with dates and custom calendars.
6//!
7//! This module is published as its own crate ([`icu_calendar`](https://docs.rs/icu_calendar/latest/icu_calendar/))
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//! The [`types`] module has a lot of common types for dealing with dates.
10//!
11//! [`Calendar`] is a trait that allows one to define custom calendars, and [`Date`]
12//! can represent dates for arbitrary calendars.
13//!
14//! The [`Iso`] and [`Gregorian`] types are implementations for the ISO and
15//! Gregorian calendars respectively. Further calendars can be found in the [`cal`] module.
16//!
17//! Most interaction with this crate will be done via the [`Date`] type.
18//!
19//! Some of the algorithms implemented here are based on
20//! Dershowitz, Nachum, and Edward M. Reingold. _Calendrical calculations_. Cambridge University Press, 2008.
21//! with associated Lisp code found at <https://github.com/EdReingold/calendar-code2>.
22//!
23//! # Examples
24//!
25//! Examples of date manipulation using `Date` object. `Date` objects are useful
26//! for working with dates, encompassing information about the day, month, year,
27//! as well as the calendar type.
28//!
29//! ```rust
30//! use icu::calendar::{types::Weekday, Date};
31//!
32//! // Creating ISO date: 1992-09-02.
33//! let mut date_iso = Date::try_new_iso(1992, 9, 2)
34//!     .expect("Failed to initialize ISO Date instance.");
35//!
36//! assert_eq!(date_iso.day_of_week(), Weekday::Wednesday);
37//! assert_eq!(date_iso.era_year().year, 1992);
38//! assert_eq!(date_iso.month().ordinal, 9);
39//! assert_eq!(date_iso.day_of_month().0, 2);
40//!
41//! // Answering questions about days in month and year.
42//! assert_eq!(date_iso.days_in_year(), 366);
43//! assert_eq!(date_iso.days_in_month(), 30);
44//! ```
45//!
46//! Example of converting an ISO date across Indian and Buddhist calendars.
47//!
48//! ```rust
49//! use icu::calendar::cal::{Buddhist, Indian};
50//! use icu::calendar::Date;
51//!
52//! // Creating ISO date: 1992-09-02.
53//! let mut date_iso = Date::try_new_iso(1992, 9, 2)
54//!     .expect("Failed to initialize ISO Date instance.");
55//!
56//! assert_eq!(date_iso.era_year().year, 1992);
57//! assert_eq!(date_iso.month().ordinal, 9);
58//! assert_eq!(date_iso.day_of_month().0, 2);
59//!
60//! // Conversion into Indian calendar: 1914-08-02.
61//! let date_indian = date_iso.to_calendar(Indian);
62//! assert_eq!(date_indian.era_year().year, 1914);
63//! assert_eq!(date_indian.month().ordinal, 6);
64//! assert_eq!(date_indian.day_of_month().0, 11);
65//!
66//! // Conversion into Buddhist calendar: 2535-09-02.
67//! let date_buddhist = date_iso.to_calendar(Buddhist);
68//! assert_eq!(date_buddhist.era_year().year, 2535);
69//! assert_eq!(date_buddhist.month().ordinal, 9);
70//! assert_eq!(date_buddhist.day_of_month().0, 2);
71//! ```
72//!
73//! [`ICU4X`]: ../icu/index.html
74
75// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
76#![cfg_attr(not(any(test, doc)), no_std)]
77#![cfg_attr(
78    not(test),
79    deny(
80        clippy::indexing_slicing,
81        clippy::unwrap_used,
82        clippy::expect_used,
83        clippy::panic,
84        clippy::exhaustive_structs,
85        clippy::exhaustive_enums,
86        clippy::trivially_copy_pass_by_ref,
87        missing_debug_implementations,
88    )
89)]
90#![warn(missing_docs)]
91// It's not worth it to try and maintain clean import lists for both
92// stable and unstable mode when the code is so entangled.
93#![cfg_attr(not(feature = "unstable"), allow(unused))]
94
95#[cfg(feature = "alloc")]
96extern crate alloc;
97
98// Make sure inherent docs go first
99mod date;
100
101// Public modules
102mod any_calendar;
103pub mod cal;
104pub mod options;
105pub mod provider;
106pub mod types;
107pub mod week;
108
109mod calendar;
110mod calendar_arithmetic;
111mod duration;
112pub mod error;
113#[cfg(feature = "ixdtf")]
114mod ixdtf;
115
116// Top-level types
117pub use any_calendar::IntoAnyCalendar;
118pub use calendar::Calendar;
119pub use date::{AsCalendar, Date, Ref};
120pub use error::{DateError, RangeError};
121#[cfg(feature = "ixdtf")]
122pub use ixdtf::ParseError;
123
124// Reexports
125#[doc(no_inline)]
126pub use cal::{AnyCalendar, AnyCalendarKind, Gregorian, Iso};
127
128/// Locale preferences used by this crate
129pub mod preferences {
130    pub use crate::any_calendar::CalendarPreferences;
131    #[doc(inline)]
132    /// **This is a reexport of a type in [`icu::locale`](icu_locale_core::preferences::extensions::unicode::keywords)**.
133    #[doc = "\n"] // prevent autoformatting
134    pub use icu_locale_core::preferences::extensions::unicode::keywords::CalendarAlgorithm;
135    #[doc(inline)]
136    /// **This is a reexport of a type in [`icu::locale`](icu_locale_core::preferences::extensions::unicode::keywords)**.
137    #[doc = "\n"] // prevent autoformatting
138    pub use icu_locale_core::preferences::extensions::unicode::keywords::HijriCalendarAlgorithm;
139}
140
141#[cfg(test)]
142mod tests;
icu_calendar/lib.rs

icu_calendar/
lib.rs
