public API

Author: robertbastian

components/calendar/src/cal/east_asian_traditional.rs

@@ -613,7 +613,7 @@ impl<R: Rules> DateFieldsResolver for EastAsianTraditional<R> {
 
         // leap_month identifies the ordinal month number of the leap month,
         // so its month number will be leap_month - 1
-        if month == Month::new_unchecked(leap_month - 1, true) {
+        if month == Month::leap(leap_month - 1) {
             return Ok(leap_month);
         }
 
@@ -1535,11 +1535,8 @@ mod test {
         for year in [4659, 4660] {
             let year = cal.year_info_from_extended(year);
             for (month, error) in [
-                (Month::new_unchecked(4, true), MonthCodeError::NotInYear),
-                (
-                    Month::new_unchecked(13, false),
-                    MonthCodeError::NotInCalendar,
-                ),
+                (Month::leap(4), MonthCodeError::NotInYear),
+                (Month::new(13), MonthCodeError::NotInCalendar),
             ] {
                 assert_eq!(
                     cal.ordinal_from_month(&year, month, reject),
@@ -1682,7 +1679,7 @@ mod test {
         use crate::{cal::Gregorian, Date};
 
         let mut related_iso = 1900;
-        let mut lunar_month = Month::new_unchecked(11, false);
+        let mut lunar_month = Month::new(11);
 
         for year in 1901..=2100 {
             println!("Validating year {year}...");
@@ -1737,7 +1734,7 @@ mod test {
                 let chinese = Date::try_new_from_codes(
                     None,
                     related_iso,
-                    lunar_month.to_month_code(),
+                    lunar_month.code(),
                     lunar_day,
                     ChineseTraditional::new(),
                 )
@@ -1825,21 +1822,21 @@ mod test {
                         for (start_year, start_month, end_year, end_month, by) in [
                             (
                                 reference_year_end.extended_year(),
-                                reference_year_end.month().month_number(),
+                                reference_year_end.month().number(),
                                 year_1900_start.extended_year(),
-                                year_1900_start.month().month_number(),
+                                year_1900_start.month().number(),
                                 -1,
                             ),
                             (
                                 reference_year_end.extended_year(),
-                                reference_year_end.month().month_number(),
+                                reference_year_end.month().number(),
                                 year_2035_end.extended_year(),
-                                year_2035_end.month().month_number(),
+                                year_2035_end.month().number(),
                                 1,
                             ),
                             (
                                 year_1900_start.extended_year(),
-                                year_1900_start.month().month_number(),
+                                year_1900_start.month().number(),
                                 -10000,
                                 1,
                                 -1,

components/calendar/src/cal/hebrew.rs

@@ -326,16 +326,16 @@ impl Calendar for Hebrew {
         let standard = self.month_from_ordinal(&date.0.year(), date.0.month());
 
         let formatting = if standard.number() == 6 && date.0.month() == 7 {
-            Month::new_unchecked(6, true) // M06L
+            Month::leap(6)
         } else {
             standard
         };
 
         types::MonthInfo {
             ordinal: date.0.month(),
-            standard_code: standard.to_month_code(),
+            standard_code: standard.code(),
             standard,
-            formatting_code: formatting.to_month_code(),
+            formatting_code: formatting.code(),
             formatting,
         }
     }
@@ -377,19 +377,19 @@ mod tests {
     use super::*;
     use crate::types::MonthCode;
 
-    pub const TISHREI: Month = Month::new_unchecked(1, false);
-    pub const ḤESHVAN: Month = Month::new_unchecked(2, false);
-    pub const KISLEV: Month = Month::new_unchecked(3, false);
-    pub const TEVET: Month = Month::new_unchecked(4, false);
-    pub const SHEVAT: Month = Month::new_unchecked(5, false);
-    pub const ADARI: Month = Month::new_unchecked(5, true);
-    pub const ADAR: Month = Month::new_unchecked(6, false);
-    pub const NISAN: Month = Month::new_unchecked(7, false);
-    pub const IYYAR: Month = Month::new_unchecked(8, false);
-    pub const SIVAN: Month = Month::new_unchecked(9, false);
-    pub const TAMMUZ: Month = Month::new_unchecked(10, false);
-    pub const AV: Month = Month::new_unchecked(11, false);
-    pub const ELUL: Month = Month::new_unchecked(12, false);
+    pub const TISHREI: Month = Month::new(1);
+    pub const ḤESHVAN: Month = Month::new(2);
+    pub const KISLEV: Month = Month::new(3);
+    pub const TEVET: Month = Month::new(4);
+    pub const SHEVAT: Month = Month::new(5);
+    pub const ADARI: Month = Month::leap(5);
+    pub const ADAR: Month = Month::new(6);
+    pub const NISAN: Month = Month::new(7);
+    pub const IYYAR: Month = Month::new(8);
+    pub const SIVAN: Month = Month::new(9);
+    pub const TAMMUZ: Month = Month::new(10);
+    pub const AV: Month = Month::new(11);
+    pub const ELUL: Month = Month::new(12);
 
     /// The leap years used in the tests below
     const LEAP_YEARS_IN_TESTS: [i32; 1] = [5782];
@@ -452,7 +452,7 @@ mod tests {
     fn test_conversions() {
         for ((iso_y, iso_m, iso_d), (y, m, d)) in ISO_HEBREW_DATE_PAIRS.into_iter() {
             let iso_date = Date::try_new_iso(iso_y, iso_m, iso_d).unwrap();
-            let hebrew_date = Date::try_new_from_codes(Some("am"), y, m.to_month_code(), d, Hebrew)
+            let hebrew_date = Date::try_new_from_codes(Some("am"), y, m.code(), d, Hebrew)
                 .expect("Date should parse");
 
             let iso_to_hebrew = iso_date.to_calendar(Hebrew);

components/calendar/src/cal/iso.rs

@@ -184,7 +184,7 @@ mod test {
             assert_eq!(
                 (
                     date_from_rd.era_year().year,
-                    date_from_rd.month().month_number(),
+                    date_from_rd.month().number(),
                     date_from_rd.day_of_month().0
                 ),
                 (case.year, case.month, case.day),

components/calendar/src/calendar_arithmetic.rs

@@ -184,7 +184,7 @@ pub(crate) trait DateFieldsResolver: Calendar {
     /// The default impl is for non-lunisolar calendars!
     #[inline]
     fn month_from_ordinal(&self, _year: &Self::YearInfo, ordinal_month: u8) -> Month {
-        Month::new_unchecked(ordinal_month, false)
+        Month::new(ordinal_month)
     }
 }
 
@@ -573,12 +573,8 @@ impl<C: DateFieldsResolver> ArithmeticDate<C> {
             .map_err(|e| {
                 // TODO: Use a narrower error type here. For now, convert into DateError.
                 match e {
-                    MonthCodeError::NotInCalendar => {
-                        DateError::UnknownMonthCode(base_month.to_month_code())
-                    }
-                    MonthCodeError::NotInYear => {
-                        DateError::UnknownMonthCode(base_month.to_month_code())
-                    }
+                    MonthCodeError::NotInCalendar => DateError::UnknownMonthCode(base_month.code()),
+                    MonthCodeError::NotInYear => DateError::UnknownMonthCode(base_month.code()),
                 }
             })?;
         // 1. Let _endOfMonth_ be BalanceNonISODate(_calendar_, _y0_, _m0_ + _duration_.[[Months]] + 1, 0).

components/calendar/src/error.rs

@@ -309,9 +309,11 @@ impl From<UnknownEraError> for DateFromFieldsError {
     }
 }
 
-/// Internal narrow error type for functions that only fail on parsing month codes
+/// Error for [`Month`](crate::types::Month) parsing
 #[derive(Debug)]
-pub(crate) enum MonthCodeParseError {
+#[non_exhaustive]
+pub enum MonthCodeParseError {
+    /// Invalid syntax
     InvalidSyntax,
 }
 

components/calendar/src/types.rs

@@ -371,7 +371,7 @@ impl MonthCode {
     pub fn new_normal(number: u8) -> Option<Self> {
         (1..=99)
             .contains(&number)
-            .then(|| Month::new_unchecked(number, false).to_month_code())
+            .then(|| Month::new(number).code())
     }
 
     /// Construct a "leap" month code given a number ("MxxL").
@@ -380,7 +380,7 @@ impl MonthCode {
     pub fn new_leap(number: u8) -> Option<Self> {
         (1..=99)
             .contains(&number)
-            .then(|| Month::new_unchecked(number, true).to_month_code())
+            .then(|| Month::leap(number).code())
     }
 }
 
@@ -427,17 +427,42 @@ impl fmt::Display for MonthCode {
     }
 }
 
-/// A [`MonthCode`] that has been parsed into its internal representation.
-#[derive(Copy, Clone, Debug, PartialEq)]
-pub(crate) struct Month {
+/// A representation of a month.
+#[derive(Copy, Clone, Debug, PartialEq, Hash, Eq)]
+pub struct Month {
     /// Month number between 0 and 99
     number: u8,
     is_leap: bool,
 }
 
 impl Month {
-    #[inline]
-    pub(crate) fn try_from_utf8(bytes: &[u8]) -> Result<Self, MonthCodeParseError> {
+    /// Constructs a non-leap with with the given number.
+    ///
+    /// The input saturates at 99.
+    pub const fn new(number: u8) -> Self {
+        Self {
+            number: if number > 99 { 99 } else { number },
+            is_leap: false,
+        }
+    }
+
+    /// Constructs a non-leap with with the given number.
+    ///
+    /// The input saturates at 99.
+    pub const fn leap(number: u8) -> Self {
+        Self {
+            number,
+            is_leap: true,
+        }
+    }
+
+    /// Parses Temporal month code syntax
+    pub fn try_from_str(s: &str) -> Result<Self, MonthCodeParseError> {
+        Self::try_from_utf8(s.as_bytes())
+    }
+
+    /// Parses Temporal month code syntax
+    pub fn try_from_utf8(bytes: &[u8]) -> Result<Self, MonthCodeParseError> {
         match *bytes {
             [b'M', tens, ones] => Ok(Self {
                 number: (tens - b'0') * 10 + ones - b'0',
@@ -452,19 +477,22 @@ impl Month {
     }
 
     /// Create a new ValidMonthCode without checking that the number is between 1 and 99
-    #[inline]
     pub(crate) const fn new_unchecked(number: u8, is_leap: bool) -> Self {
         debug_assert!(1 <= number && number <= 99);
         Self { number, is_leap }
     }
 
-    /// Returns the month number according to the month code.
+    /// Returns the month number.
+    ///
+    /// A month number N is not necessarily the Nth month in the year if there are leap
+    /// months in the year, rather it is associated with the Nth month of a "regular"
+    /// year. There may be multiple month Ns in a year.
     ///
     /// This is NOT the same as the ordinal month!
     ///
     /// # Examples
     ///
-    /// ```ignore
+    /// ```
     /// use icu::calendar::Date;
     /// use icu::calendar::cal::Hebrew;
     ///
@@ -473,25 +501,24 @@ impl Month {
     ///
     /// // Hebrew year 5784 was a leap year, so the ordinal month and month number diverge.
     /// assert_eq!(month_info.ordinal, 10);
-    /// assert_eq!(month_info.valid_month_code.number(), 9);
+    /// assert_eq!(month_info.number(), 9);
     /// ```
-    #[inline]
     pub fn number(self) -> u8 {
         self.number
     }
 
     /// Returns whether the month is a leap month.
     ///
-    /// This is true for intercalary months in [`Hebrew`] and [`LunarChinese`].
+    /// This is true for intercalary months in [`Hebrew`] and [`EastAsianTraditional`].
     ///
     /// [`Hebrew`]: crate::cal::Hebrew
-    /// [`LunarChinese`]: crate::cal::LunarChinese
-    #[inline]
+    /// [`LunarChinese`]: crate::cal::east_asian_traditional::EastAsianTraditional
     pub fn is_leap(self) -> bool {
         self.is_leap
     }
 
-    pub(crate) fn to_month_code(self) -> MonthCode {
+    /// Returns the [`MonthCode`] for this month.
+    pub fn code(self) -> MonthCode {
         #[allow(clippy::unwrap_used)] // by construction
         MonthCode(
             TinyAsciiStr::try_from_raw([
@@ -547,39 +574,45 @@ pub struct MonthInfo {
     pub(crate) formatting: Month,
 }
 
+impl core::ops::Deref for MonthInfo {
+    type Target = Month;
+
+    fn deref(&self) -> &Self::Target {
+        &self.standard
+    }
+}
+
 impl MonthInfo {
     pub(crate) fn non_lunisolar(number: u8) -> Self {
-        Self::for_month_and_ordinal(Month::new_unchecked(number, false), number)
+        Self::for_month_and_ordinal(Month::new(number), number)
     }
 
     pub(crate) fn for_month_and_ordinal(month: Month, ordinal: u8) -> Self {
         Self {
             ordinal,
-            standard_code: month.to_month_code(),
+            standard_code: month.code(),
             standard: month,
-            formatting_code: month.to_month_code(),
+            formatting_code: month.code(),
             formatting: month,
         }
     }
 
-    /// Gets the month number. A month number N is not necessarily the Nth month in the year
-    /// if there are leap months in the year, rather it is associated with the Nth month of a "regular"
-    /// year. There may be multiple month Ns in a year
+    #[doc(hidden)] // available through Deref<Target = Month>
     pub fn month_number(self) -> u8 {
         self.standard.number()
     }
 
-    /// Get whether the month is a leap month
+    #[doc(hidden)] // available through Deref<Target = Month>
     pub fn is_leap(self) -> bool {
         self.standard.is_leap()
     }
 
-    #[doc(hidden)]
+    #[doc(hidden)] // for formatting
     pub fn formatting_month_number(self) -> u8 {
         self.formatting.number()
     }
 
-    #[doc(hidden)]
+    #[doc(hidden)] // for formatting
     pub fn formatting_is_leap(self) -> bool {
         self.formatting.is_leap()
     }

components/time/src/zone/zone_name_timestamp.rs

@@ -219,7 +219,7 @@ impl serde::Serialize for ZoneNameTimestamp {
         if serializer.is_human_readable() {
             let date_time = self.to_zoned_date_time_iso();
             let year = date_time.date.era_year().year;
-            let month = date_time.date.month().month_number();
+            let month = date_time.date.month().number();
             let day = date_time.date.day_of_month().0;
             let hour = date_time.time.hour.number();
             let minute = date_time.time.minute.number();