Struct Date 

pub struct Date { /* private fields */ }

A Gregorian civil date.

A Gregorian civil date can be infallibly converted to and from UnixEpochDay values.

Note that since this supports a year 0, this technically implements the ISO 8601 proleptic calendar and not the Gregorian calendar. Notably, the Gregorian calendar does not have a year 0. Therefore, a Date with a year 0 is equivalent to the Gregorian 1 BCE year.

Implementations

impl Date

pub const MIN: Date

The minimum allowed Gregorian date.

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

pub const MAX: Date

The maximum allowed Gregorian date.

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

pub 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.

pub 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.

pub 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.

pub 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.

pub 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.

pub const fn month(self) -> i8

Returns the month component of this date.

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

pub 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()).

pub const fn weekday(self) -> Weekday

Returns the weekday corresponding to this date.

pub 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.

pub 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.

pub const fn first_of_month(self) -> Date

Returns the first date of the month for this date.

pub const fn last_of_month(self) -> Date

Returns the last date of the month for this date.

pub 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.

pub const fn first_of_year(self) -> Date

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

pub const fn last_of_year(self) -> Date

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

pub 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.

pub const fn in_leap_year(self) -> bool

Returns true when this date is in a leap year.

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

Returns the day before this date.

Returns an error when this is the minimal date.

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

Returns the day after this date.

Returns an error when this is the maximal date.

pub 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.

pub 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.

pub 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.

pub 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.

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

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

pub const fn to_unix_epoch_day(self) -> UnixEpochDay

Converts a Gregorian date to a Unix epoch day.

pub const fn to_iso_week_date(self) -> ISOWeekDate

Converts this Gregorian date to an ISO 8601 week date.

pub 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.

Trait Implementations

impl Clone for Date

fn clone(&self) -> Date

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Date

impl Debug for Date

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

Formats the value using the given formatter.

impl Eq for Date

impl Format for Date

fn format(&self, f: Formatter<'_>)

Writes the defmt representation of self to fmt.

impl Hash for Date

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Date

fn cmp(&self, other: &Date) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Date

fn eq(&self, other: &Date) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Date

fn partial_cmp(&self, other: &Date) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for Date

impl Sub for Date

Returns the number of days between two Date values.

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

// The value will be negative when the dates are flipped:
assert_eq!(-366, date1 - 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 - Date::MIN);

type Output = i32

The resulting type after applying the - operator.

fn sub(self, rhs: Date) -> i32

Performs the - operation.