impl DateTimeWith

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

impl Clone for DateTimeWith

fn clone(self: &Self) -> DateTimeWith

impl Copy for DateTimeWith

impl Debug for DateTimeWith

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

impl Freeze for DateTimeWith

impl RefUnwindSafe for DateTimeWith

impl Send for DateTimeWith

impl Sync for DateTimeWith

impl Unpin for DateTimeWith

impl UnsafeUnpin for DateTimeWith

impl UnwindSafe for DateTimeWith

impl<T> Any for DateTimeWith

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for DateTimeWith

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

impl<T> BorrowMut for DateTimeWith

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

impl<T> CloneToUninit for DateTimeWith

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

impl<T> From for DateTimeWith

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for DateTimeWith

fn to_owned(self: &Self) -> T

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

impl<T, U> Into for DateTimeWith

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 DateTimeWith

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

impl<T, U> TryInto for DateTimeWith

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