Struct DateTimeWith

pub struct DateTimeWith { /* private fields */ }

Available on crate features dep_jiff and alloc only.

A builder for setting the fields on a DateTime.

This builder is constructed via DateTime::with.

Example

The builder ensures one can chain together the individual components of a datetime without it failing at an intermediate step. For example, if you had a date of 2024-10-31T00:00:00 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 dt1 = date(2024, 10, 31).at(0, 0, 0, 0);
let dt2 = dt1.with().month(11).day(30).build()?;
assert_eq!(dt2, date(2024, 11, 30).at(0, 0, 0, 0));

let dt1 = date(2024, 4, 30).at(0, 0, 0, 0);
let dt2 = dt1.with().day(31).month(7).build()?;
assert_eq!(dt2, date(2024, 7, 31).at(0, 0, 0, 0));

Implementations

impl DateTimeWith

pub fn build(self) -> Result<DateTime, Error>

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

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

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

Example

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

use jiff::civil::date;

let dt = date(2023, 1, 1).at(12, 0, 0, 0);
assert_eq!(
    dt.with().day_of_year_no_leap(365).build()?,
    date(2023, 12, 31).at(12, 0, 0, 0),
);

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

Example: error for invalid datetime

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

use jiff::civil::date;

let dt = date(2024, 11, 30).at(15, 30, 0, 0);
assert!(dt.with().day(31).build().is_err());

let dt = date(2024, 2, 29).at(15, 30, 0, 0);
assert!(dt.with().year(2023).build().is_err());

pub fn date(self, date: Date) -> DateTimeWith

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 datetime with a different date:

use jiff::civil::date;

let dt1 = date(2005, 11, 5).at(15, 30, 0, 0);
let dt2 = dt1.with().date(date(2017, 10, 31)).build()?;
// The date changes but the time remains the same.
assert_eq!(dt2, date(2017, 10, 31).at(15, 30, 0, 0));

pub fn time(self, time: Time) -> DateTimeWith

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 datetime with a different time:

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

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

pub fn year(self, year: i16) -> DateTimeWith

Set the year field on a DateTime.

One can access this value via DateTime::year.

This overrides any previous year settings.

Errors

This returns an error when DateTimeWith::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 datetime with a different year:

use jiff::civil::date;

let dt1 = date(2005, 11, 5).at(15, 30, 0, 0);
assert_eq!(dt1.year(), 2005);
let dt2 = dt1.with().year(2007).build()?;
assert_eq!(dt2.year(), 2007);

Example: only changing the year can fail

For example, while 2024-02-29T01:30:00 is valid, 2023-02-29T01:30:00 is not:

use jiff::civil::date;

let dt = date(2024, 2, 29).at(1, 30, 0, 0);
assert!(dt.with().year(2023).build().is_err());

pub fn era_year(self, year: i16, era: Era) -> DateTimeWith

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

One can access this value via DateTime::era_year.

Errors

This returns an error when DateTimeWith::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 dt1 = date(2005, 11, 5).at(8, 0, 0, 0);
assert_eq!(dt1.year(), 2005);
let dt2 = dt1.with().era_year(2007, Era::CE).build()?;
assert_eq!(dt2.year(), 2007);

// CE years are always positive and can be at most 9999:
assert!(dt1.with().era_year(-5, Era::CE).build().is_err());
assert!(dt1.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 dt1 = date(-27, 7, 1).at(8, 22, 30, 0);
assert_eq!(dt1.year(), -27);
assert_eq!(dt1.era_year(), (28, Era::BCE));

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

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

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

Example: overrides DateTimeWith::year

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

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

let dt1 = date(2024, 7, 2).at(10, 27, 10, 123);
let dt2 = dt1.with().year(2000).era_year(1900, Era::CE).build()?;
assert_eq!(dt2, date(1900, 7, 2).at(10, 27, 10, 123));

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

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

let dt1 = date(2024, 7, 2).at(19, 0, 1, 1);
let dt2 = dt1.with().era_year(1900, Era::CE).year(2000).build()?;
assert_eq!(dt2, date(2000, 7, 2).at(19, 0, 1, 1));

pub fn month(self, month: i8) -> DateTimeWith

Set the month field on a DateTime.

One can access this value via DateTime::month.

This overrides any previous month settings.

Errors

This returns an error when DateTimeWith::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 datetime with a different month:

use jiff::civil::date;

let dt1 = date(2005, 11, 5).at(18, 3, 59, 123_456_789);
assert_eq!(dt1.month(), 11);
let dt2 = dt1.with().month(6).build()?;
assert_eq!(dt2.month(), 6);

Example: only changing the month can fail

For example, while 2024-10-31T00:00:00 is valid, 2024-11-31T00:00:00 is not:

use jiff::civil::date;

let dt = date(2024, 10, 31).at(0, 0, 0, 0);
assert!(dt.with().month(11).build().is_err());

pub fn day(self, day: i8) -> DateTimeWith

Set the day field on a DateTime.

One can access this value via DateTime::day.

This overrides any previous day settings.

Errors

This returns an error when DateTimeWith::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 dt1 = date(2024, 2, 5).at(21, 59, 1, 999);
assert_eq!(dt1.day(), 5);
let dt2 = dt1.with().day(10).build()?;
assert_eq!(dt2.day(), 10);
let dt3 = dt1.with().day(29).build()?;
assert_eq!(dt3.day(), 29);

Example: changing only the day can fail

This shows some examples that will fail:

use jiff::civil::date;

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

// September has 30 days, not 31.
let dt1 = date(2023, 9, 5).at(22, 58, 58, 9_999);
assert!(dt1.with().day(31).build().is_err());

pub fn day_of_year(self, day: i16) -> DateTimeWith

Set the day field on a DateTime 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 DateTimeWith::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 dt = date(2024, 1, 1).at(23, 59, 59, 999_999_999);
assert_eq!(
    dt.with().day_of_year(60).build()?,
    date(2024, 2, 29).at(23, 59, 59, 999_999_999),
);

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

use jiff::civil::date;

let dt = date(2023, 1, 1).at(23, 59, 59, 999_999_999);
assert_eq!(
    dt.with().day_of_year(60).build()?,
    date(2023, 3, 1).at(23, 59, 59, 999_999_999),
);

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 dt = date(2023, 1, 1).at(0, 0, 0, 0);
assert!(dt.with().day_of_year(366).build().is_err());
// The maximal year is not a leap year, so it returns an error too.
let dt = date(9999, 1, 1).at(0, 0, 0, 0);
assert!(dt.with().day_of_year(366).build().is_err());

pub fn day_of_year_no_leap(self, day: i16) -> DateTimeWith

Set the day field on a DateTime 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 datetime corresponding to February 29.

This overrides any previous day settings.

Errors

This returns an error when DateTimeWith::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 dt = date(2023, 1, 1).at(23, 59, 59, 999_999_999);
assert_eq!(
    dt.with().day_of_year_no_leap(60).build()?,
    date(2023, 3, 1).at(23, 59, 59, 999_999_999),
);

let dt = date(2024, 1, 1).at(23, 59, 59, 999_999_999);
assert_eq!(
    dt.with().day_of_year_no_leap(60).build()?,
    date(2024, 3, 1).at(23, 59, 59, 999_999_999),
);

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

use jiff::civil::date;

let dt = date(2023, 1, 1).at(23, 59, 59, 999_999_999);
assert_eq!(
    dt.with().day_of_year_no_leap(365).build()?,
    dt.last_of_year(),
);

let dt = date(2024, 1, 1).at(23, 59, 59, 999_999_999);
assert_eq!(
    dt.with().day_of_year_no_leap(365).build()?,
    dt.last_of_year(),
);

let dt = date(9999, 1, 1).at(23, 59, 59, 999_999_999);
assert_eq!(
    dt.with().day_of_year_no_leap(365).build()?,
    dt.last_of_year(),
);

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

use jiff::civil::date;

let dt = date(2024, 1, 1).at(5, 30, 0, 0);
assert!(dt.with().day_of_year_no_leap(366).build().is_err());

pub fn hour(self, hour: i8) -> DateTimeWith

Set the hour field on a DateTime.

One can access this value via DateTime::hour.

This overrides any previous hour settings.

Errors

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

Example

use jiff::civil::time;

let dt1 = time(15, 21, 59, 0).on(2010, 6, 1);
assert_eq!(dt1.hour(), 15);
let dt2 = dt1.with().hour(3).build()?;
assert_eq!(dt2.hour(), 3);

pub fn minute(self, minute: i8) -> DateTimeWith

Set the minute field on a DateTime.

One can access this value via DateTime::minute.

This overrides any previous minute settings.

Errors

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

Example

use jiff::civil::time;

let dt1 = time(15, 21, 59, 0).on(2010, 6, 1);
assert_eq!(dt1.minute(), 21);
let dt2 = dt1.with().minute(3).build()?;
assert_eq!(dt2.minute(), 3);

pub fn second(self, second: i8) -> DateTimeWith

Set the second field on a DateTime.

One can access this value via DateTime::second.

This overrides any previous second settings.

Errors

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

Example

use jiff::civil::time;

let dt1 = time(15, 21, 59, 0).on(2010, 6, 1);
assert_eq!(dt1.second(), 59);
let dt2 = dt1.with().second(3).build()?;
assert_eq!(dt2.second(), 3);

pub fn millisecond(self, millisecond: i16) -> DateTimeWith

Set the millisecond field on a DateTime.

One can access this value via DateTime::millisecond.

This overrides any previous millisecond settings.

Errors

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

Example

This shows the relationship between DateTime::millisecond and DateTime::subsec_nanosecond:

use jiff::civil::time;

let dt1 = time(15, 21, 35, 0).on(2010, 6, 1);
let dt2 = dt1.with().millisecond(123).build()?;
assert_eq!(dt2.subsec_nanosecond(), 123_000_000);

pub fn microsecond(self, microsecond: i16) -> DateTimeWith

Set the microsecond field on a DateTime.

One can access this value via DateTime::microsecond.

This overrides any previous microsecond settings.

Errors

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

Example

This shows the relationship between DateTime::microsecond and DateTime::subsec_nanosecond:

use jiff::civil::time;

let dt1 = time(15, 21, 35, 0).on(2010, 6, 1);
let dt2 = dt1.with().microsecond(123).build()?;
assert_eq!(dt2.subsec_nanosecond(), 123_000);

pub fn nanosecond(self, nanosecond: i16) -> DateTimeWith

Set the nanosecond field on a DateTime.

One can access this value via DateTime::nanosecond.

This overrides any previous nanosecond settings.

Errors

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

Example

This shows the relationship between DateTime::nanosecond and DateTime::subsec_nanosecond:

use jiff::civil::time;

let dt1 = time(15, 21, 35, 0).on(2010, 6, 1);
let dt2 = dt1.with().nanosecond(123).build()?;
assert_eq!(dt2.subsec_nanosecond(), 123);

pub fn subsec_nanosecond(self, subsec_nanosecond: i32) -> DateTimeWith

Set the subsecond nanosecond field on a DateTime.

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

This overrides any previous subsecond nanosecond settings.

Errors

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

Example

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

use jiff::civil::time;

let dt1 = time(15, 21, 35, 0).on(2010, 6, 1);
let dt2 = dt1.with().subsec_nanosecond(123_456_789).build()?;
assert_eq!(dt2.millisecond(), 123);
assert_eq!(dt2.microsecond(), 456);
assert_eq!(dt2.nanosecond(), 789);

Trait Implementations

impl Clone for DateTimeWith

fn clone(&self) -> DateTimeWith

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for DateTimeWith

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

Formats the value using the given formatter.

impl Copy for DateTimeWith