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::calendar::Iso;
use icu::datetime::fieldsets::zone::GenericLong;
use icu::datetime::NoCalendarFormatter;
use icu::locale::locale;
use icu::time::zone::IanaParser;
use icu::time::zone::ZoneNameTimestamp;
use icu::time::ZonedDateTime;
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()
    .with_zone_name_timestamp(ZoneNameTimestamp::from_zoned_date_time_iso(
        ZonedDateTime::try_offset_only_from_str("2010-01-01T00:00Z", Iso)
            .unwrap(),
    ));
let time_zone_info_2025 = metlakatla
    .without_offset()
    .with_zone_name_timestamp(ZoneNameTimestamp::from_zoned_date_time_iso(
        ZonedDateTime::try_offset_only_from_str("2025-01-01T00:00Z", Iso)
            .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_zoned_date_time_iso(self) -> ZonedDateTime<Iso, UtcOffset>

Recovers the UTC datetime for this ZoneNameTimestamp.

This will always return a ZonedDateTime with UtcOffset::zero()

pub fn from_zoned_date_time_iso( zoned_date_time: ZonedDateTime<Iso, UtcOffset>, ) -> ZoneNameTimestamp

Creates an instance of ZoneNameTimestamp from a zoned datetime.

The datetime might be clamped and might lose precision.

Examples

ZonedDateTime does not necessarily roundtrip:

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

let zoned_date_time = ZonedDateTime {
    date: Date::try_new_iso(2025, 4, 30).unwrap(),
    time: Time::try_new(13, 58, 16, 500000000).unwrap(),
    zone: UtcOffset::zero(),
};

let zone_name_timestamp = ZoneNameTimestamp::from_zoned_date_time_iso(zoned_date_time);

let recovered_zoned_date_time = zone_name_timestamp.to_zoned_date_time_iso();

// The datetime doesn't roundtrip:
assert_ne!(zoned_date_time, recovered_zoned_date_time);

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

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

👎Deprecated since 2.1.0: returns a UTC DateTime, which is the wrong type. Use to_zoned_date_time_iso instead

Recovers the UTC datetime for this ZoneNameTimestamp.

pub fn from_date_time_iso(_: DateTime<Iso>) -> ZoneNameTimestamp

👎Deprecated since 2.1.0: implicitly interprets the DateTime as UTC. Use from_zoned_date_time_iso instead.

Creates an instance of ZoneNameTimestamp from a UTC datetime.

The datetime might be clamped and might lose precision.

pub fn far_in_past() -> ZoneNameTimestamp

Returns a ZoneNameTimestamp for a time far in the past.

pub fn far_in_future() -> ZoneNameTimestamp

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) -> <ZoneNameTimestamp as AsULE>::ULE

Converts from Self to Self::ULE.

fn from_unaligned( unaligned: <ZoneNameTimestamp as AsULE>::ULE, ) -> ZoneNameTimestamp

Converts from Self::ULE to Self.

impl Clone for ZoneNameTimestamp

fn clone(&self) -> ZoneNameTimestamp

Returns a duplicate 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<(), Error>

Formats the value using the given formatter.

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

fn deserialize<D>( deserializer: D, ) -> Result<ZoneNameTimestamp, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<O> GetField<ZoneNameTimestamp> for TimeZoneInfo<O>

where O: TimeZoneModel<ZoneNameTimestamp = ZoneNameTimestamp>,

fn get_field(&self) -> ZoneNameTimestamp

Returns the value of this trait’s field T.

impl<C, A, Z> GetField<ZoneNameTimestamp> for ZonedDateTime<A, Z>

where C: Calendar, A: AsCalendar<Calendar = C>, Z: GetField<ZoneNameTimestamp>,

fn get_field(&self) -> ZoneNameTimestamp

Returns the value of this trait’s field T.

impl IntoOption<ZoneNameTimestamp> for ZoneNameTimestamp

fn into_option(self) -> Option<ZoneNameTimestamp>

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 as Serializer>::Ok, <S as Serializer>::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