Struct icu_datetime::DateTimeFormatter

source ·
pub struct DateTimeFormatter(pub(crate) DateTimeFormatter, AnyCalendar);
Expand description

DateTimeFormatter is a formatter capable of formatting date/times from any calendar, selected at runtime. For the difference between this and TypedDateTimeFormatter, please read the crate root docs.

When constructed, it uses data from the data provider, selected locale and provided options to collect all data necessary to format any dates into that locale.

For that reason, one should think of the process of formatting a date in two steps - first, a computational heavy construction of DateTimeFormatter, and then fast formatting of DateTime data using the instance. 📏 This item has a stack size of 5208 bytes on the stable toolchain at release date.

§Examples

use icu::calendar::DateTime;
use icu::datetime::{options::length, DateTimeFormatter};
use icu::locid::locale;
use writeable::assert_writeable_eq;

let mut options = length::Bag::from_date_time_style(
    length::Date::Medium,
    length::Time::Short,
);

let dtf = DateTimeFormatter::try_new(
    &locale!("en-u-ca-gregory").into(),
    options.into(),
)
.expect("Failed to create DateTimeFormatter instance.");

let datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
    .expect("Failed to construct DateTime.");
let any_datetime = datetime.to_any();

assert_writeable_eq!(
    dtf.format(&any_datetime).expect("Calendars should match"),
    "Sep 1, 2020, 12:34 PM"
);

Since this works with AnyCalendar, you can use DateTime with AnyCalendar to have a date in a runtime-selected calendar:

use icu::calendar::{AnyCalendar, DateTime, Time};
use icu::datetime::{options::length, DateTimeFormatter};
use icu::locid::locale;
use writeable::assert_writeable_eq;

let locale = locale!("en-u-ca-japanese").into(); // English with the Japanese calendar

let calendar = AnyCalendar::new_for_locale(&locale);
let calendar = Rc::new(calendar); // Avoid cloning it


// manually construct a datetime in this calendar
let manual_time = Time::try_new(12, 33, 12, 0).expect("failed to construct Time");
// construct from era code, year, month code, day, time, and a calendar
// This is March 28, 15 Heisei
let manual_datetime = DateTime::try_new_from_codes("heisei".parse().unwrap(), 15, "M03".parse().unwrap(), 28,
                                               manual_time, calendar.clone())
                    .expect("Failed to construct DateTime manually");


// construct another datetime by converting from ISO
let iso_datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
    .expect("Failed to construct ISO DateTime.");
let iso_converted = iso_datetime.to_calendar(calendar);


let options = length::Bag::from_date_time_style(length::Date::Medium, length::Time::Short);

let dtf = DateTimeFormatter::try_new(&locale, options.into())
    .expect("Failed to create DateTimeFormatter instance.");

let manual_value = dtf.format(&manual_datetime).expect("Calendars should match");
assert_writeable_eq!(manual_value, "Mar 28, 15 Heisei, 12:33 PM");

let converted_value = dtf.format(&iso_converted).expect("Calendars should match");
assert_writeable_eq!(converted_value, "Sep 1, 2 Reiwa, 12:34 PM");

This model replicates that of ICU and ECMA402.

Tuple Fields§

§0: DateTimeFormatter§1: AnyCalendar

Implementations§

source§

impl DateTimeFormatter

source

pub fn try_new( locale: &DataLocale, options: DateTimeFormatterOptions, ) -> Result<Self, DateTimeError>

Construct a new DateTimeFormatter from compiled data.

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.

📚 Help choosing a constructor

§Examples
use icu::calendar::DateTime;
use icu::datetime::{options::length, DateTimeFormatter};
use icu::locid::locale;
use writeable::assert_writeable_eq;

let options = length::Bag::from_date_time_style(
    length::Date::Medium,
    length::Time::Short,
);
let locale = locale!("en-u-ca-gregory").into();

let dtf = DateTimeFormatter::try_new(&locale, options.into())
    .expect("Failed to create TypedDateTimeFormatter instance.");

let datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
    .expect("Failed to construct DateTime.");
let any_datetime = datetime.to_any();

assert_writeable_eq!(
    dtf.format(&any_datetime).expect("Calendars should match"),
    "Sep 1, 2020, 12:34 PM"
);

Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

source

pub fn try_new_with_any_provider( provider: &impl AnyProvider, locale: &DataLocale, options: DateTimeFormatterOptions, ) -> Result<Self, DateTimeError>

A version of Self::try_new that uses custom data provided by an AnyProvider.

📚 Help choosing a constructor

source

pub fn try_new_unstable<P>( provider: &P, locale: &DataLocale, options: DateTimeFormatterOptions, ) -> Result<Self, DateTimeError>
where P: DataProvider<TimeSymbolsV1Marker> + DataProvider<TimeLengthsV1Marker> + DataProvider<OrdinalV1Marker> + DataProvider<WeekDataV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<BuddhistDateLengthsV1Marker> + DataProvider<BuddhistDateSymbolsV1Marker> + DataProvider<ChineseCacheV1Marker> + DataProvider<ChineseDateLengthsV1Marker> + DataProvider<ChineseDateSymbolsV1Marker> + DataProvider<CopticDateLengthsV1Marker> + DataProvider<CopticDateSymbolsV1Marker> + DataProvider<DangiCacheV1Marker> + DataProvider<DangiDateLengthsV1Marker> + DataProvider<DangiDateSymbolsV1Marker> + DataProvider<EthiopianDateLengthsV1Marker> + DataProvider<EthiopianDateSymbolsV1Marker> + DataProvider<GregorianDateLengthsV1Marker> + DataProvider<GregorianDateSymbolsV1Marker> + DataProvider<HebrewDateLengthsV1Marker> + DataProvider<HebrewDateSymbolsV1Marker> + DataProvider<IndianDateLengthsV1Marker> + DataProvider<IndianDateSymbolsV1Marker> + DataProvider<IslamicDateLengthsV1Marker> + DataProvider<IslamicDateSymbolsV1Marker> + DataProvider<JapaneseDateLengthsV1Marker> + DataProvider<JapaneseDateSymbolsV1Marker> + DataProvider<JapaneseErasV1Marker> + DataProvider<JapaneseExtendedDateLengthsV1Marker> + DataProvider<JapaneseExtendedDateSymbolsV1Marker> + DataProvider<JapaneseExtendedErasV1Marker> + DataProvider<IslamicObservationalCacheV1Marker> + DataProvider<IslamicUmmAlQuraCacheV1Marker> + DataProvider<PersianDateLengthsV1Marker> + DataProvider<PersianDateSymbolsV1Marker> + DataProvider<RocDateLengthsV1Marker> + DataProvider<RocDateSymbolsV1Marker> + ?Sized,

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.
source

pub fn try_from_date_and_time( date: DateFormatter, time: TimeFormatter, ) -> Result<Self, DateTimeError>

Constructor that takes a TimeFormatter and DateFormatter and combines them into a DateTimeFormatter. Prefer using one of the other constructors if possible.

§Examples
use icu::calendar::DateTime;
use icu::datetime::{
    options::length, DateFormatter, DateTimeFormatter, TimeFormatter,
};
use icu::locid::locale;
use writeable::assert_writeable_eq;

let df = DateFormatter::try_new_with_length(
    &locale!("en-u-ca-gregory").into(),
    length::Date::Medium,
)
.expect("Failed to create TypedDateFormatter instance.");

let tf = TimeFormatter::try_new_with_length(
    &locale!("en").into(),
    length::Time::Short,
)
.expect("Failed to create TimeFormatter instance.");

let dtf = DateTimeFormatter::try_from_date_and_time(df, tf).unwrap();

let datetime = DateTime::try_new_iso_datetime(2020, 9, 1, 12, 34, 28)
    .expect("Failed to construct DateTime.");
let any_datetime = datetime.to_any();

assert_writeable_eq!(
    dtf.format(&any_datetime).expect("Calendars should match"),
    "Sep 1, 2020, 12:34 PM"
);
source

pub fn format<'l, T>( &'l self, value: &T, ) -> Result<FormattedDateTime<'l>, DateTimeError>
where T: DateTimeInput<Calendar = AnyCalendar>,

Takes a DateTimeInput implementer and returns an instance of a FormattedDateTime that contains all information necessary to display a formatted date and operate on it.

This function will fail if the date passed in uses a different calendar than that of the AnyCalendar. Please convert dates before passing them in if necessary. This function will automatically convert and format dates that are associated with the ISO calendar.

source

pub fn format_to_string( &self, value: &impl DateTimeInput<Calendar = AnyCalendar>, ) -> Result<String, DateTimeError>

Takes a DateTimeInput implementer and returns it formatted as a string.

This function will fail if the date passed in uses a different calendar than that of the AnyCalendar. Please convert dates before passing them in if necessary. This function will automatically convert and format dates that are associated with the ISO calendar.

Trait Implementations§

source§

impl Debug for DateTimeFormatter

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> ErasedDestructor for T
where T: 'static,

source§

impl<T> MaybeSendSync for T