Types for dealing with dates, times, and custom calendars.
This module is published as its own crate (icu_calendar)
and as part of the icu crate. See the latter for more details on the ICU4X project.
The [types] module has a lot of common types for dealing with dates and times.
[Calendar] is a trait that allows one to define custom calendars, and [Date]
can represent dates for arbitrary calendars.
The [iso] and [gregorian] modules contain implementations for the ISO and
Gregorian calendars respectively. Further calendars can be found in modules like
[japanese], [julian], [coptic], [indian], [buddhist], and [ethiopian].
Most interaction with this crate will be done via the [Date] and [DateTime] types.
Some of the algorithms implemented here are based on Dershowitz, Nachum, and Edward M. Reingold. Calendrical calculations. Cambridge University Press, 2008. with associated Lisp code found at https://github.com/EdReingold/calendar-code2.
Examples of date manipulation using Date object. Date objects are useful
for working with dates, encompassing information about the day, month, year,
as well as the calendar type.
```rust use icu::calendar::{types::IsoWeekday, Date};
// Creating ISO date: 1992-09-02. let mut dateiso = Date::trynewisodate(1992, 9, 2) .expect("Failed to initialize ISO Date instance.");
asserteq!(dateiso.dayofweek(), IsoWeekday::Wednesday); asserteq!(dateiso.year().number, 1992); asserteq!(dateiso.month().ordinal, 9); asserteq!(dateiso.dayofmonth().0, 2);
// Answering questions about days in month and year. asserteq!(dateiso.daysinyear(), 366); asserteq!(dateiso.daysinmonth(), 30); ```
Example of converting an ISO date across Indian and Buddhist calendars.
```rust use icu::calendar::{buddhist::Buddhist, indian::Indian, Date};
// Creating ISO date: 1992-09-02. let mut dateiso = Date::trynewisodate(1992, 9, 2) .expect("Failed to initialize ISO Date instance.");
asserteq!(dateiso.year().number, 1992); asserteq!(dateiso.month().ordinal, 9); asserteq!(dateiso.dayofmonth().0, 2);
// Conversion into Indian calendar: 1914-08-02. let dateindian = dateiso.tocalendar(Indian); asserteq!(dateindian.year().number, 1914); asserteq!(dateindian.month().ordinal, 6); asserteq!(dateindian.dayof_month().0, 11);
// Conversion into Buddhist calendar: 2535-09-02. let datebuddhist = dateiso.tocalendar(Buddhist); asserteq!(datebuddhist.year().number, 2535); asserteq!(datebuddhist.month().ordinal, 9); asserteq!(datebuddhist.dayof_month().0, 2); ```
Example using DateTime object. Similar to Date objects, DateTime objects
contain an accessible Date object containing information about the day, month,
year, and calendar type. Additionally, DateTime objects contain an accessible
Time object, including granularity of hour, minute, second, and nanosecond.
```rust use icu::calendar::{types::IsoWeekday, types::Time, DateTime};
// Creating ISO date: 1992-09-02 8:59 let mut datetimeiso = DateTime::trynewisodatetime(1992, 9, 2, 8, 59, 0) .expect("Failed to initialize ISO DateTime instance.");
asserteq!(datetimeiso.date.dayofweek(), IsoWeekday::Wednesday); asserteq!(datetimeiso.date.year().number, 1992); asserteq!(datetimeiso.date.month().ordinal, 9); asserteq!(datetimeiso.date.dayofmonth().0, 2); asserteq!(datetimeiso.time.hour.number(), 8); asserteq!(datetimeiso.time.minute.number(), 59); asserteq!(datetimeiso.time.second.number(), 0); asserteq!(datetimeiso.time.nanosecond.number(), 0); ```
For more information on development, authorship, contributing etc. please visit ICU4X home page.