Struct DateTimeFormatter

pub struct DateTimeFormatter<FSet: DateTimeNamesMarker> { /* private fields */ }

DateTimeFormatter is a formatter capable of formatting dates and/or times from a calendar selected at runtime.

For more details, please read the crate root docs.

Examples

Basic usage:

use icu::datetime::fieldsets::YMD;
use icu::datetime::input::Date;
use icu::datetime::DateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let formatter = DateTimeFormatter::try_new(
    locale!("en-u-ca-hebrew").into(),
    YMD::medium(),
)
.unwrap();

let date = Date::try_new_iso(2024, 5, 8).unwrap();

assert_writeable_eq!(formatter.format(&date), "30 Nisan 5784");

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

Implementations

impl<FSet> DateTimeFormatter<FSet>

where FSet::D: DateDataMarkers, 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: AllAnyCalendarFormattingDataMarkers<FSet>,

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

This method will use the calendar specified in the calendar_algorithm preference, or fall back to the default calendar for the preferences if unspecified or unsupported. See IntoFormattableAnyCalendar for a list of supported calendars.

✨ 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 + AllAnyCalendarFormattingDataMarkers<FSet> + AllAnyCalendarExternalDataMarkers,

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<FSet: DateTimeMarkers> DateTimeFormatter<FSet>

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

pub fn format_same_calendar<I>( &self, datetime: &I, ) -> Result<FormattedDateTime<'_>, MismatchedCalendarError>

where I: ?Sized + InSameCalendar + AllInputMarkers<FSet>,

Formats a datetime, checking that the calendar system is correct.

If the datetime is not in the same calendar system as the formatter, an error is returned.

Examples

Mismatched calendars will return an error:

use icu::datetime::fieldsets::YMD;
use icu::datetime::input::Date;
use icu::datetime::DateTimeFormatter;
use icu::datetime::MismatchedCalendarError;
use icu::locale::locale;

let formatter = DateTimeFormatter::try_new(
    locale!("en-u-ca-hebrew").into(),
    YMD::long(),
)
.unwrap();

let date = Date::try_new_gregorian(2023, 12, 20).unwrap();

assert!(matches!(
    formatter.format_same_calendar(&date),
    Err(MismatchedCalendarError { .. })
));

A time cannot be passed into the formatter when a date is expected:

use icu::datetime::input::Time;
use icu::datetime::DateTimeFormatter;
use icu::datetime::fieldsets::YMD;
use icu::locale::locale;

let formatter = DateTimeFormatter::try_new(
    locale!("es-MX").into(),
    YMD::long(),
)
.unwrap();

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

pub fn format<'a, I>(&'a self, datetime: &I) -> FormattedDateTime<'a>

where I: ?Sized + ConvertCalendar, I::Converted<'a>: Sized + AllInputMarkers<FSet>,

Formats a datetime after first converting it to the formatter’s calendar.

Examples

Mismatched calendars convert and format automatically:

use icu::datetime::fieldsets::YMD;
use icu::datetime::input::Date;
use icu::datetime::DateTimeFormatter;
use icu::datetime::MismatchedCalendarError;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let formatter = DateTimeFormatter::try_new(
    locale!("en-u-ca-hebrew").into(),
    YMD::long(),
)
.unwrap();

let date = Date::try_new_roc(113, 5, 8).unwrap();

assert_writeable_eq!(formatter.format(&date), "30 Nisan 5784");

A time cannot be passed into the formatter when a date is expected:

use icu::datetime::input::Time;
use icu::datetime::DateTimeFormatter;
use icu::datetime::fieldsets::YMD;
use icu::locale::locale;

let formatter = DateTimeFormatter::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());

impl<FSet: DateTimeMarkers> DateTimeFormatter<FSet>

pub fn try_into_typed_formatter<C>( self, ) -> Result<FixedCalendarDateTimeFormatter<C, FSet>, MismatchedCalendarError>

where C: CldrCalendar + IntoAnyCalendar,

Attempt to convert this DateTimeFormatter into one with a specific calendar.

Returns an error if the type parameter does not match the inner calendar.

Examples

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

let formatter = DateTimeFormatter::try_new(
    locale!("en-u-ca-hebrew").into(),
    YMD::long(),
)
.unwrap()
.try_into_typed_formatter::<Hebrew>()
.unwrap();

let date = Date::try_new_hebrew(5785, 1, 12).unwrap();

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

An error occurs if the calendars don’t match:

use icu::calendar::cal::Hebrew;
use icu::datetime::fieldsets::YMD;
use icu::datetime::input::Date;
use icu::datetime::DateTimeFormatter;
use icu::datetime::MismatchedCalendarError;
use icu::locale::locale;

let result = DateTimeFormatter::try_new(
    locale!("en-u-ca-buddhist").into(),
    YMD::long(),
)
.unwrap()
.try_into_typed_formatter::<Hebrew>();

assert!(matches!(result, Err(MismatchedCalendarError { .. })));

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

Maps a DateTimeFormatter 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::DateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let specific_formatter =
    DateTimeFormatter::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 calendar(&self) -> Ref<'_, AnyCalendar>

Returns the calendar used in this formatter.

Examples

use icu::calendar::AnyCalendarKind;
use icu::datetime::fieldsets::YMD;
use icu::datetime::input::Date;
use icu::datetime::DateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let formatter =
    DateTimeFormatter::try_new(locale!("th-TH").into(), YMD::long())
        .unwrap();

assert_writeable_eq!(
    formatter.format(&Date::try_new_iso(2024, 12, 16).unwrap()),
    "16 ธันวาคม 2567"
);

assert_eq!(formatter.calendar().kind(), AnyCalendarKind::Buddhist);

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::YMDT;
use icu::datetime::input::*;
use icu::datetime::options::*;
use icu::datetime::DateTimeFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

// Create a simple YMDT formatter:
let formatter = DateTimeFormatter::try_new(
    locale!("und").into(),
    YMDT::long().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::Second); // set automatically
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 = DateTimeFormatter::try_new(
    locale!("und").into(),
    builder.build_composite_datetime().unwrap(),
)
.unwrap();
let datetime = DateTime {
    date: Date::try_new_iso(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<FSet: DateTimeNamesMarker> DateTimeFormatter<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::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::DateTimeFormatter;
use icu::locale::locale;
use writeable::assert_try_writeable_eq;

let formatter =
    DateTimeFormatter::try_new(locale!("th-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(formatter.calendar());

// 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<FSet: Clone + DateTimeNamesMarker> Clone for DateTimeFormatter<FSet>

fn clone(&self) -> DateTimeFormatter<FSet>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<FSet: Debug + DateTimeNamesMarker> Debug for DateTimeFormatter<FSet>

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

Formats the value using the given formatter.