Enum `AmbiguousOffset`

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