Struct TimeZoneTransition

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

A representation a single time zone transition.

A time zone transition is an instant in time the marks the beginning of a change in the offset from UTC that civil time is computed from in a particular time zone. For example, when daylight saving time comes into effect (or goes away). Another example is when a geographic region changes its permanent offset from UTC.

This is a low level type that you generally shouldn’t need. It’s useful in cases where you need to know something about the specific instants at which time zone transitions occur. For example, an embedded device might need to be explicitly programmed with daylight saving time transitions. APIs like this enable callers to explore those transitions.

This type is yielded by the iterators TimeZonePrecedingTransitions and TimeZoneFollowingTransitions. The iterators are created by TimeZone::preceding and TimeZone::following, respectively.

Example

This shows a somewhat silly example that finds all of the unique civil (or “clock” or “local”) times at which a time zone transition has occurred in a particular time zone:

use std::collections::BTreeSet;
use jiff::{civil, tz::TimeZone};

let tz = TimeZone::get("America/New_York")?;
let now = civil::date(2024, 12, 31).at(18, 25, 0, 0).to_zoned(tz.clone())?;
let mut set = BTreeSet::new();
for trans in tz.preceding(now.timestamp()) {
    let time = tz.to_datetime(trans.timestamp()).time();
    set.insert(time);
}
assert_eq!(Vec::from_iter(set), vec![
    civil::time(1, 0, 0, 0),  // typical transition out of DST
    civil::time(3, 0, 0, 0),  // typical transition into DST
    civil::time(12, 0, 0, 0), // from when IANA starts keeping track
    civil::time(19, 0, 0, 0), // from World War 2
]);

Implementations

impl<'t> TimeZoneTransition<'t>

pub fn timestamp(&self) -> Timestamp

Returns the timestamp at which this transition began.

Example

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

let tz = TimeZone::get("US/Eastern")?;
// Look for the first time zone transition in `US/Eastern` following
// 2023-03-09 00:00:00.
let start = civil::date(2024, 3, 9).to_zoned(tz.clone())?.timestamp();
let next = tz.following(start).next().unwrap();
assert_eq!(
    next.timestamp().to_zoned(tz.clone()).to_string(),
    "2024-03-10T03:00:00-04:00[US/Eastern]",
);

pub fn offset(&self) -> Offset

Returns the offset corresponding to this time zone transition. All instants at and following this transition’s timestamp (and before the next transition’s timestamp) need to apply this offset from UTC to get the civil or “local” time in the corresponding time zone.

Example

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

let tz = TimeZone::get("US/Eastern")?;
// Get the offset of the next transition after
// 2023-03-09 00:00:00.
let start = civil::date(2024, 3, 9).to_zoned(tz.clone())?.timestamp();
let next = tz.following(start).next().unwrap();
assert_eq!(next.offset(), offset(-4));
// Or go backwards to find the previous transition.
let prev = tz.preceding(start).next().unwrap();
assert_eq!(prev.offset(), offset(-5));

pub fn abbreviation<'a>(&'a self) -> &'a str

Returns the time zone abbreviation corresponding to this time zone transition. All instants at and following this transition’s timestamp (and before the next transition’s timestamp) may use this abbreviation when creating a human readable string. For example, this is the abbreviation used with the %Z specifier with Jiff’s fmt::strtime module.

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 TimeZoneTransition, 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 abbreviation of the next transition after
// 2023-03-09 00:00:00.
let start = civil::date(2024, 3, 9).to_zoned(tz.clone())?.timestamp();
let next = tz.following(start).next().unwrap();
assert_eq!(next.abbreviation(), "EDT");
// Or go backwards to find the previous transition.
let prev = tz.preceding(start).next().unwrap();
assert_eq!(prev.abbreviation(), "EST");

pub fn dst(&self) -> Dst

Returns whether daylight saving time is enabled for this time zone transition.

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 the next transition after
// 2023-03-09 00:00:00.
let start = civil::date(2024, 3, 9).to_zoned(tz.clone())?.timestamp();
let next = tz.following(start).next().unwrap();
assert_eq!(next.dst(), Dst::Yes);
// Or go backwards to find the previous transition.
let prev = tz.preceding(start).next().unwrap();
assert_eq!(prev.dst(), Dst::No);

Trait Implementations

impl<'t> Clone for TimeZoneTransition<'t>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'t> Debug for TimeZoneTransition<'t>

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

Formats the value using the given formatter.