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
92#[cfg(feature = "alloc")]
93extern crate alloc;
94
95// Make sure inherent docs go first
96mod date;
97
98// Public modules
99mod any_calendar;
100pub mod cal;
101pub mod provider;
102pub mod types;
103pub mod week;
104
105mod calendar;
106mod calendar_arithmetic;
107mod duration;
108mod error;
109#[cfg(feature = "ixdtf")]
110mod ixdtf;
111
112// Top-level types
113pub use any_calendar::IntoAnyCalendar;
114pub use calendar::Calendar;
115pub use date::{AsCalendar, Date, Ref};
116#[doc(hidden)] // unstable
117pub use duration::{DateDuration, DateDurationUnit};
118pub use error::{DateError, RangeError};
119#[cfg(feature = "ixdtf")]
120pub use ixdtf::ParseError;
121
122// Reexports
123#[doc(no_inline)]
124pub use cal::{AnyCalendar, AnyCalendarKind, Gregorian, Iso};
125
126/// Locale preferences used by this crate
127pub mod preferences {
128    pub use crate::any_calendar::CalendarPreferences;
129    #[doc(inline)]
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::CalendarAlgorithm;
133    #[doc(inline)]
134    /// **This is a reexport of a type in [`icu::locale`](icu_locale_core::preferences::extensions::unicode::keywords)**.
135    #[doc = "\n"] // prevent autoformatting
136    pub use icu_locale_core::preferences::extensions::unicode::keywords::HijriCalendarAlgorithm;
137}
138
139#[cfg(test)]
140mod tests;
icu_calendar/lib.rs

icu_calendar/
lib.rs
