Enum AmbiguousOffset

pub enum AmbiguousOffset {
    Unambiguous {
        offset: Offset,
    },
    Gap {
        before: Offset,
        after: Offset,
    },
    Fold {
        before: Offset,
        after: Offset,
    },
}

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

Variants

Unambiguous

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).

Fields

offset: Offset

The offset from UTC for the corresponding civil datetime given. The offset is determined via the relevant time zone data, and in this case, there is only one possible offset that could be applied to the given civil datetime.

Gap

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).

Fields

before: Offset

The offset corresponding to the time before a gap.

For example, given a time zone of America/Los_Angeles, the offset for time immediately preceding 2020-03-08T02:00:00 is -08.

after: Offset

The offset corresponding to the later time in a gap.

For example, given a time zone of America/Los_Angeles, the offset for time immediately following 2020-03-08T02:59:59 is -07.

Fold

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).

Fields

before: Offset

The offset corresponding to the earlier time in a fold.

For example, given a time zone of America/Los_Angeles, the offset for time on the first 2020-11-01T01:00:00 is -07.

after: Offset

The offset corresponding to the earlier time in a fold.

For example, given a time zone of America/Los_Angeles, the offset for time on the second 2020-11-01T01:00:00 is -08.

Trait Implementations

impl Clone for AmbiguousOffset

fn clone(&self) -> AmbiguousOffset

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for AmbiguousOffset

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

Formats the value using the given formatter.

impl PartialEq for AmbiguousOffset

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

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for AmbiguousOffset

impl Eq for AmbiguousOffset

impl StructuralPartialEq for AmbiguousOffset