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

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

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

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