icu_calendar/
calendar.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
5use crate::any_calendar::AnyCalendarKind;
6use crate::{types, CalendarError, Date, DateDuration, DateDurationUnit, Iso};
7use core::fmt;
8
9/// A calendar implementation
10///
11/// Only implementors of [`Calendar`] should care about these methods, in general users of
12/// these calendars should use the methods on [`Date`] instead.
13///
14/// Individual [`Calendar`] implementations may have inherent utility methods
15/// allowing for direct construction, etc.
16///
17/// For ICU4X 1.0, implementing this trait or calling methods directly is considered
18/// unstable and prone to change, especially for `offset_date()` and `until()`.
19pub trait Calendar {
20    /// The internal type used to represent dates
21    type DateInner: PartialEq + Eq + Clone + fmt::Debug;
22    /// Construct a date from era/month codes and fields
23    fn date_from_codes(
24        &self,
25        era: types::Era,
26        year: i32,
27        month_code: types::MonthCode,
28        day: u8,
29    ) -> Result<Self::DateInner, CalendarError>;
30    /// Construct the date from an ISO date
31    fn date_from_iso(&self, iso: Date<Iso>) -> Self::DateInner;
32    /// Obtain an ISO date from this date
33    fn date_to_iso(&self, date: &Self::DateInner) -> Date<Iso>;
34    // fn validate_date(&self, e: Era, y: Year, m: MonthCode, d: Day) -> bool;
35    // // similar validators for YearMonth, etc
36
37    // fn is_leap<A: AsCalendar<Calendar = Self>>(&self, date: &Date<A>) -> bool;
38    /// Count the number of months in a given year, specified by providing a date
39    /// from that year
40    fn months_in_year(&self, date: &Self::DateInner) -> u8;
41    /// Count the number of days in a given year, specified by providing a date
42    /// from that year
43    fn days_in_year(&self, date: &Self::DateInner) -> u16;
44    /// Count the number of days in a given month, specified by providing a date
45    /// from that year/month
46    fn days_in_month(&self, date: &Self::DateInner) -> u8;
47    /// Calculate the day of the week and return it
48    fn day_of_week(&self, date: &Self::DateInner) -> types::IsoWeekday {
49        self.date_to_iso(date).day_of_week()
50    }
51    // fn week_of_year(&self, date: &Self::DateInner) -> u8;
52
53    #[doc(hidden)] // unstable
54    /// Add `offset` to `date`
55    fn offset_date(&self, date: &mut Self::DateInner, offset: DateDuration<Self>);
56
57    #[doc(hidden)] // unstable
58    /// Calculate `date2 - date` as a duration
59    ///
60    /// `calendar2` is the calendar object associated with `date2`. In case the specific calendar objects
61    /// differ on data, the data for the first calendar is used, and `date2` may be converted if necessary.
62    fn until(
63        &self,
64        date1: &Self::DateInner,
65        date2: &Self::DateInner,
66        calendar2: &Self,
67        largest_unit: DateDurationUnit,
68        smallest_unit: DateDurationUnit,
69    ) -> DateDuration<Self>;
70
71    /// Obtain a name for the calendar for debug printing
72    fn debug_name(&self) -> &'static str;
73    // fn since(&self, from: &Date<Self>, to: &Date<Self>) -> Duration<Self>, Error;
74
75    /// The calendar-specific year represented by `date`
76    fn year(&self, date: &Self::DateInner) -> types::FormattableYear;
77
78    /// Calculate if a date is in a leap year
79    fn is_in_leap_year(&self, date: &Self::DateInner) -> bool;
80
81    /// The calendar-specific month represented by `date`
82    fn month(&self, date: &Self::DateInner) -> types::FormattableMonth;
83
84    /// The calendar-specific day-of-month represented by `date`
85    fn day_of_month(&self, date: &Self::DateInner) -> types::DayOfMonth;
86
87    /// Information of the day of the year
88    fn day_of_year_info(&self, date: &Self::DateInner) -> types::DayOfYearInfo;
89
90    /// The [`AnyCalendarKind`] corresponding to this calendar,
91    /// if one exists. Implementors outside of `icu::calendar` should return `None`
92    fn any_calendar_kind(&self) -> Option<AnyCalendarKind> {
93        None
94    }
95}
icu_calendar/calendar.rs

icu_calendar/
calendar.rs
