Struct icu_calendar::Date

pub struct Date<A: AsCalendar> {
    pub(crate) inner: <A::Calendar as Calendar>::DateInner,
    pub(crate) calendar: A,
}

A date for a given calendar.

This can work with wrappers around Calendar types, e.g. Rc<C>, via the AsCalendar trait.

This can be constructed constructed from its fields via Self::try_new_from_codes(), or can be constructed with one of the new_<calendar>_datetime() per-calendar methods (and then freely converted between calendars).

use icu::calendar::Date;

// Example: creation of ISO date from integers.
let date_iso = Date::try_new_iso_date(1970, 1, 2)
    .expect("Failed to initialize ISO Date instance.");

assert_eq!(date_iso.year().number, 1970);
assert_eq!(date_iso.month().ordinal, 1);
assert_eq!(date_iso.day_of_month().0, 2);

Fields

inner: <A::Calendar as Calendar>::DateInner

calendar: A

Implementations

impl<A: AsCalendar> Date<A>

pub fn try_new_from_codes( era: Era, year: i32, month_code: MonthCode, day: u8, calendar: A, ) -> Result<Self, CalendarError>

Construct a date from from era/month codes and fields, and some calendar representation

pub fn new_from_iso(iso: Date<Iso>, calendar: A) -> Self

Construct a date from an ISO date and some calendar representation

pub fn to_iso(&self) -> Date<Iso>

Convert the Date to an ISO Date

pub fn to_calendar<A2: AsCalendar>(&self, calendar: A2) -> Date<A2>

Convert the Date to a date in a different calendar

pub fn months_in_year(&self) -> u8

The number of months in the year of this date

pub fn days_in_year(&self) -> u16

The number of days in the year of this date

pub fn days_in_month(&self) -> u8

The number of days in the month of this date

pub fn day_of_week(&self) -> IsoWeekday

The day of the week for this date

Monday is 1, Sunday is 7, according to ISO

pub fn year(&self) -> FormattableYear

The calendar-specific year represented by self

pub fn is_in_leap_year(&self) -> bool

Returns whether self is in a calendar-specific leap year

pub fn month(&self) -> FormattableMonth

The calendar-specific month represented by self

pub fn day_of_month(&self) -> DayOfMonth

The calendar-specific day-of-month represented by self

pub fn day_of_year_info(&self) -> DayOfYearInfo

The calendar-specific day-of-month represented by self

pub fn week_of_month(&self, first_weekday: IsoWeekday) -> WeekOfMonth

The week of the month containing this date.

Examples

use icu::calendar::types::IsoWeekday;
use icu::calendar::types::WeekOfMonth;
use icu::calendar::Date;

let date = Date::try_new_iso_date(2022, 8, 10).unwrap(); // second Wednesday

// The following info is usually locale-specific
let first_weekday = IsoWeekday::Sunday;

assert_eq!(date.week_of_month(first_weekday), WeekOfMonth(2));

pub fn week_of_year( &self, config: &WeekCalculator, ) -> Result<WeekOf, CalendarError>

The week of the year containing this date.

Examples

use icu::calendar::week::RelativeUnit;
use icu::calendar::week::WeekCalculator;
use icu::calendar::week::WeekOf;
use icu::calendar::Date;

let date = Date::try_new_iso_date(2022, 8, 26).unwrap();

// The following info is usually locale-specific
let week_calculator = WeekCalculator::default();

assert_eq!(
    date.week_of_year(&week_calculator),
    Ok(WeekOf {
        week: 35,
        unit: RelativeUnit::Current
    })
);

pub fn from_raw( inner: <A::Calendar as Calendar>::DateInner, calendar: A, ) -> Self

Construct a date from raw values for a given calendar. This does not check any invariants for the date and calendar, and should only be called by calendar implementations.

Calling this outside of calendar implementations is sound, but calendar implementations are not expected to do anything sensible with such invalid dates.

AnyCalendar will panic if AnyCalendar Date objects with mismatching date and calendar types are constructed

pub fn inner(&self) -> &<A::Calendar as Calendar>::DateInner

Get the inner date implementation. Should not be called outside of calendar implementations

pub fn calendar(&self) -> &A::Calendar

Get a reference to the contained calendar

pub fn calendar_wrapper(&self) -> &A

Get a reference to the contained calendar wrapper

(Useful in case the user wishes to e.g. clone an Rc)

impl<C: IntoAnyCalendar, A: AsCalendar<Calendar = C>> Date<A>

pub fn to_any(&self) -> Date<AnyCalendar>

Type-erase the date, converting it to a date for AnyCalendar

impl<C: Calendar> Date<C>

pub fn wrap_calendar_in_rc(self) -> Date<Rc<C>>

Wrap the calendar type in Rc<T>

Useful when paired with Self::to_any() to obtain a Date<Rc<AnyCalendar>>

pub fn wrap_calendar_in_arc(self) -> Date<Arc<C>>

Wrap the calendar type in Arc<T>

Useful when paired with Self::to_any() to obtain a Date<Rc<AnyCalendar>>

impl Date<Buddhist>

pub fn try_new_buddhist_date( year: i32, month: u8, day: u8, ) -> Result<Date<Buddhist>, CalendarError>

Construct a new Buddhist Date.

Years are specified as BE years.

use icu::calendar::Date;

let date_buddhist = Date::try_new_buddhist_date(1970, 1, 2)
    .expect("Failed to initialize Buddhist Date instance.");

assert_eq!(date_buddhist.year().number, 1970);
assert_eq!(date_buddhist.month().ordinal, 1);
assert_eq!(date_buddhist.day_of_month().0, 2);

impl<A: AsCalendar<Calendar = Chinese>> Date<A>

pub fn try_new_chinese_date_with_calendar( year: i32, month: u8, day: u8, calendar: A, ) -> Result<Date<A>, CalendarError>

Construct a new Chinese date from a year, month, and day. year represents the Chinese year counted infinitely with -2636 (2637 BCE) as Chinese year 1; month represents the month of the year ordinally (ex. if it is a leap year, the last month will be 13, not 12); day indicates the day of month

This date will not use any precomputed calendrical calculations, one that loads such data from a provider will be added in the future (#3933)

use icu::calendar::{chinese::Chinese, Date};

let chinese = Chinese::new_always_calculating();

let date_chinese =
    Date::try_new_chinese_date_with_calendar(4660, 6, 11, chinese)
        .expect("Failed to initialize Chinese Date instance.");

assert_eq!(date_chinese.year().number, 4660);
assert_eq!(date_chinese.year().cyclic.unwrap().get(), 40);
assert_eq!(date_chinese.year().related_iso, Some(2023));
assert_eq!(date_chinese.month().ordinal, 6);
assert_eq!(date_chinese.day_of_month().0, 11);

impl Date<Coptic>

pub fn try_new_coptic_date( year: i32, month: u8, day: u8, ) -> Result<Date<Coptic>, CalendarError>

Construct new Coptic Date.

Negative years are in the B.D. era, starting with 0 = 1 B.D.

use icu::calendar::Date;

let date_coptic = Date::try_new_coptic_date(1686, 5, 6)
    .expect("Failed to initialize Coptic Date instance.");

assert_eq!(date_coptic.year().number, 1686);
assert_eq!(date_coptic.month().ordinal, 5);
assert_eq!(date_coptic.day_of_month().0, 6);

impl<A: AsCalendar<Calendar = Dangi>> Date<A>

pub fn try_new_dangi_date_with_calendar( year: i32, month: u8, day: u8, calendar: A, ) -> Result<Date<A>, CalendarError>

Construct a new Dangi date from a year, month, and day. year represents the Chinese year counted infinitely with -2332 (2333 BCE) as year 1; month represents the month of the year ordinally (ex. if it is a leap year, the last month will be 13, not 12); day indicates day of month.

This date will not use any precomputed calendrical calculations, one that loads such data from a provider will be added in the future (#3933)

use icu::calendar::dangi::Dangi;
use icu::calendar::Date;

let dangi = Dangi::new();

let date_dangi = Date::try_new_dangi_date_with_calendar(4356, 6, 18, dangi)
    .expect("Failed to initialize Dangi Date instance.");

assert_eq!(date_dangi.year().number, 4356);
assert_eq!(date_dangi.year().cyclic.unwrap().get(), 40);
assert_eq!(date_dangi.year().related_iso, Some(2023));
assert_eq!(date_dangi.month().ordinal, 6);
assert_eq!(date_dangi.day_of_month().0, 18);

impl Date<Ethiopian>

pub fn try_new_ethiopian_date( era_style: EthiopianEraStyle, year: i32, month: u8, day: u8, ) -> Result<Date<Ethiopian>, CalendarError>

Construct new Ethiopian Date.

For the Amete Mihret era style, negative years work with year 0 as 1 pre-Incarnation, year -1 as 2 pre-Incarnation, and so on.

use icu::calendar::ethiopian::EthiopianEraStyle;
use icu::calendar::Date;

let date_ethiopian = Date::try_new_ethiopian_date(
    EthiopianEraStyle::AmeteMihret,
    2014,
    8,
    25,
)
.expect("Failed to initialize Ethopic Date instance.");

assert_eq!(date_ethiopian.year().number, 2014);
assert_eq!(date_ethiopian.month().ordinal, 8);
assert_eq!(date_ethiopian.day_of_month().0, 25);

impl Date<Gregorian>

pub fn try_new_gregorian_date( year: i32, month: u8, day: u8, ) -> Result<Date<Gregorian>, CalendarError>

Construct a new Gregorian Date.

Years are specified as ISO years.

use icu::calendar::Date;

// Conversion from ISO to Gregorian
let date_gregorian = Date::try_new_gregorian_date(1970, 1, 2)
    .expect("Failed to initialize Gregorian Date instance.");

assert_eq!(date_gregorian.year().number, 1970);
assert_eq!(date_gregorian.month().ordinal, 1);
assert_eq!(date_gregorian.day_of_month().0, 2);

impl Date<Hebrew>

pub fn try_new_hebrew_date( year: i32, month: u8, day: u8, ) -> Result<Date<Hebrew>, CalendarError>

Construct new Hebrew Date.

This datetime will not use any precomputed calendrical calculations, one that loads such data from a provider will be added in the future (#3933)

use icu::calendar::Date;

let date_hebrew = Date::try_new_hebrew_date(3425, 4, 25)
    .expect("Failed to initialize Hebrew Date instance.");

assert_eq!(date_hebrew.year().number, 3425);
assert_eq!(date_hebrew.month().ordinal, 4);
assert_eq!(date_hebrew.day_of_month().0, 25);

impl<A: AsCalendar<Calendar = Hebrew>> Date<A>

pub fn try_new_hebrew_date_with_calendar( year: i32, month: u8, day: u8, calendar: A, ) -> Result<Date<A>, CalendarError>

👎Deprecated since 1.5.0: Use Date::try_new_hebrew_date()

Construct new Hebrew Date given a calendar.

This is deprecated since Hebrew is a zero-sized type, but if you find yourself needing this functionality please let us know.

impl Date<Indian>

pub fn try_new_indian_date( year: i32, month: u8, day: u8, ) -> Result<Date<Indian>, CalendarError>

Construct new Indian Date, with year provided in the Śaka era.

use icu::calendar::Date;

let date_indian = Date::try_new_indian_date(1891, 10, 12)
    .expect("Failed to initialize Indian Date instance.");

assert_eq!(date_indian.year().number, 1891);
assert_eq!(date_indian.month().ordinal, 10);
assert_eq!(date_indian.day_of_month().0, 12);

impl<A: AsCalendar<Calendar = IslamicObservational>> Date<A>

pub fn try_new_observational_islamic_date( year: i32, month: u8, day: u8, calendar: A, ) -> Result<Date<A>, CalendarError>

Construct new Islamic Observational Date.

Has no negative years, only era is the AH.

use icu::calendar::islamic::IslamicObservational;
use icu::calendar::Date;

let islamic = IslamicObservational::new_always_calculating();

let date_islamic =
    Date::try_new_observational_islamic_date(1392, 4, 25, islamic)
        .expect("Failed to initialize Islamic Date instance.");

assert_eq!(date_islamic.year().number, 1392);
assert_eq!(date_islamic.month().ordinal, 4);
assert_eq!(date_islamic.day_of_month().0, 25);

impl<A: AsCalendar<Calendar = IslamicUmmAlQura>> Date<A>

pub fn try_new_ummalqura_date( year: i32, month: u8, day: u8, calendar: A, ) -> Result<Date<A>, CalendarError>

Construct new Islamic Umm al-Qura Date.

Has no negative years, only era is the AH.

use icu::calendar::islamic::IslamicUmmAlQura;
use icu::calendar::Date;

let islamic = IslamicUmmAlQura::new_always_calculating();

let date_islamic = Date::try_new_ummalqura_date(1392, 4, 25, islamic)
    .expect("Failed to initialize Islamic Date instance.");

assert_eq!(date_islamic.year().number, 1392);
assert_eq!(date_islamic.month().ordinal, 4);
assert_eq!(date_islamic.day_of_month().0, 25);

impl<A: AsCalendar<Calendar = IslamicCivil>> Date<A>

pub fn try_new_islamic_civil_date_with_calendar( year: i32, month: u8, day: u8, calendar: A, ) -> Result<Date<A>, CalendarError>

Construct new Civil Islamic Date.

Has no negative years, only era is the AH.

use icu::calendar::islamic::IslamicCivil;
use icu::calendar::Date;

let islamic = IslamicCivil::new_always_calculating();

let date_islamic =
    Date::try_new_islamic_civil_date_with_calendar(1392, 4, 25, islamic)
        .expect("Failed to initialize Islamic Date instance.");

assert_eq!(date_islamic.year().number, 1392);
assert_eq!(date_islamic.month().ordinal, 4);
assert_eq!(date_islamic.day_of_month().0, 25);

impl<A: AsCalendar<Calendar = IslamicTabular>> Date<A>

pub fn try_new_islamic_tabular_date_with_calendar( year: i32, month: u8, day: u8, calendar: A, ) -> Result<Date<A>, CalendarError>

Construct new Tabular Islamic Date.

Has no negative years, only era is the AH.

use icu::calendar::islamic::IslamicTabular;
use icu::calendar::Date;

let islamic = IslamicTabular::new_always_calculating();

let date_islamic =
    Date::try_new_islamic_tabular_date_with_calendar(1392, 4, 25, islamic)
        .expect("Failed to initialize Islamic Date instance.");

assert_eq!(date_islamic.year().number, 1392);
assert_eq!(date_islamic.month().ordinal, 4);
assert_eq!(date_islamic.day_of_month().0, 25);

impl Date<Iso>

pub fn try_new_iso_date( year: i32, month: u8, day: u8, ) -> Result<Date<Iso>, CalendarError>

Construct a new ISO date from integers.

use icu::calendar::Date;

let date_iso = Date::try_new_iso_date(1970, 1, 2)
    .expect("Failed to initialize ISO Date instance.");

assert_eq!(date_iso.year().number, 1970);
assert_eq!(date_iso.month().ordinal, 1);
assert_eq!(date_iso.day_of_month().0, 2);

pub fn unix_epoch() -> Self

Constructs an ISO date representing the UNIX epoch on January 1, 1970.

impl Date<Japanese>

pub fn try_new_japanese_date<A: AsCalendar<Calendar = Japanese>>( era: Era, year: i32, month: u8, day: u8, japanese_calendar: A, ) -> Result<Date<A>, CalendarError>

Construct a new Japanese Date.

Years are specified in the era provided, and must be in range for Japanese eras (e.g. dates past April 30 Heisei 31 must be in Reiwa; “Jun 5 Heisei 31” and “Jan 1 Heisei 32” will not be adjusted to being in Reiwa 1 and 2 respectively)

However, dates may always be specified in “bce” or “ce” and they will be adjusted as necessary.

use icu::calendar::japanese::Japanese;
use icu::calendar::{types, Date, Ref};
use tinystr::tinystr;

let japanese_calendar = Japanese::new();
// for easy sharing
let japanese_calendar = Ref(&japanese_calendar);

let era = types::Era(tinystr!(16, "heisei"));

let date = Date::try_new_japanese_date(era, 14, 1, 2, japanese_calendar)
    .expect("Constructing a date should succeed");

assert_eq!(date.year().era, era);
assert_eq!(date.year().number, 14);
assert_eq!(date.month().ordinal, 1);
assert_eq!(date.day_of_month().0, 2);

// This function will error for eras that are out of bounds:
// (Heisei was 32 years long, Heisei 33 is in Reiwa)
let oob_date =
    Date::try_new_japanese_date(era, 33, 1, 2, japanese_calendar);
assert!(oob_date.is_err());

// and for unknown eras
let fake_era = types::Era(tinystr!(16, "neko")); // 🐱
let fake_date =
    Date::try_new_japanese_date(fake_era, 10, 1, 2, japanese_calendar);
assert!(fake_date.is_err());

impl Date<JapaneseExtended>

pub fn try_new_japanese_extended_date<A: AsCalendar<Calendar = JapaneseExtended>>( era: Era, year: i32, month: u8, day: u8, japanext_calendar: A, ) -> Result<Date<A>, CalendarError>

Construct a new Japanese Date with all eras.

Years are specified in the era provided, and must be in range for Japanese eras (e.g. dates past April 30 Heisei 31 must be in Reiwa; “Jun 5 Heisei 31” and “Jan 1 Heisei 32” will not be adjusted to being in Reiwa 1 and 2 respectively)

However, dates may always be specified in “bce” or “ce” and they will be adjusted as necessary.

use icu::calendar::japanese::JapaneseExtended;
use icu::calendar::{types, Date, Ref};
use tinystr::tinystr;

let japanext_calendar = JapaneseExtended::new();
// for easy sharing
let japanext_calendar = Ref(&japanext_calendar);

let era = types::Era(tinystr!(16, "kansei-1789"));

let date =
    Date::try_new_japanese_extended_date(era, 7, 1, 2, japanext_calendar)
        .expect("Constructing a date should succeed");

assert_eq!(date.year().era, era);
assert_eq!(date.year().number, 7);
assert_eq!(date.month().ordinal, 1);
assert_eq!(date.day_of_month().0, 2);

impl Date<Julian>

pub fn try_new_julian_date( year: i32, month: u8, day: u8, ) -> Result<Date<Julian>, CalendarError>

Construct new Julian Date.

Years are arithmetic, meaning there is a year 0. Zero and negative years are in BC, with year 0 = 1 BC

use icu::calendar::Date;

let date_julian = Date::try_new_julian_date(1969, 12, 20)
    .expect("Failed to initialize Julian Date instance.");

assert_eq!(date_julian.year().number, 1969);
assert_eq!(date_julian.month().ordinal, 12);
assert_eq!(date_julian.day_of_month().0, 20);

impl Date<Persian>

pub fn try_new_persian_date( year: i32, month: u8, day: u8, ) -> Result<Date<Persian>, CalendarError>

Construct new Persian Date.

Has no negative years, only era is the AH/AP.

use icu::calendar::Date;

let date_persian = Date::try_new_persian_date(1392, 4, 25)
    .expect("Failed to initialize Persian Date instance.");

assert_eq!(date_persian.year().number, 1392);
assert_eq!(date_persian.month().ordinal, 4);
assert_eq!(date_persian.day_of_month().0, 25);

impl Date<Roc>

pub fn try_new_roc_date( year: i32, month: u8, day: u8, ) -> Result<Date<Roc>, CalendarError>

Construct a new Republic of China calendar Date.

Years are specified in the “roc” era. This function accepts an extended year in that era, so dates before Minguo are negative and year 0 is 1 Before Minguo. To specify dates using explicit era codes, use Roc::date_from_codes().

use icu::calendar::Date;
use icu::calendar::gregorian::Gregorian;
use tinystr::tinystr;

// Create a new ROC Date
let date_roc = Date::try_new_roc_date(1, 2, 3)
    .expect("Failed to initialize ROC Date instance.");

assert_eq!(date_roc.year().era.0, tinystr!(16, "roc"));
assert_eq!(date_roc.year().number, 1, "ROC year check failed!");
assert_eq!(date_roc.month().ordinal, 2, "ROC month check failed!");
assert_eq!(date_roc.day_of_month().0, 3, "ROC day of month check failed!");

// Convert to an equivalent Gregorian date
let date_gregorian = date_roc.to_calendar(Gregorian);

assert_eq!(date_gregorian.year().number, 1912, "Gregorian from ROC year check failed!");
assert_eq!(date_gregorian.month().ordinal, 2, "Gregorian from ROC month check failed!");
assert_eq!(date_gregorian.day_of_month().0, 3, "Gregorian from ROC day of month check failed!");

Trait Implementations

impl<A: AsCalendar + Clone> Clone for Date<A>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A: AsCalendar> Debug for Date<A>

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

Formats the value using the given formatter.

impl<C, A> Ord for Date<A>

where C: Calendar, C::DateInner: Ord, A: AsCalendar<Calendar = C>,

fn cmp(&self, other: &Self) -> 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<C, A, B> PartialEq<Date<B>> for Date<A>

where C: Calendar, A: AsCalendar<Calendar = C>, B: AsCalendar<Calendar = C>,

fn eq(&self, other: &Date<B>) -> 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<C, A, B> PartialOrd<Date<B>> for Date<A>

where C: Calendar, C::DateInner: PartialOrd, A: AsCalendar<Calendar = C>, B: AsCalendar<Calendar = C>,

fn partial_cmp(&self, other: &Date<B>) -> 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<A> Copy for Date<A>

where A: AsCalendar + Copy, <<A as AsCalendar>::Calendar as Calendar>::DateInner: Copy,

impl<A: AsCalendar> Eq for Date<A>