Struct `TimeZoneOffsetInfo`

struct TimeZoneOffsetInfo<'t> { ... }

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",
);

# Ok::<(), Box<dyn std::error::Error>>(())

Implementations

`impl<'t> TimeZoneOffsetInfo<'t>`

fn offset(self: &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));

# Ok::<(), Box<dyn std::error::Error>>(())

fn abbreviation(self: &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");

# Ok::<(), Box<dyn std::error::Error>>(())

fn dst(self: &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);

# Ok::<(), Box<dyn std::error::Error>>(())

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

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

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

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

`impl<'t> Eq for TimeZoneOffsetInfo<'t>`

`impl<'t> Freeze for TimeZoneOffsetInfo<'t>`

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

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

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

fn eq(self: &Self, other: &TimeZoneOffsetInfo<'t>) -> bool

`impl<'t> RefUnwindSafe for TimeZoneOffsetInfo<'t>`

`impl<'t> Send for TimeZoneOffsetInfo<'t>`

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

`impl<'t> Sync for TimeZoneOffsetInfo<'t>`

`impl<'t> Unpin for TimeZoneOffsetInfo<'t>`

`impl<'t> UnwindSafe for TimeZoneOffsetInfo<'t>`

`impl<T> Any for TimeZoneOffsetInfo<'t>`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for TimeZoneOffsetInfo<'t>`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for TimeZoneOffsetInfo<'t>`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for TimeZoneOffsetInfo<'t>`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for TimeZoneOffsetInfo<'t>`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for TimeZoneOffsetInfo<'t>`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, U> Into for TimeZoneOffsetInfo<'t>`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for TimeZoneOffsetInfo<'t>`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for TimeZoneOffsetInfo<'t>`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>