silk.time.calendar.

Dates in other calendars than ISO 8601: Calendar, CalendarDate, Era, and MonthCode.

When to use#

Use CalendarDate to show a day to a person who reads another calendar, to read a date that a person gives in one, and to count years and months as that calendar counts them. For the dates that programs store and exchange, use PlainDate of silk.time.plain_date.

Details#

A CalendarDate is a PlainDate seen in one of 16 calendars. CalendarDate.of converts a PlainDate, and CalendarDate.date gives it back. The text form is the ISO 8601 date with the calendar in an annotation, as in 2026-11-19[u-ca=hebrew], which is the form of RFC 9557 and of ECMAScript Temporal.

The fields and the arithmetic follow ECMAScript Temporal:

The Hebrew calendar, the Islamic calendars by rule, and the Coptic, Ethiopic, Indian, and Persian calendars are computed for every date of PlainDate. The Persian calendar follows the 33-year rule with the corrections of Unicode ICU, which keep it on the astronomical calendar of Iran. The Umm al-Qura calendar has a table for the years 1300 to 1600 of the Hijra, and the Chinese and Dangi calendars have tables for 1800 to 2200; they are in silk.time.calendar_data.

Gotchas#

The Chinese and Dangi calendars have no data outside 1800-01-25 to 2201-02-03. A date outside gives CalendarError.OutOfRange.

The Japanese calendar has the eras from Meiji on, and Meiji starts on 1873-01-01, the day Japan took the Gregorian calendar. Earlier dates have the eras ce and bce.

Examples#

Show a date in the Hebrew calendar#

silk
import silk.core.result { Result }
import silk.time.calendar { Calendar, CalendarDate, CalendarError }
import silk.time.plain_date { PlainDate }

pub fn main() -> i32 {
  return match CalendarDate.of(Calendar.Hebrew, PlainDate.make(2026, 11, 19)) {
    Result<CalendarDate, CalendarError>.Success { value } => {
      // 9 Kislev 5787. Kislev is the third month.
      if value.year() != 5787 || value.month() != 3 || value.day() != 9 {
        return 1
      }
      if value.monthCode().number != 3 || value.monthCode().leap {
        return 2
      }
      return 0
    }
    Result<CalendarDate, CalendarError>.Failure {..} => 3
  }
}

Read a date that a person gives in the Japanese calendar#

silk
import silk.core.option { Option }
import silk.core.result { Result }
import silk.time.calendar { Calendar, CalendarDate, CalendarError, Era }
import silk.time.period { Overflow }
import silk.time.plain_date { PlainDate }

pub fn main() -> i32 {
  // Reiwa 8, month 11, day 19.
  let year = match Calendar.Japanese.yearOfEra(Era.Reiwa, 8) {
    Option<i32>.Some { value } => value
    Option<i32>.None => {
      return 1
    }
  }
  return match CalendarDate.fromFields(Calendar.Japanese, year, 11, 19, Overflow.Reject) {
    Result<CalendarDate, CalendarError>.Success { value } => {
      let date = value.date()
      let expected = PlainDate.make(2026, 11, 19)
      if &date != &expected {
        return 2
      }
      return 0
    }
    Result<CalendarDate, CalendarError>.Failure {..} => 3
  }
}

Add a year in a calendar with leap months#

silk
import silk.core.result { Result }
import silk.time.calendar { Calendar, CalendarDate, CalendarError, MonthCode }
import silk.time.period { Overflow, Period }
import silk.time.plain_date { PlainDate }

pub fn main() -> i32 {
  // 30 Adar I 5784. The year 5785 has no Adar I, so one year later is in Adar.
  let start = match CalendarDate.fromMonthCode(Calendar.Hebrew, 5784, MonthCode.make(5, true), 30, Overflow.Reject) {
    Result<CalendarDate, CalendarError>.Success { value } => value
    Result<CalendarDate, CalendarError>.Failure {..} => {
      return 1
    }
  }
  return match start.checkedAdd(Period.ofYears(1), Overflow.Constrain) {
    Result<CalendarDate, CalendarError>.Success { value } => {
      // Adar has 29 days.
      if value.monthCode().number != 6 || value.day() != 29 {
        return 2
      }
      return 0
    }
    Result<CalendarDate, CalendarError>.Failure {..} => 3
  }
}

Import as Calendar with import silk.time.calendar { Calendar }.

Public declarations: 5.

Calendar#

silk
pub enum Calendar

A calendar: a way to name a day with a year, a month, and a day of the month.

Details#

The names are the calendar identifiers of Unicode CLDR, which ECMAScript Temporal and the [u-ca=...] annotation of RFC 9557 use.

Iso8601#

silk
Iso8601

iso8601: the calendar of PlainDate, with the Gregorian leap year rule for every year and no eras.

Gregory#

silk
Gregory

gregory: the ISO 8601 calendar with the eras ce and bce.

Buddhist#

silk
Buddhist

buddhist: the Thai solar calendar, the ISO 8601 calendar with years counted from 543 BCE.

Roc#

silk
Roc

roc: the calendar of the Republic of China, the ISO 8601 calendar with years counted from 1912.

Japanese#

silk
Japanese

japanese: the ISO 8601 calendar with the eras of Japan from Meiji on.

Coptic#

silk
Coptic

coptic: 12 months of 30 days and a 13th month of 5 or 6 days.

Ethiopic#

silk
Ethiopic

ethiopic: the Coptic months with years counted from the year 8 CE, the era am.

EthiopicAmeteAlem#

silk
EthiopicAmeteAlem

ethioaa: the Ethiopic calendar with years counted from the creation of the world, the era aa, 5500 years earlier.

Hebrew#

silk
Hebrew

hebrew: the lunisolar Hebrew calendar, with a 13th month in 7 years of each 19.

Indian#

silk
Indian

indian: the Indian national calendar, with years of the Shaka era.

Persian#

silk
Persian

persian: the Solar Hijri calendar of Iran and Afghanistan.

IslamicCivil#

silk
IslamicCivil

islamic-civil: the Islamic calendar by rule, with 11 leap years in each 30 and a Friday epoch.

IslamicTabular#

silk
IslamicTabular

islamic-tbla: the Islamic calendar by rule with a Thursday epoch, one day earlier than islamic-civil.

IslamicUmmAlQura#

silk
IslamicUmmAlQura

islamic-umalqura: the Umm al-Qura calendar of Saudi Arabia. Outside the years 1300 to 1600 of the Hijra it is the same as islamic-civil.

Chinese#

silk
Chinese

chinese: the lunisolar Chinese calendar, for the dates 1800-01-25 to 2201-02-03.

Dangi#

silk
Dangi

dangi: the lunisolar Korean calendar, for the dates 1800-01-25 to 2201-02-03.

Era#

silk
pub enum Era

An era of a calendar: the point from which the years of a date are counted.

Ce#

silk
Ce

ce: the Common Era of gregory and japanese.

Bce#

silk
Bce

bce: before the Common Era, in gregory and japanese. Year 1 is the year before 1 CE.

Be#

silk
Be

be: the Buddhist Era of buddhist.

Am#

silk
Am

am: the Era of the Martyrs of coptic, the Incarnation Era of ethiopic, and Anno Mundi of hebrew.

Aa#

silk
Aa

aa: Amete Alem, the era of ethioaa and of the ethiopic years before am.

Shaka#

silk
Shaka

shaka: the Shaka era of indian.

Ap#

silk
Ap

ap: Anno Persico of persian.

Ah#

silk
Ah

ah: the era of the Hijra in the Islamic calendars.

Bh#

silk
Bh

bh: before the Hijra, in the Islamic calendars. Year 1 is the year before 1 AH.

Roc#

silk
Roc

roc: the era of the Republic of China, from 1912.

Broc#

silk
Broc

broc: before the Republic of China. Year 1 is 1911.

Meiji#

silk
Meiji

meiji: from 1873-01-01, when Japan took the Gregorian calendar, as year 6.

Taisho#

silk
Taisho

taisho: from 1912-07-30.

Showa#

silk
Showa

showa: from 1926-12-25.

Heisei#

silk
Heisei

heisei: from 1989-01-08.

Reiwa#

silk
Reiwa

reiwa: from 2019-05-01.

CalendarError#

silk
pub enum CalendarError

Why a calendar date cannot be made.

OutOfRange#

silk
OutOfRange

The date is outside the range of PlainDate, or the calendar has no data for it. The chinese and dangi calendars have data for 1800-01-25 to 2201-02-03 only.

NoSuchMonth#

silk
NoSuchMonth

The year has no such month: the number is 0 or too high, the month code names a month that the calendar does not have, or it names a leap month in a year without it and the overflow rule is Overflow.Reject.

NoSuchDay#

silk
NoSuchDay

The month has no such day, and the day is 0 or the overflow rule is Overflow.Reject.

NoSuchEra#

silk
NoSuchEra

The era is not an era of the calendar.

CalendarMismatch#

silk
CalendarMismatch

The two dates of an operation are in different calendars.

MonthCode#

silk
pub struct MonthCode

The name of a month that is the same in every year, such as M05 or M05L.

Details#

In a calendar with leap months, the number of a month in the year changes: the Hebrew month Nisan is month 7 of a common year and month 8 of a leap year. The month code does not change: Nisan is always M07. A leap month has the number of the month before it and the letter L. In the Hebrew calendar the only leap month is M05L, Adar I. In the Chinese and Dangi calendars a leap month can follow any month.

Field number#

silk
pub number: u8

The number in the code, from 1.

Field leap#

silk
pub leap: bool

true for a leap month, written with L.

Implementation Copy for MonthCode#

silk
impl Copy for MonthCode

CalendarDate#

silk
pub struct CalendarDate

A day in one calendar.

Details#

A CalendarDate holds a PlainDate and a Calendar. The year, the month, and the day are the fields of that day in the calendar. Two values are equal when they name the same day in the same calendar.

The year is the year that arithmetic uses. It can be zero or negative. Calendars with eras also give an Era and a year of the era, which is what people write.

Implementation Copy for CalendarDate#

silk
impl Copy for CalendarDate

Implementation Calendar#

silk
impl Calendar

Associated function named#

silk
pub fn named(name: string) -> Option<Calendar>

Returns the calendar with the given identifier, such as hebrew, in any letter case, or None for a name that is not one of the 16 calendars.

Details#

ethiopic-amete-alem is another name of ethioaa, and islamicc of islamic-civil.

Associated function namedBytes#

silk
pub fn namedBytes(name: &[u8]) -> Option<Calendar>

Returns the calendar with the identifier in name, such as hebrew, in any letter case, or None for a name that is not one of the 16 calendars.

Method name#

silk
pub fn name(self: Self) -> string<'static>

Returns the identifier of the calendar, such as hebrew or islamic-umalqura.

Method monthsInYear#

silk
pub fn monthsInYear(self: Self, year: i32) -> Option<u8>

Returns the number of months in year, or None when the calendar has no data for the year.

Details#

It is 12 in most calendars, 13 in the Coptic and Ethiopic calendars, and 12 or 13 in the Hebrew, Chinese, and Dangi calendars.

Method daysInMonth#

silk
pub fn daysInMonth(self: Self, year: i32, month: u8) -> Option<u8>

Returns the number of days in the month with the number month in year, or None when the year has no such month or the calendar has no data for the year.

Method daysInYear#

silk
pub fn daysInYear(self: Self, year: i32) -> Option<u16>

Returns the number of days in year, or None when the calendar has no data for the year.

Method isLeapYear#

silk
pub fn isLeapYear(self: Self, year: i32) -> Option<bool>

Returns true when year is longer than a common year of the calendar, or None when the calendar has no data for the year.

Details#

A leap year has a 13th month in the Hebrew, Chinese, and Dangi calendars, and one more day in the others.

Method monthCode#

silk
pub fn monthCode(self: Self, year: i32, month: u8) -> Option<MonthCode>

Returns the code of the month with the number month in year, or None when the year has no such month or the calendar has no data for the year.

Method monthOfCode#

silk
pub fn monthOfCode(self: Self, year: i32, code: MonthCode) -> Option<u8>

Returns the number in year of the month with the code code, or None when the year has no month with that code or the calendar has no data for the year.

Method hasEras#

silk
pub fn hasEras(self: Self) -> bool

Returns true when the dates of the calendar have an era.

Method yearOfEra#

silk
pub fn yearOfEra(self: Self, era: Era, eraYear: i32) -> Option<i32>

Returns the year that eraYear of era is in the calendar, or None when era is not an era of the calendar.

Details#

The result is the year that CalendarDate.year returns and CalendarDate.fromFields takes. Year 1 of an era that counts back, such as bce, is year 0.

ad and bc are not separate eras: use Era.Ce and Era.Bce.

Method monthDayReference#

silk
pub fn monthDayReference(self: Self, code: MonthCode, day: u8, overflow: Overflow) -> Option<PlainDate>

Returns the ISO 8601 date that stands for a month and a day of the calendar without a year, or None when no year has that day, or the overflow rule is Overflow.Reject and the day does not exist as given.

Details#

This is the reference date of an ECMAScript Temporal.PlainMonthDay. For the calendars with the ISO 8601 months it is in 1972. For the others it is the last day with that month code and day at or before the end of 1972, except a few days that need an earlier or a later year. With Overflow.Constrain, a day past the longest form of the month becomes its last day, and a leap month that no year has with that day becomes the common month.

Implementation Equal for Calendar#

silk
impl Equal for Calendar

Operation equals#

silk
equals: Calendar.same

Implementation Display for Calendar#

silk
impl Display for Calendar

Writes the identifier of the calendar, such as hebrew.

Operation display#

silk
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Implementation Debug for Calendar#

silk
impl Debug for Calendar

Writes the same text as Display: the identifier of the calendar.

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Implementation Era#

silk
impl Era

Associated function named#

silk
pub fn named(name: string) -> Option<Era>

Returns the era with the given code, such as ce or reiwa, in any letter case, or None for a name that is not an era code. ad is Era.Ce and bc is Era.Bce.

Method name#

silk
pub fn name(self: Self) -> string<'static>

Returns the code of the era, such as ce or reiwa.

Implementation Equal for Era#

silk
impl Equal for Era

Operation equals#

silk
equals: Era.same

Implementation Display for Era#

silk
impl Display for Era

Writes the code of the era, such as ce.

Operation display#

silk
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Implementation Debug for Era#

silk
impl Debug for Era

Writes the same text as Display: the code of the era.

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Implementation Debug for CalendarError#

silk
impl Debug for CalendarError

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Implementation MonthCode#

silk
impl MonthCode

Associated function make#

silk
pub fn make(number: u8, leap: bool) -> MonthCode

Returns the month code with the given number and leap mark. It does not check that a calendar has such a month.

Associated function parse#

silk
pub fn parse(text: string) -> Option<MonthCode>

Reads a month code such as M05 or M05L: the letter M, two digits, and L for a leap month. Returns None for any other text, and for M00.

Implementation Equal for MonthCode#

silk
impl Equal for MonthCode

Operation equals#

silk
equals: MonthCode.same

Implementation Display for MonthCode#

silk
impl Display for MonthCode

Writes the code as M, two digits, and L for a leap month, as in M05L.

Operation display#

silk
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Implementation Debug for MonthCode#

silk
impl Debug for MonthCode

Writes the same text as Display, such as M05L.

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Implementation CalendarDate#

silk
impl CalendarDate

Associated function of#

silk
pub fn of(calendar: Calendar, date: PlainDate) -> Result<CalendarDate, CalendarError>

Returns date in calendar.

Errors#

  • CalendarError.OutOfRange if the calendar has no data for the date. Only Chinese and Dangi have a limit: 1800-01-25 to 2201-02-03.

Associated function fromFields#

silk
pub fn fromFields(calendar: Calendar, year: i32, month: u8, day: u8, overflow: Overflow) -> Result<CalendarDate, CalendarError>

Returns the date with the given year, number of the month in the year, and day of the month.

Details#

year is the year that CalendarDate.year returns. For a year of an era, convert it with Calendar.yearOfEra first. month counts the months of that year from 1, so in a leap year of a calendar with leap months it is not the number in the month code.

Errors#

  • CalendarError.NoSuchMonth if month is 0, or the year has fewer months and overflow is Overflow.Reject. With Overflow.Constrain the last month is used.

  • CalendarError.NoSuchDay if day is 0, or the month has fewer days and overflow is Overflow.Reject. With Overflow.Constrain the last day is used.

  • CalendarError.OutOfRange if the date is outside the range of PlainDate or the calendar has no data for the year.

Associated function fromMonthCode#

silk
pub fn fromMonthCode(calendar: Calendar, year: i32, code: MonthCode, day: u8, overflow: Overflow) -> Result<CalendarDate, CalendarError>

Returns the date with the given year, month code, and day of the month.

Details#

With Overflow.Constrain, a leap month in a year without it becomes the month that takes its place: Adar (M06) for the Hebrew M05L, and the month with the same number for a Chinese or Dangi leap month.

Errors#

  • CalendarError.NoSuchMonth if no year of the calendar has a month with that code, or this year does not have it and overflow is Overflow.Reject.

  • CalendarError.NoSuchDay if day is 0, or the month has fewer days and overflow is Overflow.Reject.

  • CalendarError.OutOfRange if the date is outside the range of PlainDate or the calendar has no data for the year.

Method calendar#

silk
pub fn calendar(self: Self) -> Calendar

Returns the calendar of the date.

Method date#

silk
pub fn date(self: Self) -> PlainDate

Returns the same day in the ISO 8601 calendar.

Method withCalendar#

silk
pub fn withCalendar(self: Self, calendar: Calendar) -> Result<CalendarDate, CalendarError>

Returns the same day in calendar.

Errors#

  • CalendarError.OutOfRange if the calendar has no data for the day.

Method year#

silk
pub fn year(self: Self) -> i32

Returns the year, counted on one line through all eras. It can be zero or negative.

Details#

It is the year of the main era of the calendar where that era applies: the ISO 8601 year for gregory and japanese, the year of the Hijra for the Islamic calendars. For chinese and dangi, which do not number their years, it is the ISO 8601 year in which the year starts.

Method month#

silk
pub fn month(self: Self) -> u8

Returns the number of the month in its year, from 1.

Method monthCode#

silk
pub fn monthCode(self: Self) -> MonthCode

Returns the code of the month, which is the same in every year.

Method day#

silk
pub fn day(self: Self) -> u8

Returns the day of the month, from 1.

Method era#

silk
pub fn era(self: Self) -> Option<Era>

Returns the era of the date, or None for iso8601, chinese, and dangi, which have no eras.

Method eraYear#

silk
pub fn eraYear(self: Self) -> Option<i32>

Returns the year in the era of the date, or None for a calendar without eras.

Method dayOfYear#

silk
pub fn dayOfYear(self: Self) -> u16

Returns the day of the year, from 1.

Method daysInMonth#

silk
pub fn daysInMonth(self: Self) -> u8

Returns the number of days in the month of the date.

Method daysInYear#

silk
pub fn daysInYear(self: Self) -> u16

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

Method monthsInYear#

silk
pub fn monthsInYear(self: Self) -> u8

Returns the number of months in the year of the date.

Method inLeapYear#

silk
pub fn inLeapYear(self: Self) -> bool

Returns true when the year of the date is a leap year of the calendar: a year with a 13th month in the Hebrew, Chinese, and Dangi calendars, and a year with one more day in the others.

Method checkedAdd#

silk
pub fn checkedAdd(self: Self, period: Period, overflow: Overflow) -> Result<CalendarDate, CalendarError>

Returns the date that period leads to from this date, counted in the calendar.

Details#

The years are added first and keep the month code: one year after Nisan is Nisan. Then the months are added by counting months of the calendar through the years. If the month reached has no such day, Overflow.Constrain uses its last day. Then the weeks and the days are added, with the whole days of the time part of the period. This is the rule of ECMAScript Temporal.

With Overflow.Constrain, a leap month that the year reached does not have becomes the month that takes its place, as in CalendarDate.fromMonthCode.

Errors#

  • CalendarError.NoSuchMonth or NoSuchDay if overflow is Overflow.Reject and the month or the day does not exist in the year or the month reached.

  • CalendarError.OutOfRange if the result is outside the range of PlainDate or the calendar has no data for it.

Method until#

silk
pub fn until(self: Self, other: CalendarDate, largest: DateUnit) -> Result<Period, CalendarError>

Returns the span from this date to other, counted in the calendar in largest units first. It is negative when other is earlier, and its time part is empty.

Details#

With DateUnit.Year, the result has the most whole years that can be added to this date without passing other, then the most whole months, then the days that are left. With DateUnit.Month it has months and days, with DateUnit.Week weeks and days, and with DateUnit.Day only days. Adding the result to this date with CalendarDate.checkedAdd gives other. This is the rule of ECMAScript Temporal.

Errors#

  • CalendarError.CalendarMismatch if other is in another calendar. Convert one of the dates with CalendarDate.withCalendar first.

Associated function parse#

silk
pub fn parse(text: string) -> Result<CalendarDate, TimeParseError>

Reads a date with a calendar annotation, such as 2026-11-19[u-ca=hebrew].

Details#

The text is the one that PlainDate.parse reads: the date is always written in the ISO 8601 calendar, and the annotation names the calendar of the result. A text without a calendar annotation gives a date in Calendar.Iso8601.

Errors#

  • The errors of PlainDate.parse for the date.

  • TimeParseReason.UnsupportedCalendar if the annotation names no calendar of Calendar.

  • TimeParseReason.OutOfRange if the calendar has no data for the date.

Associated function parseBytes#

silk
pub fn parseBytes(bytes: &[u8]) -> Result<CalendarDate, TimeParseError>

Reads a date with a calendar annotation from the bytes of a text such as 2026-11-19[u-ca=hebrew].

Errors#

  • The errors of PlainDate.parseBytes for the date.

  • TimeParseReason.UnsupportedCalendar if the annotation names no calendar of Calendar.

  • TimeParseReason.OutOfRange if the calendar has no data for the date.

Implementation Equal for CalendarDate#

silk
impl Equal for CalendarDate

Operation equals#

silk
equals: CalendarDate.same

Implementation Display for CalendarDate#

silk
impl Display for CalendarDate

Writes the ISO 8601 date and the calendar annotation, as in 2026-11-19[u-ca=hebrew]. A date in Calendar.Iso8601 has no annotation.

Operation display#

silk
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Implementation Debug for CalendarDate#

silk
impl Debug for CalendarDate

Writes the same text as Display, such as 2026-11-19[u-ca=hebrew].

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Category: Time.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page