Enum Disambiguation

#[non_exhaustive]
pub enum Disambiguation {
    Compatible,
    Earlier,
    Later,
    Reject,
}

Configuration for resolving ambiguous datetimes in a particular time zone.

This is useful for specifying how to disambiguate ambiguous datetimes at runtime. For example, as configuration for parsing Zoned values via fmt::temporal::DateTimeParser::disambiguation.

Note that there is no difference in using Disambiguation::Compatible.disambiguate(ambiguous_timestamp) and ambiguous_timestamp.compatible(). They are equivalent. The purpose of this enum is to expose the disambiguation strategy as a runtime value for configuration purposes.

The default value is Disambiguation::Compatible, which matches the behavior specified in RFC 5545 (iCalendar). Namely, when an ambiguous datetime is found in a fold (the clocks are rolled back), then the earlier time is selected. And when an ambiguous datetime is found in a gap (the clocks are skipped forward), then the later time is selected.

This enum is non-exhaustive so that other forms of disambiguation may be added in semver compatible releases.

Example

This example shows the default disambiguation mode (“compatible”) when given a datetime that falls in a “gap” (i.e., a forwards DST transition).

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

let newyork = tz::db().get("America/New_York")?;
let ambiguous = newyork.to_ambiguous_zoned(date(2024, 3, 10).at(2, 30, 0, 0));

// NOTE: This is identical to `ambiguous.compatible()`.
let zdt = ambiguous.disambiguate(tz::Disambiguation::Compatible)?;
assert_eq!(zdt.datetime(), date(2024, 3, 10).at(3, 30, 0, 0));
// In compatible mode, forward transitions select the later
// time. In the EST->EDT transition, that's the -04 (EDT) offset.
assert_eq!(zdt.offset(), tz::offset(-4));

Example: parsing

This example shows how to set the disambiguation configuration while parsing a Zoned datetime. In this example, we always prefer the earlier time.

use jiff::{civil::date, fmt::temporal::DateTimeParser, tz};

static PARSER: DateTimeParser = DateTimeParser::new()
    .disambiguation(tz::Disambiguation::Earlier);

let zdt = PARSER.parse_zoned("2024-03-10T02:30[America/New_York]")?;
// In earlier mode, forward transitions select the earlier time, unlike
// in compatible mode. In this case, that's the pre-DST offset of -05.
assert_eq!(zdt.datetime(), date(2024, 3, 10).at(1, 30, 0, 0));
assert_eq!(zdt.offset(), tz::offset(-5));

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Compatible

In a backward transition, the earlier time is selected. In forward transition, the later time is selected.

This is equivalent to AmbiguousTimestamp::compatible and AmbiguousZoned::compatible.

Earlier

The earlier time is always selected.

This is equivalent to AmbiguousTimestamp::earlier and AmbiguousZoned::earlier.

Later

The later time is always selected.

This is equivalent to AmbiguousTimestamp::later and AmbiguousZoned::later.

Reject

When an ambiguous datetime is encountered, this strategy will always result in an error. This is useful if you need to require datetimes from users to unambiguously refer to a specific instant.

This is equivalent to AmbiguousTimestamp::unambiguous and AmbiguousZoned::unambiguous.

Trait Implementations

impl Clone for Disambiguation

fn clone(&self) -> Disambiguation

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Disambiguation

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

Formats the value using the given formatter.

impl Default for Disambiguation

fn default() -> Disambiguation

Returns the “default value” for a type.

impl Copy for Disambiguation