From 0ae4bfa8b71b1e74559113923369f4ddb28b11b5 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Fri, 17 Oct 2025 09:53:32 -0700 Subject: [PATCH 1/5] Add precise definitions and limits for all calendars --- components/calendar/src/cal/buddhist.rs | 6 ++++ components/calendar/src/cal/chinese.rs | 35 ++++++++++++++++++++-- components/calendar/src/cal/coptic.rs | 6 ++++ components/calendar/src/cal/ethiopian.rs | 6 ++++ components/calendar/src/cal/gregorian.rs | 7 +++++ components/calendar/src/cal/hebrew.rs | 10 +++++++ components/calendar/src/cal/hijri.rs | 37 ++++++++++++++++++++++++ components/calendar/src/cal/indian.rs | 7 +++++ components/calendar/src/cal/iso.rs | 5 ++++ components/calendar/src/cal/japanese.rs | 6 ++++ components/calendar/src/cal/julian.rs | 5 ++++ components/calendar/src/cal/persian.rs | 14 +++++++++ components/calendar/src/cal/roc.rs | 6 ++++ 13 files changed, 148 insertions(+), 2 deletions(-) diff --git a/components/calendar/src/cal/buddhist.rs b/components/calendar/src/cal/buddhist.rs index 443bddd0d44..291d2811b10 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 1912 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..4bb808055cc 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 East Asian-style lunisolar calendar with twelve months, and leap months possible +/// after any month. 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 intended to represent the traditional Chinese lunar calendar as used +/// officially in the People's Republic of China as of 2025. This takes a best-effort approach +/// to match past and future dates as used in the region for the year 1900 onwards. +/// +/// 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 official the [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,12 @@ 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: +/// - The ground truth in China changes, either through published government sources or most almanacs +/// - Future data is published that we wish to incorporate +/// - We decide to tweak the simplified calculation +/// - We decide to expand 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 +296,12 @@ impl Rules for China { /// The [`Rules`] used in [Korea](https://en.wikipedia.org/wiki/Korean_calendar). /// +/// # Precise definition and limits +/// +/// This calendar is intended to represent the traditional Korean lunar calendar as used +/// officially in the Republic of Korea as of 2025. This takes a best-effort approach +/// to match past and future dates as used in the region for the year 1900 onwards. +/// /// This type agrees with the official data published by the /// [Korea Astronomy and Space Science Institute for the years 1900-2050]. /// @@ -297,11 +320,19 @@ 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: +/// - The ground truth in South Korea changes, either through published government sources or most almanacs +/// - Future data is published that we wish to incorporate +/// - We decide to tweak the simplified calculation +/// - We decide to expand 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..1e328ebf974 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, as used by the Coptic orthodox church as of 2025. This calendar 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..a9a338245b7 100644 --- a/components/calendar/src/cal/ethiopian.rs +++ b/components/calendar/src/cal/ethiopian.rs @@ -57,6 +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. +/// +/// # Precise definition and limits +/// +/// This calendar is defined algorithmically as a solar calendar that has 13 months, +/// as used as a civil calendar in Ethiopia as of 2025. This calendar extends proleptically +/// before the time of its introduction. // The bool specifies whether dates should be in the Amete Alem era scheme #[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..33ec7951aff 100644 --- a/components/calendar/src/cal/hebrew.rs +++ b/components/calendar/src/cal/hebrew.rs @@ -36,6 +36,16 @@ 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, as used as an ecclesiastical calendar in Judaism +/// as of 2025 (using 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..0af676e3002 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 ecclesiastically 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, an algorithm with 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, @@ -236,6 +254,20 @@ impl Rules for AstronomicalSimulation { /// calendar authority. /// /// This corresponds to the `"islamic-umalqura"` [CLDR calendar](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier). +/// +/// # Precise definition and limits +/// +/// This calendar is intended to match the Umm al-Qura calendar defined and published by the Kingdom of Saudi Arabia, +/// with the source of truth being government published data/almanacs. +/// +/// Outside the range 1300 AH (1882-11-12 ISO) to the end of 1600 AH (2174-11-25 ISO) it falls back +/// to a tabular approximation. These ranges may change in the future. +/// +/// The precise behavior of this calendar may change in the future if: +/// - The ground truth in Saudi Arabia changes, either through published government sources or most almanacs +/// - Future data is published that we wish to incorporate +/// - We decide to tweak the simplified calculation +/// - We decide to expand the range where we are handling past dates. #[derive(Copy, Clone, Debug, Default)] #[non_exhaustive] pub struct UmmAlQura; @@ -311,6 +343,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..87f786d0c35 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 2025.` +/// +/// 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..5628e1aa9ee 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 happens to be 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..686b7bab6c2 100644 --- a/components/calendar/src/cal/julian.rs +++ b/components/calendar/src/cal/julian.rs @@ -59,6 +59,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 with a leap month every 4 years, as used +/// by the Roman Empire since 1 CE. #[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..49359ca45d2 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 2025. 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 1500-3000 CE. 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; From 8bb8a957d627d7853baffa0e14aa826f05021817 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Fri, 17 Oct 2025 23:54:23 -0700 Subject: [PATCH 2/5] nit --- components/calendar/src/cal/chinese.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/calendar/src/cal/chinese.rs b/components/calendar/src/cal/chinese.rs index 4bb808055cc..9ba32634526 100644 --- a/components/calendar/src/cal/chinese.rs +++ b/components/calendar/src/cal/chinese.rs @@ -153,7 +153,7 @@ pub trait Rules: Clone + core::fmt::Debug + crate::cal::scaffold::UnstableSealed /// [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 official 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 From 1edf9f1183c0cd411b41d0b7a9fadab85e855235 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Mon, 20 Oct 2025 14:23:34 -0700 Subject: [PATCH 3/5] feedback --- components/calendar/src/cal/buddhist.rs | 2 +- components/calendar/src/cal/chinese.rs | 22 +++++++++++----------- components/calendar/src/cal/coptic.rs | 4 ++-- components/calendar/src/cal/ethiopian.rs | 6 +++--- components/calendar/src/cal/hebrew.rs | 5 +++-- components/calendar/src/cal/hijri.rs | 2 +- components/calendar/src/cal/indian.rs | 2 +- components/calendar/src/cal/japanese.rs | 2 +- components/calendar/src/cal/julian.rs | 5 +++-- components/calendar/src/cal/persian.rs | 2 +- 10 files changed, 27 insertions(+), 25 deletions(-) diff --git a/components/calendar/src/cal/buddhist.rs b/components/calendar/src/cal/buddhist.rs index 291d2811b10..b18d9a69aff 100644 --- a/components/calendar/src/cal/buddhist.rs +++ b/components/calendar/src/cal/buddhist.rs @@ -35,7 +35,7 @@ use tinystr::tinystr; /// # 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 1912 onwards, +/// 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 9ba32634526..3ddf3330c06 100644 --- a/components/calendar/src/cal/chinese.rs +++ b/components/calendar/src/cal/chinese.rs @@ -83,7 +83,7 @@ mod simple; /// /// # Precise definition and limits /// -/// This calendar generically covers any East Asian-style lunisolar calendar with twelve months, and leap months possible +/// This calendar generically covers any Chinese-style lunisolar calendar with twelve months, and leap months possible /// after any month. Individual variants [`China`] and [`Korea`] contain more information. #[derive(Clone, Debug, Default, Copy, PartialEq, Eq, PartialOrd, Ord)] #[allow(clippy::exhaustive_structs)] // newtype @@ -145,9 +145,9 @@ pub trait Rules: Clone + core::fmt::Debug + crate::cal::scaffold::UnstableSealed /// /// # Precise definition and limits /// -/// This calendar is intended to represent the traditional Chinese lunar calendar as used -/// officially in the People's Republic of China as of 2025. This takes a best-effort approach -/// to match past and future dates as used in the region for the year 1900 onwards. +/// This calendar is represents 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 @@ -167,10 +167,10 @@ pub trait Rules: Clone + core::fmt::Debug + crate::cal::scaffold::UnstableSealed /// using data such as from the excellent compilation by [Yuk Tung Liu]. /// /// The precise behavior of this calendar may change in the future if: -/// - The ground truth in China changes, either through published government sources or most almanacs +/// - New ground truth in China is established, either through published government sources or most almanacs /// - Future data is published that we wish to incorporate /// - We decide to tweak the simplified calculation -/// - We decide to expand the range where we are handling past dates. +/// - 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 @@ -298,9 +298,9 @@ impl Rules for China { /// /// # Precise definition and limits /// -/// This calendar is intended to represent the traditional Korean lunar calendar as used -/// officially in the Republic of Korea as of 2025. This takes a best-effort approach -/// to match past and future dates as used in the region for the year 1900 onwards. +/// This calendar represents the traditional Korean lunar calendar as used +/// officially 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]. @@ -321,10 +321,10 @@ impl Rules for China { /// by [Yuk Tung Liu]. /// /// The precise behavior of this calendar may change in the future if: -/// - The ground truth in South Korea changes, either through published government sources or most almanacs +/// - New ground truth in South Korea is established, either through published government sources or most almanacs /// - Future data is published that we wish to incorporate /// - We decide to tweak the simplified calculation -/// - We decide to expand the range where we are handling past dates. +/// - 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 diff --git a/components/calendar/src/cal/coptic.rs b/components/calendar/src/cal/coptic.rs index 1e328ebf974..0d6e971d3d1 100644 --- a/components/calendar/src/cal/coptic.rs +++ b/components/calendar/src/cal/coptic.rs @@ -38,8 +38,8 @@ use tinystr::tinystr; /// # 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, as used by the Coptic orthodox church as of 2025. This calendar extends proleptically -/// before the time of its introduction. +/// the 13th month every 4 years, used by the Coptic orthodox church as of the publication date of this crate. +/// This calendar 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 a9a338245b7..d9b7af6a11d 100644 --- a/components/calendar/src/cal/ethiopian.rs +++ b/components/calendar/src/cal/ethiopian.rs @@ -60,9 +60,9 @@ pub enum EthiopianEraStyle { /// /// # Precise definition and limits /// -/// This calendar is defined algorithmically as a solar calendar that has 13 months, -/// as used as a civil calendar in Ethiopia as of 2025. This calendar extends proleptically -/// before the time of its introduction. +/// This calendar is defined algorithmically as a solar calendar that has 13 months, with a leap day in +/// the 13th month every 4 years, used as a civil calendar in Ethiopia as of the publication date of this crate. +/// This calendar extends proleptically before the time of its introduction. // The bool specifies whether dates should be in the Amete Alem era scheme #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)] pub struct Ethiopian(EthiopianEraStyle); diff --git a/components/calendar/src/cal/hebrew.rs b/components/calendar/src/cal/hebrew.rs index 33ec7951aff..300a9758922 100644 --- a/components/calendar/src/cal/hebrew.rs +++ b/components/calendar/src/cal/hebrew.rs @@ -40,8 +40,9 @@ use calendrical_calculations::rata_die::RataDie; /// # 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, as used as an ecclesiastical calendar in Judaism -/// as of 2025 (using the "civil new year" variant where Tishrei is the first month of the year). +/// 3rd, 6th, 8th, 11th, 14th, 17th, and 19th years (in a 19-year Metonic cycle), 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. /// diff --git a/components/calendar/src/cal/hijri.rs b/components/calendar/src/cal/hijri.rs index 0af676e3002..5260b82eeaf 100644 --- a/components/calendar/src/cal/hijri.rs +++ b/components/calendar/src/cal/hijri.rs @@ -50,7 +50,7 @@ mod ummalqura_data; /// /// # Precise definition and limits /// -/// This calendar generically covers any pure lunar calendar used ecclesiastically in Islam, +/// 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, an algorithm with official tables, diff --git a/components/calendar/src/cal/indian.rs b/components/calendar/src/cal/indian.rs index 87f786d0c35..e6a847b0593 100644 --- a/components/calendar/src/cal/indian.rs +++ b/components/calendar/src/cal/indian.rs @@ -31,7 +31,7 @@ use tinystr::tinystr; /// # 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 2025.` +/// 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)] diff --git a/components/calendar/src/cal/japanese.rs b/components/calendar/src/cal/japanese.rs index 5628e1aa9ee..9c5907a6b67 100644 --- a/components/calendar/src/cal/japanese.rs +++ b/components/calendar/src/cal/japanese.rs @@ -43,7 +43,7 @@ use tinystr::tinystr; /// # 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 happens to be the civil calendar used in Japan from 1873, this calendar extends proleptically +/// 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 { diff --git a/components/calendar/src/cal/julian.rs b/components/calendar/src/cal/julian.rs index 686b7bab6c2..9376d7441a2 100644 --- a/components/calendar/src/cal/julian.rs +++ b/components/calendar/src/cal/julian.rs @@ -62,8 +62,9 @@ use tinystr::tinystr; /// /// # Precise definition and limits /// -/// This calendar is defined algorithmically as a solar calendar with a leap month every 4 years, as used -/// by the Roman Empire since 1 CE. +/// 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 49359ca45d2..5c9a4dbd0dd 100644 --- a/components/calendar/src/cal/persian.rs +++ b/components/calendar/src/cal/persian.rs @@ -41,7 +41,7 @@ use calendrical_calculations::rata_die::RataDie; /// 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 1500-3000 CE. Outside of that range one can expect this calendar implementation to no longer +/// 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)] From 7b3fc9fa31bfce2e8cff81429d090a529395de67 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Mon, 20 Oct 2025 16:00:16 -0700 Subject: [PATCH 4/5] shane comments --- components/calendar/src/cal/chinese.rs | 4 ++-- components/calendar/src/cal/hijri.rs | 9 ++++----- components/calendar/src/cal/persian.rs | 2 +- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/components/calendar/src/cal/chinese.rs b/components/calendar/src/cal/chinese.rs index 3ddf3330c06..7f718a6cb07 100644 --- a/components/calendar/src/cal/chinese.rs +++ b/components/calendar/src/cal/chinese.rs @@ -145,7 +145,7 @@ pub trait Rules: Clone + core::fmt::Debug + crate::cal::scaffold::UnstableSealed /// /// # Precise definition and limits /// -/// This calendar is represents the traditional Chinese lunar calendar as used +/// 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. /// @@ -298,7 +298,7 @@ impl Rules for China { /// /// # Precise definition and limits /// -/// This calendar represents the traditional Korean lunar calendar as used +/// This calendar is the traditional Korean lunar calendar as used /// officially in Korea as of the publication date of this crate. /// This takes a best-effort approach future dates as used in the region. /// diff --git a/components/calendar/src/cal/hijri.rs b/components/calendar/src/cal/hijri.rs index 5260b82eeaf..d2af8971cb6 100644 --- a/components/calendar/src/cal/hijri.rs +++ b/components/calendar/src/cal/hijri.rs @@ -257,17 +257,16 @@ impl Rules for AstronomicalSimulation { /// /// # Precise definition and limits /// -/// This calendar is intended to match the Umm al-Qura calendar defined and published by the Kingdom of Saudi Arabia, -/// with the source of truth being government published data/almanacs. +/// This calendar represents the Umm al-Qura calendar defined by the Kingdom of Saudi Arabia. /// -/// Outside the range 1300 AH (1882-11-12 ISO) to the end of 1600 AH (2174-11-25 ISO) it falls back -/// to a tabular approximation. These ranges may change in the future. +/// This calendar agrees with official data published for the years 1300 AH through 1600 AH. +/// Outside that range (1882-11-12 through 2174-11-25), it falls back to a tabular approximation. /// /// The precise behavior of this calendar may change in the future if: /// - The ground truth in Saudi Arabia changes, either through published government sources or most almanacs /// - Future data is published that we wish to incorporate /// - We decide to tweak the simplified calculation -/// - We decide to expand the range where we are handling past dates. +/// - We decide to expand or reduce the range where we are handling past dates. #[derive(Copy, Clone, Debug, Default)] #[non_exhaustive] pub struct UmmAlQura; diff --git a/components/calendar/src/cal/persian.rs b/components/calendar/src/cal/persian.rs index 5c9a4dbd0dd..9c717ec18ba 100644 --- a/components/calendar/src/cal/persian.rs +++ b/components/calendar/src/cal/persian.rs @@ -33,7 +33,7 @@ use calendrical_calculations::rata_die::RataDie; /// # 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 2025. This calendar was introduced in Iran in 1925, +/// 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 From e7b3645e38b3186590477b4444d8539b71a3bbd9 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Tue, 21 Oct 2025 15:19:36 -0700 Subject: [PATCH 5/5] Address comments --- components/calendar/src/cal/chinese.rs | 10 ++++------ components/calendar/src/cal/coptic.rs | 4 ++-- components/calendar/src/cal/ethiopian.rs | 5 ++--- components/calendar/src/cal/hebrew.rs | 2 +- components/calendar/src/cal/hijri.rs | 19 ++++++------------- 5 files changed, 15 insertions(+), 25 deletions(-) diff --git a/components/calendar/src/cal/chinese.rs b/components/calendar/src/cal/chinese.rs index 7f718a6cb07..7ba78584de2 100644 --- a/components/calendar/src/cal/chinese.rs +++ b/components/calendar/src/cal/chinese.rs @@ -84,7 +84,7 @@ mod simple; /// # Precise definition and limits /// /// This calendar generically covers any Chinese-style lunisolar calendar with twelve months, and leap months possible -/// after any month. Individual variants [`China`] and [`Korea`] contain more information. +/// 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); @@ -167,8 +167,7 @@ pub trait Rules: Clone + core::fmt::Debug + crate::cal::scaffold::UnstableSealed /// 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 in China is established, either through published government sources or most almanacs -/// - Future data is published that we wish to incorporate +/// - 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. /// @@ -299,7 +298,7 @@ impl Rules for China { /// # Precise definition and limits /// /// This calendar is the traditional Korean lunar calendar as used -/// officially in Korea as of the publication date of this crate. +/// 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 @@ -321,8 +320,7 @@ impl Rules for China { /// by [Yuk Tung Liu]. /// /// The precise behavior of this calendar may change in the future if: -/// - New ground truth in South Korea is established, either through published government sources or most almanacs -/// - Future data is published that we wish to incorporate +/// - 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. /// diff --git a/components/calendar/src/cal/coptic.rs b/components/calendar/src/cal/coptic.rs index 0d6e971d3d1..bd09f1ac7e2 100644 --- a/components/calendar/src/cal/coptic.rs +++ b/components/calendar/src/cal/coptic.rs @@ -38,8 +38,8 @@ use tinystr::tinystr; /// # 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, used by the Coptic orthodox church as of the publication date of this crate. -/// This calendar extends proleptically before the time of its introduction. +/// 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 d9b7af6a11d..489d34fd33e 100644 --- a/components/calendar/src/cal/ethiopian.rs +++ b/components/calendar/src/cal/ethiopian.rs @@ -61,9 +61,8 @@ pub enum EthiopianEraStyle { /// # 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, used as a civil calendar in Ethiopia as of the publication date of this crate. -/// This calendar extends proleptically before the time of its introduction. -// The bool specifies whether dates should be in the Amete Alem era scheme +/// 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/hebrew.rs b/components/calendar/src/cal/hebrew.rs index 300a9758922..c72fffefabf 100644 --- a/components/calendar/src/cal/hebrew.rs +++ b/components/calendar/src/cal/hebrew.rs @@ -40,7 +40,7 @@ use calendrical_calculations::rata_die::RataDie; /// # 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), used as a +/// 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 diff --git a/components/calendar/src/cal/hijri.rs b/components/calendar/src/cal/hijri.rs index d2af8971cb6..4b1287fcb32 100644 --- a/components/calendar/src/cal/hijri.rs +++ b/components/calendar/src/cal/hijri.rs @@ -53,7 +53,7 @@ mod ummalqura_data; /// 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, an algorithm with official tables, +/// 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. @@ -245,26 +245,19 @@ 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. /// -/// 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). /// /// # Precise definition and limits /// /// This calendar represents the Umm al-Qura calendar defined by the Kingdom of Saudi Arabia. /// -/// This calendar agrees with official data published for the years 1300 AH through 1600 AH. -/// Outside that range (1882-11-12 through 2174-11-25), it falls back to a tabular approximation. +/// 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`]. /// /// The precise behavior of this calendar may change in the future if: -/// - The ground truth in Saudi Arabia changes, either through published government sources or most almanacs -/// - Future data is published that we wish to incorporate +/// - 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)]