Struct TimeZoneInfo

pub struct TimeZoneInfo<Model: TimeZoneModel> { /* private fields */ }

A utility type that can hold time zone information.

The primary definition of this type is in the icu_time crate. Other ICU4X crates re-export it for convenience.

See the docs on zone for more information.

Examples

use icu::calendar::Date;
use icu::locale::subtags::subtag;
use icu::time::zone::IanaParser;
use icu::time::zone::TimeZoneVariant;
use icu::time::DateTime;
use icu::time::Time;
use icu::time::TimeZone;

// Parse the IANA ID
let id = IanaParser::new().parse("America/Chicago");

// Alternatively, use the BCP47 ID directly
let id = TimeZone(subtag!("uschi"));

// Create a TimeZoneInfo<Base> by associating the ID with an offset
let time_zone = id.with_offset("-0600".parse().ok());

// Extend to a TimeZoneInfo<AtTime> by adding a local time
let time_zone_at_time = time_zone.at_date_time_iso(DateTime {
    date: Date::try_new_iso(2023, 12, 2).unwrap(),
    time: Time::start_of_day(),
});

// Extend to a TimeZoneInfo<Full> by adding a zone variant
let time_zone_with_variant =
    time_zone_at_time.with_variant(TimeZoneVariant::Standard);

Implementations

impl<Model: TimeZoneModel> TimeZoneInfo<Model>

pub fn id(self) -> TimeZone

The BCP47 time-zone identifier.

pub fn offset(self) -> Option<UtcOffset>

The UTC offset, if known.

This field is not enforced to be consistent with the time zone id.

impl<Model> TimeZoneInfo<Model>

where Model: TimeZoneModel<ZoneNameTimestamp = ZoneNameTimestamp>,

pub fn zone_name_timestamp(self) -> ZoneNameTimestamp

The time at which to interpret the time zone.

impl<Model> TimeZoneInfo<Model>

where Model: TimeZoneModel<TimeZoneVariant = TimeZoneVariant>,

pub fn variant(self) -> TimeZoneVariant

The time variant e.g. daylight or standard, if known.

This field is not enforced to be consistent with the time zone id and offset.

impl TimeZoneInfo<Base>

pub const fn unknown() -> Self

Creates a time zone info with no information.

pub const fn utc() -> Self

Creates a new TimeZoneInfo for the UTC time zone.

pub fn with_zone_name_timestamp( self, zone_name_timestamp: ZoneNameTimestamp, ) -> TimeZoneInfo<AtTime>

Sets the ZoneNameTimestamp field.

pub fn at_date_time_iso(self, date_time: DateTime<Iso>) -> TimeZoneInfo<AtTime>

Sets the ZoneNameTimestamp to the given local datetime.

impl TimeZoneInfo<AtTime>

pub const fn with_variant(self, variant: TimeZoneVariant) -> TimeZoneInfo<Full>

Sets a TimeZoneVariant on this time zone.

pub fn infer_variant( self, calculator: VariantOffsetsCalculatorBorrowed<'_>, ) -> TimeZoneInfo<Full>

Sets the zone variant by calculating it using a VariantOffsetsCalculator.

If offset() is None, or if it doesn’t match either of the timezone’s standard or daylight offset around local_time(), the variant will be set to TimeZoneVariant::Standard and the time zone to TimeZone::UNKNOWN.

Example

use icu::calendar::Date;
use icu::locale::subtags::subtag;
use icu::time::zone::TimeZoneVariant;
use icu::time::zone::VariantOffsetsCalculator;
use icu::time::DateTime;
use icu::time::Time;
use icu::time::TimeZone;

// Chicago at UTC-6
let info = TimeZone(subtag!("uschi"))
    .with_offset("-0600".parse().ok())
    .at_date_time_iso(DateTime {
        date: Date::try_new_iso(2023, 12, 2).unwrap(),
        time: Time::start_of_day(),
    })
    .infer_variant(VariantOffsetsCalculator::new());

assert_eq!(info.variant(), TimeZoneVariant::Standard);

// Chicago at at UTC-5
let info = TimeZone(subtag!("uschi"))
    .with_offset("-0500".parse().ok())
    .at_date_time_iso(DateTime {
        date: Date::try_new_iso(2023, 6, 2).unwrap(),
        time: Time::start_of_day(),
    })
    .infer_variant(VariantOffsetsCalculator::new());

assert_eq!(info.variant(), TimeZoneVariant::Daylight);

// Chicago at UTC-7
let info = TimeZone(subtag!("uschi"))
    .with_offset("-0700".parse().ok())
    .at_date_time_iso(DateTime {
        date: Date::try_new_iso(2023, 12, 2).unwrap(),
        time: Time::start_of_day(),
    })
    .infer_variant(VariantOffsetsCalculator::new());

// Whatever it is, it's not Chicago
assert_eq!(info.id(), TimeZone::UNKNOWN);
assert_eq!(info.variant(), TimeZoneVariant::Standard);

Trait Implementations

impl<Model: TimeZoneModel> Clone for TimeZoneInfo<Model>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Model: Debug + TimeZoneModel> Debug for TimeZoneInfo<Model>

where Model::ZoneNameTimestamp: Debug, Model::TimeZoneVariant: Debug,

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

Formats the value using the given formatter.

impl<Model: PartialEq + TimeZoneModel> PartialEq for TimeZoneInfo<Model>

where Model::ZoneNameTimestamp: PartialEq, Model::TimeZoneVariant: PartialEq,

fn eq(&self, other: &TimeZoneInfo<Model>) -> 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<Model: TimeZoneModel> Copy for TimeZoneInfo<Model>

impl<Model: Eq + TimeZoneModel> Eq for TimeZoneInfo<Model>

where Model::ZoneNameTimestamp: Eq, Model::TimeZoneVariant: Eq,

impl<Model: TimeZoneModel> StructuralPartialEq for TimeZoneInfo<Model>