Struct TimeZoneTransition
pub struct TimeZoneTransition<'t> { /* private fields */ }
dep_jiff
and alloc
only.Expand description
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>
impl<'t> TimeZoneTransition<'t>
pub fn timestamp(&self) -> Timestamp
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
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(&self) -> &'t str ⓘ
pub fn abbreviation(&self) -> &'t 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
.
§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
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>
impl<'t> Clone for TimeZoneTransition<'t>
§fn clone(&self) -> TimeZoneTransition<'t>
fn clone(&self) -> TimeZoneTransition<'t>
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreAuto Trait Implementations§
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>
Blanket Implementations§
§impl<T> ArchivePointee for T
impl<T> ArchivePointee for T
§type ArchivedMetadata = ()
type ArchivedMetadata = ()
§fn pointer_metadata(
_: &<T as ArchivePointee>::ArchivedMetadata,
) -> <T as Pointee>::Metadata
fn pointer_metadata( _: &<T as ArchivePointee>::ArchivedMetadata, ) -> <T as Pointee>::Metadata
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> ByteSized for T
impl<T> ByteSized for T
Source§const BYTE_ALIGN: usize = _
const BYTE_ALIGN: usize = _
Source§fn byte_align(&self) -> usize ⓘ
fn byte_align(&self) -> usize ⓘ
Source§fn ptr_size_ratio(&self) -> [usize; 2]
fn ptr_size_ratio(&self) -> [usize; 2]
Source§impl<T, R> Chain<R> for Twhere
T: ?Sized,
impl<T, R> Chain<R> for Twhere
T: ?Sized,
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> ExtAny for T
impl<T> ExtAny for T
Source§fn as_any_mut(&mut self) -> &mut dyn Anywhere
Self: Sized,
fn as_any_mut(&mut self) -> &mut dyn Anywhere
Self: Sized,
Source§impl<T> ExtMem for Twhere
T: ?Sized,
impl<T> ExtMem for Twhere
T: ?Sized,
Source§const NEEDS_DROP: bool = _
const NEEDS_DROP: bool = _
Source§fn mem_align_of_val(&self) -> usize ⓘ
fn mem_align_of_val(&self) -> usize ⓘ
Source§fn mem_size_of_val(&self) -> usize ⓘ
fn mem_size_of_val(&self) -> usize ⓘ
Source§fn mem_needs_drop(&self) -> bool
fn mem_needs_drop(&self) -> bool
true
if dropping values of this type matters. Read moreSource§fn mem_forget(self)where
Self: Sized,
fn mem_forget(self)where
Self: Sized,
self
without running its destructor. Read moreSource§fn mem_replace(&mut self, other: Self) -> Selfwhere
Self: Sized,
fn mem_replace(&mut self, other: Self) -> Selfwhere
Self: Sized,
Source§unsafe fn mem_zeroed<T>() -> T
unsafe fn mem_zeroed<T>() -> T
unsafe_layout
only.T
represented by the all-zero byte-pattern. Read moreSource§unsafe fn mem_transmute_copy<Src, Dst>(src: &Src) -> Dst
unsafe fn mem_transmute_copy<Src, Dst>(src: &Src) -> Dst
unsafe_layout
only.T
represented by the all-zero byte-pattern. Read moreSource§fn mem_as_bytes(&self) -> &[u8] ⓘ
fn mem_as_bytes(&self) -> &[u8] ⓘ
unsafe_slice
only.§impl<S> FromSample<S> for S
impl<S> FromSample<S> for S
fn from_sample_(s: S) -> S
Source§impl<T> Hook for T
impl<T> Hook for T
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more§impl<F, T> IntoSample<T> for Fwhere
T: FromSample<F>,
impl<F, T> IntoSample<T> for Fwhere
T: FromSample<F>,
fn into_sample(self) -> T
§impl<T> LayoutRaw for T
impl<T> LayoutRaw for T
§fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError> ⓘ
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError> ⓘ
§impl<T, N1, N2> Niching<NichedOption<T, N1>> for N2
impl<T, N1, N2> Niching<NichedOption<T, N1>> for N2
§unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
§fn resolve_niched(out: Place<NichedOption<T, N1>>)
fn resolve_niched(out: Place<NichedOption<T, N1>>)
out
indicating that a T
is niched.