impl Date

const MIN: Date = _;

The minimum allowed Gregorian date.

This is guaranteed to be equivalent to UnixEpochDay::MIN when converted to a Unix epoch day.

const MAX: Date = _;

The maximum allowed Gregorian date.

This is guaranteed to be equivalent to UnixEpochDay::MAX when converted to a Unix epoch day.

const fn new(year: i16, month: i8, day: i8) -> Result<Date, RangeError>

Creates a new date in the Gregorian calendar.

If the date is invalid or any of the values are out of their supported ranges, then an error is returned.

Note that, technically, the date returned is in the ISO 8601 proleptic calendar. The only difference between it and the Gregorian calendar is that ISO 8601 has a year 0. ISO 8601's year 0 corresponds to -1 BCE in the Gregorian calendar.

const fn new_constrain(year: i16, month: i8, day: i8) -> Result<Date, RangeError>

Like Date::new, but constrains the day value to the last day of month.

This still returns an error when day < 1 or when year or month are invalid.

const fn from_day_of_year(year: i16, day: i16) -> Result<Date, RangeError>

Returns the date corresponding to the day of the given year. The day of the year should be a value in 1..=366, with 366 only being valid if year is a leap year.

Returns an error if year is not in the range specified by Year, or if day is invalid for the given year.

const fn from_day_of_year_no_leap(year: i16, day: i16) -> Result<Date, RangeError>

Returns the date corresponding to the day of the given year. The day of the year must be a value in 1..=365, with February 29 being completely ignored. That is, it is guaranteed that February 29 will never be returned by this function. It is impossible.

Returns an error if year is not in the range specified by Year, or if day is outside the range 1..=365.

const fn year(self) -> i16

Returns the year component of this date.

The value returned is guaranteed to be in the range specified by Year.

const fn month(self) -> i8

Returns the month component of this date.

The value returned is guaranteed to be in the range 1..=12.

const fn day(self) -> i8

Returns the day component of this date.

The value returned is guaranteed to be in the range 1..=jiff_core::civil::days_in_month(date.year(), date.month()).

const fn weekday(self) -> Weekday

Returns the weekday corresponding to this date.

const fn day_of_year(self) -> i16

Returns the ordinal day of the year that this date resides in.

For leap years, this always returns a value in the range 1..=366. Otherwise, the value is in the range 1..=365.

const fn day_of_year_no_leap(self) -> Option<i16>

Returns the ordinal day of the year that this date resides in, but ignores leap years.

That is, the range of possible values returned by this routine is 1..=365, even if this date resides in a leap year. If this date is February 29, then this routine returns None.

The value 365 always corresponds to the last day in the year, December 31, even for leap years.

const fn first_of_month(self) -> Date

Returns the first date of the month for this date.

const fn last_of_month(self) -> Date

Returns the last date of the month for this date.

const fn days_in_month(self) -> i8

Returns the total number of days in the the month in which this date resides.

This is guaranteed to always return one of the following values, depending on the year and the month: 28, 29, 30 or 31.

const fn first_of_year(self) -> Date

Returns the first date of the year that this date resides in.

const fn last_of_year(self) -> Date

Returns the last date of the year that this date resides in.

const fn days_in_year(self) -> i16

Returns the number of days in the year for this date.

It is guaranteed that the value returned is either 365 or 366.

const fn in_leap_year(self) -> bool

Returns true when this date is in a leap year.

const fn yesterday(self) -> Result<Date, RangeError>

Returns the day before this date.

Returns an error when this is the minimal date.

const fn tomorrow(self) -> Result<Date, RangeError>

Returns the day after this date.

Returns an error when this is the maximal date.

const fn nth_weekday_of_month(&self, nth: i8, weekday: Weekday) -> Result<Date, RangeError>

Returns the nth weekday of the month represented by this date.

nth must be non-zero and otherwise in the range -5..=5. If it isn't, an error is returned.

This also returns an error if abs(nth)==5 and there is no "5th" weekday of this month.

const fn nth_weekday(self, nth: i32, weekday: Weekday) -> Result<Date, RangeError>

Returns the "nth" weekday from this date, not including itself.

The nth parameter can be positive or negative. A positive value computes the "nth" weekday starting at the day after this date and going forwards in time. A negative value computes the "nth" weekday starting at the day before this date and going backwards in time.

For example, if this date's weekday is a Sunday and the first Sunday is asked for (that is, date.nth_weekday(1, Weekday::Sunday)), then the result is a week from this date corresponding to the following Sunday.

const fn checked_add(self, days: i32) -> Result<Date, RangeError>

Adds the given number of days to this date.

Returns an error if the result is outside the valid range of a Date.

const fn checked_sub(self, days: i32) -> Result<Date, RangeError>

Subtracts the given number of days to this date.

Returns an error if the result is outside the valid range of a Date.

const fn until(self, other: Date) -> i32

Returns the number of days from this date until other.

This routine never overflows because of the enforced range on Date values.

Example

use jiff_core::civil::date;

let date1 = date(2023, 7, 1);
let date2 = date(2024, 7, 1);
assert_eq!(366, date1.until(date2));

// The value will be negative when the dates are flipped:
assert_eq!(-366, date2.until(date1));

Example: overflow isn't possible

Even when using the minimum or maximum values:

use jiff_core::civil::Date;

assert_eq!(7_304_483, Date::MIN.until(Date::MAX));
assert_eq!(-7_304_483, Date::MAX.until(Date::MIN));

const fn since(self, other: Date) -> i32

Returns the number of days from this date since other.

This routine never overflows because of the enforced range on Date values.

Example

use jiff_core::civil::date;

let date1 = date(2023, 7, 1);
let date2 = date(2024, 7, 1);
assert_eq!(366, date2.since(date1));

// The value will be negative when the dates are flipped:
assert_eq!(-366, date1.since(date2));

Example: overflow isn't possible

Even when using the minimum or maximum values:

use jiff_core::civil::Date;

assert_eq!(7_304_483, Date::MAX.since(Date::MIN));

const fn to_unix_epoch_day(self) -> UnixEpochDay

Converts a Gregorian date to a Unix epoch day.

const fn to_iso_week_date(self) -> ISOWeekDate

Converts this Gregorian date to an ISO 8601 week date.

const fn at(self, hour: i8, minute: i8, second: i8, subsec_nanosecond: i32) -> DateTime

A convenience function for constructing a DateTime from this date at the time given by its components.

Panics

This panics if the provided values do not correspond to a valid Time. All of the following conditions must be true:

• 0 <= hour <= 23
• 0 <= minute <= 59
• 0 <= second <= 59
• 0 <= subsec_nanosecond <= 999,999,999

Similarly, when used in a const context, invalid parameters will prevent your Rust program from compiling.