Struct date::Date

pub struct Date(/* private fields */);

A representation of a single date.

Implementations

impl Date

pub const fn new(year: i16, month: u8, day: u8) -> Self

Construct a new Date from the provided year, month, and day.

Examples

use date::Date;
let date = Date::new(2012, 4, 21);
assert_eq!(date.year(), 2012);
assert_eq!(date.month(), 4);
assert_eq!(date.day(), 21);

Panic

This function panics if it receives “out-of-bounds” values (e.g. “March 32” or “February 30”). However, it can be convenient to be able to send such values to avoid having to handle overflow yourself; use Date::overflowing_new for this purpose.

pub const fn from_timestamp(unix_timestamp: i64) -> Self

Construct a new Date based on the Unix timestamp.

Examples

use date::date;
use date::Date;

let day_one = Date::from_timestamp(0);
assert_eq!(day_one, date! { 1970-01-01 });
let later = Date::from_timestamp(15_451 * 86_400);
assert_eq!(later, date! { 2012-04-21 });

Negative timestamps are also supported:

let before_unix_era = Date::from_timestamp(-1);
assert_eq!(before_unix_era, date! { 1969-12-31 });
let hobbit_publication = Date::from_timestamp(-11_790 * 86_400);
assert_eq!(hobbit_publication, date! { 1937-09-21 });

pub const fn overflowing_new(year: i16, month: u8, day: u8) -> Self

Construct a new Date from the provided year, month, and day.

This function accepts “overflow” values that would lead to invalid dates, and canonicalizes them to correct dates, allowing for some math to be done on the inputs without needing to perform overflow checks yourself.

For example, it’s legal to send “March 32” to this function, and it will yield April 1 of the same year. It’s also legal to send a month or day value of zero, and it will conform to the month or day (respectively) prior to the first.

pub fn parse( date_str: impl AsRef<str>, date_fmt: &'static str ) -> ParseResult<Date>

Parse a date from a string, according to the provided format string.

impl Date

pub const fn year(&self) -> i16

Returns the year number in the calendar date.

pub const fn month(&self) -> u8

Returns the month number, starting from 1.

The return value ranges from 1 to 12.

pub const fn day(&self) -> u8

Returns the day of the month, starting from 1.

The return value ranges from 1 to 31. (The last day of the month differs by months.)

pub const fn day_of_year(&self) -> u16

The day of the current year. Range: [1, 366]

pub const fn week(&self) -> u16

The week number of the year (between 0 and 53, inclusive), with a new week starting each Sunday.

Week 1 begins on the first Sunday of the year; leading days before that are part of week 0.

pub const fn weekday(&self) -> Weekday

Return the weekday corresponding to the given date.

impl Date

pub const fn timestamp(&self) -> i64

The Unix timestamp for this date at midnight UTC.

Examples

assert_eq!(date! { 1969-12-31 }.timestamp(), -86_400);
assert_eq!(date! { 1970-01-01 }.timestamp(), 0);
assert_eq!(date! { 1970-01-05 }.timestamp(), 4 * 86_400);
assert_eq!(date! { 2012-04-21 }.timestamp(), 1334966400);

impl Date

pub fn today_utc() -> Self

The date representing today, in UTC.

Panic

This function will panic if the system clock is set to a time prior to January 1, 1970.

impl Date

pub fn format<'a>(&'a self, format_str: &'a str) -> FormattedDate<'_>

Format the date according to the provided strftime specifier. The following date specifiers are supported:

Year

Token	Example	Description
%C	20	Gregorian year divided by 100, zero-padded to 2 digits
%Y	2012	Gregorian year, zero-padded to 4 digits
%y	12	Gregorian year modulo 100, zero-padded to 2 digits

Month

Token	Example	Description
%B	December	Full English name of the month
%b or %h	Dec	Three-letter abbreviation for the month’s English name
%m	07	Month number (01–12), zero-padded to 2 digits

Day

Token	Example	Description
%d	21	Day number (01–31), zero-padded to 2 digits
%a	Sat	Three-letter abbreviation for the weekday’s English name
%A	Saturday	Full English name of the weekday
%w	6	Integer representing the weekday: Sunday (0) to Saturday (6)
%u	6	Integer representing the weekday: Monday (1) to Sunday (7)
%j	112	Day of the year (001–366), zero-padded to 3 digits

Full Date Shortcuts

Token	Example	Description
%D	07/08/01	Month-day-year format. Same as %m/%d/%y.
%F	2001-07-08	Year-month-day format (ISO 8601). Same as %Y-%m-%d.
%v	8-Jul-2001	Day-month-year format. Same as %e-%b-%Y.

For tokens with default padding, the padding can be modified or suppressed with a modifier:

Token Modifier	Effect
- (e.g. %-d)	Suppress padding
_ (e.g. %_d)	Use spaces for padding
0 (e.g. %0d)	Use zeroes for padding (currently the default for padded tokens)

Additionally, the following tokens convert to plain characters:

Token	Literal
%n	\n (newline)
%t	\t (tab)
%%	%

impl Date

pub fn iter_through(&self, end: Date) -> DateIterator

An iterator of dates beginning with this date, and ending with the provided end date (inclusive).

impl Date

pub const MAX: Self = _

The maximum date that can be represented.

pub const MIN: Self = _

The minimum date that can be represented.

Trait Implementations

impl Add<DateInterval> for Date

fn add(self, interval: DateInterval) -> Self::Output

Return a new Date that is the given number of days later.

type Output = Date

The resulting type after applying the + operator.

impl Add<MonthInterval> for Date

type Output = Date

The resulting type after applying the + operator.

fn add(self, interval: MonthInterval) -> Self

Performs the + operation.

impl AddAssign<DateInterval> for Date

fn add_assign(&mut self, interval: DateInterval)

Performs the += operation.

impl Clone for Date

fn clone(&self) -> Date

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Date

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Date

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for Date

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

Formats the value using the given formatter.

impl From<RawDate> for Date

fn from(value: RawDate) -> Self

Converts to this type from the input type.

impl FromStr for Date

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> ParseResult<Self>

Parses a string s to return a value of this type.

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 + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Date

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl Serialize for Date

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl Sub<DateInterval> for Date

fn sub(self, interval: DateInterval) -> Self::Output

Return a new Date that is the given number of days earlier.

type Output = Date

The resulting type after applying the - operator.

impl Sub<MonthInterval> for Date

type Output = Date

The resulting type after applying the - operator.

fn sub(self, interval: MonthInterval) -> Self

Performs the - operation.

impl Sub for Date

type Output = DateInterval

The resulting type after applying the - operator.

fn sub(self, rhs: Date) -> Self::Output

Performs the - operation.

impl SubAssign<DateInterval> for Date

fn sub_assign(&mut self, interval: DateInterval)

Performs the -= operation.

impl Copy for Date

impl Eq for Date

impl StructuralPartialEq for Date