Enum `AmbiguousOffset`

enum AmbiguousOffset

A possibly ambiguous Offset.

An AmbiguousOffset is part of both AmbiguousTimestamp and AmbiguousZoned, which are created by TimeZone::to_ambiguous_timestamp and TimeZone::to_ambiguous_zoned, respectively.

When converting a civil datetime in a particular time zone to a precise instant in time (that is, either Timestamp or Zoned), then the primary thing needed to form a precise instant in time is an Offset. The problem is that some civil datetimes are ambiguous. That is, some do not exist (because they fall into a gap, where some civil time is skipped), or some are repeated (because they fall into a fold, where some civil time is repeated).

The purpose of this type is to represent that ambiguity when it occurs. The ambiguity is manifest through the offset choice: it is either the offset before the transition or the offset after the transition. This is true regardless of whether the ambiguity occurs as a result of a gap or a fold.

It is generally considered very rare to need to inspect values of this type directly. Instead, higher level routines like AmbiguousZoned::compatible or AmbiguousZoned::unambiguous will implement a strategy for you.

Example

This example shows how the "compatible" disambiguation strategy is implemented. Recall that the "compatible" strategy chooses the offset corresponding to the civil datetime after a gap, and the offset corresponding to the civil datetime before a gap.

use jiff::{civil::date, tz::{self, AmbiguousOffset}};

let tz = tz::db().get("America/New_York")?;
let dt = date(2024, 3, 10).at(2, 30, 0, 0);
let offset = match tz.to_ambiguous_timestamp(dt).offset() {
    AmbiguousOffset::Unambiguous { offset } => offset,
    // This is counter-intuitive, but in order to get the civil datetime
    // *after* the gap, we need to select the offset from *before* the
    // gap.
    AmbiguousOffset::Gap { before, .. } => before,
    AmbiguousOffset::Fold { before, .. } => before,
};
assert_eq!(offset.to_timestamp(dt)?.to_string(), "2024-03-10T07:30:00Z");

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

Variants

Unambiguous { offset: Offset }

The offset for a particular civil datetime and time zone is unambiguous.

This is the overwhelmingly common case. In general, the only time this case does not occur is when there is a transition to a different time zone (rare) or to/from daylight saving time (occurs for 1 hour twice in year in many geographic locations).

Gap { before: Offset, after: Offset }

The offset for a particular civil datetime and time zone is ambiguous because there is a gap.

This most commonly occurs when a civil datetime corresponds to an hour that was "skipped" in a jump to DST (daylight saving time).

Fold { before: Offset, after: Offset }

The offset for a particular civil datetime and time zone is ambiguous because there is a fold.

This most commonly occurs when a civil datetime corresponds to an hour that was "repeated" in a jump to standard time from DST (daylight saving time).

Implementations

`impl Clone for AmbiguousOffset`

fn clone(self: &Self) -> AmbiguousOffset

`impl Copy for AmbiguousOffset`

`impl Debug for AmbiguousOffset`

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

`impl Eq for AmbiguousOffset`

`impl Freeze for AmbiguousOffset`

`impl PartialEq for AmbiguousOffset`

fn eq(self: &Self, other: &AmbiguousOffset) -> bool

`impl RefUnwindSafe for AmbiguousOffset`

`impl Send for AmbiguousOffset`

`impl StructuralPartialEq for AmbiguousOffset`

`impl Sync for AmbiguousOffset`

`impl Unpin for AmbiguousOffset`

`impl UnwindSafe for AmbiguousOffset`

`impl<T> Any for AmbiguousOffset`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for AmbiguousOffset`

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

`impl<T> BorrowMut for AmbiguousOffset`

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

`impl<T> CloneToUninit for AmbiguousOffset`

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

`impl<T> From for AmbiguousOffset`

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

`impl<T> ToOwned for AmbiguousOffset`

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

`impl<T, U> Into for AmbiguousOffset`

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 AmbiguousOffset`

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

`impl<T, U> TryInto for AmbiguousOffset`

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