Struct ZonedWith
pub struct ZonedWith { /* private fields */ }
dep_jiff
and alloc
only.Expand description
A builder for setting the fields on a Zoned
.
This builder is constructed via Zoned::with
.
§Example
The builder ensures one can chain together the individual components of a
zoned datetime without it failing at an intermediate step. For example,
if you had a date of 2024-10-31T00:00:00[America/New_York]
and wanted
to change both the day and the month, and each setting was validated
independent of the other, you would need to be careful to set the day first
and then the month. In some cases, you would need to set the month first
and then the day!
But with the builder, you can set values in any order:
use jiff::civil::date;
let zdt1 = date(2024, 10, 31).at(0, 0, 0, 0).intz("America/New_York")?;
let zdt2 = zdt1.with().month(11).day(30).build()?;
assert_eq!(
zdt2,
date(2024, 11, 30).at(0, 0, 0, 0).intz("America/New_York")?,
);
let zdt1 = date(2024, 4, 30).at(0, 0, 0, 0).intz("America/New_York")?;
let zdt2 = zdt1.with().day(31).month(7).build()?;
assert_eq!(
zdt2,
date(2024, 7, 31).at(0, 0, 0, 0).intz("America/New_York")?,
);
Implementations§
§impl ZonedWith
impl ZonedWith
pub fn build(self) -> Result<Zoned, Error> ⓘ
pub fn build(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).intz("America/New_York")?;
assert_eq!(
zdt.with().day_of_year_no_leap(365).build()?,
date(2023, 12, 31).at(12, 0, 0, 0).intz("America/New_York")?,
);
// It also works with leap years for the same input:
let zdt = date(2024, 1, 1).at(12, 0, 0, 0).intz("America/New_York")?;
assert_eq!(
zdt.with().day_of_year_no_leap(365).build()?,
date(2024, 12, 31).at(12, 0, 0, 0).intz("America/New_York")?,
);
§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).intz("America/New_York")?;
assert!(zdt.with().day(31).build().is_err());
let zdt = date(2024, 2, 29).at(15, 30, 0, 0).intz("America/New_York")?;
assert!(zdt.with().year(2023).build().is_err());
pub fn date(self, date: Date) -> ZonedWith
pub fn date(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).intz("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).intz("America/New_York")?,
);
pub fn time(self, time: Time) -> ZonedWith
pub fn time(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).intz("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)
.intz("America/New_York")?,
);
pub fn year(self, year: i16) -> ZonedWith
pub fn year(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).intz("America/New_York")?;
assert_eq!(zdt1.year(), 2005);
let zdt2 = zdt1.with().year(2007).build()?;
assert_eq!(zdt2.year(), 2007);
§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).intz("America/New_York")?;
assert!(zdt.with().year(2023).build().is_err());
pub fn era_year(self, year: i16, era: Era) -> ZonedWith
pub fn era_year(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).intz("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());
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).intz("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());
§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).intz("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).intz("America/New_York")?,
);
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).intz("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).intz("America/New_York")?,
);
pub fn month(self, month: i8) -> ZonedWith
pub fn month(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)
.intz("America/New_York")?;
assert_eq!(zdt1.month(), 11);
let zdt2 = zdt1.with().month(6).build()?;
assert_eq!(zdt2.month(), 6);
§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).intz("America/New_York")?;
assert!(zdt.with().month(11).build().is_err());
pub fn day(self, day: i8) -> ZonedWith
pub fn day(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).intz("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);
§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)
.intz("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).intz("America/New_York")?;
assert!(zdt1.with().day(31).build().is_err());
pub fn day_of_year(self, day: i16) -> ZonedWith
pub fn day_of_year(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)
.intz("America/New_York")?;
assert_eq!(
zdt.with().day_of_year(60).build()?,
date(2024, 2, 29)
.at(23, 59, 59, 999_999_999)
.intz("America/New_York")?,
);
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)
.intz("America/New_York")?;
assert_eq!(
zdt.with().day_of_year(60).build()?,
date(2023, 3, 1)
.at(23, 59, 59, 999_999_999)
.intz("America/New_York")?,
);
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).intz("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).intz("America/New_York")?;
assert!(zdt.with().day_of_year(366).build().is_err());
pub fn day_of_year_no_leap(self, day: i16) -> ZonedWith
pub fn day_of_year_no_leap(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)
.intz("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)
.intz("America/New_York")?,
);
let zdt = date(2024, 1, 1)
.at(23, 59, 59, 999_999_999)
.intz("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)
.intz("America/New_York")?,
);
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)
.intz("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)
.intz("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)
.intz("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()?,
);
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).intz("America/New_York")?;
assert!(zdt.with().day_of_year_no_leap(366).build().is_err());
pub fn hour(self, hour: i8) -> ZonedWith
pub fn hour(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).intz("America/New_York")?;
assert_eq!(zdt1.hour(), 15);
let zdt2 = zdt1.with().hour(3).build()?;
assert_eq!(zdt2.hour(), 3);
pub fn minute(self, minute: i8) -> ZonedWith
pub fn minute(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).intz("America/New_York")?;
assert_eq!(zdt1.minute(), 21);
let zdt2 = zdt1.with().minute(3).build()?;
assert_eq!(zdt2.minute(), 3);
pub fn second(self, second: i8) -> ZonedWith
pub fn second(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).intz("America/New_York")?;
assert_eq!(zdt1.second(), 59);
let zdt2 = zdt1.with().second(3).build()?;
assert_eq!(zdt2.second(), 3);
pub fn millisecond(self, millisecond: i16) -> ZonedWith
pub fn millisecond(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).intz("America/New_York")?;
let zdt2 = zdt1.with().millisecond(123).build()?;
assert_eq!(zdt2.subsec_nanosecond(), 123_000_000);
pub fn microsecond(self, microsecond: i16) -> ZonedWith
pub fn microsecond(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).intz("America/New_York")?;
let zdt2 = zdt1.with().microsecond(123).build()?;
assert_eq!(zdt2.subsec_nanosecond(), 123_000);
pub fn nanosecond(self, nanosecond: i16) -> ZonedWith
pub fn nanosecond(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).intz("America/New_York")?;
let zdt2 = zdt1.with().nanosecond(123).build()?;
assert_eq!(zdt2.subsec_nanosecond(), 123);
pub fn subsec_nanosecond(self, subsec_nanosecond: i32) -> ZonedWith
pub fn subsec_nanosecond(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).intz("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);
pub fn offset(self, offset: Offset) -> ZonedWith
pub fn offset(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());
pub fn offset_conflict(self, strategy: OffsetConflict) -> ZonedWith
pub fn offset_conflict(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::{civil::date, tz, 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]",
);
pub fn disambiguation(self, strategy: Disambiguation) -> ZonedWith
pub fn disambiguation(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
This example shows how to set the disambiguation configuration while
creating a Zoned
datetime. In this example, we always prefer the
earlier time.
use jiff::{civil::date, tz, Zoned};
// This datetime is unambiguous.
let zdt1 = "2024-03-11T02:05[America/New_York]".parse::<Zoned>()?;
// 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));
§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()));
Trait Implementations§
Auto Trait Implementations§
impl Freeze for ZonedWith
impl RefUnwindSafe for ZonedWith
impl Send for ZonedWith
impl Sync for ZonedWith
impl Unpin for ZonedWith
impl UnwindSafe for ZonedWith
Blanket Implementations§
§impl<T> ArchivePointee for T
impl<T> ArchivePointee for T
§type ArchivedMetadata = ()
type ArchivedMetadata = ()
§fn pointer_metadata(
_: &<T as ArchivePointee>::ArchivedMetadata,
) -> <T as Pointee>::Metadata
fn pointer_metadata( _: &<T as ArchivePointee>::ArchivedMetadata, ) -> <T as Pointee>::Metadata
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> ByteSized for T
impl<T> ByteSized for T
Source§const BYTE_ALIGN: usize = _
const BYTE_ALIGN: usize = _
Source§fn byte_align(&self) -> usize ⓘ
fn byte_align(&self) -> usize ⓘ
Source§fn ptr_size_ratio(&self) -> [usize; 2]
fn ptr_size_ratio(&self) -> [usize; 2]
Source§impl<T, R> Chain<R> for Twhere
T: ?Sized,
impl<T, R> Chain<R> for Twhere
T: ?Sized,
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> ExtAny for T
impl<T> ExtAny for T
Source§fn as_any_mut(&mut self) -> &mut dyn Anywhere
Self: Sized,
fn as_any_mut(&mut self) -> &mut dyn Anywhere
Self: Sized,
Source§impl<T> ExtMem for Twhere
T: ?Sized,
impl<T> ExtMem for Twhere
T: ?Sized,
Source§const NEEDS_DROP: bool = _
const NEEDS_DROP: bool = _
Source§fn mem_align_of_val(&self) -> usize ⓘ
fn mem_align_of_val(&self) -> usize ⓘ
Source§fn mem_size_of_val(&self) -> usize ⓘ
fn mem_size_of_val(&self) -> usize ⓘ
Source§fn mem_needs_drop(&self) -> bool
fn mem_needs_drop(&self) -> bool
true
if dropping values of this type matters. Read moreSource§fn mem_forget(self)where
Self: Sized,
fn mem_forget(self)where
Self: Sized,
self
without running its destructor. Read moreSource§fn mem_replace(&mut self, other: Self) -> Selfwhere
Self: Sized,
fn mem_replace(&mut self, other: Self) -> Selfwhere
Self: Sized,
Source§unsafe fn mem_zeroed<T>() -> T
unsafe fn mem_zeroed<T>() -> T
unsafe_layout
only.T
represented by the all-zero byte-pattern. Read moreSource§unsafe fn mem_transmute_copy<Src, Dst>(src: &Src) -> Dst
unsafe fn mem_transmute_copy<Src, Dst>(src: &Src) -> Dst
unsafe_layout
only.T
represented by the all-zero byte-pattern. Read moreSource§fn mem_as_bytes(&self) -> &[u8] ⓘ
fn mem_as_bytes(&self) -> &[u8] ⓘ
unsafe_slice
only.§impl<S> FromSample<S> for S
impl<S> FromSample<S> for S
fn from_sample_(s: S) -> S
Source§impl<T> Hook for T
impl<T> Hook for T
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more§impl<F, T> IntoSample<T> for Fwhere
T: FromSample<F>,
impl<F, T> IntoSample<T> for Fwhere
T: FromSample<F>,
fn into_sample(self) -> T
§impl<T> LayoutRaw for T
impl<T> LayoutRaw for T
§fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError> ⓘ
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError> ⓘ
§impl<T, N1, N2> Niching<NichedOption<T, N1>> for N2
impl<T, N1, N2> Niching<NichedOption<T, N1>> for N2
§unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
§fn resolve_niched(out: Place<NichedOption<T, N1>>)
fn resolve_niched(out: Place<NichedOption<T, N1>>)
out
indicating that a T
is niched.