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) used to be on Pacific Time but is now on Alaska Time.

use icu::calendar::Iso;
use icu::datetime::fieldsets::zone::GenericLong;
use icu::datetime::NoCalendarFormatter;
use icu::locale::locale;
use icu::time::zone::TimeZone;
use icu::time::zone::ZoneNameTimestamp;
use icu::time::ZonedDateTime;
use writeable::assert_writeable_eq;

let metlakatla = TimeZone::from_iana_id("America/Metlakatla");

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

let time_zone_info_past = metlakatla
    .without_offset()
    .with_zone_name_timestamp(ZoneNameTimestamp::far_in_past());
let time_zone_info_future = metlakatla
    .without_offset()
    .with_zone_name_timestamp(ZoneNameTimestamp::far_in_future());

// Check the display names:
let name_past = zone_formatter.format(&time_zone_info_past);
let name_future = zone_formatter.format(&time_zone_info_future);

assert_writeable_eq!(name_past, "Pacific Time");
assert_writeable_eq!(name_future, "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()

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(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 from_zoned_date_time<C>( zoned_date_time: ZonedDateTime<C, UtcOffset>, ) -> ZoneNameTimestamp

where C: AsCalendar,

Creates an instance of ZoneNameTimestamp from a ZonedDateTime with an explicit UtcOffset.

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

👎Deprecated since 2.2.0:

use Self::from_zoned_date_time

Use Self::from_zoned_date_time.

pub fn from_epoch_seconds(seconds: i64) -> ZoneNameTimestamp

Creates an instance of ZoneNameTimestamp from a number of seconds since the UNIX epoch.

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 Copy for ZoneNameTimestamp

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

Available on crate feature serde only.

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 Eq for ZoneNameTimestamp

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<Z> GetField<ZoneNameTimestamp> for ZonedTime<Z>

where Z: GetField<ZoneNameTimestamp>,

Available on crate feature unstable only.

fn get_field(&self) -> ZoneNameTimestamp

Returns the value of this trait’s field T.

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

Available on crate feature serde only.

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 StructuralPartialEq for ZoneNameTimestamp

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

Available on crate feature alloc only.

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()