Restrict Rata Die API (#6440)

Fixes #6386

Author: robertbastian

components/calendar/src/types.rs

@@ -4,6 +4,7 @@
 
 //! This module contains various types used by `icu_calendar` and `icu::datetime`
 
+#[doc(no_inline)]
 pub use calendrical_calculations::rata_die::RataDie;
 use core::fmt;
 use core::num::NonZeroU8;

utils/calendrical_calculations/src/rata_die.rs

@@ -12,17 +12,21 @@ use core::ops::{Add, AddAssign, Sub, SubAssign};
 #[allow(unused_imports)]
 use core_maths::*;
 
-/// The *Rata Die*, or *R.D.*, or `fixed_date`: number of days since January 1, 1 CE.
+/// The *Rata Die*, or *R.D.*: number of days since January 1, 1 CE.
 ///
 /// See: <https://en.wikipedia.org/wiki/Rata_Die>
 ///
-/// It is a logic error to construct a RataDie
-/// except from a date that is in range of one of the official calendars.
+/// Typically, one should obtain RataDies from other calendrical code, rather than constructing them from integers.
+/// The valid range for direct construction is deliberately not documented as it may change.
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct RataDie(i64);
 
 impl RataDie {
-    /// Create a RataDie
+    /// Create a `RataDie`
+    ///
+    /// Typically, one should obtain `RataDie`s from other calendrical code, rather than
+    /// constructing them from integers. The valid range for direct construction is
+    /// deliberately not documented as it may change.
     pub const fn new(fixed_date: i64) -> Self {
         let result = Self(fixed_date);
         #[cfg(debug_assertions)]
@@ -32,7 +36,7 @@ impl RataDie {
 
     /// Check that it is in range
     #[cfg(debug_assertions)]
-    pub const fn check(&self) {
+    const fn check(self) {
         if self.0 > i64::MAX / 256 {
             debug_assert!(
                 false,
@@ -47,34 +51,34 @@ impl RataDie {
         }
     }
 
-    /// A valid RataDie that is intended to be below all dates representable in calendars
-    #[doc(hidden)] // for testing only
+    /// A valid `RataDie` that is intended to be below all dates representable in calendars
+    #[doc(hidden)]
     pub const fn big_negative() -> Self {
         Self::new(i64::MIN / 256 / 256)
     }
 
-    /// Convert this to an i64 value representing the RataDie
+    /// Convert this to an `i64` value representing the `RataDie`
     pub const fn to_i64_date(self) -> i64 {
         self.0
     }
 
-    /// Convert this to an f64 value representing the RataDie
-    pub const fn to_f64_date(self) -> f64 {
+    /// Convert this to an `f64` value representing the `RataDie`
+    pub(crate) const fn to_f64_date(self) -> f64 {
         self.0 as f64
     }
 
-    /// Calculate the number of days between two RataDie in a const-friendly way
+    /// Calculate the number of days between two `RataDie` in a const-friendly way
     pub const fn const_diff(self, rhs: Self) -> i64 {
         self.0 - rhs.0
     }
 
-    /// Adds a number of days to this RataDie in a const-friendly way
+    /// Adds a number of days to this `RataDie` in a const-friendly way
     pub const fn const_add(self, rhs: i64) -> Self {
         Self(self.0 + rhs)
     }
 
     /// Convert this to a [`Moment`]
-    pub const fn as_moment(&self) -> Moment {
+    pub(crate) const fn as_moment(self) -> Moment {
         Moment::new(self.0 as f64)
     }
 }
@@ -141,7 +145,7 @@ impl Sub for RataDie {
 /// NOTE: This should not cause overflow errors for most cases, but consider
 /// alternative implementations if necessary.
 #[derive(Debug, Copy, Clone, PartialEq, PartialOrd)]
-pub struct Moment(f64);
+pub(crate) struct Moment(f64);
 
 /// Add a number of days to a Moment
 impl Add<f64> for Moment {
@@ -186,12 +190,12 @@ impl Moment {
     }
 
     /// Get the inner field of a Moment
-    pub const fn inner(&self) -> f64 {
+    pub const fn inner(self) -> f64 {
         self.0
     }
 
     /// Get the RataDie of a Moment
-    pub fn as_rata_die(&self) -> RataDie {
+    pub fn as_rata_die(self) -> RataDie {
         RataDie::new(self.0.floor() as i64)
     }
 }