Enum OffsetConflict

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

Available on crate features dep_jiff and alloc only.

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

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