Struct icu::datetime::pattern::DateTimePatternFormatter

pub struct DateTimePatternFormatter<'a, C, FSet>
where
    C: CldrCalendar,
{ /* private fields */ }

A formatter for a specific DateTimePattern.

❗ This type forgoes most internationalization functionality of the datetime crate. It assumes that the pattern is already localized for the customer’s locale. Most clients should use DateTimeFormatter instead of directly formatting with patterns.

Create one of these via factory methods on TypedDateTimeNames.

Implementations

impl<'a, C, FSet> DateTimePatternFormatter<'a, C, FSet>

where C: CldrCalendar, FSet: DateTimeMarkers, <FSet as DateTimeMarkers>::D: TypedDateDataMarkers<C> + DateInputMarkers, <FSet as DateTimeMarkers>::T: TimeMarkers, <FSet as DateTimeMarkers>::Z: ZoneMarkers,

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

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

Formats a date and time of day with a custom date/time pattern.

Examples

Format a date:

use icu::calendar::Date;
use icu::calendar::Gregorian;
use icu::datetime::fields;
use icu::datetime::fields::FieldLength;
use icu::datetime::fieldsets::enums::DateFieldSet;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::TypedDateTimeNames;
use icu::locale::locale;
use writeable::assert_try_writeable_eq;

// Create an instance that can format wide month and era names:
let mut names: TypedDateTimeNames<Gregorian, DateFieldSet> =
    TypedDateTimeNames::try_new(locale!("en-GB").into()).unwrap();
names
    .include_month_names(fields::Month::Format, FieldLength::Four)
    .unwrap()
    .include_year_names(FieldLength::Four)
    .unwrap();

// Create a pattern from a pattern string:
let pattern_str = "'The date is:' MMMM d, y GGGG";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

// Test it with some different dates:
// Note: extended year -50 is year 51 BCE
let date_bce = Date::try_new_gregorian(-50, 3, 15).unwrap();
let date_ce = Date::try_new_gregorian(1700, 11, 20).unwrap();
assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&date_bce),
    "The date is: March 15, 51 Before Christ"
);
assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&date_ce),
    "The date is: November 20, 1700 Anno Domini"
);

Format a time:

use icu::calendar::Gregorian;
use icu::calendar::Time;
use icu::datetime::fields::FieldLength;
use icu::datetime::fieldsets::enums::TimeFieldSet;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::pattern::TypedDateTimeNames;
use icu::locale::locale;
use writeable::assert_try_writeable_eq;

// Create an instance that can format abbreviated day periods:
let mut names: TypedDateTimeNames<Gregorian, TimeFieldSet> =
    TypedDateTimeNames::try_new(locale!("en-US").into()).unwrap();
names
    .include_day_period_names(FieldLength::Three)
    .unwrap();

// Create a pattern from a pattern string:
let pattern_str = "'The time is:' h:mm b";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

// Test it with different times of day:
let time_am = Time::try_new(11, 4, 14, 0).unwrap();
let time_pm = Time::try_new(13, 41, 28, 0).unwrap();
let time_noon = Time::try_new(12, 0, 0, 0).unwrap();
let time_midnight = Time::try_new(0, 0, 0, 0).unwrap();
assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&time_am),
    "The time is: 11:04 AM"
);
assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&time_pm),
    "The time is: 1:41 PM"
);
assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&time_noon),
    "The time is: 12:00 noon"
);
assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&time_midnight),
    "The time is: 12:00 midnight"
);

Format a time zone:

use icu::calendar::Gregorian;
use icu::datetime::pattern::DateTimePattern;
use icu::datetime::fieldsets::enums::ZoneFieldSet;
use icu::datetime::pattern::TypedDateTimeNames;
use icu::locale::locale;
use icu::timezone::IxdtfParser;
use writeable::assert_try_writeable_eq;

let mut london_winter = IxdtfParser::new().try_from_str(
    "2024-01-01T00:00:00+00:00[Europe/London]",
)
.unwrap()
.to_calendar(Gregorian);
let mut london_summer = IxdtfParser::new().try_from_str(
    "2024-07-01T00:00:00+01:00[Europe/London]",
)
.unwrap()
.to_calendar(Gregorian);

let mut names =
    TypedDateTimeNames::<Gregorian, ZoneFieldSet>::try_new(
        locale!("en-GB").into(),
    )
    .unwrap();

names.include_time_zone_essentials().unwrap();
names.include_time_zone_specific_short_names().unwrap();

// Create a pattern with symbol `z`:
let pattern_str = "'Your time zone is:' z";
let pattern: DateTimePattern = pattern_str.parse().unwrap();

assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&london_winter),
    "Your time zone is: GMT",
);
assert_try_writeable_eq!(
    names.with_pattern_unchecked(&pattern).format(&london_summer),
    "Your time zone is: BST",
);

Trait Implementations

impl<'a, C, FSet> Clone for DateTimePatternFormatter<'a, C, FSet>

where C: Clone + CldrCalendar, FSet: Clone,

fn clone(&self) -> DateTimePatternFormatter<'a, C, FSet>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, C, FSet> Debug for DateTimePatternFormatter<'a, C, FSet>

where C: Debug + CldrCalendar, FSet: Debug,

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

Formats the value using the given formatter.

impl<'a, C, FSet> Copy for DateTimePatternFormatter<'a, C, FSet>

where C: Copy + CldrCalendar, FSet: Copy,