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:
CalendarDate.yearis one count through all eras, andCalendarDate.eraandCalendarDate.eraYeargive the year as people write it.CalendarDate.monthis the number of the month in its year.CalendarDate.monthCodeis the name of the month that does not change when a year has a leap month.CalendarDate.checkedAddandCalendarDate.untilcount the years and the months of the calendar.
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#
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#
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#
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#
pub enum CalendarA 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#
Iso8601iso8601: the calendar of PlainDate, with the Gregorian leap year rule for every year and
no eras.
Gregory#
Gregorygregory: the ISO 8601 calendar with the eras ce and bce.
Buddhist#
Buddhistbuddhist: the Thai solar calendar, the ISO 8601 calendar with years counted from 543 BCE.
Roc#
Rocroc: the calendar of the Republic of China, the ISO 8601 calendar with years counted from
1912.
Japanese#
Japanesejapanese: the ISO 8601 calendar with the eras of Japan from Meiji on.
Coptic#
Copticcoptic: 12 months of 30 days and a 13th month of 5 or 6 days.
Ethiopic#
Ethiopicethiopic: the Coptic months with years counted from the year 8 CE, the era am.
EthiopicAmeteAlem#
EthiopicAmeteAlemethioaa: the Ethiopic calendar with years counted from the creation of the world, the era
aa, 5500 years earlier.
Hebrew#
Hebrewhebrew: the lunisolar Hebrew calendar, with a 13th month in 7 years of each 19.
Indian#
Indianindian: the Indian national calendar, with years of the Shaka era.
Persian#
Persianpersian: the Solar Hijri calendar of Iran and Afghanistan.
IslamicCivil#
IslamicCivilislamic-civil: the Islamic calendar by rule, with 11 leap years in each 30 and a Friday
epoch.
IslamicTabular#
IslamicTabularislamic-tbla: the Islamic calendar by rule with a Thursday epoch, one day earlier than
islamic-civil.
IslamicUmmAlQura#
IslamicUmmAlQuraislamic-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#
Chinesechinese: the lunisolar Chinese calendar, for the dates 1800-01-25 to 2201-02-03.
Dangi#
Dangidangi: the lunisolar Korean calendar, for the dates 1800-01-25 to 2201-02-03.
Era#
pub enum EraAn era of a calendar: the point from which the years of a date are counted.
Ce#
Cece: the Common Era of gregory and japanese.
Bce#
Bcebce: before the Common Era, in gregory and japanese. Year 1 is the year before 1 CE.
Be#
Bebe: the Buddhist Era of buddhist.
Am#
Amam: the Era of the Martyrs of coptic, the Incarnation Era of ethiopic, and Anno Mundi of
hebrew.
Aa#
Aaaa: Amete Alem, the era of ethioaa and of the ethiopic years before am.
Shaka#
Shakashaka: the Shaka era of indian.
Ap#
Apap: Anno Persico of persian.
Ah#
Ahah: the era of the Hijra in the Islamic calendars.
Bh#
Bhbh: before the Hijra, in the Islamic calendars. Year 1 is the year before 1 AH.
Roc#
Rocroc: the era of the Republic of China, from 1912.
Broc#
Brocbroc: before the Republic of China. Year 1 is 1911.
Meiji#
Meijimeiji: from 1873-01-01, when Japan took the Gregorian calendar, as year 6.
Taisho#
Taishotaisho: from 1912-07-30.
Showa#
Showashowa: from 1926-12-25.
Heisei#
Heiseiheisei: from 1989-01-08.
Reiwa#
Reiwareiwa: from 2019-05-01.
CalendarError#
pub enum CalendarErrorWhy a calendar date cannot be made.
OutOfRange#
OutOfRangeThe 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#
NoSuchMonthThe 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#
NoSuchDayThe month has no such day, and the day is 0 or the overflow rule is Overflow.Reject.
NoSuchEra#
NoSuchEraThe era is not an era of the calendar.
CalendarMismatch#
CalendarMismatchThe two dates of an operation are in different calendars.
MonthCode#
pub struct MonthCodeThe 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#
pub number: u8The number in the code, from 1.
Field leap#
pub leap: booltrue for a leap month, written with L.
Implementation Copy for MonthCode#
impl Copy for MonthCodeCalendarDate#
pub struct CalendarDateA 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#
impl Copy for CalendarDateImplementation Calendar#
impl CalendarAssociated function named#
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#
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#
pub fn name(self: Self) -> string<'static>Returns the identifier of the calendar, such as hebrew or islamic-umalqura.
Method monthsInYear#
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#
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#
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#
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#
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#
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#
pub fn hasEras(self: Self) -> boolReturns true when the dates of the calendar have an era.
Method yearOfEra#
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#
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#
impl Equal for CalendarOperation equals#
equals: Calendar.sameImplementation Display for Calendar#
impl Display for CalendarWrites the identifier of the calendar, such as hebrew.
Operation display#
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for Calendar#
impl Debug for CalendarWrites the same text as Display: the identifier of the calendar.
Operation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Era#
impl EraAssociated function named#
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#
pub fn name(self: Self) -> string<'static>Returns the code of the era, such as ce or reiwa.
Implementation Equal for Era#
impl Equal for EraOperation equals#
equals: Era.sameImplementation Display for Era#
impl Display for EraWrites the code of the era, such as ce.
Operation display#
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for Era#
impl Debug for EraWrites the same text as Display: the code of the era.
Operation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for CalendarError#
impl Debug for CalendarErrorOperation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation MonthCode#
impl MonthCodeAssociated function make#
pub fn make(number: u8, leap: bool) -> MonthCodeReturns the month code with the given number and leap mark. It does not check that a calendar has such a month.
Associated function parse#
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#
impl Equal for MonthCodeOperation equals#
equals: MonthCode.sameImplementation Display for MonthCode#
impl Display for MonthCodeWrites the code as M, two digits, and L for a leap month, as in M05L.
Operation display#
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for MonthCode#
impl Debug for MonthCodeWrites the same text as Display, such as M05L.
Operation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation CalendarDate#
impl CalendarDateAssociated function of#
pub fn of(calendar: Calendar, date: PlainDate) -> Result<CalendarDate, CalendarError>Returns date in calendar.
Errors#
CalendarError.OutOfRangeif the calendar has no data for the date. OnlyChineseandDangihave a limit: 1800-01-25 to 2201-02-03.
Associated function fromFields#
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.NoSuchMonthifmonthis 0, or the year has fewer months andoverflowisOverflow.Reject. WithOverflow.Constrainthe last month is used.CalendarError.NoSuchDayifdayis 0, or the month has fewer days andoverflowisOverflow.Reject. WithOverflow.Constrainthe last day is used.CalendarError.OutOfRangeif the date is outside the range ofPlainDateor the calendar has no data for the year.
Associated function fromMonthCode#
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.NoSuchMonthif no year of the calendar has a month with that code, or this year does not have it andoverflowisOverflow.Reject.CalendarError.NoSuchDayifdayis 0, or the month has fewer days andoverflowisOverflow.Reject.CalendarError.OutOfRangeif the date is outside the range ofPlainDateor the calendar has no data for the year.
Method calendar#
pub fn calendar(self: Self) -> CalendarReturns the calendar of the date.
Method date#
pub fn date(self: Self) -> PlainDateReturns the same day in the ISO 8601 calendar.
Method withCalendar#
pub fn withCalendar(self: Self, calendar: Calendar) -> Result<CalendarDate, CalendarError>Returns the same day in calendar.
Errors#
CalendarError.OutOfRangeif the calendar has no data for the day.
Method year#
pub fn year(self: Self) -> i32Returns 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#
pub fn month(self: Self) -> u8Returns the number of the month in its year, from 1.
Method monthCode#
pub fn monthCode(self: Self) -> MonthCodeReturns the code of the month, which is the same in every year.
Method day#
pub fn day(self: Self) -> u8Returns the day of the month, from 1.
Method era#
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#
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#
pub fn dayOfYear(self: Self) -> u16Returns the day of the year, from 1.
Method daysInMonth#
pub fn daysInMonth(self: Self) -> u8Returns the number of days in the month of the date.
Method daysInYear#
pub fn daysInYear(self: Self) -> u16Returns the number of days in the year of the date.
Method monthsInYear#
pub fn monthsInYear(self: Self) -> u8Returns the number of months in the year of the date.
Method inLeapYear#
pub fn inLeapYear(self: Self) -> boolReturns 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#
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.NoSuchMonthorNoSuchDayifoverflowisOverflow.Rejectand the month or the day does not exist in the year or the month reached.CalendarError.OutOfRangeif the result is outside the range ofPlainDateor the calendar has no data for it.
Method until#
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.CalendarMismatchifotheris in another calendar. Convert one of the dates withCalendarDate.withCalendarfirst.
Associated function parse#
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.parsefor the date.TimeParseReason.UnsupportedCalendarif the annotation names no calendar ofCalendar.TimeParseReason.OutOfRangeif the calendar has no data for the date.
Associated function parseBytes#
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.parseBytesfor the date.TimeParseReason.UnsupportedCalendarif the annotation names no calendar ofCalendar.TimeParseReason.OutOfRangeif the calendar has no data for the date.
Implementation Equal for CalendarDate#
impl Equal for CalendarDateOperation equals#
equals: CalendarDate.sameImplementation Display for CalendarDate#
impl Display for CalendarDateWrites 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#
effect fn display(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterImplementation Debug for CalendarDate#
impl Debug for CalendarDateWrites the same text as Display, such as 2026-11-19[u-ca=hebrew].
Operation debug#
effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
! WriterError
? &mut WriterCategory: 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.