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, times, 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 and times.
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`] modules contain implementations for the ISO and
15//! Gregorian calendars respectively. Further calendars can be found in modules like
16//! [`japanese`], [`julian`], [`coptic`], [`indian`], [`buddhist`], and [`ethiopian`].
17//!
18//! Most interaction with this crate will be done via the [`Date`] and [`DateTime`] types.
19//!
20//! Some of the algorithms implemented here are based on
21//! Dershowitz, Nachum, and Edward M. Reingold. _Calendrical calculations_. Cambridge University Press, 2008.
22//! with associated Lisp code found at <https://github.com/EdReingold/calendar-code2>.
23//!
24//! # Examples
25//!
26//! Examples of date manipulation using `Date` object. `Date` objects are useful
27//! for working with dates, encompassing information about the day, month, year,
28//! as well as the calendar type.
29//!
30//! ```rust
31//! use icu::calendar::{types::IsoWeekday, Date};
32//!
33//! // Creating ISO date: 1992-09-02.
34//! let mut date_iso = Date::try_new_iso_date(1992, 9, 2)
35//!     .expect("Failed to initialize ISO Date instance.");
36//!
37//! assert_eq!(date_iso.day_of_week(), IsoWeekday::Wednesday);
38//! assert_eq!(date_iso.year().number, 1992);
39//! assert_eq!(date_iso.month().ordinal, 9);
40//! assert_eq!(date_iso.day_of_month().0, 2);
41//!
42//! // Answering questions about days in month and year.
43//! assert_eq!(date_iso.days_in_year(), 366);
44//! assert_eq!(date_iso.days_in_month(), 30);
45//! ```
46//!
47//! Example of converting an ISO date across Indian and Buddhist calendars.
48//!
49//! ```rust
50//! use icu::calendar::{buddhist::Buddhist, indian::Indian, Date};
51//!
52//! // Creating ISO date: 1992-09-02.
53//! let mut date_iso = Date::try_new_iso_date(1992, 9, 2)
54//!     .expect("Failed to initialize ISO Date instance.");
55//!
56//! assert_eq!(date_iso.year().number, 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.year().number, 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.year().number, 2535);
69//! assert_eq!(date_buddhist.month().ordinal, 9);
70//! assert_eq!(date_buddhist.day_of_month().0, 2);
71//! ```
72//!
73//! Example using `DateTime` object. Similar to `Date` objects, `DateTime` objects
74//! contain an accessible `Date` object containing information about the day, month,
75//! year, and calendar type. Additionally, `DateTime` objects contain an accessible
76//! `Time` object, including granularity of hour, minute, second, and nanosecond.
77//!
78//! ```rust
79//! use icu::calendar::{types::IsoWeekday, DateTime, Time};
80//!
81//! // Creating ISO date: 1992-09-02 8:59
82//! let mut datetime_iso = DateTime::try_new_iso_datetime(1992, 9, 2, 8, 59, 0)
83//!     .expect("Failed to initialize ISO DateTime instance.");
84//!
85//! assert_eq!(datetime_iso.date.day_of_week(), IsoWeekday::Wednesday);
86//! assert_eq!(datetime_iso.date.year().number, 1992);
87//! assert_eq!(datetime_iso.date.month().ordinal, 9);
88//! assert_eq!(datetime_iso.date.day_of_month().0, 2);
89//! assert_eq!(datetime_iso.time.hour.number(), 8);
90//! assert_eq!(datetime_iso.time.minute.number(), 59);
91//! assert_eq!(datetime_iso.time.second.number(), 0);
92//! assert_eq!(datetime_iso.time.nanosecond.number(), 0);
93//! ```
94//! [`ICU4X`]: ../icu/index.html
95
96// https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations
97#![cfg_attr(not(any(test, feature = "std")), no_std)]
98#![cfg_attr(
99    not(test),
100    deny(
101        clippy::indexing_slicing,
102        clippy::unwrap_used,
103        clippy::expect_used,
104        clippy::panic,
105        clippy::exhaustive_structs,
106        clippy::exhaustive_enums,
107        missing_debug_implementations,
108    )
109)]
110#![warn(missing_docs)]
111
112extern crate alloc;
113
114// Make sure inherent docs go first
115mod date;
116mod datetime;
117
118pub mod any_calendar;
119pub mod buddhist;
120mod calendar;
121mod calendar_arithmetic;
122pub mod chinese;
123mod chinese_based;
124pub mod coptic;
125pub mod dangi;
126mod duration;
127mod error;
128pub mod ethiopian;
129pub mod gregorian;
130pub mod hebrew;
131pub mod indian;
132pub mod islamic;
133pub mod iso;
134pub mod japanese;
135pub mod julian;
136pub mod persian;
137pub mod provider;
138pub mod roc;
139#[cfg(test)]
140mod tests;
141pub mod types;
142mod week_of;
143
144pub mod week {
145    //! Functions for week-of-month and week-of-year arithmetic.
146    use crate::week_of;
147    pub use week_of::RelativeUnit;
148    pub use week_of::WeekCalculator;
149    pub use week_of::WeekOf;
150    #[doc(hidden)]
151    pub use week_of::MIN_UNIT_DAYS;
152}
153
154#[doc(no_inline)]
155pub use any_calendar::{AnyCalendar, AnyCalendarKind};
156pub use calendar::Calendar;
157pub use date::{AsCalendar, Date, Ref};
158pub use datetime::DateTime;
159#[doc(hidden)]
160pub use duration::{DateDuration, DateDurationUnit};
161pub use error::CalendarError;
162#[doc(no_inline)]
163pub use gregorian::Gregorian;
164#[doc(no_inline)]
165pub use iso::Iso;
166pub use types::Time;
167
168#[doc(no_inline)]
169pub use CalendarError as Error;
icu_calendar/lib.rs

icu_calendar/
lib.rs
