Struct FixedCalendarDateTimeFormatter

pub struct FixedCalendarDateTimeFormatter<C: CldrCalendar, FSet: DateTimeNamesMarker> { /* private fields */ }

FixedCalendarDateTimeFormatter is a formatter capable of formatting dates and/or times from a calendar selected at compile time.

For more details, please read the crate root docs.

Examples

Basic usage:

use icu::calendar::cal::JapaneseExtended;
use icu::datetime::fieldsets::YMD;
use icu::datetime::input::Date;
use icu::datetime::FixedCalendarDateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

// The JapaneseExtended generic is inferred by passing this a JapaneseExtended date later
let formatter = FixedCalendarDateTimeFormatter::try_new(
    locale!("es-MX").into(),
    YMD::long(),
)
.unwrap();

assert_writeable_eq!(
    formatter.format(&Date::try_new_iso(2023, 12, 20).unwrap().to_calendar(JapaneseExtended::new())),
    "20 de diciembre de 5 Reiwa"
);

Mismatched calendars will not compile:

use icu::datetime::input::Date;
use icu::datetime::input::cal::Buddhist;
use icu::datetime::FixedCalendarDateTimeFormatter;
use icu::datetime::fieldsets::YMD;
use icu::locale::locale;

let formatter =
    FixedCalendarDateTimeFormatter::<Buddhist, _>::try_new(
        locale!("es-MX").into(),
        YMD::long(),
    )
    .unwrap();

// type mismatch resolving `<Gregorian as AsCalendar>::Calendar == Buddhist`
formatter.format(&Date::try_new_gregorian(2023, 12, 20).unwrap());

As with DateTimeFormatter, a time cannot be passed into the formatter when a date is expected:

use icu::datetime::input::Time;
use icu::calendar::Gregorian;
use icu::datetime::FixedCalendarDateTimeFormatter;
use icu::datetime::fieldsets::YMD;
use icu::locale::locale;

let formatter =
    FixedCalendarDateTimeFormatter::<Gregorian, _>::try_new(
        locale!("es-MX").into(),
        YMD::long(),
    )
    .unwrap();

// error[E0277]: the trait bound `Time: AllInputMarkers<fieldsets::YMD>` is not satisfied
formatter.format(&Time::start_of_day());

📏 This item has a stack size of 328 bytes on the stable toolchain at release date.

Implementations

impl<C: CldrCalendar, FSet> FixedCalendarDateTimeFormatter<C, FSet>

where FSet::D: TypedDateDataMarkers<C>, FSet::T: TimeMarkers, FSet::Z: ZoneMarkers, FSet: GetField<CompositeFieldSet> + DateTimeMarkers,

pub fn try_new( prefs: DateTimeFormatterPreferences, field_set_with_options: FSet, ) -> Result<Self, DateTimeFormatterLoadError>

where Baked: AllFixedCalendarFormattingDataMarkers<C, FSet>,

Creates a new FixedCalendarDateTimeFormatter from compiled data with datetime components specified at build time.

This ignores the calendar_kind preference and instead uses the static calendar type, and supports calendars that are not expressible as preferences, such as JapaneseExtended.

✨ Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

pub fn try_new_with_buffer_provider<P>( provider: &P, prefs: DateTimeFormatterPreferences, field_set_with_options: FSet, ) -> Result<Self, DateTimeFormatterLoadError>

where P: BufferProvider + ?Sized,

A version of [Self :: try_new] that uses custom data provided by a BufferProvider.

✨ Enabled with the serde feature.

📚 Help choosing a constructor

pub fn try_new_unstable<P>( provider: &P, prefs: DateTimeFormatterPreferences, field_set_with_options: FSet, ) -> Result<Self, DateTimeFormatterLoadError>

where P: ?Sized + AllFixedCalendarFormattingDataMarkers<C, FSet> + AllFixedCalendarExternalDataMarkers,

A version of Self::try_new that uses custom data provided by a DataProvider.

📚 Help choosing a constructor

⚠️ The bounds on provider may change over time, including in SemVer minor releases.

impl<C: CldrCalendar, FSet: DateTimeMarkers> FixedCalendarDateTimeFormatter<C, FSet>

where FSet::D: DateInputMarkers, FSet::T: TimeMarkers, FSet::Z: ZoneMarkers,

pub fn format<I>(&self, input: &I) -> FormattedDateTime<'_>

where I: ?Sized + InFixedCalendar<C> + AllInputMarkers<FSet>,

Formats a datetime. Calendars and fields must match at compile time.

impl<C: CldrCalendar, FSet: DateTimeMarkers> FixedCalendarDateTimeFormatter<C, FSet>

pub fn into_formatter(self, calendar: C) -> DateTimeFormatter<FSet>

where C: IntoFormattableAnyCalendar,

Make this FixedCalendarDateTimeFormatter adopt a calendar so it can format any date.

This is useful if you need a DateTimeFormatter but know the calendar system ahead of time, so that you do not need to link extra data you aren’t using.

DateTimeFormatter does not necesarily support all calendars that are supported by FixedCalendarDateTimeFormatter, which is why this function can fail.

Examples

use icu::calendar::cal::Hebrew;
use icu::datetime::fieldsets::YMD;
use icu::datetime::input::Date;
use icu::datetime::FixedCalendarDateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let formatter = FixedCalendarDateTimeFormatter::try_new(
    locale!("en").into(),
    YMD::long(),
)
.unwrap()
.into_formatter(Hebrew::new());

let date = Date::try_new_iso(2024, 10, 14).unwrap();

assert_writeable_eq!(formatter.format(&date), "12 Tishri 5785");

pub fn cast_into_fset<FSet2: DateTimeNamesFrom<FSet>>( self, ) -> FixedCalendarDateTimeFormatter<C, FSet2>

Maps a FixedCalendarDateTimeFormatter of a specific FSet to a more general FSet.

For example, this can transform a formatter for YMD to one for DateFieldSet.

Examples

use icu::calendar::Gregorian;
use icu::datetime::fieldsets::{enums::DateFieldSet, YMD};
use icu::datetime::input::Date;
use icu::datetime::FixedCalendarDateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let specific_formatter = FixedCalendarDateTimeFormatter::try_new(
    locale!("fr").into(),
    YMD::medium(),
)
.unwrap();

// Test that the specific formatter works:
let date = Date::try_new_gregorian(2024, 12, 20).unwrap();
assert_writeable_eq!(specific_formatter.format(&date), "20 déc. 2024");

// Make a more general formatter:
let general_formatter = specific_formatter.cast_into_fset::<DateFieldSet>();

// Test that it still works:
assert_writeable_eq!(general_formatter.format(&date), "20 déc. 2024");

pub fn to_field_set_builder(&self) -> FieldSetBuilder

Gets a FieldSetBuilder corresponding to the fields and options configured in this formatter. The builder can be used to recreate the formatter.

Examples

use icu::datetime::fieldsets::builder::*;
use icu::datetime::fieldsets::YMD;
use icu::datetime::input::*;
use icu::datetime::options::*;
use icu::datetime::FixedCalendarDateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

// Create a simple YMDT formatter:
let formatter = FixedCalendarDateTimeFormatter::try_new(
    locale!("und").into(),
    YMD::long().with_time_hm().with_alignment(Alignment::Column),
)
.unwrap();

// Get the builder corresponding to it:
let builder = formatter.to_field_set_builder();

// Check that the builder is what we expect:
let mut equivalent_builder = FieldSetBuilder::default();
equivalent_builder.length = Some(Length::Long);
equivalent_builder.date_fields = Some(DateFields::YMD);
equivalent_builder.time_precision = Some(TimePrecision::Minute);
equivalent_builder.alignment = Some(Alignment::Column);
equivalent_builder.year_style = None;
assert_eq!(builder, equivalent_builder,);

// Check that it creates a formatter with equivalent behavior:
let built_formatter = FixedCalendarDateTimeFormatter::try_new(
    locale!("und").into(),
    builder.build_composite_datetime().unwrap(),
)
.unwrap();
let datetime = DateTime {
    date: Date::try_new_gregorian(2025, 3, 6).unwrap(),
    time: Time::try_new(16, 41, 0, 0).unwrap(),
};
assert_eq!(
    formatter.format(&datetime).to_string(),
    built_formatter.format(&datetime).to_string(),
);

impl<C: CldrCalendar, FSet: DateTimeNamesMarker> FixedCalendarDateTimeFormatter<C, FSet>

pub fn format_unchecked( &self, datetime: DateTimeInputUnchecked, ) -> FormattedDateTimeUnchecked<'_>

Formats a datetime without enforcing either the field set or the calendar.

This function is useful when the caller knows something about the field set that the type system is unaware of. For example, if the formatter is represented with a dynamic field set, the caller may be able to provide a narrower type for formatting.

❗ The caller must ensure that:

1. The calendar of the input matches the calendar of the formatter
2. The fields of the input are a superset of the fields of the formatter

Returns a FormattedDateTimeUnchecked to surface errors when they occur, but not every invariant will result in an error. Use with caution!

Examples

In the following example, we know that the formatter’s field set is YMD, but the type system thinks we are a CompositeFieldSet, which requires a ZonedDateTime as input. However, since Date contains all the fields required by YMD, we can successfully pass it into format_unchecked.

use icu::calendar::cal::Buddhist;
use icu::datetime::fieldsets::enums::CompositeFieldSet;
use icu::datetime::fieldsets::{T, YMD};
use icu::datetime::input::{Date, Time};
use icu::datetime::unchecked::DateTimeInputUnchecked;
use icu::datetime::unchecked::FormattedDateTimeUncheckedError;
use icu::datetime::unchecked::MissingInputFieldKind;
use icu::datetime::FixedCalendarDateTimeFormatter;
use icu::locale::locale;
use writeable::assert_try_writeable_eq;

let formatter = FixedCalendarDateTimeFormatter::<Buddhist, _>::try_new(
    locale!("th").into(),
    YMD::long(),
)
.unwrap()
.cast_into_fset::<CompositeFieldSet>();

// Create a date and convert it to the correct calendar:
let mut input = DateTimeInputUnchecked::default();
let date = Date::try_new_iso(2025, 3, 7).unwrap().to_calendar(Buddhist);

// Safe because the calendar matches the formatter:
input.set_date_fields_unchecked(date);

// Safe because YMD needs only date fields, which are in the input:
let result = formatter.format_unchecked(input);

assert_try_writeable_eq!(result, "7 มีนาคม 2568");

// If we don't give all needed fields, we will get an error!
let mut input = DateTimeInputUnchecked::default();
let result = formatter.format_unchecked(input);
assert_try_writeable_eq!(
    result,
    "{d} {M} {G} {y}",
    Err(FormattedDateTimeUncheckedError::MissingInputField(
        MissingInputFieldKind::DayOfMonth
    ))
);

Trait Implementations

impl<C: Clone + CldrCalendar, FSet: Clone + DateTimeNamesMarker> Clone for FixedCalendarDateTimeFormatter<C, FSet>

fn clone(&self) -> FixedCalendarDateTimeFormatter<C, FSet>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<C: Debug + CldrCalendar, FSet: Debug + DateTimeNamesMarker> Debug for FixedCalendarDateTimeFormatter<C, FSet>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.