Struct `TimeZoneTransition`

struct TimeZoneTransition<'t> { ... }

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
]);

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

Implementations

`impl<'t> TimeZoneTransition<'t>`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

fn type_id(self: &Self) -> TypeId

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

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

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

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

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

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

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

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

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

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

`impl<T, U> Into for TimeZoneTransition<'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 TimeZoneTransition<'t>`

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

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

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