Enum OffsetConflict

#[non_exhaustive]
pub enum OffsetConflict {
    AlwaysOffset,
    AlwaysTimeZone,
    PreferOffset,
    Reject,
}

Configuration for resolving disparities between an offset and a time zone.

A conflict between an offset and a time zone most commonly appears in a datetime string. For example, 2024-06-14T17:30-05[America/New_York] has a definitive inconsistency between the reported offset (-05) and the time zone (America/New_York), because at this time in New York, daylight saving time (DST) was in effect. In New York in the year 2024, DST corresponded to the UTC offset -04.

Other conflict variations exist. For example, in 2019, Brazil abolished DST completely. But if one were to create a datetime for 2020 in 2018, that datetime in 2020 would reflect the DST rules as they exist in 2018. That could in turn result in a datetime with an offset that is incorrect with respect to the rules in 2019.

For this reason, this crate exposes a few ways of resolving these conflicts. It is most commonly used as configuration for parsing Zoned values via fmt::temporal::DateTimeParser::offset_conflict. But this configuration can also be used directly via OffsetConflict::resolve.

The default value is OffsetConflict::Reject, which results in an error being returned if the offset and a time zone are not in agreement. This is the default so that Jiff does not automatically make silent choices about whether to prefer the time zone or the offset. The fmt::temporal::DateTimeParser::parse_zoned_with documentation shows an example demonstrating its utility in the face of changes in the law, such as the abolition of daylight saving time. By rejecting such things, one can ensure that the original timestamp is preserved or else an error occurs.

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

Example

This example shows how to always use the time zone even if the offset is wrong.

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

let dt = date(2024, 6, 14).at(17, 30, 0, 0);
let offset = tz::offset(-5); // wrong! should be -4
let newyork = tz::db().get("America/New_York")?;

// The default conflict resolution, 'Reject', will error.
let result = tz::OffsetConflict::Reject
    .resolve(dt, offset, newyork.clone());
assert!(result.is_err());

// But we can change it to always prefer the time zone.
let zdt = tz::OffsetConflict::AlwaysTimeZone
    .resolve(dt, offset, newyork.clone())?
    .unambiguous()?;
assert_eq!(zdt.datetime(), date(2024, 6, 14).at(17, 30, 0, 0));
// The offset has been corrected automatically.
assert_eq!(zdt.offset(), tz::offset(-4));

Example: parsing

This example shows how to set the offset conflict resolution configuration while parsing a Zoned datetime. In this example, we always prefer the offset, even if it conflicts with the time zone.

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

static PARSER: DateTimeParser = DateTimeParser::new()
    .offset_conflict(tz::OffsetConflict::AlwaysOffset);

let zdt = PARSER.parse_zoned("2024-06-14T17:30-05[America/New_York]")?;
// The time *and* offset have been corrected. The offset given was invalid,
// so it cannot be kept, but the timestamp returned is equivalent to
// `2024-06-14T17:30-05`. It is just adjusted automatically to be correct
// in the `America/New_York` time zone.
assert_eq!(zdt.datetime(), date(2024, 6, 14).at(18, 30, 0, 0));
assert_eq!(zdt.offset(), tz::offset(-4));

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.

AlwaysOffset

When the offset and time zone are in conflict, this will always use the offset to interpret the date time.

When resolving to a AmbiguousZoned, the time zone attached to the timestamp will still be the same as the time zone given. The difference here is that the offset will be adjusted such that it is correct for the given time zone. However, the timestamp itself will always match the datetime and offset given (and which is always unambiguous).

Basically, you should use this option when you want to keep the exact time unchanged (as indicated by the datetime and offset), even if it means a change to civil time.

AlwaysTimeZone

When the offset and time zone are in conflict, this will always use the time zone to interpret the date time.

When resolving to an AmbiguousZoned, the offset attached to the timestamp will always be determined by only looking at the time zone. This in turn implies that the timestamp returned could be ambiguous, since this conflict resolution strategy specifically ignores the offset. (And, we’re only at this point because the offset is not possible for the given time zone, so it can’t be used in concert with the time zone anyway.) This is unlike the AlwaysOffset strategy where the timestamp returned is guaranteed to be unambiguous.

You should use this option when you want to keep the civil time unchanged even if it means a change to the exact time.

PreferOffset

Always attempt to use the offset to resolve a datetime to a timestamp, unless the offset is invalid for the provided time zone. In that case, use the time zone. When the time zone is used, it’s possible for an ambiguous datetime to be returned.

See ZonedWith::offset_conflict for an example of when this strategy is useful.

Reject

When the offset and time zone are in conflict, this strategy always results in conflict resolution returning an error.

This is the default since a conflict between the offset and the time zone usually implies an invalid datetime in some way.

Implementations

impl OffsetConflict

pub fn resolve( self, dt: DateTime, offset: Offset, tz: TimeZone, ) -> Result<AmbiguousZoned, Error>

Resolve a potential conflict between an Offset and a TimeZone.

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 OffsetConflict::Reject strategy. Namely, when using the Reject strategy, any offset that is not compatible with the given datetime and time zone will always result in an error.

Example

This example shows how each of the different conflict resolution strategies are applied.

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

let dt = date(2024, 6, 14).at(17, 30, 0, 0);
let offset = tz::offset(-5); // wrong! should be -4
let newyork = tz::db().get("America/New_York")?;

// Here, we use the offset and ignore the time zone.
let zdt = tz::OffsetConflict::AlwaysOffset
    .resolve(dt, offset, newyork.clone())?
    .unambiguous()?;
// The datetime (and offset) have been corrected automatically
// and the resulting Zoned instant corresponds precisely to
// `2024-06-14T17:30-05[UTC]`.
assert_eq!(zdt.to_string(), "2024-06-14T18:30:00-04:00[America/New_York]");

// Here, we use the time zone and ignore the offset.
let zdt = tz::OffsetConflict::AlwaysTimeZone
    .resolve(dt, offset, newyork.clone())?
    .unambiguous()?;
// The offset has been corrected automatically and the resulting
// Zoned instant corresponds precisely to `2024-06-14T17:30-04[UTC]`.
// Notice how the civil time remains the same, but the exact instant
// has changed!
assert_eq!(zdt.to_string(), "2024-06-14T17:30:00-04:00[America/New_York]");

// Here, we prefer the offset, but fall back to the time zone.
// In this example, it has the same behavior as `AlwaysTimeZone`.
let zdt = tz::OffsetConflict::PreferOffset
    .resolve(dt, offset, newyork.clone())?
    .unambiguous()?;
assert_eq!(zdt.to_string(), "2024-06-14T17:30:00-04:00[America/New_York]");

// The default conflict resolution, 'Reject', will error.
let result = tz::OffsetConflict::Reject
    .resolve(dt, offset, newyork.clone());
assert!(result.is_err());

pub fn resolve_with<F>( self, dt: DateTime, offset: Offset, tz: TimeZone, is_equal: F, ) -> Result<AmbiguousZoned, Error>

where F: FnMut(Offset, Offset) -> bool,

Resolve a potential conflict between an Offset and a TimeZone using the given definition of equality for an Offset.

The equality predicate is always given a pair of offsets where the first is the offset given to resolve_with and the second is the offset found in the TimeZone.

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 OffsetConflict::Reject strategy. Namely, when using the Reject strategy, any offset that is not compatible with the given datetime and time zone will always result in an error.

Example

Unlike OffsetConflict::resolve, this routine permits overriding the definition of equality used for comparing offsets. In OffsetConflict::resolve, exact equality is used. This can be troublesome in some cases when a time zone has an offset with fractional minutes, such as Africa/Monrovia before 1972.

Because RFC 3339 and RFC 9557 do not support time zone offsets with fractional minutes, Jiff will serialize offsets with fractional minutes by rounding to the nearest minute. This will result in a different offset than what is actually used in the time zone. Parsing this should succeed, but if exact offset equality is used, it won’t. This is why a fmt::temporal::DateTimeParser uses this routine with offset equality that rounds offsets to the nearest minute before comparison.

use jiff::{civil::date, tz::{Offset, OffsetConflict, TimeZone}, Unit};

let dt = date(1968, 2, 1).at(23, 15, 0, 0);
let offset = Offset::from_seconds(-(44 * 60 + 30)).unwrap();
let zdt = dt.in_tz("Africa/Monrovia")?;
assert_eq!(zdt.offset(), offset);
// Notice that the offset has been rounded!
assert_eq!(zdt.to_string(), "1968-02-01T23:15:00-00:45[Africa/Monrovia]");

// Now imagine parsing extracts the civil datetime, the offset and
// the time zone, and then naively does exact offset comparison:
let tz = TimeZone::get("Africa/Monrovia")?;
// This is the parsed offset, which won't precisely match the actual
// offset used by `Africa/Monrovia` at this time.
let offset = Offset::from_seconds(-45 * 60).unwrap();
let result = OffsetConflict::Reject.resolve(dt, offset, tz.clone());
assert_eq!(
    result.unwrap_err().to_string(),
    "datetime 1968-02-01T23:15:00 could not resolve to a timestamp \
     since 'reject' conflict resolution was chosen, and because \
     datetime has offset -00:45, but the time zone Africa/Monrovia \
     for the given datetime unambiguously has offset -00:44:30",
);
let is_equal = |parsed: Offset, candidate: Offset| {
    parsed == candidate || candidate.round(Unit::Minute).map_or(
        parsed == candidate,
        |candidate| parsed == candidate,
    )
};
let zdt = OffsetConflict::Reject.resolve_with(
    dt,
    offset,
    tz.clone(),
    is_equal,
)?.unambiguous()?;
// Notice that the offset is the actual offset from the time zone:
assert_eq!(zdt.offset(), Offset::from_seconds(-(44 * 60 + 30)).unwrap());
// But when we serialize, the offset gets rounded. If we didn't
// do this, we'd risk the datetime not being parsable by other
// implementations since RFC 3339 and RFC 9557 don't support fractional
// minutes in the offset.
assert_eq!(zdt.to_string(), "1968-02-01T23:15:00-00:45[Africa/Monrovia]");

And indeed, notice that parsing uses this same kind of offset equality to permit zoned datetimes whose offsets would be equivalent after rounding:

use jiff::{tz::Offset, Zoned};

let zdt: Zoned = "1968-02-01T23:15:00-00:45[Africa/Monrovia]".parse()?;
// As above, notice that even though we parsed `-00:45` as the
// offset, the actual offset of our zoned datetime is the correct
// one from the time zone.
assert_eq!(zdt.offset(), Offset::from_seconds(-(44 * 60 + 30)).unwrap());
// And similarly, re-serializing it results in rounding the offset
// again for compatibility with RFC 3339 and RFC 9557.
assert_eq!(zdt.to_string(), "1968-02-01T23:15:00-00:45[Africa/Monrovia]");

// And we also support parsing the actual fractional minute offset
// as well:
let zdt: Zoned = "1968-02-01T23:15:00-00:44:30[Africa/Monrovia]".parse()?;
assert_eq!(zdt.offset(), Offset::from_seconds(-(44 * 60 + 30)).unwrap());
assert_eq!(zdt.to_string(), "1968-02-01T23:15:00-00:45[Africa/Monrovia]");

Trait Implementations

impl Clone for OffsetConflict

fn clone(&self) -> OffsetConflict

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for OffsetConflict

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

Formats the value using the given formatter.

impl Default for OffsetConflict

fn default() -> OffsetConflict

Returns the “default value” for a type.

impl Copy for OffsetConflict