diff --git a/components/calendar/src/cal/buddhist.rs b/components/calendar/src/cal/buddhist.rs index 443bddd0d44..b18d9a69aff 100644 --- a/components/calendar/src/cal/buddhist.rs +++ b/components/calendar/src/cal/buddhist.rs @@ -31,6 +31,12 @@ use tinystr::tinystr; /// # Month codes /// /// This calendar supports 12 solar month codes (`"M01" - "M12"`) +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar that is identical to the proleptic Gregorian calendar in everything +/// except year numbering. This is the civil calendar used in Thailand from the year 1941 onwards, +/// but the algorithm is extended proleptically before that. #[allow(clippy::exhaustive_structs)] // this type is stable pub struct Buddhist; diff --git a/components/calendar/src/cal/chinese.rs b/components/calendar/src/cal/chinese.rs index d42693c50fe..7ba78584de2 100644 --- a/components/calendar/src/cal/chinese.rs +++ b/components/calendar/src/cal/chinese.rs @@ -80,6 +80,11 @@ mod simple; /// /// This calendar is currently in a preview state: formatting for this calendar is not /// going to be perfect. +/// +/// # Precise definition and limits +/// +/// This calendar generically covers any Chinese-style lunisolar calendar with twelve months, and leap months possible +/// after any month (at most once per year). Individual variants [`China`] and [`Korea`] contain more information. #[derive(Clone, Debug, Default, Copy, PartialEq, Eq, PartialOrd, Ord)] #[allow(clippy::exhaustive_structs)] // newtype pub struct LunarChinese(pub X); @@ -138,11 +143,17 @@ pub trait Rules: Clone + core::fmt::Debug + crate::cal::scaffold::UnstableSealed /// The [`Rules`] used in China. /// -/// This type agrees with the official data published by the +/// # Precise definition and limits +/// +/// This calendar is the traditional Chinese lunar calendar as used +/// in China as of the publication date of this crate. +/// This takes a best-effort approach future dates as used in the region. +/// +/// This calendar agrees with the official data published by the /// [Purple Mountain Observatory for the years 1900-2025], as well as with /// the data published by the [Hong Kong Observatory for the years 1901-2100]. /// -/// For years since 1912, this uses the [GB/T 33661-2017] rules. +/// For years since 1912, this uses the official [GB/T 33661-2017] rules. /// As accurate computation is computationally expensive, years until /// 2100 are precomputed, and after that this type regresses to a simplified /// calculation. If accuracy beyond 2100 is required, clients @@ -155,6 +166,11 @@ pub trait Rules: Clone + core::fmt::Debug + crate::cal::scaffold::UnstableSealed /// required before 1900, clients can implement their own [`Rules`] type /// using data such as from the excellent compilation by [Yuk Tung Liu]. /// +/// The precise behavior of this calendar may change in the future if: +/// - New ground truth is established by published government sources +/// - We decide to tweak the simplified calculation +/// - We decide to expand or reduce the range where we are handling past dates. +/// /// [Purple Mountain Observatory for the years 1900-2025]: http://www.pmo.cas.cn/xwdt2019/kpdt2019/202203/P020250414456381274062.pdf /// [Hong Kong Observatory for the years 1901-2100]: https://www.hko.gov.hk/en/gts/time/conversion.htm /// [GB/T 33661-2017]: China::gb_t_33661_2017 @@ -279,6 +295,12 @@ impl Rules for China { /// The [`Rules`] used in [Korea](https://en.wikipedia.org/wiki/Korean_calendar). /// +/// # Precise definition and limits +/// +/// This calendar is the traditional Korean lunar calendar as used +/// in Korea as of the publication date of this crate. +/// This takes a best-effort approach future dates as used in the region. +/// /// This type agrees with the official data published by the /// [Korea Astronomy and Space Science Institute for the years 1900-2050]. /// @@ -297,11 +319,18 @@ impl Rules for China { /// their own [`Rules`] type using data such as from the excellent compilation /// by [Yuk Tung Liu]. /// +/// The precise behavior of this calendar may change in the future if: +/// - New ground truth is established by published government sources +/// - We decide to tweak the simplified calculation +/// - We decide to expand/reduce the range where we are handling past dates. +/// /// [Korea Astronomy and Space Science Institute for the years 1900-2050]: https://astro.kasi.re.kr/life/pageView/5 /// [adapted GB/T 33661-2017]: Korea::adapted_gb_t_33661_2017 /// [GB/T 33661-2017]: China::gb_t_33661_2017 /// [Yuk Tung Liu]: https://ytliu0.github.io/ChineseCalendar/table.html /// +/// # Example +/// /// ```rust /// use icu::calendar::cal::LunarChinese; /// use icu::calendar::Date; diff --git a/components/calendar/src/cal/coptic.rs b/components/calendar/src/cal/coptic.rs index 96a9343cb0e..bd09f1ac7e2 100644 --- a/components/calendar/src/cal/coptic.rs +++ b/components/calendar/src/cal/coptic.rs @@ -34,6 +34,12 @@ use tinystr::tinystr; /// /// This calendar supports 13 solar month codes (`"M01" - "M13"`), with `"M13"` being used for the short epagomenal month /// at the end of the year. +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar that has 13 months, with a leap day in +/// the 13th month every 4 years. It is used by the Coptic Orthodox Church as of the publication date +/// of this crate, and extends proleptically before the time of its introduction. #[derive(Copy, Clone, Debug, Hash, Default, Eq, PartialEq, PartialOrd, Ord)] #[allow(clippy::exhaustive_structs)] // this type is stable pub struct Coptic; diff --git a/components/calendar/src/cal/ethiopian.rs b/components/calendar/src/cal/ethiopian.rs index 2043a98a400..489d34fd33e 100644 --- a/components/calendar/src/cal/ethiopian.rs +++ b/components/calendar/src/cal/ethiopian.rs @@ -57,7 +57,12 @@ pub enum EthiopianEraStyle { /// /// This calendar supports 13 solar month codes (`"M01" - "M13"`), with `"M13"` being used for the short epagomenal month /// at the end of the year. -// The bool specifies whether dates should be in the Amete Alem era scheme +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar that has 13 months, with a leap day in +/// the 13th month every 4 years. It is used as a civil calendar in Ethiopia as of the publication date +/// of this crate, and extends proleptically before the time of its introduction. #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)] pub struct Ethiopian(EthiopianEraStyle); diff --git a/components/calendar/src/cal/gregorian.rs b/components/calendar/src/cal/gregorian.rs index 01b00afda02..145fba7e481 100644 --- a/components/calendar/src/cal/gregorian.rs +++ b/components/calendar/src/cal/gregorian.rs @@ -102,6 +102,13 @@ impl GregorianYears for CeBce { /// # Month codes /// /// This calendar supports 12 solar month codes (`"M01" - "M12"`) +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar that has 12 months, with a leap day in the +/// 2nd month every 4 and 400 years (but not every 100 years). As of 2025 it is a widely used civil calendar +/// in most countries, including the UN. The Gregorian calendar was adopted gradually starting in the 1500s, +/// this calendar extends proleptically before that. #[derive(Copy, Clone, Debug, Default)] #[allow(clippy::exhaustive_structs)] // this type is stable pub struct Gregorian; diff --git a/components/calendar/src/cal/hebrew.rs b/components/calendar/src/cal/hebrew.rs index 3564a8a23dd..c72fffefabf 100644 --- a/components/calendar/src/cal/hebrew.rs +++ b/components/calendar/src/cal/hebrew.rs @@ -36,6 +36,17 @@ use calendrical_calculations::rata_die::RataDie; /// [`MonthInfo`] has slightly divergent behavior: because the regular month Adar is formatted /// as "Adar II" in a leap year, this calendar will produce the special code `"M06L"` in any [`MonthInfo`] /// objects it creates. +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a lunar calendar with a leap 6th month every +/// 3rd, 6th, 8th, 11th, 14th, 17th, and 19th years (in a 19-year Metonic cycle). It is used as a +/// liturgical calendar in Judaism as of the publication date of this crate. +/// This calendar uses the the "civil new year" variant where Tishrei is the first month of the year. +/// The precise algorithm used has [changed over time], with the modern one being in place +/// since about 776 CE. This calendar extends that algorithm proleptically before that. +/// +/// [changed over time]: https://hakirah.org/vol20AjdlerAppendices.pdf #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord, Default)] #[allow(clippy::exhaustive_structs)] // unit struct pub struct Hebrew; diff --git a/components/calendar/src/cal/hijri.rs b/components/calendar/src/cal/hijri.rs index fe444b2781d..4b1287fcb32 100644 --- a/components/calendar/src/cal/hijri.rs +++ b/components/calendar/src/cal/hijri.rs @@ -47,6 +47,16 @@ mod ummalqura_data; /// /// This calendar is a pure lunar calendar with no leap months. It uses month codes /// `"M01" - "M12"`. +/// +/// # Precise definition and limits +/// +/// This calendar generically covers any pure lunar calendar used liturgically in Islam, +/// with 12 months each of length 29 or 30, with an epoch intended to mark the Hijrah in 622 CE. +/// +/// In practice, this calendar can be backed by a precise algorithm, a lookup in official tables, +/// astronomical simulation, or pure observation. +/// +/// Further details can be found on individual calendar types. #[derive(Clone, Debug, Default, Copy)] #[allow(clippy::exhaustive_structs)] // newtype pub struct Hijri(pub S); @@ -111,6 +121,14 @@ pub trait Rules: Clone + Debug + crate::cal::scaffold::UnstableSealed { /// /// This corresponds to the `"islamic-rgsa"` [CLDR calendar](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier) /// if constructed with [`Hijri::new_simulated_mecca()`]. +/// +/// # Precise definition and limits +/// +/// This calendar simulates the lunar cycle for a given location. This currently +/// simulates the calendar for all time using the same calculations, but we may +/// in the future introduce approximations for non-modern dates. +/// +/// The precise behavior of this calendar for any and all dates may change in the future. #[derive(Copy, Clone, Debug)] pub struct AstronomicalSimulation { pub(crate) location: SimulatedLocation, @@ -227,15 +245,21 @@ impl Rules for AstronomicalSimulation { /// [`Hijri`] [`Rules`] for the [Umm al-Qura](https://en.wikipedia.org/wiki/Islamic_calendar#Saudi_Arabia's_Umm_al-Qura_calendar) calendar. /// +/// This corresponds to the `"islamic-umalqura"` [CLDR calendar](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier). +/// +/// # Precise definition and limits +/// +/// This calendar represents the Umm al-Qura calendar defined by the Kingdom of Saudi Arabia. +/// /// From the start of 1300 AH (1882-11-12 ISO) to the end of 1600 AH (2174-11-25 ISO), this /// `Rules` implementation uses Umm al-Qura month lengths obtained from /// [KACST](https://kacst.gov.sa/). Outside this range, this implementation falls back to /// [`TabularAlgorithm`] with [`TabularAlgorithmLeapYears::TypeII`] and [`TabularAlgorithmEpoch::Friday`]. /// -/// Future versions of this crate may extend the range that uses month length data from the -/// calendar authority. -/// -/// This corresponds to the `"islamic-umalqura"` [CLDR calendar](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier). +/// The precise behavior of this calendar may change in the future if: +/// - New ground truth is established by published government sources +/// - We decide to tweak the simplified calculation +/// - We decide to expand or reduce the range where we are handling past dates. #[derive(Copy, Clone, Debug, Default)] #[non_exhaustive] pub struct UmmAlQura; @@ -311,6 +335,11 @@ impl Rules for UmmAlQura { /// /// When constructed with [`TabularAlgorithmLeapYears::TypeII`], and either [`TabularAlgorithmEpoch::Friday`] or [`TabularAlgorithmEpoch::Thursday`], /// this corresponds to the `"islamic-civil"` and `"islamic-tbla"` [CLDR calendars](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier) respectively. +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically based on the algorithm selected by the choice of [`TabularAlgorithmLeapYears`], +/// and the epoch selected by the choice of [`TabularAlgorithmEpoch`]. #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)] pub struct TabularAlgorithm { pub(crate) leap_years: TabularAlgorithmLeapYears, diff --git a/components/calendar/src/cal/indian.rs b/components/calendar/src/cal/indian.rs index 84c3488bff9..e6a847b0593 100644 --- a/components/calendar/src/cal/indian.rs +++ b/components/calendar/src/cal/indian.rs @@ -27,6 +27,13 @@ use tinystr::tinystr; /// # Month codes /// /// This calendar supports 12 solar month codes (`"M01" - "M12"`) +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar that has 12 months, as used alongside the +/// Gregorian calendar by the Government of India by the name "Śaka calendar" as of publication date of this crate. +/// +/// The Śaka calendar was introduced in 1957, but this calendar extends proleptically before that. #[derive(Copy, Clone, Debug, Hash, Default, Eq, PartialEq, PartialOrd, Ord)] #[allow(clippy::exhaustive_structs)] // this type is stable pub struct Indian; diff --git a/components/calendar/src/cal/iso.rs b/components/calendar/src/cal/iso.rs index 1792c7e76e9..9eade5ec79d 100644 --- a/components/calendar/src/cal/iso.rs +++ b/components/calendar/src/cal/iso.rs @@ -21,6 +21,11 @@ use tinystr::tinystr; /// # Month codes /// /// This calendar supports 12 solar month codes (`"M01" - "M12"`) +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar that is identical to the proleptic Gregorian calendar +/// in everything except the way eras are handled. #[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] #[allow(clippy::exhaustive_structs)] // this type is stable pub struct Iso; diff --git a/components/calendar/src/cal/japanese.rs b/components/calendar/src/cal/japanese.rs index 8d8b4301193..9c5907a6b67 100644 --- a/components/calendar/src/cal/japanese.rs +++ b/components/calendar/src/cal/japanese.rs @@ -39,6 +39,12 @@ use tinystr::tinystr; /// # Month codes /// /// This calendar supports 12 solar month codes (`M01` - `M12`) +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar that is identical to the proleptic Gregorian calendar in everything +/// except year numbering. This is the civil calendar used in Japan from 1873, this calendar extends proleptically +/// before that. #[derive(Clone, Debug, Default)] pub struct Japanese { eras: DataPayload, diff --git a/components/calendar/src/cal/julian.rs b/components/calendar/src/cal/julian.rs index 1ab10bf9e22..9376d7441a2 100644 --- a/components/calendar/src/cal/julian.rs +++ b/components/calendar/src/cal/julian.rs @@ -59,6 +59,12 @@ use tinystr::tinystr; /// # Month codes /// /// This calendar supports 12 solar month codes (`"M01" - "M12"`) +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar with a leap month every 4 years, as was used +/// by the Roman empire in 4 CE. That algorithm is extended proleptically before and after its period of use. +/// #[derive(Copy, Clone, Debug, Hash, Default, Eq, PartialEq, PartialOrd, Ord)] #[allow(clippy::exhaustive_structs)] // this type is stable pub struct Julian; diff --git a/components/calendar/src/cal/persian.rs b/components/calendar/src/cal/persian.rs index 031f00c5d3f..9c717ec18ba 100644 --- a/components/calendar/src/cal/persian.rs +++ b/components/calendar/src/cal/persian.rs @@ -29,6 +29,20 @@ use calendrical_calculations::rata_die::RataDie; /// # Month codes /// /// This calendar supports 12 solar month codes (`"M01" - "M12"`) +/// +/// # Precise definition and limits +/// +/// This calendar is defined as a solar calendar which uses the astronomical vernal equinox as its new year, and +/// is the official calendar of the Islamic Republic of Iran as of the publication date of this crate. This calendar was introduced in Iran in 1925, +/// but the astronomical calculations are extended proleptically before that. +/// +/// As these are pure solar computations, the astronomical calculations can be treated as a relatively +/// precise algorithm and there is much less need to match ground truth. Nevertheless, in the event that the calculations +/// disagree with the ground truth of calendar usage in Iran, the ground truth will prevail. +/// +/// The underlying implementation uses a cyclic approximation with overrides to match the precise astronomic calculations +/// for the years 1178-3500 AP. Outside of that range one can expect this calendar implementation to no longer +/// accurately match the astronomical calculations. #[derive(Copy, Clone, Debug, Default, Hash, Eq, PartialEq, PartialOrd, Ord)] #[allow(clippy::exhaustive_structs)] pub struct Persian; diff --git a/components/calendar/src/cal/roc.rs b/components/calendar/src/cal/roc.rs index e1a6795f0ed..2a0d6a5a10e 100644 --- a/components/calendar/src/cal/roc.rs +++ b/components/calendar/src/cal/roc.rs @@ -29,6 +29,12 @@ use tinystr::tinystr; /// # Month codes /// /// This calendar supports 12 solar month codes (`"M01" - "M12"`) +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar that is identical to the proleptic Gregorian calendar in everything +/// except year numbering. This is the civil calendar used in the Republic of China from the year 1912 onwards, +/// but the algorithm is extended proleptically before that. #[derive(Copy, Clone, Debug, Default)] #[allow(clippy::exhaustive_structs)] // this type is stable pub struct Roc;