Rename datetime format functions and traits (#5847)

#5837

README.md

@@ -49,7 +49,7 @@ let dtf = DateTimeFormatter::try_new(
 let date = DateTime::try_new_iso(2020, 9, 12, 12, 35, 0).expect("datetime should be valid");
 let date = date.to_any();
 
-let formatted_date = dtf.convert_and_format(&date).to_string_lossy();
+let formatted_date = dtf.format_any_calendar(&date).to_string_lossy();
 assert_eq!(
     formatted_date,
     "12 de septiembre de 2020, 12:35:00"

components/datetime/src/combo.rs

@@ -45,7 +45,7 @@ use crate::{provider::neo::*, scaffold::*};
 /// .unwrap();
 ///
 /// assert_try_writeable_eq!(
-///     formatter.convert_and_format(&zdt),
+///     formatter.format_any_calendar(&zdt),
 ///     "Fri, 3:44 PM Los Angeles Time"
 /// );
 /// ```
@@ -102,7 +102,7 @@ use crate::{provider::neo::*, scaffold::*};
 /// .unwrap();
 ///
 /// assert_try_writeable_eq!(
-///     formatter.convert_and_format(&zdt),
+///     formatter.format_any_calendar(&zdt),
 ///     "October 18, 2024 PT"
 /// );
 /// ```

components/datetime/src/dynamic.rs

@@ -50,7 +50,7 @@
 //! let results = [true, false].map(get_field_set).map(|field_set| {
 //!     DateTimeFormatter::try_new(locale!("en-US").into(), field_set).unwrap()
 //! }).map(|formatter| {
-//!     formatter.convert_and_format(&datetime).try_write_to_string().unwrap().into_owned()
+//!     formatter.format_any_calendar(&datetime).try_write_to_string().unwrap().into_owned()
 //! });
 //!
 //! assert_eq!(results, ["Jan 15, 4:00 PM", "Jan 15"])

components/datetime/src/fieldsets.rs

@@ -380,7 +380,7 @@ macro_rules! impl_date_or_calendar_period_marker {
             /// let dt = Date::try_new_iso(2024, 5, 17).unwrap();
             ///
             /// assert_try_writeable_eq!(
-            ///     fmt.convert_and_format(&dt),
+            ///     fmt.format_any_calendar(&dt),
             #[doc = concat!("    \"", $sample, "\"")]
             /// );
             /// ```
@@ -526,7 +526,7 @@ macro_rules! impl_date_marker {
             /// let dt = DateTime::try_new_iso(2024, 5, 17, 15, 47, 50).unwrap();
             ///
             /// assert_try_writeable_eq!(
-            ///     fmt.convert_and_format(&dt),
+            ///     fmt.format_any_calendar(&dt),
             #[doc = concat!("    \"", $sample_time, "\"")]
             /// );
             /// ```
@@ -922,7 +922,7 @@ macro_rules! impl_zoneddatetime_marker {
         /// let mut dtz = IxdtfParser::new().try_from_str("2024-05-17T15:47:50+01:00[Europe/London]").unwrap();
         ///
         /// assert_try_writeable_eq!(
-        ///     fmt.convert_and_format(&dtz),
+        ///     fmt.format_any_calendar(&dtz),
         #[doc = concat!("    \"", $sample, "\"")]
         /// );
         /// ```

components/datetime/src/lib.rs

@@ -64,7 +64,7 @@
 //!
 //! // Format something:
 //! let datetime = DateTime::try_new_iso(2025, 1, 15, 16, 9, 35).unwrap();
-//! let formatted_date = dtf.convert_and_format(&datetime);
+//! let formatted_date = dtf.format_any_calendar(&datetime);
 //!
 //! assert_try_writeable_eq!(formatted_date, "15 de ene de 2025, 4:09 p. m.");
 //! ```

components/datetime/src/neo.rs

@@ -14,7 +14,7 @@ use crate::raw::neo::*;
 use crate::scaffold::*;
 use crate::scaffold::{
     AllInputMarkers, ConvertCalendar, DateDataMarkers, DateInputMarkers, DateTimeMarkers, GetField,
-    IsAnyCalendarKind, IsInCalendar, TimeMarkers, TypedDateDataMarkers, ZoneMarkers,
+    InFixedCalendar, InSameCalendar, TimeMarkers, TypedDateDataMarkers, ZoneMarkers,
 };
 use crate::size_test_macro::size_test;
 use crate::DateTimeWriteError;
@@ -330,7 +330,7 @@ where
     /// ```
     pub fn format<I>(&self, input: &I) -> FormattedDateTime
     where
-        I: ?Sized + IsInCalendar<C> + AllInputMarkers<FSet>,
+        I: ?Sized + InFixedCalendar<C> + AllInputMarkers<FSet>,
     {
         let input = ExtractedInput::extract_from_neo_input::<FSet::D, FSet::T, FSet::Z, I>(input);
         FormattedDateTime {
@@ -400,7 +400,7 @@ where
     /// let datetime = DateTime::try_new_iso(2024, 5, 8, 0, 0, 0).unwrap();
     ///
     /// assert_try_writeable_eq!(
-    ///     formatter.convert_and_format(&datetime),
+    ///     formatter.format_any_calendar(&datetime),
     ///     "30 Nisan 5784"
     /// );
     /// ```
@@ -535,7 +535,7 @@ where
     /// let date = Date::try_new_gregorian(2023, 12, 20).unwrap();
     ///
     /// assert!(matches!(
-    ///     formatter.strict_format(&date),
+    ///     formatter.format_same_calendar(&date),
     ///     Err(MismatchedCalendarError { .. })
     /// ));
     /// ```
@@ -556,14 +556,14 @@ where
     ///
     /// // the trait `GetField<AnyCalendarKind>`
     /// // is not implemented for `icu::icu_calendar::Time`
-    /// formatter.strict_format(&Time::try_new(0, 0, 0, 0).unwrap());
+    /// formatter.format_same_calendar(&Time::try_new(0, 0, 0, 0).unwrap());
     /// ```
-    pub fn strict_format<I>(
+    pub fn format_same_calendar<I>(
         &self,
         datetime: &I,
     ) -> Result<FormattedDateTime, crate::MismatchedCalendarError>
     where
-        I: ?Sized + IsAnyCalendarKind + AllInputMarkers<FSet>,
+        I: ?Sized + InSameCalendar + AllInputMarkers<FSet>,
     {
         datetime.check_any_calendar_kind(self.calendar.kind())?;
         let datetime =
@@ -599,7 +599,7 @@ where
     /// let date = Date::try_new_roc(113, 5, 8).unwrap();
     ///
     /// assert_try_writeable_eq!(
-    ///     formatter.convert_and_format(&date),
+    ///     formatter.format_any_calendar(&date),
     ///     "30 Nisan 5784"
     /// );
     /// ```
@@ -620,9 +620,9 @@ where
     ///
     /// // the trait `GetField<AnyCalendarKind>`
     /// // is not implemented for `icu::icu_calendar::Time`
-    /// formatter.convert_and_format(&Time::try_new(0, 0, 0, 0).unwrap());
+    /// formatter.format_any_calendar(&Time::try_new(0, 0, 0, 0).unwrap());
     /// ```
-    pub fn convert_and_format<'a, I>(&'a self, datetime: &I) -> FormattedDateTime<'a>
+    pub fn format_any_calendar<'a, I>(&'a self, datetime: &I) -> FormattedDateTime<'a>
     where
         I: ?Sized + ConvertCalendar,
         I::Converted<'a>: Sized + AllInputMarkers<FSet>,
@@ -666,7 +666,7 @@ impl<C: CldrCalendar, FSet: DateTimeMarkers> FixedCalendarDateTimeFormatter<C, F
     /// let date = Date::try_new_iso(2024, 10, 14).unwrap();
     ///
     /// assert_try_writeable_eq!(
-    ///     formatter.convert_and_format(&date),
+    ///     formatter.format_any_calendar(&date),
     ///     "12 Tishri 5785"
     /// );
     /// ```

components/datetime/src/pattern/formatter.rs

@@ -8,7 +8,7 @@ use crate::format::datetime::try_write_pattern_items;
 use crate::input::ExtractedInput;
 use crate::scaffold::*;
 use crate::scaffold::{
-    AllInputMarkers, DateInputMarkers, DateTimeMarkers, IsInCalendar, TimeMarkers,
+    AllInputMarkers, DateInputMarkers, DateTimeMarkers, InFixedCalendar, TimeMarkers,
     TypedDateDataMarkers, ZoneMarkers,
 };
 use crate::DateTimeWriteError;
@@ -195,7 +195,7 @@ where
     /// ```
     pub fn format<I>(&self, datetime: &I) -> FormattedDateTimePattern<'a>
     where
-        I: ?Sized + IsInCalendar<C> + AllInputMarkers<FSet>,
+        I: ?Sized + InFixedCalendar<C> + AllInputMarkers<FSet>,
     {
         FormattedDateTimePattern {
             pattern: self.inner.pattern,

components/datetime/src/scaffold/calendar.rs

@@ -438,10 +438,8 @@ impl<O: TimeZoneModel> ConvertCalendar for TimeZoneInfo<O> {
     }
 }
 
-/// A type that might be compatible with a specific calendar system.
-///
-/// All formattable types should implement this trait.
-pub trait IsAnyCalendarKind {
+/// An input that may be associated with a specific runtime calendar.
+pub trait InSameCalendar {
     /// Checks whether this type is compatible with the given calendar.
     ///
     /// Types that are agnostic to calendar systems should return `Ok(())`.
@@ -451,7 +449,7 @@ pub trait IsAnyCalendarKind {
     ) -> Result<(), MismatchedCalendarError>;
 }
 
-impl<C: Calendar, A: AsCalendar<Calendar = C>> IsAnyCalendarKind for Date<A> {
+impl<C: Calendar, A: AsCalendar<Calendar = C>> InSameCalendar for Date<A> {
     #[inline]
     fn check_any_calendar_kind(
         &self,
@@ -468,14 +466,14 @@ impl<C: Calendar, A: AsCalendar<Calendar = C>> IsAnyCalendarKind for Date<A> {
     }
 }
 
-impl IsAnyCalendarKind for Time {
+impl InSameCalendar for Time {
     #[inline]
     fn check_any_calendar_kind(&self, _: AnyCalendarKind) -> Result<(), MismatchedCalendarError> {
         Ok(())
     }
 }
 
-impl<C: Calendar, A: AsCalendar<Calendar = C>> IsAnyCalendarKind for DateTime<A> {
+impl<C: Calendar, A: AsCalendar<Calendar = C>> InSameCalendar for DateTime<A> {
     #[inline]
     fn check_any_calendar_kind(
         &self,
@@ -492,38 +490,38 @@ impl<C: Calendar, A: AsCalendar<Calendar = C>> IsAnyCalendarKind for DateTime<A>
     }
 }
 
-impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> IsAnyCalendarKind for CustomZonedDateTime<A, Z> {
+impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> InSameCalendar for CustomZonedDateTime<A, Z> {
     #[inline]
     fn check_any_calendar_kind(&self, _: AnyCalendarKind) -> Result<(), MismatchedCalendarError> {
         Ok(())
     }
 }
 
-impl IsAnyCalendarKind for UtcOffset {
+impl InSameCalendar for UtcOffset {
     #[inline]
     fn check_any_calendar_kind(&self, _: AnyCalendarKind) -> Result<(), MismatchedCalendarError> {
         Ok(())
     }
 }
 
-impl<O: TimeZoneModel> IsAnyCalendarKind for TimeZoneInfo<O> {
+impl<O: TimeZoneModel> InSameCalendar for TimeZoneInfo<O> {
     #[inline]
     fn check_any_calendar_kind(&self, _: AnyCalendarKind) -> Result<(), MismatchedCalendarError> {
         Ok(())
     }
 }
 
-/// An input associated with a specific calendar.
-pub trait IsInCalendar<C> {}
+/// An input associated with a fixed, static calendar.
+pub trait InFixedCalendar<C> {}
 
-impl<C: Calendar, A: AsCalendar<Calendar = C>> IsInCalendar<C> for Date<A> {}
+impl<C: Calendar, A: AsCalendar<Calendar = C>> InFixedCalendar<C> for Date<A> {}
 
-impl<C> IsInCalendar<C> for Time {}
+impl<C> InFixedCalendar<C> for Time {}
 
-impl<C: Calendar, A: AsCalendar<Calendar = C>> IsInCalendar<C> for DateTime<A> {}
+impl<C: Calendar, A: AsCalendar<Calendar = C>> InFixedCalendar<C> for DateTime<A> {}
 
-impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> IsInCalendar<C> for CustomZonedDateTime<A, Z> {}
+impl<C: Calendar, A: AsCalendar<Calendar = C>, Z> InFixedCalendar<C> for CustomZonedDateTime<A, Z> {}
 
-impl<C> IsInCalendar<C> for UtcOffset {}
+impl<C> InFixedCalendar<C> for UtcOffset {}
 
-impl<C, O: TimeZoneModel> IsInCalendar<C> for TimeZoneInfo<O> {}
+impl<C, O: TimeZoneModel> InFixedCalendar<C> for TimeZoneInfo<O> {}

components/datetime/src/scaffold/mod.rs

@@ -18,8 +18,8 @@ pub use calendar::CalMarkers;
 pub use calendar::CldrCalendar;
 pub use calendar::ConvertCalendar;
 pub use calendar::FullDataCalMarkers;
-pub use calendar::IsAnyCalendarKind;
-pub use calendar::IsInCalendar;
+pub use calendar::InFixedCalendar;
+pub use calendar::InSameCalendar;
 pub use calendar::NoDataCalMarkers;
 
 pub(crate) use fieldset_traits::datetime_marker_helper;

components/datetime/tests/datetime.rs

@@ -310,7 +310,7 @@ fn assert_fixture_element<A>(
         description
     );
 
-    let actual2 = any_dtf.strict_format(&any_input).unwrap();
+    let actual2 = any_dtf.format_same_calendar(&any_input).unwrap();
     assert_try_writeable_eq!(
         actual2,
         output_value.expectation(),
@@ -319,7 +319,7 @@ fn assert_fixture_element<A>(
         description
     );
 
-    let actual3 = any_dtf.convert_and_format(&iso_any_input);
+    let actual3 = any_dtf.format_any_calendar(&iso_any_input);
     assert_try_writeable_eq!(
         actual3,
         output_value.expectation(),

ffi/capi/src/datetime_formatter.rs

@@ -207,7 +207,7 @@ pub mod ffi {
             value: &Date,
             write: &mut diplomat_runtime::DiplomatWrite,
         ) -> Result<(), DateTimeFormatError> {
-            let _lossy = self.0.convert_and_format(&value.0).try_write_to(write);
+            let _lossy = self.0.format_any_calendar(&value.0).try_write_to(write);
             Ok(())
         }
 
@@ -220,7 +220,7 @@ pub mod ffi {
             write: &mut diplomat_runtime::DiplomatWrite,
         ) -> Result<(), DateTimeFormatError> {
             let any = value.0.to_any();
-            let _lossy = self.0.convert_and_format(&any).try_write_to(write);
+            let _lossy = self.0.format_any_calendar(&any).try_write_to(write);
             Ok(())
         }
 
@@ -230,7 +230,7 @@ pub mod ffi {
             value: &DateTime,
             write: &mut diplomat_runtime::DiplomatWrite,
         ) -> Result<(), DateTimeFormatError> {
-            let _lossy = self.0.convert_and_format(&value.0).try_write_to(write);
+            let _lossy = self.0.format_any_calendar(&value.0).try_write_to(write);
             Ok(())
         }
 
@@ -243,7 +243,7 @@ pub mod ffi {
             write: &mut diplomat_runtime::DiplomatWrite,
         ) -> Result<(), DateTimeFormatError> {
             let any = value.0.to_any();
-            let _lossy = self.0.convert_and_format(&any).try_write_to(write);
+            let _lossy = self.0.format_any_calendar(&any).try_write_to(write);
             Ok(())
         }
     }
@@ -282,7 +282,7 @@ pub mod ffi {
             value: &DateTime,
             write: &mut diplomat_runtime::DiplomatWrite,
         ) -> Result<(), DateTimeFormatError> {
-            let _lossy = self.0.convert_and_format(&value.0).try_write_to(write);
+            let _lossy = self.0.format_any_calendar(&value.0).try_write_to(write);
             Ok(())
         }
 
@@ -295,7 +295,7 @@ pub mod ffi {
             write: &mut diplomat_runtime::DiplomatWrite,
         ) -> Result<(), DateTimeFormatError> {
             let any = value.0.to_any();
-            let _lossy = self.0.convert_and_format(&any).try_write_to(write);
+            let _lossy = self.0.format_any_calendar(&any).try_write_to(write);
             Ok(())
         }
     }

ffi/capi/src/zoned_formatter.rs

@@ -127,7 +127,7 @@ pub mod ffi {
                             .ok_or(DateTimeFormatError::ZoneInfoMissingFields)?,
                     ),
             };
-            let _lossy = self.0.convert_and_format(&zdt).try_write_to(write);
+            let _lossy = self.0.format_any_calendar(&zdt).try_write_to(write);
             Ok(())
         }
 
@@ -147,7 +147,7 @@ pub mod ffi {
                     .at_time((datetime.0.date, datetime.0.time))
                     .with_zone_variant(time_zone.zone_variant.unwrap_or(ZoneVariant::Standard)),
             };
-            let _lossy = self.0.convert_and_format(&zdt).try_write_to(write);
+            let _lossy = self.0.format_any_calendar(&zdt).try_write_to(write);
             Ok(())
         }
     }

ffi/capi/tests/missing_apis.txt

@@ -22,8 +22,8 @@ icu::calendar::types::YearAmbiguity#Enum
 icu::calendar::types::YearInfo::year_ambiguity#FnInStruct
 icu::collator::CollatorPreferences::extend#FnInStruct
 icu::datetime::DateTimeFormatter#Struct
-icu::datetime::DateTimeFormatter::convert_and_format#FnInStruct
-icu::datetime::DateTimeFormatter::strict_format#FnInStruct
+icu::datetime::DateTimeFormatter::format_any_calendar#FnInStruct
+icu::datetime::DateTimeFormatter::format_same_calendar#FnInStruct
 icu::datetime::DateTimeFormatter::try_into_typed_formatter#FnInStruct
 icu::datetime::DateTimeFormatter::try_new#FnInStruct
 icu::datetime::DateTimeFormatterLoadError#Enum