Struct TimeZoneOffsetInfo

pub struct TimeZoneOffsetInfo<'t> { /* private fields */ }

An offset along with DST status and a time zone abbreviation.

This information can be computed from a TimeZone given a Timestamp via TimeZone::to_offset_info.

Generally, the extra information associated with the offset is not commonly needed. And indeed, inspecting the daylight saving time status of a particular instant in a time zone usually leads to bugs. For example, not all time zone transitions are the result of daylight saving time. Some are the result of permanent changes to the standard UTC offset of a region.

This information is available via an API distinct from TimeZone::to_offset because it is not commonly needed and because it can sometimes be more expensive to compute.

The main use case for daylight saving time status or time zone abbreviations is for formatting datetimes in an end user’s locale. If you want this, consider using the icu crate via jiff-icu.

The lifetime parameter 't corresponds to the lifetime of the TimeZone that this info was extracted from.

Example

use jiff::{tz::{self, Dst, TimeZone}, Timestamp};

let tz = TimeZone::get("America/New_York")?;

// A timestamp in DST in New York.
let ts = Timestamp::from_second(1_720_493_204)?;
let info = tz.to_offset_info(ts);
assert_eq!(info.offset(), tz::offset(-4));
assert_eq!(info.dst(), Dst::Yes);
assert_eq!(info.abbreviation(), "EDT");
assert_eq!(
    info.offset().to_datetime(ts).to_string(),
    "2024-07-08T22:46:44",
);

// A timestamp *not* in DST in New York.
let ts = Timestamp::from_second(1_704_941_204)?;
let info = tz.to_offset_info(ts);
assert_eq!(info.offset(), tz::offset(-5));
assert_eq!(info.dst(), Dst::No);
assert_eq!(info.abbreviation(), "EST");
assert_eq!(
    info.offset().to_datetime(ts).to_string(),
    "2024-01-10T21:46:44",
);

Implementations

impl<'t> TimeZoneOffsetInfo<'t>

pub fn offset(&self) -> Offset

Returns the offset.

The offset is duration, from UTC, that should be used to offset the civil time in a particular location.

Example

use jiff::{civil, tz::{TimeZone, offset}};

let tz = TimeZone::get("US/Eastern")?;
// Get the offset for 2023-03-10 00:00:00.
let start = civil::date(2024, 3, 10).to_zoned(tz.clone())?.timestamp();
let info = tz.to_offset_info(start);
assert_eq!(info.offset(), offset(-5));
// Go forward a day and notice the offset changes due to DST!
let start = civil::date(2024, 3, 11).to_zoned(tz.clone())?.timestamp();
let info = tz.to_offset_info(start);
assert_eq!(info.offset(), offset(-4));

pub fn abbreviation(&self) -> &str

Returns the time zone abbreviation corresponding to this offset info.

Note that abbreviations can to be ambiguous. For example, the abbreviation CST can be used for the time zones Asia/Shanghai, America/Chicago and America/Havana.

The lifetime of the string returned is tied to this TimeZoneOffsetInfo, which may be shorter than 't (the lifetime of the time zone this transition was created from).

Example

use jiff::{civil, tz::TimeZone};

let tz = TimeZone::get("US/Eastern")?;
// Get the time zone abbreviation for 2023-03-10 00:00:00.
let start = civil::date(2024, 3, 10).to_zoned(tz.clone())?.timestamp();
let info = tz.to_offset_info(start);
assert_eq!(info.abbreviation(), "EST");
// Go forward a day and notice the abbreviation changes due to DST!
let start = civil::date(2024, 3, 11).to_zoned(tz.clone())?.timestamp();
let info = tz.to_offset_info(start);
assert_eq!(info.abbreviation(), "EDT");

pub fn dst(&self) -> Dst

Returns whether daylight saving time is enabled for this offset info.

Callers should generally treat this as informational only. In particular, not all time zone transitions are related to daylight saving time. For example, some transitions are a result of a region permanently changing their offset from UTC.

Example

use jiff::{civil, tz::{Dst, TimeZone}};

let tz = TimeZone::get("US/Eastern")?;
// Get the DST status of 2023-03-11 00:00:00.
let start = civil::date(2024, 3, 11).to_zoned(tz.clone())?.timestamp();
let info = tz.to_offset_info(start);
assert_eq!(info.dst(), Dst::Yes);

Trait Implementations

impl<'t> Clone for TimeZoneOffsetInfo<'t>

fn clone(&self) -> TimeZoneOffsetInfo<'t>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'t> Debug for TimeZoneOffsetInfo<'t>

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

Formats the value using the given formatter.

impl<'t> Hash for TimeZoneOffsetInfo<'t>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'t> PartialEq for TimeZoneOffsetInfo<'t>

fn eq(&self, other: &TimeZoneOffsetInfo<'t>) -> 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<'t> Eq for TimeZoneOffsetInfo<'t>

impl<'t> StructuralPartialEq for TimeZoneOffsetInfo<'t>