Struct icu_datetime::TimeFormatter

pub struct TimeFormatter(_);

TimeFormatter is a structure of the icu_datetime component that provides time formatting only. When constructed, it uses data from the data provider, selected locale and provided preferences to collect all data necessary to format any time into that locale.

For that reason, one should think of the process of formatting a time in two steps - first, a computational heavy construction of TimeFormatter, and then fast formatting of DateTimeInput data using the instance.

Examples

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

let provider = icu_testdata::get_provider();

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

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

assert_writeable_eq!(tf.format(&datetime), "12:34 PM");

This model replicates that of ICU and ECMA402.

Implementations

impl TimeFormatter

pub fn try_new_unstable<D>(
    data_provider: &D,
    locale: &DataLocale,
    length: Time
) -> Result<Self, DateTimeFormatterError> where
    D: DataProvider<TimeLengthsV1Marker> + DataProvider<TimeSymbolsV1Marker> + DataProvider<DecimalSymbolsV1Marker> + ?Sized, 

Constructor that takes a selected locale, reference to a data provider and a list of preferences, then collects all data necessary to format date and time values into the given locale, using the short style.

Examples

use icu::datetime::{options::length::Time, TimeFormatter};
use icu::locid::locale;

let provider = icu_testdata::get_provider();

TimeFormatter::try_new_with_buffer_provider(
    &provider,
    &locale!("en").into(),
    Time::Short,
)
.unwrap();

pub fn try_new_with_any_provider(
    provider: &impl AnyProvider + ?Sized,
    locale: &DataLocale,
    length: Time
) -> Result<Self, DateTimeFormatterError>

Create a new instance using an AnyProvider.

See also: Self::try_new_unstable

pub fn try_new_with_buffer_provider(
    provider: &impl BufferProvider + ?Sized,
    locale: &DataLocale,
    length: Time
) -> Result<Self, DateTimeFormatterError>

Create a new instance using a BufferProvider. Enabled with the "serde" feature.

See also: Self::try_new_unstable

pub fn format<'l, T>(&'l self, value: &T) -> FormattedDateTime<'l> where
    T: IsoTimeInput, 

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

Examples

use icu::calendar::DateTime;
use icu::datetime::{options::length::Time, TimeFormatter};
use writeable::assert_writeable_eq;
let tf =
    TimeFormatter::try_new_with_buffer_provider(&provider, &locale.into(), Time::Short)
        .expect("Failed to create TimeFormatter instance.");

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

assert_writeable_eq!(tf.format(&datetime), "12:34 PM");

At the moment, there’s little value in using that over one of the other format methods, but FormattedDateTime will grow with methods for iterating over fields, extracting information about formatted date and so on.

pub fn format_to_write(
    &self,
    w: &mut impl Write,
    value: &impl IsoTimeInput
) -> Result

Takes a mutable reference to anything that implements Write trait and a IsoTimeInput implementer and populates the buffer with a formatted value.

Examples

use icu::calendar::DateTime;
use icu::datetime::{options::length::Time, TimeFormatter};
let tf =
    TimeFormatter::try_new_with_buffer_provider(&provider, &locale.into(), Time::Short)
        .expect("Failed to create TimeFormatter instance.");

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

let mut buffer = String::new();
tf.format_to_write(&mut buffer, &datetime)
    .expect("Failed to write to a buffer.");

assert_eq!(buffer, "12:34 PM");

pub fn format_to_string(&self, value: &impl IsoTimeInput) -> String

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

Examples

use icu::calendar::DateTime;
use icu::datetime::{options::length::Time, TimeFormatter};
let tf =
    TimeFormatter::try_new_with_buffer_provider(&provider, &locale.into(), Time::Short)
        .expect("Failed to create TimeFormatter instance.");

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

assert_eq!(tf.format_to_string(&datetime), "12:34 PM");