General HijriTabular constructor (#6406)

#6330 

#6397

Author: robertbastian

components/calendar/benches/convert.rs

@@ -78,7 +78,10 @@ fn convert_benches(c: &mut Criterion) {
     bench_calendar(
         &mut group,
         "calendar/islamic/civil",
-        icu::calendar::cal::HijriTabular::new_civil_epoch(),
+        icu::calendar::cal::HijriTabular::new(
+            icu::calendar::cal::HijriTabularEpoch::Friday,
+            icu::calendar::cal::HijriTabularLeapYears::TypeII,
+        ),
     );
 
     bench_calendar(
@@ -90,7 +93,10 @@ fn convert_benches(c: &mut Criterion) {
     bench_calendar(
         &mut group,
         "calendar/islamic/tabular",
-        icu::calendar::cal::HijriTabular::new_astronomical_epoch(),
+        icu::calendar::cal::HijriTabular::new(
+            icu::calendar::cal::HijriTabularEpoch::Thursday,
+            icu::calendar::cal::HijriTabularLeapYears::TypeII,
+        ),
     );
 
     group.finish();

components/calendar/benches/date.rs

@@ -197,13 +197,19 @@ fn date_benches(c: &mut Criterion) {
         &mut group,
         "calendar/islamic/civil",
         &fxs,
-        icu::calendar::cal::HijriTabular::new_civil_epoch(),
+        icu::calendar::cal::HijriTabular::new(
+            icu::calendar::cal::HijriTabularEpoch::Friday,
+            icu::calendar::cal::HijriTabularLeapYears::TypeII,
+        ),
         |y, m, d| {
             Date::try_new_hijri_tabular_with_calendar(
                 y,
                 m,
                 d,
-                icu::calendar::cal::HijriTabular::new_civil_epoch(),
+                icu::calendar::cal::HijriTabular::new(
+                    icu::calendar::cal::HijriTabularEpoch::Friday,
+                    icu::calendar::cal::HijriTabularLeapYears::TypeII,
+                ),
             )
             .unwrap()
         },
@@ -213,13 +219,19 @@ fn date_benches(c: &mut Criterion) {
         &mut group,
         "calendar/islamic/tabular",
         &fxs,
-        icu::calendar::cal::HijriTabular::new_astronomical_epoch(),
+        icu::calendar::cal::HijriTabular::new(
+            icu::calendar::cal::HijriTabularEpoch::Thursday,
+            icu::calendar::cal::HijriTabularLeapYears::TypeII,
+        ),
         |y, m, d| {
             Date::try_new_hijri_tabular_with_calendar(
                 y,
                 m,
                 d,
-                icu::calendar::cal::HijriTabular::new_astronomical_epoch(),
+                icu::calendar::cal::HijriTabular::new(
+                    icu::calendar::cal::HijriTabularEpoch::Thursday,
+                    icu::calendar::cal::HijriTabularLeapYears::TypeII,
+                ),
             )
             .unwrap()
         },

components/calendar/src/any_calendar.rs

@@ -95,10 +95,11 @@ pub struct HijriUmmAlQura {
 #[derive(Debug, Clone, Copy)]
 pub struct HijriUmmAlQuraMarker;
 
-/// The [tabular Hijri Calendar](https://en.wikipedia.org/wiki/Tabular_Islamic_calendar) (astronomical epoch)
+/// The [tabular Hijri Calendar](https://en.wikipedia.org/wiki/Tabular_Islamic_calendar).
 ///
-/// This is a tabular/arithmetic Hijri calendar with leap years (1-based) 2, 5, 7, 10,
-/// 13, 16, 18, 21, 24, 26, and 29 in the 30-year cycle.
+/// See [`HijriTabularEpoch`] and [`HijriTabularLeapYears`] for customization.
+///
+/// The most common version of this calendar uses [`HijriTabularEpoch::Friday`] and [`HijriTabularLeapYears::TypeII`].
 ///
 /// # Era codes
 ///
@@ -111,7 +112,10 @@ pub struct HijriUmmAlQuraMarker;
 /// This calendar is a pure lunar calendar with no leap months. It uses month codes
 /// `"M01" - "M12"`.
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)]
-pub struct HijriTabular(pub(crate) RataDie);
+pub struct HijriTabular {
+    pub(crate) epoch: HijriTabularEpoch,
+    pub(crate) leap_years: HijriTabularLeapYears,
+}
 
 impl HijriSimulated {
     /// Creates a new [`HijriSimulated`] for reference location Mecca, with some compiled data containing precomputed calendrical calculations.
@@ -226,21 +230,40 @@ impl HijriUmmAlQura {
     }
 }
 
-impl HijriTabular {
-    /// Construct a new [`HijriTabular`] with the civil/Friday epoch. That is,
-    /// the year 1 starts on Friday July 16, 622 AD (0622-07-19 ISO).
-    ///
-    /// This is the most common version of the tabular Hijri calendar.
-    pub const fn new_civil_epoch() -> Self {
-        Self(ISLAMIC_EPOCH_FRIDAY)
+/// The epoch for the [`HijriTabular`] calendar.
+#[non_exhaustive]
+#[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)]
+pub enum HijriTabularEpoch {
+    /// Thusday July 15, 622 AD (0622-07-18 ISO)
+    Thursday,
+    /// Friday July 16, 622 AD (0622-07-19 ISO)
+    Friday,
+}
+
+impl HijriTabularEpoch {
+    fn rata_die(self) -> RataDie {
+        match self {
+            Self::Thursday => ISLAMIC_EPOCH_THURSDAY,
+            Self::Friday => ISLAMIC_EPOCH_FRIDAY,
+        }
     }
+}
 
-    /// Construct a new [`HijriTabular`] with the astronomical/Thursday epoch.
-    /// That is, the AH era starts on Thusday July 15, 622 AD (0622-07-18 ISO).
-    ///
-    /// This version of the calendar is also known as the "Microsoft Kuwaiti calendar".
-    pub const fn new_astronomical_epoch() -> Self {
-        Self(ISLAMIC_EPOCH_THURSDAY)
+/// The leap year rule for the [`HijriTabular`] calendar.
+///
+/// This specifies which years of a 30-year cycle have an additional day at
+/// the end of the year.
+#[non_exhaustive]
+#[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)]
+pub enum HijriTabularLeapYears {
+    /// Leap years 2, 5, 7, 10, 13, 16, 18, 21, 24, 26, 29
+    TypeII,
+}
+
+impl HijriTabular {
+    /// Construct a new [`HijriTabular`] with the given epoch and leap year rule.
+    pub const fn new(epoch: HijriTabularEpoch, leap_years: HijriTabularLeapYears) -> Self {
+        Self { epoch, leap_years }
     }
 }
 
@@ -960,28 +983,39 @@ impl Calendar for HijriTabular {
     ) -> Result<Self::DateInner, DateError> {
         let year = match era {
             Some("ah") | None => year,
-            Some("islamic-civil" | "islamicc") if self.0 == ISLAMIC_EPOCH_FRIDAY => year,
-            Some("islamic-tbla") if self.0 == ISLAMIC_EPOCH_THURSDAY => year,
+            Some("islamic-civil" | "islamicc") if self.epoch == HijriTabularEpoch::Friday => year,
+            Some("islamic-tbla") if self.epoch == HijriTabularEpoch::Thursday => year,
             Some(_) => return Err(DateError::UnknownEra),
         };
 
         ArithmeticDate::new_from_codes(self, year, month_code, day).map(HijriTabularDateInner)
     }
 
     fn from_rata_die(&self, rd: RataDie) -> Self::DateInner {
-        let (y, m, d) = calendrical_calculations::islamic::tabular_islamic_from_fixed(rd, self.0);
+        let (y, m, d) = match self.leap_years {
+            HijriTabularLeapYears::TypeII => {
+                calendrical_calculations::islamic::tabular_islamic_from_fixed(
+                    rd,
+                    self.epoch.rata_die(),
+                )
+            }
+        };
 
         debug_assert!(Date::try_new_hijri_tabular_with_calendar(y, m, d, crate::Ref(self)).is_ok());
         HijriTabularDateInner(ArithmeticDate::new_unchecked(y, m, d))
     }
 
     fn to_rata_die(&self, date: &Self::DateInner) -> RataDie {
-        calendrical_calculations::islamic::fixed_from_tabular_islamic(
-            date.0.year,
-            date.0.month,
-            date.0.day,
-            self.0,
-        )
+        match self.leap_years {
+            HijriTabularLeapYears::TypeII => {
+                calendrical_calculations::islamic::fixed_from_tabular_islamic(
+                    date.0.year,
+                    date.0.month,
+                    date.0.day,
+                    self.epoch.rata_die(),
+                )
+            }
+        }
     }
 
     fn from_iso(&self, iso: IsoDateInner) -> Self::DateInner {
@@ -1020,18 +1054,17 @@ impl Calendar for HijriTabular {
     }
 
     fn debug_name(&self) -> &'static str {
-        match self.0 {
-            ISLAMIC_EPOCH_FRIDAY => "Hijri (civil)",
-            _ => "Hijri (astronomical)",
+        match self.epoch {
+            HijriTabularEpoch::Friday => "Hijri (civil)",
+            HijriTabularEpoch::Thursday => "Hijri (astronomical)",
         }
     }
 
     fn year(&self, date: &Self::DateInner) -> types::YearInfo {
         year_as_hijri(
-            if self.0 == ISLAMIC_EPOCH_FRIDAY {
-                tinystr!(16, "islamic-civil")
-            } else {
-                tinystr!(16, "islamic-tbla")
+            match self.epoch {
+                HijriTabularEpoch::Friday => tinystr!(16, "islamic-civil"),
+                HijriTabularEpoch::Thursday => tinystr!(16, "islamic-tbla"),
             },
             date.0.year,
         )
@@ -1064,10 +1097,10 @@ impl<A: AsCalendar<Calendar = HijriTabular>> Date<A> {
     /// Has no negative years, only era is the AH.
     ///
     /// ```rust
-    /// use icu::calendar::cal::HijriTabular;
+    /// use icu::calendar::cal::{HijriTabular, HijriTabularEpoch, HijriTabularLeapYears};
     /// use icu::calendar::Date;
     ///
-    /// let hijri = HijriTabular::new_civil_epoch();
+    /// let hijri = HijriTabular::new(HijriTabularEpoch::Thursday, HijriTabularLeapYears::TypeII);
     ///
     /// let date_hijri =
     ///     Date::try_new_hijri_tabular_with_calendar(1392, 4, 25, hijri)
@@ -1814,7 +1847,7 @@ mod test {
 
     #[test]
     fn test_rd_from_hijri() {
-        let calendar = HijriTabular::new_civil_epoch();
+        let calendar = HijriTabular::new(HijriTabularEpoch::Friday, HijriTabularLeapYears::TypeII);
         let calendar = Ref(&calendar);
         for (case, f_date) in ARITHMETIC_CASES.iter().zip(TEST_RD.iter()) {
             let date = Date::try_new_hijri_tabular_with_calendar(
@@ -1827,7 +1860,7 @@ mod test {
 
     #[test]
     fn test_hijri_from_rd() {
-        let calendar = HijriTabular::new_civil_epoch();
+        let calendar = HijriTabular::new(HijriTabularEpoch::Friday, HijriTabularLeapYears::TypeII);
         let calendar = Ref(&calendar);
         for (case, f_date) in ARITHMETIC_CASES.iter().zip(TEST_RD.iter()) {
             let date = Date::try_new_hijri_tabular_with_calendar(
@@ -1842,7 +1875,8 @@ mod test {
 
     #[test]
     fn test_rd_from_hijri_tbla() {
-        let calendar = HijriTabular::new_astronomical_epoch();
+        let calendar =
+            HijriTabular::new(HijriTabularEpoch::Thursday, HijriTabularLeapYears::TypeII);
         let calendar = Ref(&calendar);
         for (case, f_date) in ASTRONOMICAL_CASES.iter().zip(TEST_RD.iter()) {
             let date = Date::try_new_hijri_tabular_with_calendar(
@@ -1855,7 +1889,8 @@ mod test {
 
     #[test]
     fn test_hijri_tbla_from_rd() {
-        let calendar = HijriTabular::new_astronomical_epoch();
+        let calendar =
+            HijriTabular::new(HijriTabularEpoch::Thursday, HijriTabularLeapYears::TypeII);
         let calendar = Ref(&calendar);
         for (case, f_date) in ASTRONOMICAL_CASES.iter().zip(TEST_RD.iter()) {
             let date = Date::try_new_hijri_tabular_with_calendar(

components/calendar/src/cal/hijri.rs

@@ -26,31 +26,14 @@ pub use dangi::Dangi;
 pub use ethiopian::{Ethiopian, EthiopianEraStyle};
 pub use gregorian::Gregorian;
 pub use hebrew::Hebrew;
-pub use hijri::{HijriSimulated, HijriTabular, HijriUmmAlQura};
+pub use hijri::{
+    HijriSimulated, HijriTabular, HijriTabularEpoch, HijriTabularLeapYears, HijriUmmAlQura,
+};
 pub use indian::Indian;
 pub use iso::Iso;
 pub use japanese::{Japanese, JapaneseExtended};
 pub use julian::Julian;
 pub use persian::Persian;
 pub use roc::Roc;
 
-pub use crate::any_calendar::AnyCalendar;
-
-/// Scaffolding types: You shouldn't need to use these, they need to be public for the `Calendar` trait impl to work.
-pub mod scaffold {
-    pub use super::chinese::ChineseDateInner;
-    pub use super::coptic::CopticDateInner;
-    pub use super::dangi::DangiDateInner;
-    pub use super::ethiopian::EthiopianDateInner;
-    pub use super::gregorian::GregorianDateInner;
-    pub use super::hebrew::HebrewDateInner;
-    pub use super::hijri::{HijriDateInner, HijriTabularDateInner, HijriUmmAlQuraDateInner};
-    pub use super::indian::Indian;
-    pub use super::iso::Iso;
-    pub use super::japanese::Japanese;
-    pub use super::julian::JulianDateInner;
-    pub use super::persian::PersianDateInner;
-    pub use super::roc::RocDateInner;
-
-    pub use crate::any_calendar::AnyDateInner;
-}
+pub use crate::any_calendar::{AnyCalendar, AnyCalendarKind};

components/calendar/src/cal/mod.rs

@@ -96,7 +96,7 @@ extern crate alloc;
 mod date;
 
 // Public modules
-pub mod any_calendar;
+mod any_calendar;
 pub mod cal;
 pub mod provider;
 pub mod types;
@@ -110,6 +110,7 @@ mod error;
 mod ixdtf;
 
 // Top-level types
+pub use any_calendar::IntoAnyCalendar;
 pub use calendar::Calendar;
 pub use date::{AsCalendar, Date, Ref};
 #[doc(hidden)] // unstable
@@ -120,12 +121,11 @@ pub use ixdtf::ParseError;
 
 // Reexports
 #[doc(no_inline)]
-pub use any_calendar::{AnyCalendar, AnyCalendarKind, CalendarPreferences};
-#[doc(no_inline)]
-pub use cal::{Gregorian, Iso};
+pub use cal::{AnyCalendar, AnyCalendarKind, Gregorian, Iso};
 
 /// Locale preferences used by this crate
 pub mod preferences {
+    pub use crate::any_calendar::CalendarPreferences;
     #[doc(inline)]
     /// **This is a reexport of a type in [`icu::locale`](icu_locale_core::preferences::extensions::unicode::keywords)**.
     #[doc = "\n"] // prevent autoformatting

components/calendar/src/lib.rs

@@ -147,7 +147,10 @@ fn test_indian_continuity() {
 
 #[test]
 fn test_hijri_civil_continuity() {
-    let cal = crate::cal::HijriTabular::new_civil_epoch();
+    let cal = crate::cal::HijriTabular::new(
+        crate::cal::HijriTabularEpoch::Friday,
+        crate::cal::HijriTabularLeapYears::TypeII,
+    );
     let cal = Ref(&cal);
     let date = Date::try_new_hijri_tabular_with_calendar(-10, 1, 1, cal);
     check_continuity(date.unwrap());
@@ -169,7 +172,10 @@ fn test_hijri_simulated_mecca_continuity() {
 
 #[test]
 fn test_hijri_tabular_continuity() {
-    let cal = crate::cal::HijriTabular::new_astronomical_epoch();
+    let cal = crate::cal::HijriTabular::new(
+        crate::cal::HijriTabularEpoch::Thursday,
+        crate::cal::HijriTabularLeapYears::TypeII,
+    );
     let cal = Ref(&cal);
     let date = Date::try_new_hijri_tabular_with_calendar(-10, 1, 1, cal);
     check_continuity(date.unwrap());

components/calendar/src/tests/continuity_test.rs

@@ -5,8 +5,8 @@
 use crate::pattern::PatternLoadError;
 use displaydoc::Display;
 use icu_calendar::{
-    any_calendar::AnyCalendarKind,
     types::{FormattingEra, MonthCode},
+    AnyCalendarKind,
 };
 use icu_provider::DataError;
 

components/datetime/src/error.rs

@@ -22,8 +22,7 @@ use crate::MismatchedCalendarError;
 use crate::{external_loaders::*, DateTimeWriteError};
 use core::fmt;
 use core::marker::PhantomData;
-use icu_calendar::any_calendar::IntoAnyCalendar;
-use icu_calendar::{AnyCalendar, CalendarPreferences};
+use icu_calendar::{preferences::CalendarPreferences, AnyCalendar, IntoAnyCalendar};
 use icu_decimal::DecimalFormatterPreferences;
 use icu_locale_core::preferences::{define_preferences, prefs_convert};
 use icu_provider::prelude::*;