icu_calendar

The icu_calendar crate contains the core types used by ICU4X for dealing with dates, times, and custom calendars.

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.

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

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::{Date, DateDuration, DateDurationUnit, types::IsoWeekday};

// Creating ISO date: 1992-09-02. let mut dateiso = Date::newisodatefromintegers(1992, 9, 2).unwrap(); asserteq!(dateiso.dayofweek(), IsoWeekday::Wednesday); asserteq!(dateiso.year().number, 1992); asserteq!(dateiso.month().number, 9); asserteq!(dateiso.dayof_month().0, 2);

// Answering questions about days in month and year. asserteq!(dateiso.daysinyear(), 366); asserteq!(dateiso.daysinmonth(), 30);

// Advancing date in-place by 1 year, 2 months, 3 weeks, 4 days. dateiso.add(DateDuration::new(1, 2, 3, 4)); asserteq!(dateiso.year().number, 1993); asserteq!(dateiso.month().number, 11); asserteq!(dateiso.dayof_month().0, 27);

// Reverse date advancement. dateiso.add(DateDuration::new(-1, -2, -3, -4)); asserteq!(dateiso.year().number, 1992); asserteq!(dateiso.month().number, 9); asserteq!(dateiso.dayof_month().0, 2);

// Creating ISO date: 2022-01-30. let newerdateiso = Date::newisodatefromintegers(2022, 1, 30).unwrap();

// Comparing dates: 2022-01-30 and 1992-09-02. let duration = newerdateiso.until(&dateiso, DateDurationUnit::Years, DateDurationUnit::Days); asserteq!(duration.years, 30); asserteq!(duration.months, -8); asserteq!(duration.days, 28);

// Create new date with date advancement. Reassign to new variable. let mutateddateiso = dateiso.added(DateDuration::new(1, 2, 3, 4)); asserteq!(mutateddateiso.year().number, 1993); asserteq!(mutateddateiso.month().number, 11); asserteq!(mutateddateiso.dayofmonth().0, 27); ```

Example of converting an ISO date across Indian and Buddhist calendars.

```rust use icu_calendar::{Date, buddhist::Buddhist, indian::Indian};

// Creating ISO date: 1992-09-02. let mut dateiso = Date::newisodatefromintegers(1992, 9, 2).unwrap(); asserteq!(dateiso.year().number, 1992); asserteq!(dateiso.month().number, 9); asserteq!(dateiso.dayof_month().0, 2);

// Conversion into Indian calendar: 1914-08-02. let dateindian = dateiso.tocalendar(Indian); asserteq!(dateindian.year().number, 1914); asserteq!(dateindian.month().number, 8); asserteq!(dateindian.dayof_month().0, 30);

// Conversion into Buddhist calendar: 2535-09-02. let datebuddhist = dateiso.tocalendar(Buddhist); asserteq!(datebuddhist.year().number, 2535); asserteq!(datebuddhist.month().number, 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::{DateTime, DateDuration, types::IsoWeekday, types::IsoHour, types::IsoMinute, types::IsoSecond, types::NanoSecond, types::Time};

// Creating ISO date: 1992-09-02 8:59 let mut datetimeiso = DateTime::newisodatetimefromintegers(1992, 9, 2, 8, 59, 0).unwrap(); asserteq!(datetimeiso.date.dayofweek(), IsoWeekday::Wednesday); asserteq!(datetimeiso.date.year().number, 1992); asserteq!(datetimeiso.date.month().number, 9); asserteq!(datetimeiso.date.dayofmonth().0, 2); asserteq!(datetimeiso.time.hour, IsoHour::newunchecked(8)); asserteq!(datetimeiso.time.minute, IsoMinute::newunchecked(59)); asserteq!(datetimeiso.time.second, IsoSecond::newunchecked(0)); asserteq!(datetimeiso.time.nanosecond, NanoSecond::new_unchecked(0));

// Advancing date by 1 year, 2 months, 3 weeks, 4 days. datetimeiso.date.add(DateDuration::new(1, 2, 3, 4)); // New time of 14:30 datetimeiso.time = Time::try_new(14, 30, 0, 0).unwrap();

asserteq!(datetimeiso.date.year().number, 1993); asserteq!(datetimeiso.date.month().number, 11); asserteq!(datetimeiso.date.dayofmonth().0, 27); asserteq!(datetimeiso.time.hour, IsoHour::newunchecked(14)); asserteq!(datetimeiso.time.minute, IsoMinute::newunchecked(30)); asserteq!(datetimeiso.time.second, IsoSecond::newunchecked(0)); asserteq!(datetimeiso.time.nanosecond, NanoSecond::newunchecked(0)); ```

More Information

For more information on development, authorship, contributing etc. please visit ICU4X home page.