Struct ZoneNameTimestamp

pub struct ZoneNameTimestamp(/* private fields */);

The moment in time for resolving a time zone name.

What is this for? Most software deals with time zone transitions, computing the UTC offset on a given point in time. In ICU4X, we deal with time zone display names. Whereas time zone transitions occur multiple times per year in some time zones, the set of display names changes more rarely. For example, ICU4X needs to know when a region switches from Eastern Time to Central Time.

This type can only represent display name changes after 1970, and only to a coarse (15-minute) granularity, which is sufficient for CLDR and TZDB data within that time frame.

Examples

The region of Metlakatla (Alaska) switched between Pacific Time and Alaska Time multiple times between 2010 and 2025.

use icu::time::zone::IanaParser;
use icu::time::zone::ZoneNameTimestamp;
use icu::datetime::NoCalendarFormatter;
use icu::datetime::fieldsets::zone::GenericLong;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let metlakatla = IanaParser::new().parse("America/Metlakatla");

let zone_formatter = NoCalendarFormatter::try_new(
    locale!("en-US").into(),
    GenericLong,
)
.unwrap();

let time_zone_info_2010 = metlakatla.without_offset().at_date_time_iso("2010-01-01T00:00".parse().unwrap());
let time_zone_info_2025 = metlakatla.without_offset().at_date_time_iso("2025-01-01T00:00".parse().unwrap());

// TimeZoneInfo::at_date_time_iso and ZoneNameTimestamp::from_date_time_iso are equivalent:
assert_eq!(
    time_zone_info_2010.zone_name_timestamp(),
    ZoneNameTimestamp::from_date_time_iso("2010-01-01T00:00".parse().unwrap())
);
assert_eq!(
    time_zone_info_2025.zone_name_timestamp(),
    ZoneNameTimestamp::from_date_time_iso("2025-01-01T00:00".parse().unwrap())
);

// Check the display names:
let name_2010 = zone_formatter.format(&time_zone_info_2010);
let name_2025 = zone_formatter.format(&time_zone_info_2025);

assert_writeable_eq!(name_2010, "Pacific Time");
assert_writeable_eq!(name_2025, "Alaska Time");

Implementations

impl ZoneNameTimestamp

pub fn to_date_time_iso(self) -> DateTime<Iso>

Recovers the local datetime for this ZoneNameTimestamp.

For more information, see Self::from_date_time_iso().

pub fn from_date_time_iso(date_time: DateTime<Iso>) -> Self

Creates an instance of ZoneNameTimestamp from a local datetime.

The datetime might be clamped and might lose precision.

Note: Currently, this type cannot represent ambiguous times in the period after a time zone transition. For example, if a “fall back” time zone transition occurs at 02:00, then the times 01:00-02:00 occur twice. To ensure that you get the correct time zone display name after a transition, you can pick any time later in the day.

Examples

DateTime does not necessarily roundtrip:

use icu::calendar::Date;
use icu::time::zone::ZoneNameTimestamp;
use icu::time::{DateTime, Time};

let date_time = DateTime {
    date: Date::try_new_iso(2025, 4, 30).unwrap(),
    time: Time::try_new(13, 58, 16, 500000000).unwrap(),
};

let zone_name_timestamp = ZoneNameTimestamp::from_date_time_iso(date_time);

let recovered_date_time = zone_name_timestamp.to_date_time_iso();

// The datetime doesn't roundtrip:
assert_ne!(date_time, recovered_date_time);

// The exact behavior is subject to change. For illustration only:
assert_eq!(recovered_date_time.date, date_time.date);
assert_eq!(recovered_date_time.time.hour, date_time.time.hour);
assert_eq!(recovered_date_time.time.minute.number(), 45); // rounded down
assert_eq!(recovered_date_time.time.second.number(), 0); // always zero
assert_eq!(recovered_date_time.time.subsecond.number(), 0); // always zero

pub fn far_in_past() -> Self

Returns a ZoneNameTimestamp for a time far in the past.

pub fn far_in_future() -> Self

Returns a ZoneNameTimestamp for a time far in the future.

Trait Implementations

impl AsULE for ZoneNameTimestamp

type ULE = <u32 as AsULE>::ULE

The ULE type corresponding to Self.

fn to_unaligned(self) -> Self::ULE

Converts from Self to Self::ULE.

fn from_unaligned(unaligned: Self::ULE) -> Self

Converts from Self::ULE to Self.

impl Clone for ZoneNameTimestamp

fn clone(&self) -> ZoneNameTimestamp

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ZoneNameTimestamp

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ZoneNameTimestamp

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl IntoOption<ZoneNameTimestamp> for ZoneNameTimestamp

fn into_option(self) -> Option<Self>

Return self as an Option<T>

impl Ord for ZoneNameTimestamp

fn cmp(&self, other: &ZoneNameTimestamp) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for ZoneNameTimestamp

fn eq(&self, other: &ZoneNameTimestamp) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for ZoneNameTimestamp

fn partial_cmp(&self, other: &ZoneNameTimestamp) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for ZoneNameTimestamp

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'a> ZeroMapKV<'a> for ZoneNameTimestamp

type Container = ZeroVec<'a, ZoneNameTimestamp>

The container that can be used with this type: ZeroVec or VarZeroVec.

type Slice = ZeroSlice<ZoneNameTimestamp>

type GetType = <ZoneNameTimestamp as AsULE>::ULE

The type produced by Container::get()

type OwnedType = ZoneNameTimestamp

The type produced by Container::replace() and Container::remove(), also used during deserialization. If Self is human readable serialized, deserializing to Self::OwnedType should produce the same value once passed through Self::owned_as_self()

impl Copy for ZoneNameTimestamp

impl Eq for ZoneNameTimestamp

impl StructuralPartialEq for ZoneNameTimestamp