From 3bb5417d98e7c6df5eb87379dacebf3453541ff7 Mon Sep 17 00:00:00 2001 From: "Shane F. Carr" Date: Tue, 30 Sep 2025 11:58:32 -0700 Subject: [PATCH 1/7] Don't blanket-impl CldrCalendar for Hijri --- components/datetime/src/scaffold/calendar.rs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/components/datetime/src/scaffold/calendar.rs b/components/datetime/src/scaffold/calendar.rs index b632df7e219..b24b554d210 100644 --- a/components/datetime/src/scaffold/calendar.rs +++ b/components/datetime/src/scaffold/calendar.rs @@ -91,7 +91,19 @@ impl CldrCalendar for Indian { type SkeletaV1 = DatetimePatternsDateIndianV1; } -impl CldrCalendar for Hijri { +impl CldrCalendar for Hijri { + type YearNamesV1 = DatetimeNamesYearHijriV1; + type MonthNamesV1 = DatetimeNamesMonthHijriV1; + type SkeletaV1 = DatetimePatternsDateHijriV1; +} + +impl CldrCalendar for Hijri { + type YearNamesV1 = DatetimeNamesYearHijriV1; + type MonthNamesV1 = DatetimeNamesMonthHijriV1; + type SkeletaV1 = DatetimePatternsDateHijriV1; +} + +impl CldrCalendar for Hijri { type YearNamesV1 = DatetimeNamesYearHijriV1; type MonthNamesV1 = DatetimeNamesMonthHijriV1; type SkeletaV1 = DatetimePatternsDateHijriV1; From e939d123f20d4346ad1e29829325e42570f9fd2f Mon Sep 17 00:00:00 2001 From: "Shane F. Carr" Date: Tue, 30 Sep 2025 12:00:11 -0700 Subject: [PATCH 2/7] Change CldrCalendar docs to be unstable-but-implementable --- components/datetime/src/scaffold/calendar.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/datetime/src/scaffold/calendar.rs b/components/datetime/src/scaffold/calendar.rs index b24b554d210..c4a64c70590 100644 --- a/components/datetime/src/scaffold/calendar.rs +++ b/components/datetime/src/scaffold/calendar.rs @@ -23,8 +23,8 @@ use icu_time::{ /// in the CLDR transformer to support any new era maps. /// ///
-/// 🚫 This trait is sealed; it cannot be implemented by user code. If an API requests an item that implements this -/// trait, please consider using a type from the implementors listed below. +/// 🚧 This trait is considered unstable; it may change at any time, in breaking or non-breaking ways, +/// including in SemVer minor releases. Do not implement this trait in userland unless you are prepared for things to occasionally break. ///
pub trait CldrCalendar: UnstableSealed { /// The data marker for loading year symbols for this calendar. From 89efadf56dc0f5ba88cea603250d5d53305e1b77 Mon Sep 17 00:00:00 2001 From: "Shane F. Carr" Date: Tue, 30 Sep 2025 13:09:31 -0700 Subject: [PATCH 3/7] one more hijri::Rules in icu_datetime --- components/datetime/src/scaffold/calendar.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/components/datetime/src/scaffold/calendar.rs b/components/datetime/src/scaffold/calendar.rs index c4a64c70590..fbfcaffea92 100644 --- a/components/datetime/src/scaffold/calendar.rs +++ b/components/datetime/src/scaffold/calendar.rs @@ -142,7 +142,9 @@ impl UnstableSealed for Ethiopian {} impl UnstableSealed for Gregorian {} impl UnstableSealed for Hebrew {} impl UnstableSealed for Indian {} -impl UnstableSealed for Hijri {} +impl UnstableSealed for Hijri {} +impl UnstableSealed for Hijri {} +impl UnstableSealed for Hijri {} impl UnstableSealed for Japanese {} impl UnstableSealed for JapaneseExtended {} impl UnstableSealed for Persian {} From daf0da8a1c08d9a0aed60a4b6bf9fc73e19e205b Mon Sep 17 00:00:00 2001 From: "Shane F. Carr" Date: Tue, 30 Sep 2025 13:20:54 -0700 Subject: [PATCH 4/7] More docs improvements --- components/calendar/src/types.rs | 18 ++++++++++++------ components/datetime/src/provider/neo/mod.rs | 2 +- components/datetime/src/scaffold/calendar.rs | 12 +++++++++--- 3 files changed, 22 insertions(+), 10 deletions(-) diff --git a/components/calendar/src/types.rs b/components/calendar/src/types.rs index de122ff5836..bbacff4ab5e 100644 --- a/components/calendar/src/types.rs +++ b/components/calendar/src/types.rs @@ -43,16 +43,19 @@ pub struct DateFields<'a> { pub day: Option, } -/// The type of year: Calendars like Chinese don't have an era and instead format with cyclic years. +/// Information about the year. Returned by [`Date::year()`](crate::Date::year) +/// +/// This enum supports calendars based on eras as well as calendars based on cycles. #[derive(Copy, Clone, Debug, PartialEq)] #[non_exhaustive] pub enum YearInfo { - /// An era and a year in that era + /// Information about the year in calendars with eras. + /// + /// A majority of calendars use this variant. Era(EraYear), - /// A cyclic year, and the related ISO year + /// Information about the year in calendars with cycles. /// - /// Knowing the cyclic year is typically not enough to pinpoint a date, however cyclic calendars - /// don't typically use eras, so disambiguation can be done by saying things like "Year 甲辰 (2024)" + /// This is used in the Chinese and Dangi lunisolar calendars. Cyclic(CyclicYear), } @@ -144,6 +147,9 @@ pub struct EraYear { } /// Year information for a year that is specified as a cyclic year +/// +/// Knowing the cyclic year is typically not enough to pinpoint a date, however cyclic calendars +/// don't typically use eras, so disambiguation can be done by saying things like "Year 甲辰 (2024)" #[derive(Copy, Clone, Debug, PartialEq)] #[non_exhaustive] pub struct CyclicYear { @@ -269,7 +275,7 @@ impl fmt::Display for MonthCode { } } -/// Representation of a formattable month. +/// Representation of a formattable month. Returned by [`Date::month()`](crate::Date::month) #[derive(Copy, Clone, Debug, PartialEq)] #[non_exhaustive] pub struct MonthInfo { diff --git a/components/datetime/src/provider/neo/mod.rs b/components/datetime/src/provider/neo/mod.rs index 00812cad701..2ed7ce77276 100644 --- a/components/datetime/src/provider/neo/mod.rs +++ b/components/datetime/src/provider/neo/mod.rs @@ -548,7 +548,7 @@ size_test!(YearNames, year_names_v1_size, 32); pub enum YearNames<'data> { /// This calendar has a small, fixed set of eras with numeric years, this stores the era names in chronological order. /// - /// See FormattableEra for a definition of what chronological order is in this context. + /// See [`EraYear`](icu_calendar::types::EraYear) for a definition of what chronological order is in this context. FixedEras(#[cfg_attr(feature = "serde", serde(borrow))] VarZeroVec<'data, str>), /// This calendar has a variable set of eras with numeric years, this stores the era names mapped from /// era code to the name. diff --git a/components/datetime/src/scaffold/calendar.rs b/components/datetime/src/scaffold/calendar.rs index fbfcaffea92..472f6d3049f 100644 --- a/components/datetime/src/scaffold/calendar.rs +++ b/components/datetime/src/scaffold/calendar.rs @@ -17,15 +17,21 @@ use icu_time::{ DateTime, Time, TimeZoneInfo, ZonedDateTime, }; -/// A calendar that can be found in CLDR. +/// A calendar that can be formatted with CLDR data. /// -/// New implementors of this trait will likely also wish to modify `get_era_code_map()` -/// in the CLDR transformer to support any new era maps. +/// When formatting: +/// +/// - The pattern is loaded from [`Self::SkeletaV1`] +/// - The era and year names are loaded from [`Self::YearNamesV1`] and accessed based on [`YearInfo`] +/// - The month name is loaded from [`Self::MonthNamesV1`] and accessed based on [`MonthInfo`] /// ///
/// 🚧 This trait is considered unstable; it may change at any time, in breaking or non-breaking ways, /// including in SemVer minor releases. Do not implement this trait in userland unless you are prepared for things to occasionally break. ///
+/// +/// [`YearInfo`]: icu_calendar::types::YearInfo +/// [`MonthInfo`]: icu_calendar::types::MonthInfo pub trait CldrCalendar: UnstableSealed { /// The data marker for loading year symbols for this calendar. type YearNamesV1: DataMarker>; From 6486d68cf9f0e8eadbd2a960ef527a08e8712202 Mon Sep 17 00:00:00 2001 From: "Shane F. Carr" Date: Tue, 30 Sep 2025 16:08:12 -0500 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Robert Bastian <4706271+robertbastian@users.noreply.github.com> --- components/calendar/src/types.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/components/calendar/src/types.rs b/components/calendar/src/types.rs index bbacff4ab5e..bbe60221ac8 100644 --- a/components/calendar/src/types.rs +++ b/components/calendar/src/types.rs @@ -55,7 +55,7 @@ pub enum YearInfo { Era(EraYear), /// Information about the year in calendars with cycles. /// - /// This is used in the Chinese and Dangi lunisolar calendars. + /// This is used by the [`LunarChinese`] calendar. Cyclic(CyclicYear), } @@ -275,7 +275,9 @@ impl fmt::Display for MonthCode { } } -/// Representation of a formattable month. Returned by [`Date::month()`](crate::Date::month) +/// Representation of a formattable month. +/// +/// Returned by [`Date::month()`](crate::Date::month) #[derive(Copy, Clone, Debug, PartialEq)] #[non_exhaustive] pub struct MonthInfo { From c28484f78f9bfa01fe4ad47ead0ba770c4f9ea0d Mon Sep 17 00:00:00 2001 From: "Shane F. Carr" Date: Tue, 30 Sep 2025 14:11:50 -0700 Subject: [PATCH 6/7] Feedback --- components/calendar/src/types.rs | 8 +++++--- components/datetime/src/provider/neo/mod.rs | 5 ++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/components/calendar/src/types.rs b/components/calendar/src/types.rs index bbe60221ac8..11034b5482d 100644 --- a/components/calendar/src/types.rs +++ b/components/calendar/src/types.rs @@ -43,7 +43,9 @@ pub struct DateFields<'a> { pub day: Option, } -/// Information about the year. Returned by [`Date::year()`](crate::Date::year) +/// Information about the year. +/// +/// Returned by [`Date::year()`](crate::Date::year). /// /// This enum supports calendars based on eras as well as calendars based on cycles. #[derive(Copy, Clone, Debug, PartialEq)] @@ -275,9 +277,9 @@ impl fmt::Display for MonthCode { } } -/// Representation of a formattable month. +/// Representation of a formattable month. /// -/// Returned by [`Date::month()`](crate::Date::month) +/// Returned by [`Date::month()`](crate::Date::month). #[derive(Copy, Clone, Debug, PartialEq)] #[non_exhaustive] pub struct MonthInfo { diff --git a/components/datetime/src/provider/neo/mod.rs b/components/datetime/src/provider/neo/mod.rs index 2ed7ce77276..c7a8e5ec950 100644 --- a/components/datetime/src/provider/neo/mod.rs +++ b/components/datetime/src/provider/neo/mod.rs @@ -546,9 +546,8 @@ size_test!(YearNames, year_names_v1_size, 32); #[cfg_attr(feature = "serde", derive(serde::Deserialize))] #[yoke(prove_covariance_manually)] pub enum YearNames<'data> { - /// This calendar has a small, fixed set of eras with numeric years, this stores the era names in chronological order. - /// - /// See [`EraYear`](icu_calendar::types::EraYear) for a definition of what chronological order is in this context. + /// This calendar has a small, fixed set of eras with numeric years. Eras are stored + /// according to their [era index](icu_calendar::types::EraYear::era_index). FixedEras(#[cfg_attr(feature = "serde", serde(borrow))] VarZeroVec<'data, str>), /// This calendar has a variable set of eras with numeric years, this stores the era names mapped from /// era code to the name. From 22683686c5d70bc666deaddd7634259dab892e6c Mon Sep 17 00:00:00 2001 From: "Shane F. Carr" Date: Tue, 30 Sep 2025 14:12:29 -0700 Subject: [PATCH 7/7] doc --- components/calendar/src/types.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/components/calendar/src/types.rs b/components/calendar/src/types.rs index 11034b5482d..db94ad286ff 100644 --- a/components/calendar/src/types.rs +++ b/components/calendar/src/types.rs @@ -58,6 +58,8 @@ pub enum YearInfo { /// Information about the year in calendars with cycles. /// /// This is used by the [`LunarChinese`] calendar. + /// + /// [`LunarChinese`]: crate::cal::LunarChinese Cyclic(CyclicYear), }