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 calendrical_calculations::rata_die::RataDie;
6
7use crate::cal::iso::IsoDateInner;
8use crate::error::DateError;
9use crate::{types, DateDuration, DateDurationUnit};
10use core::fmt;
11
12/// A calendar implementation
13///
14/// Only implementors of [`Calendar`] should care about these methods, in general users of
15/// these calendars should use the methods on [`Date`](crate::Date) instead.
16///
17/// Individual [`Calendar`] implementations may have inherent utility methods
18/// allowing for direct construction, etc.
19///
20/// <div class="stab unstable">
21/// 🚫 This trait is sealed; it should not be implemented by user code. If an API requests an item that implements this
22/// trait, please consider using a type from the implementors listed below.
23///
24/// It is still possible to implement this trait in userland (since `UnstableSealed` is public),
25/// do not do so unless you are prepared for things to occasionally break.
26/// </div>
27pub trait Calendar: crate::cal::scaffold::UnstableSealed {
28    /// The internal type used to represent dates
29    type DateInner: Eq + Copy + fmt::Debug;
30    /// The type of YearInfo returned by the date
31    type Year: fmt::Debug + Into<types::YearInfo>;
32
33    /// Construct a date from era/month codes and fields
34    ///
35    /// The year is extended_year if no era is provided
36    #[allow(clippy::wrong_self_convention)]
37    fn from_codes(
38        &self,
39        era: Option<&str>,
40        year: i32,
41        month_code: types::MonthCode,
42        day: u8,
43    ) -> Result<Self::DateInner, DateError>;
44
45    /// Construct the date from an ISO date
46    #[allow(clippy::wrong_self_convention)]
47    fn from_iso(&self, iso: IsoDateInner) -> Self::DateInner;
48    /// Obtain an ISO date from this date
49    fn to_iso(&self, date: &Self::DateInner) -> IsoDateInner;
50
51    /// Construct the date from a [`RataDie`]
52    #[allow(clippy::wrong_self_convention)]
53    fn from_rata_die(&self, rd: RataDie) -> Self::DateInner;
54    /// Obtain a [`RataDie`] from this date
55    fn to_rata_die(&self, date: &Self::DateInner) -> RataDie;
56
57    /// Count the number of months in a given year, specified by providing a date
58    /// from that year
59    fn months_in_year(&self, date: &Self::DateInner) -> u8;
60    /// Count the number of days in a given year, specified by providing a date
61    /// from that year
62    fn days_in_year(&self, date: &Self::DateInner) -> u16;
63    /// Count the number of days in a given month, specified by providing a date
64    /// from that year/month
65    fn days_in_month(&self, date: &Self::DateInner) -> u8;
66    /// Calculate if a date is in a leap year
67    fn is_in_leap_year(&self, date: &Self::DateInner) -> bool;
68
69    /// Information about the year
70    fn year_info(&self, date: &Self::DateInner) -> Self::Year;
71    /// The extended year value
72    fn extended_year(&self, date: &Self::DateInner) -> i32;
73    /// The calendar-specific month represented by `date`
74    fn month(&self, date: &Self::DateInner) -> types::MonthInfo;
75    /// The calendar-specific day-of-month represented by `date`
76    fn day_of_month(&self, date: &Self::DateInner) -> types::DayOfMonth;
77    /// Information of the day of the year
78    fn day_of_year(&self, date: &Self::DateInner) -> types::DayOfYear;
79
80    #[doc(hidden)] // unstable
81    /// Add `offset` to `date`
82    fn offset_date(&self, date: &mut Self::DateInner, offset: DateDuration<Self>);
83    #[doc(hidden)] // unstable
84    /// Calculate `date2 - date` as a duration
85    ///
86    /// `calendar2` is the calendar object associated with `date2`. In case the specific calendar objects
87    /// differ on data, the data for the first calendar is used, and `date2` may be converted if necessary.
88    fn until(
89        &self,
90        date1: &Self::DateInner,
91        date2: &Self::DateInner,
92        calendar2: &Self,
93        largest_unit: DateDurationUnit,
94        smallest_unit: DateDurationUnit,
95    ) -> DateDuration<Self>;
96
97    /// Returns the [`CalendarAlgorithm`](crate::preferences::CalendarAlgorithm) that is required to match
98    /// when parsing into this calendar.
99    ///
100    /// If left empty, any algorithm will parse successfully.
101    fn calendar_algorithm(&self) -> Option<crate::preferences::CalendarAlgorithm>;
102
103    /// Obtain a name for the calendar for debug printing
104    fn debug_name(&self) -> &'static str;
105}
icu_calendar/calendar.rs

icu_calendar/
calendar.rs
