Struct AmbiguousTimestamp

pub struct AmbiguousTimestamp { /* private fields */ }

A possibly ambiguous Timestamp, created by TimeZone::to_ambiguous_timestamp.

While this is called an ambiguous timestamp, the thing that is actually ambiguous is the offset. That is, an ambiguous timestamp is actually a pair of a civil::DateTime and an AmbiguousOffset.

When the offset is ambiguous, it either represents a gap (civil time is skipped) or a fold (civil time is repeated). In both cases, there are, by construction, two different offsets to choose from: the offset from before the transition and the offset from after the transition.

The purpose of this type is to represent that ambiguity (when it occurs) and enable callers to make a choice about how to resolve that ambiguity. In some cases, you might want to reject ambiguity altogether, which is supported by the AmbiguousTimestamp::unambiguous routine.

This type provides four different out-of-the-box disambiguation strategies:

• AmbiguousTimestamp::compatible implements the Disambiguation::Compatible strategy. In the case of a gap, the offset after the gap is selected. In the case of a fold, the offset before the fold occurs is selected.
• AmbiguousTimestamp::earlier implements the Disambiguation::Earlier strategy. This always selects the “earlier” offset.
• AmbiguousTimestamp::later implements the Disambiguation::Later strategy. This always selects the “later” offset.
• AmbiguousTimestamp::unambiguous implements the Disambiguation::Reject strategy. It acts as an assertion that the offset is unambiguous. If it is ambiguous, then an appropriate error is returned.

The AmbiguousTimestamp::disambiguate method can be used with the Disambiguation enum when the disambiguation strategy isn’t known until runtime.

Note also that these aren’t the only disambiguation strategies. The AmbiguousOffset type, accessible via AmbiguousTimestamp::offset, exposes the full details of the ambiguity. So any strategy can be implemented.

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

Implementations

impl AmbiguousTimestamp

pub fn datetime(&self) -> DateTime

Returns the civil datetime that was used to create this ambiguous timestamp.

Example

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

let tz = tz::db().get("America/New_York")?;
let dt = date(2024, 7, 10).at(17, 15, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(ts.datetime(), dt);

pub fn offset(&self) -> AmbiguousOffset

Returns the possibly ambiguous offset that is the ultimate source of ambiguity.

Most civil datetimes are not ambiguous, and thus, the offset will not be ambiguous either. In this case, the offset returned will be the AmbiguousOffset::Unambiguous variant.

But, not all civil datetimes are unambiguous. There are exactly two cases where a civil datetime can be ambiguous: when a civil datetime does not exist (a gap) or when a civil datetime is repeated (a fold). In both such cases, the offset is the thing that is ambiguous as there are two possible choices for the offset in both cases: the offset before the transition (whether it’s a gap or a fold) or the offset after the transition.

This type captures the fact that computing an offset from a civil datetime in a particular time zone is in one of three possible states:

1. It is unambiguous.
2. It is ambiguous because there is a gap in time.
3. It is ambiguous because there is a fold in time.

Example

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

let tz = tz::db().get("America/New_York")?;

// Not ambiguous.
let dt = date(2024, 7, 15).at(17, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(ts.offset(), AmbiguousOffset::Unambiguous {
    offset: tz::offset(-4),
});

// Ambiguous because of a gap.
let dt = date(2024, 3, 10).at(2, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(ts.offset(), AmbiguousOffset::Gap {
    before: tz::offset(-5),
    after: tz::offset(-4),
});

// Ambiguous because of a fold.
let dt = date(2024, 11, 3).at(1, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(ts.offset(), AmbiguousOffset::Fold {
    before: tz::offset(-4),
    after: tz::offset(-5),
});

pub fn is_ambiguous(&self) -> bool

Returns true if and only if this possibly ambiguous timestamp is actually ambiguous.

This occurs precisely in cases when the offset is not AmbiguousOffset::Unambiguous.

Example

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

let tz = tz::db().get("America/New_York")?;

// Not ambiguous.
let dt = date(2024, 7, 15).at(17, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert!(!ts.is_ambiguous());

// Ambiguous because of a gap.
let dt = date(2024, 3, 10).at(2, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert!(ts.is_ambiguous());

// Ambiguous because of a fold.
let dt = date(2024, 11, 3).at(1, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert!(ts.is_ambiguous());

pub fn compatible(self) -> Result<Timestamp, Error>

Disambiguates this timestamp according to the Disambiguation::Compatible strategy.

If this timestamp is unambiguous, then this is a no-op.

The “compatible” strategy selects the offset corresponding to the civil time after a gap, and the offset corresponding to the civil time before a fold. This is what is specified in RFC 5545.

Errors

This returns an error when the combination of the civil datetime and offset would lead to a Timestamp outside of the Timestamp::MIN and Timestamp::MAX limits. This only occurs when the civil datetime is “close” to its own DateTime::MIN and DateTime::MAX limits.

Example

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

let tz = tz::db().get("America/New_York")?;

// Not ambiguous.
let dt = date(2024, 7, 15).at(17, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.compatible()?.to_string(),
    "2024-07-15T21:30:00Z",
);

// Ambiguous because of a gap.
let dt = date(2024, 3, 10).at(2, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.compatible()?.to_string(),
    "2024-03-10T07:30:00Z",
);

// Ambiguous because of a fold.
let dt = date(2024, 11, 3).at(1, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.compatible()?.to_string(),
    "2024-11-03T05:30:00Z",
);

pub fn earlier(self) -> Result<Timestamp, Error>

Disambiguates this timestamp according to the Disambiguation::Earlier strategy.

If this timestamp is unambiguous, then this is a no-op.

The “earlier” strategy selects the offset corresponding to the civil time before a gap, and the offset corresponding to the civil time before a fold.

Errors

This returns an error when the combination of the civil datetime and offset would lead to a Timestamp outside of the Timestamp::MIN and Timestamp::MAX limits. This only occurs when the civil datetime is “close” to its own DateTime::MIN and DateTime::MAX limits.

Example

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

let tz = tz::db().get("America/New_York")?;

// Not ambiguous.
let dt = date(2024, 7, 15).at(17, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.earlier()?.to_string(),
    "2024-07-15T21:30:00Z",
);

// Ambiguous because of a gap.
let dt = date(2024, 3, 10).at(2, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.earlier()?.to_string(),
    "2024-03-10T06:30:00Z",
);

// Ambiguous because of a fold.
let dt = date(2024, 11, 3).at(1, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.earlier()?.to_string(),
    "2024-11-03T05:30:00Z",
);

pub fn later(self) -> Result<Timestamp, Error>

Disambiguates this timestamp according to the Disambiguation::Later strategy.

If this timestamp is unambiguous, then this is a no-op.

The “later” strategy selects the offset corresponding to the civil time after a gap, and the offset corresponding to the civil time after a fold.

Errors

This returns an error when the combination of the civil datetime and offset would lead to a Timestamp outside of the Timestamp::MIN and Timestamp::MAX limits. This only occurs when the civil datetime is “close” to its own DateTime::MIN and DateTime::MAX limits.

Example

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

let tz = tz::db().get("America/New_York")?;

// Not ambiguous.
let dt = date(2024, 7, 15).at(17, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.later()?.to_string(),
    "2024-07-15T21:30:00Z",
);

// Ambiguous because of a gap.
let dt = date(2024, 3, 10).at(2, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.later()?.to_string(),
    "2024-03-10T07:30:00Z",
);

// Ambiguous because of a fold.
let dt = date(2024, 11, 3).at(1, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.later()?.to_string(),
    "2024-11-03T06:30:00Z",
);

pub fn unambiguous(self) -> Result<Timestamp, Error>

Disambiguates this timestamp according to the Disambiguation::Reject strategy.

If this timestamp is unambiguous, then this is a no-op.

The “reject” strategy always returns an error when the timestamp is ambiguous.

Errors

This returns an error when the combination of the civil datetime and offset would lead to a Timestamp outside of the Timestamp::MIN and Timestamp::MAX limits. This only occurs when the civil datetime is “close” to its own DateTime::MIN and DateTime::MAX limits.

This also returns an error when the timestamp is ambiguous.

Example

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

let tz = tz::db().get("America/New_York")?;

// Not ambiguous.
let dt = date(2024, 7, 15).at(17, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert_eq!(
    ts.later()?.to_string(),
    "2024-07-15T21:30:00Z",
);

// Ambiguous because of a gap.
let dt = date(2024, 3, 10).at(2, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert!(ts.unambiguous().is_err());

// Ambiguous because of a fold.
let dt = date(2024, 11, 3).at(1, 30, 0, 0);
let ts = tz.to_ambiguous_timestamp(dt);
assert!(ts.unambiguous().is_err());

pub fn disambiguate(self, option: Disambiguation) -> Result<Timestamp, Error>

Disambiguates this (possibly ambiguous) timestamp into a specific timestamp.

This is the same as calling one of the disambiguation methods, but the method chosen is indicated by the option given. This is useful when the disambiguation option needs to be chosen at runtime.

Errors

This returns an error if this would have returned a timestamp outside of its minimum and maximum values.

This can also return an error when using the Disambiguation::Reject strategy. Namely, when using the Reject strategy, any ambiguous timestamp always results in an error.

Example

This example shows the various disambiguation modes when given a datetime that falls in a “fold” (i.e., a backwards DST transition).

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

let newyork = tz::db().get("America/New_York")?;
let dt = date(2024, 11, 3).at(1, 30, 0, 0);
let ambiguous = newyork.to_ambiguous_timestamp(dt);

// In compatible mode, backward transitions select the earlier
// time. In the EDT->EST transition, that's the -04 (EDT) offset.
let ts = ambiguous.clone().disambiguate(Disambiguation::Compatible)?;
assert_eq!(ts.to_string(), "2024-11-03T05:30:00Z");

// The earlier time in the EDT->EST transition is the -04 (EDT) offset.
let ts = ambiguous.clone().disambiguate(Disambiguation::Earlier)?;
assert_eq!(ts.to_string(), "2024-11-03T05:30:00Z");

// The later time in the EDT->EST transition is the -05 (EST) offset.
let ts = ambiguous.clone().disambiguate(Disambiguation::Later)?;
assert_eq!(ts.to_string(), "2024-11-03T06:30:00Z");

// Since our datetime is ambiguous, the 'reject' strategy errors.
assert!(ambiguous.disambiguate(Disambiguation::Reject).is_err());

Trait Implementations

impl Clone for AmbiguousTimestamp

fn clone(&self) -> AmbiguousTimestamp

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for AmbiguousTimestamp

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

Formats the value using the given formatter.

impl PartialEq for AmbiguousTimestamp

fn eq(&self, other: &AmbiguousTimestamp) -> 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 AmbiguousTimestamp

impl Eq for AmbiguousTimestamp

impl StructuralPartialEq for AmbiguousTimestamp