ako/
calendar.rs

1//! Provides the [`Calendar`] trait which is used to define a **calendar** system.
2//!
3//! In **Ako**, several types have a type parameter of `Calendar`.
4//! This type parameter enables these types to be generic across different calendar systems,
5//! allowing for flexible and adaptable time representations.
6//!
7//! Humans traditionally divide time into components such as years, months, and days.
8//! There are
9//! multiple calendar systems in common use around the world, including the Gregorian, Julian,
10//! and Buddhist calendars.
11//! Each of these systems allows people to reference the same moments in
12//! time in various culturally specific ways.
13//!
14//! By default, this module uses the [ISO-8601] calendar, represented by the [`Iso`] type.
15//! The
16//! ISO-8601 calendar is an internationally accepted way to represent dates and times, and it is
17//! widely supported in most libraries and applications that deal with calendar systems.
18//! If you
19//! are unsure which calendar system to use, the ISO-8601 calendar is probably the best choice.
20//!
21//! [ISO-8601]: https://en.wikipedia.org/wiki/ISO_8601https://en.wikipedia.org/wiki/ISO_8601
22//!
23
24use core::hash::Hash;
25
26use crate::{Date, Month, Year, YearMonth};
27
28pub(crate) mod iso;
29
30pub use iso::Iso;
31
32/// A **calendar** system translates a generic “local timeline”
33/// into human-readable units such as years, months, and days.
34///
35pub trait Calendar: PartialEq + Eq + Hash + Copy + Clone + Sized + Send + Sync + 'static {
36    // Date
37
38    /// Obtains a [`Date`] for the `year`, `month`, and `day` on the calendar.
39    // TODO: Return ako::Result<_>
40    fn date(self, year: i32, month: u8, day: u8) -> crate::Result<Date<Self>>;
41
42    /// Gets the day-of-year of the given [`Date`].
43    #[doc(hidden)]
44    fn date_from_ordinal(self, year: i32, day: u16) -> crate::Result<Date<Self>>;
45
46    /// Gets the components of the given [`Date`].
47    #[doc(hidden)]
48    fn date_components(self, days: i32) -> (Year<Self>, Month<Self>, u8);
49
50    /// Gets the day-of-year of the given [`Date`].
51    #[doc(hidden)]
52    fn date_to_ordinal(self, days: i32) -> (Year<Self>, u16);
53
54    // Year
55
56    /// Obtains a [`Year`] for the `year`.
57    fn year(self, year: i32) -> crate::Result<Year<Self>>;
58
59    /// Checks if the `year` is a leap year.
60    #[doc(hidden)]
61    fn year_is_leap(self, year: i32) -> bool;
62
63    /// Gets the number of days in `year`.
64    #[doc(hidden)]
65    fn year_days(self, year: i32) -> u16;
66
67    /// Gets the number of months in `year`.
68    #[doc(hidden)]
69    fn year_months(self, year: i32) -> u8;
70
71    // YearMonth
72
73    /// Obtains a [`YearMonth`] for the `year` and `month`.
74    fn year_month(self, year: i32, month: u8) -> crate::Result<YearMonth<Self>>;
75
76    /// Gets the number of days in the `month` of a `year`.
77    #[doc(hidden)]
78    fn year_month_days(self, year: i32, month: u8) -> u8;
79}
ako/calendar.rs

ako/
calendar.rs
