Struct DateWith

pub struct DateWith { /* private fields */ }

A builder for setting the fields on a Date.

This builder is constructed via Date::with.

Example

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

let d1 = date(2024, 4, 30);
let d2 = d1.with().day(31).month(7).build()?;
assert_eq!(d2, date(2024, 7, 31));

Implementations

impl DateWith

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

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

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

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

Example

This creates a date corresponding to the last day in the year:

use jiff::civil::date;

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

Example: error for invalid date

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

use jiff::civil::date;

let d = date(2024, 11, 30);
assert!(d.with().day(31).build().is_err());

let d = date(2024, 2, 29);
assert!(d.with().year(2023).build().is_err());

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

Set the year field on a Date.

One can access this value via Date::year.

This overrides any previous year settings.

Errors

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

use jiff::civil::date;

let d1 = date(2005, 11, 5);
assert_eq!(d1.year(), 2005);
let d2 = d1.with().year(2007).build()?;
assert_eq!(d2.year(), 2007);

Example: only changing the year can fail

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

use jiff::civil::date;

let d1 = date(2024, 2, 29);
assert!(d1.with().year(2023).build().is_err());

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

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

One can access this value via Date::era_year.

Errors

This returns an error when DateWith::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 d1 = date(2005, 11, 5);
assert_eq!(d1.year(), 2005);
let d2 = d1.with().era_year(2007, Era::CE).build()?;
assert_eq!(d2.year(), 2007);

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

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

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

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

Example: overrides DateWith::year

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

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

let d1 = date(2024, 7, 2);
let d2 = d1.with().year(2000).era_year(1900, Era::CE).build()?;
assert_eq!(d2, date(1900, 7, 2));

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

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

let d1 = date(2024, 7, 2);
let d2 = d1.with().era_year(1900, Era::CE).year(2000).build()?;
assert_eq!(d2, date(2000, 7, 2));

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

Set the month field on a Date.

One can access this value via Date::month.

This overrides any previous month settings.

Errors

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

use jiff::civil::date;

let d1 = date(2005, 11, 5);
assert_eq!(d1.month(), 11);
let d2 = d1.with().month(6).build()?;
assert_eq!(d2.month(), 6);

Example: only changing the month can fail

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

use jiff::civil::date;

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

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

Set the day field on a Date.

One can access this value via Date::day.

This overrides any previous day settings.

Errors

This returns an error when DateWith::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 d1 = date(2024, 2, 5);
assert_eq!(d1.day(), 5);
let d2 = d1.with().day(10).build()?;
assert_eq!(d2.day(), 10);
let d3 = d1.with().day(29).build()?;
assert_eq!(d3.day(), 29);

Example: changing only the day can fail

This shows some examples that will fail:

use jiff::civil::date;

let d1 = date(2023, 2, 5);
// 2023 is not a leap year
assert!(d1.with().day(29).build().is_err());

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

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

Set the day field on a Date 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 DateWith::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 d = date(2024, 1, 1);
assert_eq!(d.with().day_of_year(60).build()?, date(2024, 2, 29));

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

use jiff::civil::date;

let d = date(2023, 1, 1);
assert_eq!(d.with().day_of_year(60).build()?, date(2023, 3, 1));

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

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

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

This overrides any previous day settings.

Errors

This returns an error when DateWith::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;

assert_eq!(
    date(2023, 1, 1).with().day_of_year_no_leap(60).build()?,
    date(2023, 3, 1),
);

assert_eq!(
    date(2024, 1, 1).with().day_of_year_no_leap(60).build()?,
    date(2024, 3, 1),
);

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

use jiff::civil::date;

let d = date(2023, 1, 1);
assert_eq!(
    d.with().day_of_year_no_leap(365).build()?,
    d.last_of_year(),
);

let d = date(2024, 1, 1);
assert_eq!(
    d.with().day_of_year_no_leap(365).build()?,
    d.last_of_year(),
);

let d = date(9999, 1, 1);
assert_eq!(
    d.with().day_of_year_no_leap(365).build()?,
    d.last_of_year(),
);

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

use jiff::civil::date;

let d = date(2024, 1, 1);
assert!(d.with().day_of_year_no_leap(366).build().is_err());

Trait Implementations

impl Clone for DateWith

fn clone(&self) -> DateWith

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for DateWith

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

Formats the value using the given formatter.

impl Copy for DateWith