Clean up icu_datetime/experimental (#4096)

components/datetime/src/any/datetime.rs

@@ -2,8 +2,6 @@
 // called LICENSE at the top level of the ICU4X source tree
 // (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
 
-#[cfg(feature = "experimental")]
-use crate::options::components;
 use crate::provider::{calendar::*, date_time::PatternSelector};
 use crate::{calendar, options::DateTimeFormatterOptions, raw, DateFormatter, TimeFormatter};
 use crate::{input::DateTimeInput, DateTimeError, FormattedDateTime};
@@ -277,7 +275,7 @@ impl DateTimeFormatter {
 
     /// Constructor that supports experimental options with compiled data.
     ///
-    /// ✨ *Enabled with the `compiled_data` Cargo feature.*
+    /// ✨ *Enabled with the `compiled_data` and `experimental` Cargo features.*
     ///
     /// [📚 Help choosing a constructor](icu_provider::constructors)
     ///
@@ -499,11 +497,20 @@ where {
         Ok(self.format(value)?.write_to_string().into_owned())
     }
 
-    /// Returns a [`components::Bag`] that represents the resolved components for the
+    /// Returns a [`components::Bag`](crate::options::components::Bag) that represents the resolved components for the
     /// options that were provided to the [`DateTimeFormatter`]. The developer may request
     /// a certain set of options for a [`DateTimeFormatter`] but the locale and resolution
     /// algorithm may change certain details of what actually gets resolved.
     ///
+    /// ✨ *Enabled with the `experimental` Cargo feature.*
+    ///
+    /// <div class="stab unstable">
+    /// 🚧 This code is experimental; it may change at any time, in breaking or non-breaking ways,
+    /// including in SemVer minor releases. It can be enabled with the "experimental" Cargo feature
+    /// of the icu meta-crate. Use with caution.
+    /// <a href="https://github.com/unicode-org/icu4x/issues/1317">#1317</a>
+    /// </div>
+    ///
     /// # Examples
     ///
     /// ```
@@ -529,7 +536,7 @@ where {
     /// assert_eq!(dtf.resolve_components(), expected_components_bag);
     /// ```
     #[cfg(feature = "experimental")]
-    pub fn resolve_components(&self) -> components::Bag {
+    pub fn resolve_components(&self) -> crate::options::components::Bag {
         self.0.resolve_components()
     }
 

components/datetime/src/any/zoned_datetime.rs

@@ -127,10 +127,17 @@ impl ZonedDateTimeFormatter {
     /// This method will pick the calendar off of the locale; and if unspecified or unknown will fall back to the default
     /// calendar for the locale. See [`AnyCalendarKind`] for a list of supported calendars.
     ///
-    /// ✨ *Enabled with the `compiled_data` Cargo feature.*
+    /// ✨ *Enabled with the `compiled_data` and `experimental` Cargo features.*
     ///
     /// [📚 Help choosing a constructor](icu_provider::constructors)
     ///
+    /// <div class="stab unstable">
+    /// 🚧 This code is experimental; it may change at any time, in breaking or non-breaking ways,
+    /// including in SemVer minor releases. It can be enabled with the "experimental" Cargo feature
+    /// of the icu meta-crate. Use with caution.
+    /// <a href="https://github.com/unicode-org/icu4x/issues/1317">#1317</a>
+    /// </div>
+    ///
     /// # Examples
     ///
     /// ```

components/datetime/src/datetime.rs

@@ -24,9 +24,6 @@ use crate::{
     DateTimeError, FormattedDateTime,
 };
 
-#[cfg(feature = "experimental")]
-use crate::options::components;
-
 /// [`TimeFormatter`] is a structure of the [`icu_datetime`] component that provides time formatting only.
 /// When constructed, it uses data from the [data provider], selected locale and provided preferences to
 /// collect all data necessary to format any time into that locale.
@@ -591,7 +588,7 @@ where {
 
     /// Constructor that supports experimental options using compiled data.
     ///
-    /// ✨ *Enabled with the `compiled_data` Cargo feature.*
+    /// ✨ *Enabled with the `compiled_data` and `experimental` Cargo features.*
     ///
     /// [📚 Help choosing a constructor](icu_provider::constructors)
     ///
@@ -661,41 +658,7 @@ where {
         ))
     }
 
-    /// Constructor that supports experimental options.
-    ///
-    /// <div class="stab unstable">
-    /// 🚧 This code is experimental; it may change at any time, in breaking or non-breaking ways,
-    /// including in SemVer minor releases. It can be enabled with the "experimental" Cargo feature
-    /// of the icu meta-crate. Use with caution.
-    /// <a href="https://github.com/unicode-org/icu4x/issues/1317">#1317</a>
-    /// </div>
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// use icu::calendar::{DateTime, Gregorian};
-    /// use icu::datetime::{options::components, TypedDateTimeFormatter};
-    /// use icu::locid::locale;
-    /// use icu_provider::AsDeserializingBufferProvider;
-    /// use writeable::assert_writeable_eq;
-    ///
-    /// let mut options = components::Bag::default();
-    /// options.year = Some(components::Year::Numeric);
-    /// options.month = Some(components::Month::Long);
-    ///
-    /// let dtf = TypedDateTimeFormatter::<Gregorian>::try_new_experimental(
-    ///     &locale!("en").into(),
-    ///     options.into(),
-    /// )
-    /// .unwrap();
-    ///
-    /// let datetime =
-    ///     DateTime::try_new_gregorian_datetime(2022, 8, 31, 1, 2, 3).unwrap();
-    ///
-    /// assert_writeable_eq!(dtf.format(&datetime), "August 2022");
-    /// ```
-    ///
-    /// [data provider]: icu_provider
+    #[doc = icu_provider::gen_any_buffer_unstable_docs!(UNSTABLE, Self::try_new_experimental)]
     #[cfg(feature = "experimental")]
     #[inline]
     pub fn try_new_experimental_unstable<D>(
@@ -781,7 +744,7 @@ where {
         self.format(value).write_to_string().into_owned()
     }
 
-    /// Returns a [`components::Bag`] that represents the resolved components for the
+    /// Returns a [`components::Bag`](crate::options::components::Bag) that represents the resolved components for the
     /// options that were provided to the [`TypedDateTimeFormatter`]. The developer may request
     /// a certain set of options for a [`TypedDateTimeFormatter`] but the locale and resolution
     /// algorithm may change certain details of what actually gets resolved.
@@ -811,7 +774,7 @@ where {
     /// assert_eq!(dtf.resolve_components(), expected_components_bag);
     /// ```
     #[cfg(feature = "experimental")]
-    pub fn resolve_components(&self) -> components::Bag {
+    pub fn resolve_components(&self) -> crate::options::components::Bag {
         self.0.resolve_components()
     }
 }

components/datetime/src/error.rs

@@ -5,8 +5,6 @@
 use crate::fields::FieldSymbol;
 use crate::input::CalendarError;
 use crate::pattern::PatternError;
-#[cfg(feature = "experimental")]
-use crate::skeleton::SkeletonError;
 use displaydoc::Display;
 use icu_calendar::any_calendar::AnyCalendarKind;
 use icu_calendar::types::MonthCode;
@@ -39,7 +37,7 @@ pub enum DateTimeError {
     /// An error originating from skeleton matching.
     #[displaydoc("{0}")]
     #[cfg(feature = "experimental")]
-    Skeleton(SkeletonError),
+    Skeleton(crate::skeleton::SkeletonError),
     /// An error originating from an unsupported field in a datetime format.
     #[displaydoc("Unsupported field: {0:?}")]
     UnsupportedField(FieldSymbol),
@@ -96,13 +94,6 @@ impl From<core::fmt::Error> for DateTimeError {
     }
 }
 
-#[cfg(feature = "experimental")]
-impl From<SkeletonError> for DateTimeError {
-    fn from(e: SkeletonError) -> Self {
-        DateTimeError::Skeleton(e)
-    }
-}
-
 impl From<PluralsError> for DateTimeError {
     fn from(e: PluralsError) -> Self {
         DateTimeError::PluralRules(e)

components/datetime/src/options/components.rs

@@ -4,6 +4,8 @@
 
 //! 🚧 \[Experimental\] Options for constructing DateTimeFormatter objects by each component style.
 //!
+//! ✨ *Enabled with the `experimental` Cargo feature.*
+//!
 //! <div class="stab unstable">
 //! 🚧 This code is experimental; it may change at any time, in breaking or non-breaking ways,
 //! including in SemVer minor releases. It can be enabled with the "experimental" Cargo feature
@@ -85,9 +87,6 @@ use crate::{
     pattern::{runtime::PatternPlurals, PatternItem},
 };
 
-#[cfg(feature = "experimental")]
-use alloc::vec::Vec;
-
 use super::preferences;
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
@@ -146,8 +145,8 @@ impl Bag {
     /// significant field to least significant. This is the order the fields are listed in
     /// the UTS 35 table - https://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
     #[cfg(any(test, feature = "experimental"))] // only used in test and experimental code
-    pub(crate) fn to_vec_fields(&self) -> Vec<Field> {
-        let mut fields = Vec::new();
+    pub(crate) fn to_vec_fields(&self) -> alloc::vec::Vec<Field> {
+        let mut fields = alloc::vec::Vec::new();
         if let Some(era) = self.era {
             fields.push(Field {
                 symbol: FieldSymbol::Era,

components/datetime/src/options/mod.rs

@@ -62,6 +62,8 @@ pub enum DateTimeFormatterOptions {
     Length(length::Bag),
     /// Bag of components describing which fields and how should be displayed.
     ///
+    /// ✨ *Enabled with the `experimental` Cargo feature.*
+    ///
     /// <div class="stab unstable">
     /// 🚧 This code is experimental; it may change at any time, in breaking or non-breaking ways,
     /// including in SemVer minor releases. It can be enabled with the "experimental" Cargo feature

components/datetime/src/options/preferences.rs

@@ -4,6 +4,8 @@
 
 //! 🚧 \[Experimental\] Types to hold user preferences to configure a DateTimeFormatter.
 //!
+//! ✨ *Enabled with the `experimental` Cargo feature.*
+//!
 //! Preferences is a bag of options to be associated with either [`length::Bag`] or [`components::Bag`]
 //! which provides information on user preferences that can affect the result of the formatting.
 //!

components/datetime/src/provider/date_time.rs

@@ -277,7 +277,6 @@ where
         )))
     }
 
-    #[cfg(feature = "experimental")]
     fn skeleton_data_payload(&self) -> Result<DataPayload<DateSkeletonPatternsV1Marker>> {
         use icu_locid::extensions::unicode::{key, value};
         use tinystr::tinystr;

components/datetime/src/raw/datetime.rs

@@ -5,8 +5,6 @@
 //! The collection of code that is needed for handling formatting operations for DateTimes.
 //! Central to this is the [`DateTimeFormatter`].
 
-#[cfg(feature = "experimental")]
-use crate::options::components;
 use crate::{
     format::datetime,
     input::{DateInput, DateTimeInput, ExtractedDateTimeInput, IsoTimeInput},
@@ -526,10 +524,10 @@ impl DateTimeFormatter {
         }
     }
 
-    /// Returns a [`components::Bag`] that represents the resolved components for the
+    /// Returns a [`components::Bag`](crate::options::components::Bag) that represents the resolved components for the
     /// options that were provided to the [`DateTimeFormatter`].
     #[cfg(feature = "experimental")]
-    pub fn resolve_components(&self) -> components::Bag {
-        components::Bag::from(&self.patterns.get().0)
+    pub fn resolve_components(&self) -> crate::options::components::Bag {
+        crate::options::components::Bag::from(&self.patterns.get().0)
     }
 }

components/datetime/src/skeleton/error.rs

@@ -34,6 +34,13 @@ pub enum SkeletonError {
 #[cfg(feature = "std")]
 impl std::error::Error for SkeletonError {}
 
+#[cfg(feature = "experimental")]
+impl From<SkeletonError> for crate::DateTimeError {
+    fn from(e: SkeletonError) -> Self {
+        crate::DateTimeError::Skeleton(e)
+    }
+}
+
 impl From<fields::Error> for SkeletonError {
     fn from(e: fields::Error) -> Self {
         SkeletonError::Fields(e)