@@ -134,6 +134,71 @@ size_test!(FixedCalendarDateTimeFormatter<icu_calendar::Gregorian, crate::fields
134134/// a calendar selected at compile time.
135135///
136136/// For more details, please read the [crate root docs][crate].
137+ ///
138+ /// # Examples
139+ ///
140+ /// Basic usage:
141+ ///
142+ /// ```
143+ /// use icu::calendar::cal::JapaneseExtended;
144+ /// use icu::datetime::fieldsets::YMD;
145+ /// use icu::datetime::input::Date;
146+ /// use icu::datetime::FixedCalendarDateTimeFormatter;
147+ /// use icu::locale::locale;
148+ /// use writeable::assert_writeable_eq;
149+ ///
150+ /// // The JapaneseExtended generic is inferred by passing this a JapaneseExtended date later
151+ /// let formatter = FixedCalendarDateTimeFormatter::try_new(
152+ /// locale!("es-MX").into(),
153+ /// YMD::long(),
154+ /// )
155+ /// .unwrap();
156+ ///
157+ /// assert_writeable_eq!(
158+ /// formatter.format(&Date::try_new_iso(2023, 12, 20).unwrap().to_calendar(JapaneseExtended::new())),
159+ /// "20 de diciembre de 5 Reiwa"
160+ /// );
161+ /// ```
162+ ///
163+ /// Mismatched calendars will not compile:
164+ ///
165+ /// ```compile_fail
166+ /// use icu::datetime::input::Date;
167+ /// use icu::datetime::input::cal::Buddhist;
168+ /// use icu::datetime::FixedCalendarDateTimeFormatter;
169+ /// use icu::datetime::fieldsets::YMD;
170+ /// use icu::locale::locale;
171+ ///
172+ /// let formatter =
173+ /// FixedCalendarDateTimeFormatter::<Buddhist, _>::try_new(
174+ /// locale!("es-MX").into(),
175+ /// YMD::long(),
176+ /// )
177+ /// .unwrap();
178+ ///
179+ /// // type mismatch resolving `<Gregorian as AsCalendar>::Calendar == Buddhist`
180+ /// formatter.format(&Date::try_new_gregorian(2023, 12, 20).unwrap());
181+ /// ```
182+ ///
183+ /// As with [`DateTimeFormatter`], a time cannot be passed into the formatter when a date is expected:
184+ ///
185+ /// ```compile_fail,E0277
186+ /// use icu::datetime::input::Time;
187+ /// use icu::calendar::Gregorian;
188+ /// use icu::datetime::FixedCalendarDateTimeFormatter;
189+ /// use icu::datetime::fieldsets::YMD;
190+ /// use icu::locale::locale;
191+ ///
192+ /// let formatter =
193+ /// FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
194+ /// locale!("es-MX").into(),
195+ /// YMD::long(),
196+ /// )
197+ /// .unwrap();
198+ ///
199+ /// // error[E0277]: the trait bound `Time: AllInputMarkers<fieldsets::YMD>` is not satisfied
200+ /// formatter.format(&Time::midnight());
201+ /// ```
137202#[ doc = typed_neo_year_month_day_formatter_size ! ( ) ]
138203#[ derive( Debug , Clone ) ]
139204pub struct FixedCalendarDateTimeFormatter < C : CldrCalendar , FSet : DateTimeNamesMarker > {
@@ -154,35 +219,6 @@ where
154219///
155220/// This ignores the `calendar_kind` preference and instead uses the static calendar type,
156221/// and supports calendars that are not expressible as preferences, such as [`JapaneseExtended`](icu_calendar::cal::JapaneseExtended).
157- ///
158- /// Use this constructor for optimal data size and memory use
159- /// if you know the required datetime components at build time.
160- /// If you do not know the datetime components until runtime,
161- /// use a `with_components` constructor.
162- ///
163- /// # Examples
164- ///
165- /// Basic usage:
166- ///
167- /// ```
168- /// use icu::calendar::cal::JapaneseExtended;
169- /// use icu::datetime::fieldsets::YMD;
170- /// use icu::datetime::input::Date;
171- /// use icu::datetime::FixedCalendarDateTimeFormatter;
172- /// use icu::locale::locale;
173- /// use writeable::assert_writeable_eq;
174- ///
175- /// let formatter = FixedCalendarDateTimeFormatter::try_new(
176- /// locale!("es-MX").into(),
177- /// YMD::long(),
178- /// )
179- /// .unwrap();
180- ///
181- /// assert_writeable_eq!(
182- /// formatter.format(&Date::try_new_iso(2023, 12, 20).unwrap().to_calendar(JapaneseExtended::new())),
183- /// "20 de diciembre de 5 Reiwa"
184- /// );
185- /// ```
186222#[ cfg( feature = "compiled_data" ) ]
187223 pub fn try_new (
188224 prefs : DateTimeFormatterPreferences ,
@@ -312,48 +348,6 @@ where
312348 FSet :: Z : ZoneMarkers ,
313349{
314350 /// Formats a datetime. Calendars and fields must match at compile time.
315- ///
316- /// # Examples
317- ///
318- /// Mismatched calendars will not compile:
319- ///
320- /// ```compile_fail
321- /// use icu::datetime::input::Date;
322- /// use icu::datetime::input::cal::Buddhist;
323- /// use icu::datetime::FixedCalendarDateTimeFormatter;
324- /// use icu::datetime::fieldsets::YMD;
325- /// use icu::locale::locale;
326- ///
327- /// let formatter =
328- /// FixedCalendarDateTimeFormatter::<Buddhist, _>::try_new(
329- /// locale!("es-MX").into(),
330- /// YMD::long(),
331- /// )
332- /// .unwrap();
333- ///
334- /// // type mismatch resolving `<Gregorian as AsCalendar>::Calendar == Buddhist`
335- /// formatter.format(&Date::try_new_gregorian(2023, 12, 20).unwrap());
336- /// ```
337- ///
338- /// A time cannot be passed into the formatter when a date is expected:
339- ///
340- /// ```compile_fail,E0277
341- /// use icu::datetime::input::Time;
342- /// use icu::calendar::Gregorian;
343- /// use icu::datetime::FixedCalendarDateTimeFormatter;
344- /// use icu::datetime::fieldsets::YMD;
345- /// use icu::locale::locale;
346- ///
347- /// let formatter =
348- /// FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
349- /// locale!("es-MX").into(),
350- /// YMD::long(),
351- /// )
352- /// .unwrap();
353- ///
354- /// // error[E0277]: the trait bound `Time: AllInputMarkers<fieldsets::YMD>` is not satisfied
355- /// formatter.format(&Time::midnight());
356- /// ```
357351pub fn format < I > ( & self , input : & I ) -> FormattedDateTime
358352 where
359353 I : ?Sized + InFixedCalendar < C > + AllInputMarkers < FSet > ,
@@ -470,13 +464,8 @@ where
470464 /// Creates a new [`DateTimeFormatter`] from compiled data with
471465/// datetime components specified at build time.
472466///
473- /// This method will pick the calendar off of the locale; and if unspecified or unknown will fall back to the default
474- /// calendar for the locale. See [`AnyCalendarKind`] for a list of supported calendars.
475- ///
476- /// Use this constructor for optimal data size and memory use
477- /// if you know the required datetime components at build time.
478- /// If you do not know the datetime components until runtime,
479- /// use a `with_components` constructor.
467+ /// This method will use the calendar specified in the `calendar_algorithm` preference, or fall back to the default
468+ /// calendar for the preferences if unspecified or unsupported. See [`IntoFormattableAnyCalendar`] for a list of supported calendars.
480469///
481470/// ✨ *Enabled with the `compiled_data` Cargo feature.*
482471///
@@ -954,7 +943,7 @@ impl<C: CldrCalendar, FSet: DateTimeMarkers> FixedCalendarDateTimeFormatter<C, F
954943/// // Create a simple YMDT formatter:
955944/// let formatter = FixedCalendarDateTimeFormatter::try_new(
956945/// locale!("und").into(),
957- /// YMDT::long().hm ().with_alignment(Alignment::Column)
946+ /// YMDT::long().with_hm ().with_alignment(Alignment::Column)
958947/// )
959948/// .unwrap();
960949///
@@ -1184,6 +1173,18 @@ impl<FSet: DateTimeMarkers> DateTimeFormatter<FSet> {
11841173///
11851174/// # Examples
11861175///
1176+ /// A [`NoCalendarFormatter`] can be used to format a time:
1177+ ///
1178+ /// ```
1179+ /// use icu::datetime::fieldsets::T;
1180+ /// use icu::datetime::NoCalendarFormatter;
1181+ /// use icu::datetime::input::Time;
1182+ /// use icu::locale::locale;
1183+ ///
1184+ /// let formatter = NoCalendarFormatter::try_new(locale!("bn").into(), T::long()).unwrap();
1185+ /// assert_eq!(formatter.format(&Time::midnight()).to_string(), "১২:০০:০০ AM");
1186+ /// ```
1187+ ///
11871188/// A [`NoCalendarFormatter`] cannot be constructed with a fieldset that involves dates:
11881189///
11891190/// ```
0 commit comments