impl DateWith

fn build(self: 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),
);

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

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

fn year(self: 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);

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

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

fn era_year(self: 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());

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

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

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

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

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

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

fn month(self: 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);

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

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

fn day(self: 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);

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

fn day_of_year(self: 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));

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

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

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

fn day_of_year_no_leap(self: 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),
);

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

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

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

impl Clone for DateWith

fn clone(self: &Self) -> DateWith

impl Copy for DateWith

impl Debug for DateWith

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

impl Freeze for DateWith

impl RefUnwindSafe for DateWith

impl Send for DateWith

impl Sync for DateWith

impl Unpin for DateWith

impl UnsafeUnpin for DateWith

impl UnwindSafe for DateWith

impl<T> Any for DateWith

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for DateWith

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

impl<T> BorrowMut for DateWith

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

impl<T> CloneToUninit for DateWith

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

impl<T> From for DateWith

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for DateWith

fn to_owned(self: &Self) -> T

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

impl<T, U> Into for DateWith

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 DateWith

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

impl<T, U> TryInto for DateWith

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