impl ZonedWith

fn build(self: Self) -> Result<Zoned, Error>

Create a new Zoned from the fields set on this configuration.

An error occurs when the fields combine to an invalid zoned datetime.

For any fields not set on this configuration, the values are taken from the Zoned that originally created this configuration. When no values are set, this routine is guaranteed to succeed and will always return the original zoned datetime without modification.

Example

This creates a zoned datetime corresponding to the last day in the year at noon:

use jiff::civil::date;

let zdt = date(2023, 1, 1).at(12, 0, 0, 0).in_tz("America/New_York")?;
assert_eq!(
    zdt.with().day_of_year_no_leap(365).build()?,
    date(2023, 12, 31).at(12, 0, 0, 0).in_tz("America/New_York")?,
);

// It also works with leap years for the same input:
let zdt = date(2024, 1, 1).at(12, 0, 0, 0).in_tz("America/New_York")?;
assert_eq!(
    zdt.with().day_of_year_no_leap(365).build()?,
    date(2024, 12, 31).at(12, 0, 0, 0).in_tz("America/New_York")?,
);

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

Example: error for invalid zoned datetime

If the fields combine to form an invalid datetime, then an error is returned:

use jiff::civil::date;

let zdt = date(2024, 11, 30).at(15, 30, 0, 0).in_tz("America/New_York")?;
assert!(zdt.with().day(31).build().is_err());

let zdt = date(2024, 2, 29).at(15, 30, 0, 0).in_tz("America/New_York")?;
assert!(zdt.with().year(2023).build().is_err());

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

fn date(self: Self, date: Date) -> ZonedWith

Set the year, month and day fields via the Date given.

This overrides any previous year, month or day settings.

Example

This shows how to create a new zoned datetime with a different date:

use jiff::civil::date;

let zdt1 = date(2005, 11, 5).at(15, 30, 0, 0).in_tz("America/New_York")?;
let zdt2 = zdt1.with().date(date(2017, 10, 31)).build()?;
// The date changes but the time remains the same.
assert_eq!(
    zdt2,
    date(2017, 10, 31).at(15, 30, 0, 0).in_tz("America/New_York")?,
);

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

fn time(self: Self, time: Time) -> ZonedWith

Set the hour, minute, second, millisecond, microsecond and nanosecond fields via the Time given.

This overrides any previous hour, minute, second, millisecond, microsecond, nanosecond or subsecond nanosecond settings.

Example

This shows how to create a new zoned datetime with a different time:

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

let zdt1 = date(2005, 11, 5).at(15, 30, 0, 0).in_tz("America/New_York")?;
let zdt2 = zdt1.with().time(time(23, 59, 59, 123_456_789)).build()?;
// The time changes but the date remains the same.
assert_eq!(
    zdt2,
    date(2005, 11, 5)
        .at(23, 59, 59, 123_456_789)
        .in_tz("America/New_York")?,
);

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

fn year(self: Self, year: i16) -> ZonedWith

Set the year field on a Zoned.

One can access this value via Zoned::year.

This overrides any previous year settings.

Errors

This returns an error when ZonedWith::build is called if the given year is outside the range -9999..=9999. This can also return an error if the resulting date is otherwise invalid.

Example

This shows how to create a new zoned datetime with a different year:

use jiff::civil::date;

let zdt1 = date(2005, 11, 5).at(15, 30, 0, 0).in_tz("America/New_York")?;
assert_eq!(zdt1.year(), 2005);
let zdt2 = zdt1.with().year(2007).build()?;
assert_eq!(zdt2.year(), 2007);

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

Example: only changing the year can fail

For example, while 2024-02-29T01:30:00[America/New_York] is valid, 2023-02-29T01:30:00[America/New_York] is not:

use jiff::civil::date;

let zdt = date(2024, 2, 29).at(1, 30, 0, 0).in_tz("America/New_York")?;
assert!(zdt.with().year(2023).build().is_err());

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

fn era_year(self: Self, year: i16, era: Era) -> ZonedWith

Set the year of a zoned datetime via its era and its non-negative numeric component.

One can access this value via Zoned::era_year.

Errors

This returns an error when ZonedWith::build is called if the year is outside the range for the era specified. For Era::BCE, the range is 1..=10000. For Era::CE, the range is 1..=9999.

Example

This shows that CE years are equivalent to the years used by this crate:

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

let zdt1 = date(2005, 11, 5).at(8, 0, 0, 0).in_tz("America/New_York")?;
assert_eq!(zdt1.year(), 2005);
let zdt2 = zdt1.with().era_year(2007, Era::CE).build()?;
assert_eq!(zdt2.year(), 2007);

// CE years are always positive and can be at most 9999:
assert!(zdt1.with().era_year(-5, Era::CE).build().is_err());
assert!(zdt1.with().era_year(10_000, Era::CE).build().is_err());

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

But BCE years always correspond to years less than or equal to 0 in this crate:

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

let zdt1 = date(-27, 7, 1).at(8, 22, 30, 0).in_tz("America/New_York")?;
assert_eq!(zdt1.year(), -27);
assert_eq!(zdt1.era_year(), (28, Era::BCE));

let zdt2 = zdt1.with().era_year(509, Era::BCE).build()?;
assert_eq!(zdt2.year(), -508);
assert_eq!(zdt2.era_year(), (509, Era::BCE));

let zdt2 = zdt1.with().era_year(10_000, Era::BCE).build()?;
assert_eq!(zdt2.year(), -9_999);
assert_eq!(zdt2.era_year(), (10_000, Era::BCE));

// BCE years are always positive and can be at most 10000:
assert!(zdt1.with().era_year(-5, Era::BCE).build().is_err());
assert!(zdt1.with().era_year(10_001, Era::BCE).build().is_err());

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

Example: overrides ZonedWith::year

Setting this option will override any previous ZonedWith::year option:

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

let zdt1 = date(2024, 7, 2).at(10, 27, 10, 123).in_tz("America/New_York")?;
let zdt2 = zdt1.with().year(2000).era_year(1900, Era::CE).build()?;
assert_eq!(
    zdt2,
    date(1900, 7, 2).at(10, 27, 10, 123).in_tz("America/New_York")?,
);

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

Similarly, ZonedWith::year will override any previous call to ZonedWith::era_year:

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

let zdt1 = date(2024, 7, 2).at(19, 0, 1, 1).in_tz("America/New_York")?;
let zdt2 = zdt1.with().era_year(1900, Era::CE).year(2000).build()?;
assert_eq!(
    zdt2,
    date(2000, 7, 2).at(19, 0, 1, 1).in_tz("America/New_York")?,
);

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

fn month(self: Self, month: i8) -> ZonedWith

Set the month field on a Zoned.

One can access this value via Zoned::month.

This overrides any previous month settings.

Errors

This returns an error when ZonedWith::build is called if the given month is outside the range 1..=12. This can also return an error if the resulting date is otherwise invalid.

Example

This shows how to create a new zoned datetime with a different month:

use jiff::civil::date;

let zdt1 = date(2005, 11, 5)
    .at(18, 3, 59, 123_456_789)
    .in_tz("America/New_York")?;
assert_eq!(zdt1.month(), 11);

let zdt2 = zdt1.with().month(6).build()?;
assert_eq!(zdt2.month(), 6);

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

Example: only changing the month can fail

For example, while 2024-10-31T00:00:00[America/New_York] is valid, 2024-11-31T00:00:00[America/New_York] is not:

use jiff::civil::date;

let zdt = date(2024, 10, 31).at(0, 0, 0, 0).in_tz("America/New_York")?;
assert!(zdt.with().month(11).build().is_err());

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

fn day(self: Self, day: i8) -> ZonedWith

Set the day field on a Zoned.

One can access this value via Zoned::day.

This overrides any previous day settings.

Errors

This returns an error when ZonedWith::build is called if the given given day is outside of allowable days for the corresponding year and month fields.

Example

This shows some examples of setting the day, including a leap day:

use jiff::civil::date;

let zdt1 = date(2024, 2, 5).at(21, 59, 1, 999).in_tz("America/New_York")?;
assert_eq!(zdt1.day(), 5);
let zdt2 = zdt1.with().day(10).build()?;
assert_eq!(zdt2.day(), 10);
let zdt3 = zdt1.with().day(29).build()?;
assert_eq!(zdt3.day(), 29);

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

Example: changing only the day can fail

This shows some examples that will fail:

use jiff::civil::date;

let zdt1 = date(2023, 2, 5)
    .at(22, 58, 58, 9_999)
    .in_tz("America/New_York")?;
// 2023 is not a leap year
assert!(zdt1.with().day(29).build().is_err());

// September has 30 days, not 31.
let zdt1 = date(2023, 9, 5).in_tz("America/New_York")?;
assert!(zdt1.with().day(31).build().is_err());

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

fn day_of_year(self: Self, day: i16) -> ZonedWith

Set the day field on a Zoned via the ordinal number of a day within a year.

When used, any settings for month are ignored since the month is determined by the day of the year.

The valid values for day are 1..=366. Note though that 366 is only valid for leap years.

This overrides any previous day settings.

Errors

This returns an error when ZonedWith::build is called if the given day is outside the allowed range of 1..=366, or when a value of 366 is given for a non-leap year.

Example

This demonstrates that if a year is a leap year, then 60 corresponds to February 29:

use jiff::civil::date;

let zdt = date(2024, 1, 1)
    .at(23, 59, 59, 999_999_999)
    .in_tz("America/New_York")?;
assert_eq!(
    zdt.with().day_of_year(60).build()?,
    date(2024, 2, 29)
        .at(23, 59, 59, 999_999_999)
        .in_tz("America/New_York")?,
);

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

But for non-leap years, day 60 is March 1:

use jiff::civil::date;

let zdt = date(2023, 1, 1)
    .at(23, 59, 59, 999_999_999)
    .in_tz("America/New_York")?;
assert_eq!(
    zdt.with().day_of_year(60).build()?,
    date(2023, 3, 1)
        .at(23, 59, 59, 999_999_999)
        .in_tz("America/New_York")?,
);

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

And using 366 for a non-leap year will result in an error, since non-leap years only have 365 days:

use jiff::civil::date;

let zdt = date(2023, 1, 1).at(0, 0, 0, 0).in_tz("America/New_York")?;
assert!(zdt.with().day_of_year(366).build().is_err());
// The maximal year is not a leap year, so it returns an error too.
let zdt = date(9999, 1, 1).at(0, 0, 0, 0).in_tz("America/New_York")?;
assert!(zdt.with().day_of_year(366).build().is_err());

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

fn day_of_year_no_leap(self: Self, day: i16) -> ZonedWith

Set the day field on a Zoned via the ordinal number of a day within a year, but ignoring leap years.

When used, any settings for month are ignored since the month is determined by the day of the year.

The valid values for day are 1..=365. The value 365 always corresponds to the last day of the year, even for leap years. It is impossible for this routine to return a zoned datetime corresponding to February 29. (Unless there is a relevant time zone transition that provokes disambiguation that shifts the datetime into February 29.)

This overrides any previous day settings.

Errors

This returns an error when ZonedWith::build is called if the given day is outside the allowed range of 1..=365.

Example

This demonstrates that 60 corresponds to March 1, regardless of whether the year is a leap year or not:

use jiff::civil::date;

let zdt = date(2023, 1, 1)
    .at(23, 59, 59, 999_999_999)
    .in_tz("America/New_York")?;
assert_eq!(
    zdt.with().day_of_year_no_leap(60).build()?,
    date(2023, 3, 1)
        .at(23, 59, 59, 999_999_999)
        .in_tz("America/New_York")?,
);

let zdt = date(2024, 1, 1)
    .at(23, 59, 59, 999_999_999)
    .in_tz("America/New_York")?;
assert_eq!(
    zdt.with().day_of_year_no_leap(60).build()?,
    date(2024, 3, 1)
        .at(23, 59, 59, 999_999_999)
        .in_tz("America/New_York")?,
);

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

And using 365 for any year will always yield the last day of the year:

use jiff::civil::date;

let zdt = date(2023, 1, 1)
    .at(23, 59, 59, 999_999_999)
    .in_tz("America/New_York")?;
assert_eq!(
    zdt.with().day_of_year_no_leap(365).build()?,
    zdt.last_of_year()?,
);

let zdt = date(2024, 1, 1)
    .at(23, 59, 59, 999_999_999)
    .in_tz("America/New_York")?;
assert_eq!(
    zdt.with().day_of_year_no_leap(365).build()?,
    zdt.last_of_year()?,
);

// Careful at the boundaries. The last day of the year isn't
// representable with all time zones. For example:
let zdt = date(9999, 1, 1)
    .at(23, 59, 59, 999_999_999)
    .in_tz("America/New_York")?;
assert!(zdt.with().day_of_year_no_leap(365).build().is_err());
// But with other time zones, it works okay:
let zdt = date(9999, 1, 1)
    .at(23, 59, 59, 999_999_999)
    .to_zoned(jiff::tz::TimeZone::fixed(jiff::tz::Offset::MAX))?;
assert_eq!(
    zdt.with().day_of_year_no_leap(365).build()?,
    zdt.last_of_year()?,
);

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

A value of 366 is out of bounds, even for leap years:

use jiff::civil::date;

let zdt = date(2024, 1, 1).at(5, 30, 0, 0).in_tz("America/New_York")?;
assert!(zdt.with().day_of_year_no_leap(366).build().is_err());

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

fn hour(self: Self, hour: i8) -> ZonedWith

Set the hour field on a Zoned.

One can access this value via Zoned::hour.

This overrides any previous hour settings.

Errors

This returns an error when ZonedWith::build is called if the given hour is outside the range 0..=23.

Example

use jiff::civil::time;

let zdt1 = time(15, 21, 59, 0).on(2010, 6, 1).in_tz("America/New_York")?;
assert_eq!(zdt1.hour(), 15);
let zdt2 = zdt1.with().hour(3).build()?;
assert_eq!(zdt2.hour(), 3);

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

fn minute(self: Self, minute: i8) -> ZonedWith

Set the minute field on a Zoned.

One can access this value via Zoned::minute.

This overrides any previous minute settings.

Errors

This returns an error when ZonedWith::build is called if the given minute is outside the range 0..=59.

Example

use jiff::civil::time;

let zdt1 = time(15, 21, 59, 0).on(2010, 6, 1).in_tz("America/New_York")?;
assert_eq!(zdt1.minute(), 21);
let zdt2 = zdt1.with().minute(3).build()?;
assert_eq!(zdt2.minute(), 3);

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

fn second(self: Self, second: i8) -> ZonedWith

Set the second field on a Zoned.

One can access this value via Zoned::second.

This overrides any previous second settings.

Errors

This returns an error when ZonedWith::build is called if the given second is outside the range 0..=59.

Example

use jiff::civil::time;

let zdt1 = time(15, 21, 59, 0).on(2010, 6, 1).in_tz("America/New_York")?;
assert_eq!(zdt1.second(), 59);
let zdt2 = zdt1.with().second(3).build()?;
assert_eq!(zdt2.second(), 3);

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

fn millisecond(self: Self, millisecond: i16) -> ZonedWith

Set the millisecond field on a Zoned.

One can access this value via Zoned::millisecond.

This overrides any previous millisecond settings.

Errors

This returns an error when ZonedWith::build is called if the given millisecond is outside the range 0..=999, or if both this and ZonedWith::subsec_nanosecond are set.

Example

This shows the relationship between Zoned::millisecond and [Zoned::subsec_nanosecond]:

use jiff::civil::time;

let zdt1 = time(15, 21, 35, 0).on(2010, 6, 1).in_tz("America/New_York")?;
let zdt2 = zdt1.with().millisecond(123).build()?;
assert_eq!(zdt2.subsec_nanosecond(), 123_000_000);

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

fn microsecond(self: Self, microsecond: i16) -> ZonedWith

Set the microsecond field on a Zoned.

One can access this value via Zoned::microsecond.

This overrides any previous microsecond settings.

Errors

This returns an error when ZonedWith::build is called if the given microsecond is outside the range 0..=999, or if both this and ZonedWith::subsec_nanosecond are set.

Example

This shows the relationship between Zoned::microsecond and [Zoned::subsec_nanosecond]:

use jiff::civil::time;

let zdt1 = time(15, 21, 35, 0).on(2010, 6, 1).in_tz("America/New_York")?;
let zdt2 = zdt1.with().microsecond(123).build()?;
assert_eq!(zdt2.subsec_nanosecond(), 123_000);

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

fn nanosecond(self: Self, nanosecond: i16) -> ZonedWith

Set the nanosecond field on a Zoned.

One can access this value via Zoned::nanosecond.

This overrides any previous nanosecond settings.

Errors

This returns an error when ZonedWith::build is called if the given nanosecond is outside the range 0..=999, or if both this and ZonedWith::subsec_nanosecond are set.

Example

This shows the relationship between Zoned::nanosecond and [Zoned::subsec_nanosecond]:

use jiff::civil::time;

let zdt1 = time(15, 21, 35, 0).on(2010, 6, 1).in_tz("America/New_York")?;
let zdt2 = zdt1.with().nanosecond(123).build()?;
assert_eq!(zdt2.subsec_nanosecond(), 123);

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

fn subsec_nanosecond(self: Self, subsec_nanosecond: i32) -> ZonedWith

Set the subsecond nanosecond field on a Zoned.

If you want to access this value on Zoned, then use Zoned::subsec_nanosecond.

This overrides any previous subsecond nanosecond settings.

Errors

This returns an error when ZonedWith::build is called if the given subsecond nanosecond is outside the range 0..=999,999,999, or if both this and one of ZonedWith::millisecond, ZonedWith::microsecond or ZonedWith::nanosecond are set.

Example

This shows the relationship between constructing a Zoned value with subsecond nanoseconds and its individual subsecond fields:

use jiff::civil::time;

let zdt1 = time(15, 21, 35, 0).on(2010, 6, 1).in_tz("America/New_York")?;
let zdt2 = zdt1.with().subsec_nanosecond(123_456_789).build()?;
assert_eq!(zdt2.millisecond(), 123);
assert_eq!(zdt2.microsecond(), 456);
assert_eq!(zdt2.nanosecond(), 789);

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

fn offset(self: Self, offset: Offset) -> ZonedWith

Set the offset to use in the new zoned datetime.

This can be used in some cases to explicitly disambiguate a datetime that could correspond to multiple instants in time.

How the offset is used to construct a new zoned datetime depends on the offset conflict resolution strategy set via ZonedWith::offset_conflict. The default is OffsetConflict::PreferOffset, which will always try to use the offset to resolve a datetime to an instant, unless the offset is incorrect for this zoned datetime's time zone. In which case, only the time zone is used to select the correct offset (which may involve using the disambiguation strategy set via ZonedWith::disambiguation).

Example

This example shows parsing the first time the 1 o'clock hour appeared on a clock in New York on 2024-11-03, and then changing only the offset to flip it to the second time 1 o'clock appeared on the clock:

use jiff::{tz, Zoned};

let zdt1: Zoned = "2024-11-03 01:30-04[America/New_York]".parse()?;
let zdt2 = zdt1.with().offset(tz::offset(-5)).build()?;
assert_eq!(
    zdt2.to_string(),
    // Everything stays the same, except for the offset.
    "2024-11-03T01:30:00-05:00[America/New_York]",
);

// If we use an invalid offset for the America/New_York time zone,
// then it will be ignored and the disambiguation strategy set will
// be used.
let zdt3 = zdt1.with().offset(tz::offset(-12)).build()?;
assert_eq!(
    zdt3.to_string(),
    // The default disambiguation is Compatible.
    "2024-11-03T01:30:00-04:00[America/New_York]",
);
// But we could change the disambiguation strategy to reject such
// cases!
let result = zdt1
    .with()
    .offset(tz::offset(-12))
    .disambiguation(tz::Disambiguation::Reject)
    .build();
assert!(result.is_err());

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

fn offset_conflict(self: Self, strategy: OffsetConflict) -> ZonedWith

Set the conflict resolution strategy for when an offset is inconsistent with the time zone.

See the documentation on OffsetConflict for more details about the different strategies one can choose.

Unlike parsing (where the default is OffsetConflict::Reject), the default for ZonedWith is OffsetConflict::PreferOffset, which avoids daylight saving time disambiguation causing unexpected 1-hour shifts after small changes to clock time.

Example

use jiff::Zoned;

// Set to the "second" time 1:30 is on the clocks in New York on
// 2024-11-03. The offset in the datetime string makes this
// unambiguous.
let zdt1 = "2024-11-03T01:30-05[America/New_York]".parse::<Zoned>()?;
// Now we change the minute field:
let zdt2 = zdt1.with().minute(34).build()?;
assert_eq!(
    zdt2.to_string(),
    // Without taking the offset of the `Zoned` value into account,
    // this would have defaulted to using the "compatible"
    // disambiguation strategy, which would have selected the earlier
    // offset of -04 instead of sticking with the later offset of -05.
    "2024-11-03T01:34:00-05:00[America/New_York]",
);

// But note that if we change the clock time such that the previous
// offset is no longer valid (by moving back before DST ended), then
// the default strategy will automatically adapt and change the offset.
let zdt2 = zdt1.with().hour(0).build()?;
assert_eq!(
    zdt2.to_string(),
    "2024-11-03T00:30:00-04:00[America/New_York]",
);

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

fn disambiguation(self: Self, strategy: Disambiguation) -> ZonedWith

Set the disambiguation strategy for when a zoned datetime falls into a time zone transition "fold" or "gap."

The most common manifestation of such time zone transitions is daylight saving time. In most cases, the transition into daylight saving time moves the civil time ("the time you see on the clock") ahead one hour. This is called a "gap" because an hour on the clock is skipped. While the transition out of daylight saving time moves the civil time back one hour. This is called a "fold" because an hour on the clock is repeated.

In the case of a gap, an ambiguous datetime manifests as a time that never appears on a clock. (For example, 02:30 on 2024-03-10 in New York.) In the case of a fold, an ambiguous datetime manifests as a time that repeats itself. (For example, 01:30 on 2024-11-03 in New York.) So when a fold occurs, you don't know whether it's the "first" occurrence of that time or the "second."

Time zone transitions are not just limited to daylight saving time, although those are the most common. In other cases, a transition occurs because of a change in the offset of the time zone itself. (See the examples below.)

Example: time zone offset change

In this example, we explore a time zone offset change in Hawaii that occurred on 1947-06-08. Namely, Hawaii went from a -10:30 offset to a -10:00 offset at 02:00. This results in a 30 minute gap in civil time.

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

// This datetime is unambiguous...
let zdt1 = "1943-06-02T02:05[Pacific/Honolulu]".parse::<Zoned>()?;
// but... 02:05 didn't exist on clocks on 1947-06-08.
let zdt2 = zdt1
    .with()
    .disambiguation(tz::Disambiguation::Later)
    .year(1947)
    .day(8)
    .build()?;
// Our parser is configured to select the later time, so we jump to
// 02:35. But if we used `Disambiguation::Earlier`, then we'd get
// 01:35.
assert_eq!(zdt2.datetime(), date(1947, 6, 8).at(2, 35, 0, 0));
assert_eq!(zdt2.offset(), tz::offset(-10));

// If we subtract 10 minutes from 02:35, notice that we (correctly)
// jump to 01:55 *and* our offset is corrected to -10:30.
let zdt3 = zdt2.checked_sub(10.minutes())?;
assert_eq!(zdt3.datetime(), date(1947, 6, 8).at(1, 55, 0, 0));
assert_eq!(zdt3.offset(), tz::offset(-10).saturating_sub(30.minutes()));

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

Example: offset conflict resolution and disambiguation

This example shows how the disambiguation configuration can interact with the default offset conflict resolution strategy of [OffsetConflict::PreferOffset]:

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

// This datetime is unambiguous.
let zdt1 = "2024-03-11T02:05[America/New_York]".parse::<Zoned>()?;
assert_eq!(zdt1.offset(), tz::offset(-4));
// But the same time on March 10 is ambiguous because there is a gap!
let zdt2 = zdt1
    .with()
    .disambiguation(tz::Disambiguation::Earlier)
    .day(10)
    .build()?;
assert_eq!(zdt2.datetime(), date(2024, 3, 10).at(1, 5, 0, 0));
assert_eq!(zdt2.offset(), tz::offset(-5));

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

Namely, while we started with an offset of -04, it (along with all other offsets) are considered invalid during civil time gaps due to time zone transitions (such as the beginning of daylight saving time in most locations).

The default disambiguation strategy is Disambiguation::Compatible, which in the case of gaps, chooses the time after the gap:

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

// This datetime is unambiguous.
let zdt1 = "2024-03-11T02:05[America/New_York]".parse::<Zoned>()?;
assert_eq!(zdt1.offset(), tz::offset(-4));
// But the same time on March 10 is ambiguous because there is a gap!
let zdt2 = zdt1
    .with()
    .day(10)
    .build()?;
assert_eq!(zdt2.datetime(), date(2024, 3, 10).at(3, 5, 0, 0));
assert_eq!(zdt2.offset(), tz::offset(-4));

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

Alternatively, one can choose to always respect the offset, and thus civil time for the provided time zone will be adjusted to match the instant prescribed by the offset. In this case, no disambiguation is performed:

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

// This datetime is unambiguous. But `2024-03-10T02:05` is!
let zdt1 = "2024-03-11T02:05[America/New_York]".parse::<Zoned>()?;
assert_eq!(zdt1.offset(), tz::offset(-4));
// But the same time on March 10 is ambiguous because there is a gap!
let zdt2 = zdt1
    .with()
    .offset_conflict(tz::OffsetConflict::AlwaysOffset)
    .day(10)
    .build()?;
// Why do we get this result? Because `2024-03-10T02:05-04` is
// `2024-03-10T06:05Z`. And in `America/New_York`, the civil time
// for that timestamp is `2024-03-10T01:05-05`.
assert_eq!(zdt2.datetime(), date(2024, 3, 10).at(1, 5, 0, 0));
assert_eq!(zdt2.offset(), tz::offset(-5));

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

impl Clone for ZonedWith

fn clone(self: &Self) -> ZonedWith

impl Debug for ZonedWith

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

impl Freeze for ZonedWith

impl RefUnwindSafe for ZonedWith

impl Send for ZonedWith

impl Sync for ZonedWith

impl Unpin for ZonedWith

impl UnsafeUnpin for ZonedWith

impl UnwindSafe for ZonedWith

impl<T> Any for ZonedWith

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for ZonedWith

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for ZonedWith

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for ZonedWith

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for ZonedWith

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for ZonedWith

fn to_owned(self: &Self) -> T

fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for ZonedWith

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for ZonedWith

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for ZonedWith

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>