Class CalendarSystem

A calendar system maps the non-calendar-specific "local time line" to human concepts such as years, months and days.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Inheritance
object
CalendarSystem
Inherited Members
Namespace: NodaTime
Assembly: NodaTime.dll
Syntax
public sealed class CalendarSystem
Remarks

Many developers will never need to touch this class, other than to potentially ask a calendar how many days are in a particular year/month and the like. Noda Time defaults to using the ISO-8601 calendar anywhere that a calendar system is required but hasn't been explicitly specified.

If you need to obtain a CalendarSystem instance, use one of the static properties or methods in this class, such as the Iso property or the GetHebrewCalendar(HebrewMonthNumbering) method.

Although this class is currently sealed (as of Noda Time 1.2), in the future this decision may be reversed. In any case, there is no current intention for third-party developers to be able to implement their own calendar systems (for various reasons). If you require a calendar system which is not currently supported, please file a feature request and we'll see what we can do.

Properties

Badi

Returns the Badíʿ (meaning "wondrous" or "unique") calendar, as described at https://en.wikipedia.org/wiki/Badi_calendar. This is a purely solar calendar with years starting at the vernal equinox.
Since 2.3.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem Badi { get; }
Property Value
Type Description
CalendarSystem The Badíʿ calendar system.
Remarks

The Badíʿ calendar was developed and defined by the founders of the Bahá'í Faith in the mid to late 1800's A.D. The first year in the calendar coincides with 1844 A.D. Years are labeled "B.E." for Bahá'í Era.

A year consists of 19 months, each with 19 days. Each day starts at sunset. Years are grouped into sets of 19 "Unities" (Váḥid) and 19 Unities make up 1 "All Things" (Kull-i-Shay’).

A period of days (usually 4 or 5, called Ayyám-i-Há) occurs between the 18th and 19th months. The length of this period of intercalary days is solely determined by the date of the following vernal equinox. The vernal equinox is a momentary point in time, so the "date" of the equinox is determined by the date (beginning at sunset) in effect in Tehran, Iran at the moment of the equinox.

In this Noda Time implementation, days start at midnight and lookup tables are used to determine vernal equinox dates. Ayyám-i-Há is internally modelled as extra days added to the 18th month. As a result, a few functions will not work as expected for Ayyám-i-Há, such as EndOfMonth.

Coptic

Returns a Coptic calendar system, which defines every fourth year as leap, much like the Julian calendar. The year is broken down into 12 months, each 30 days in length. An extra period at the end of the year is either 5 or 6 days in length. In this implementation, it is considered a 13th month.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem Coptic { get; }
Property Value
Type Description
CalendarSystem A suitable Coptic calendar reference; the same reference may be returned by several calls as the object is immutable and thread-safe.
Remarks

Year 1 in the Coptic calendar began on August 29, 284 CE (Julian), thus Coptic years do not begin at the same time as Julian years. This calendar is not proleptic, as it does not allow dates before the first Coptic year.

This implementation defines a day as midnight to midnight exactly as per the ISO calendar. Some references indicate that a Coptic day starts at sunset on the previous ISO day, but this has not been confirmed and is not implemented.

Eras

Gets a read-only list of eras used in this calendar system.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public IList<Era> Eras { get; }
Property Value
Type Description
IList<Era> A read-only list of eras used in this calendar system.

Gregorian

Returns a Gregorian calendar system.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem Gregorian { get; }
Property Value
Type Description
CalendarSystem A Gregorian calendar system.
Remarks

The Gregorian calendar system defines every fourth year as leap, unless the year is divisible by 100 and not by 400. This improves upon the Julian calendar leap year rule.

Although the Gregorian calendar did not exist before 1582 CE, this calendar system assumes it did, thus it is proleptic. This implementation also fixes the start of the year at January 1.

HebrewCivil

Returns a Hebrew calendar system using the civil month numbering, equivalent to the one used by the BCL HebrewCalendar.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem HebrewCivil { get; }
Property Value
Type Description
CalendarSystem A Hebrew calendar system using the civil month numbering, equivalent to the one used by the BCL.
See Also

HebrewScriptural

Returns a Hebrew calendar system using the scriptural month numbering.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem HebrewScriptural { get; }
Property Value
Type Description
CalendarSystem A Hebrew calendar system using the scriptural month numbering.
See Also

Id

Returns the unique identifier for this calendar system. This is provides full round-trip capability using ForId(string) to retrieve the calendar system from the identifier.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public string Id { get; }
Property Value
Type Description
string The unique identifier for this calendar system.
Remarks

A unique ID for a calendar is required when serializing types which include a CalendarSystem. As of 2 Nov 2012 (ISO calendar) there are no ISO or RFC standards for naming a calendar system. As such, the identifiers provided here are specific to Noda Time, and are not guaranteed to interoperate with any other date and time API.

Calendar IDEquivalent factory method or property
ISO Iso
Gregorian Gregorian
Coptic Coptic
Badi Badi
Julian Julian
Hijri Civil-Indian GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Indian, IslamicEpoch.Civil)
Hijri Civil-Base15 GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Base15, IslamicEpoch.Civil)
Hijri Civil-Base16 GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Base16, IslamicEpoch.Civil)
Hijri Civil-HabashAlHasib GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.HabashAlHasib, IslamicEpoch.Civil)
Hijri Astronomical-Indian GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Indian, IslamicEpoch.Astronomical)
Hijri Astronomical-Base15 GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Base15, IslamicEpoch.Astronomical)
Hijri Astronomical-Base16 GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Base16, IslamicEpoch.Astronomical)
Hijri Astronomical-HabashAlHasib GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.HabashAlHasib, IslamicEpoch.Astronomical)
Persian Simple PersianSimple
Persian Arithmetic PersianArithmetic
Persian Algorithmic PersianAstronomical (see note)
Um Al Qura UmAlQura()
Hebrew Civil HebrewCivil
Hebrew Scriptural HebrewScriptural

The ID "Persian Algorithmic" for the Persian Astronomical calendar is an unfortunate error. The ID has been incorrect in Noda Time for so long that "fixing" it now would cause compatibility issues between systems storing or exchanging Noda Time data.

Ids

Returns the IDs of all calendar systems available within Noda Time. The order of the keys is not guaranteed.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static IEnumerable<string> Ids { get; }
Property Value
Type Description
IEnumerable<string> The IDs of all calendar systems available within Noda Time.

IslamicBcl

Returns an Islamic calendar system equivalent to the one used by the BCL HijriCalendar.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem IslamicBcl { get; }
Property Value
Type Description
CalendarSystem An Islamic calendar system equivalent to the one used by the BCL.
Remarks
This uses the Base16 leap year pattern and the Astronomical epoch. This is equivalent to HijriCalendar when the HijriCalendar.HijriAdjustment is 0.
See Also

Iso

Returns a calendar system that follows the rules of the ISO-8601 standard, which is compatible with Gregorian for all modern dates.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem Iso { get; }
Property Value
Type Description
CalendarSystem The ISO calendar system.
Remarks
As of Noda Time 2.0, this calendar system is equivalent to Gregorian. The only areas in which the calendars differed were around centuries, and the members relating to those differences were removed in Noda Time 2.0. The distinction between Gregorian and ISO has been maintained for the sake of simplicity, compatibility and consistency.

Julian

Returns a pure proleptic Julian calendar system, which defines every fourth year as a leap year. This implementation follows the leap year rule strictly, even for dates before 8 CE, where leap years were actually irregular.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem Julian { get; }
Property Value
Type Description
CalendarSystem A suitable Julian calendar reference; the same reference may be returned by several calls as the object is immutable and thread-safe.
Remarks
Although the Julian calendar did not exist before 45 BCE, this calendar assumes it did, thus it is proleptic. This implementation also fixes the start of the year at January 1.

MaxYear

Gets the maximum valid year (inclusive) within this calendar.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int MaxYear { get; }
Property Value
Type Description
int The maximum valid year (inclusive) within this calendar.

MinYear

Gets the minimum valid year (inclusive) within this calendar.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int MinYear { get; }
Property Value
Type Description
int The minimum valid year (inclusive) within this calendar.

Name

Returns the name of this calendar system. Each kind of calendar system has a unique name, but this does not usually provide enough information for round-tripping. (For example, the name of an Islamic calendar system does not indicate which kind of leap cycle it uses.)
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public string Name { get; }
Property Value
Type Description
string The name of this calendar system.

PersianArithmetic

Returns a Persian (also known as Solar Hijri) calendar system implementing the behaviour proposed by Ahmad Birashk with nested cycles of years determining which years are leap years.
Since 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem PersianArithmetic { get; }
Property Value
Type Description
CalendarSystem A Persian calendar system using cycles-within-cycles of years to determine leap years.
Remarks
This calendar is also known as the algorithmic Solar Hijri calendar.

PersianAstronomical

Returns a Persian (also known as Solar Hijri) calendar system implementing the behaviour of the BCL PersianCalendar from .NET 4.6 onwards (and Windows 10), and the astronomical system described in Wikipedia and Calendrical Calculations.
Since 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem PersianAstronomical { get; }
Property Value
Type Description
CalendarSystem A Persian calendar system using astronomical calculations to determine leap years.
Remarks
This implementation uses data derived from the .NET 4.6 implementation (with the data built into Noda Time, so there's no BCL dependency) for simplicity; the actual implementation involves computing the time of noon in Iran, and is complex.

PersianSimple

Returns a Persian (also known as Solar Hijri) calendar system implementing the behaviour of the BCL PersianCalendar before .NET 4.6, and the sole Persian calendar in Noda Time 1.3.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem PersianSimple { get; }
Property Value
Type Description
CalendarSystem A Persian calendar system using a simple 33-year leap cycle.
Remarks
This implementation uses a simple 33-year leap cycle, where years 1, 5, 9, 13, 17, 22, 26, and 30 in each cycle are leap years.

UmAlQura

Returns an Um Al Qura calendar system - an Islamic calendar system primarily used by Saudi Arabia.
Since 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem UmAlQura { get; }
Property Value
Type Description
CalendarSystem A calendar system for the Um Al Qura calendar.
Remarks
This is a tabular calendar, relying on pregenerated data.

Methods

ForId(string)

Fetches a calendar system by its unique identifier. This provides full round-tripping of a calendar system. This method will always return the same reference for the same ID.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem ForId(string id)
Parameters
Type Name Description
string id The ID of the calendar system. This is case-sensitive.
Returns
Type Description
CalendarSystem The calendar system with the given ID.
Exceptions
Type Condition
KeyNotFoundException No calendar system for the specified ID can be found.
NotSupportedException The calendar system with the specified ID is known, but not supported on this platform.
See Also

GetAbsoluteYear(int, Era)

Returns the "absolute year" (the one used throughout most of the API, without respect to eras) from a year-of-era and an era.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int GetAbsoluteYear(int yearOfEra, Era era)
Parameters
Type Name Description
int yearOfEra The year within the era.
Era era The era in which to consider the year
Returns
Type Description
int The absolute year represented by the specified year of era.
Remarks
For example, in the Gregorian and Julian calendar systems, the BCE era starts at year 1, which is equivalent to an "absolute year" of 0 (then BCE year 2 has an absolute year of -1, and so on). The absolute year is the year that is used throughout the API; year-of-era is typically used primarily when formatting and parsing date values to and from text.
Exceptions
Type Condition
ArgumentOutOfRangeException yearOfEra is out of the range of years for the given era.
ArgumentException era is not an era used in this calendar.

GetDaysInMonth(int, int)

Returns the number of days in the given month within the given year.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int GetDaysInMonth(int year, int month)
Parameters
Type Name Description
int year The year in which to consider the month
int month The month to determine the number of days in
Returns
Type Description
int The number of days in the given month and year.
Exceptions
Type Condition
ArgumentOutOfRangeException The given year / month combination is invalid for this calendar.

GetDaysInYear(int)

Returns the number of days in the given year.
Since 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int GetDaysInYear(int year)
Parameters
Type Name Description
int year The year to determine the number of days in
Returns
Type Description
int The number of days in the given year.
Exceptions
Type Condition
ArgumentOutOfRangeException The given year is invalid for this calendar.

GetHebrewCalendar(HebrewMonthNumbering)

Returns a Hebrew calendar, as described at https://en.wikipedia.org/wiki/Hebrew_calendar. This is a purely mathematical calculator, applied proleptically to the period where the real calendar was observational.
Since 1.3.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem GetHebrewCalendar(HebrewMonthNumbering monthNumbering)
Parameters
Type Name Description
HebrewMonthNumbering monthNumbering The month numbering system to use
Returns
Type Description
CalendarSystem A Hebrew calendar system for the given month numbering.
Remarks

Please note that support for the Hebrew calendar is somewhat experimental, particularly in terms of calculations involving adding or subtracting years. Additionally, text formatting and parsing using month names is not currently supported, due to the challenges of handling leap months. It is hoped that this will be improved in future versions.

The implementation for this was taken from https://www.cs.tau.ac.il/~nachum/calendar-book/papers/calendar.ps, which is a public domain algorithm presumably equivalent to that given in the Calendrical Calculations book by the same authors (Nachum Dershowitz and Edward Reingold).

GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)

Returns an Islamic, or Hijri, calendar system.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static CalendarSystem GetIslamicCalendar(IslamicLeapYearPattern leapYearPattern, IslamicEpoch epoch)
Parameters
Type Name Description
IslamicLeapYearPattern leapYearPattern The pattern of years in the 30-year cycle to consider as leap years
IslamicEpoch epoch The kind of epoch to use (astronomical or civil)
Returns
Type Description
CalendarSystem A suitable Islamic calendar reference; the same reference may be returned by several calls as the object is immutable and thread-safe.
Remarks

This returns a tabular calendar, rather than one based on lunar observation. This calendar is a lunar calendar with 12 months, each of 29 or 30 days, resulting in a year of 354 days (or 355 on a leap year).

Year 1 in the Islamic calendar began on July 15th or 16th, 622 CE (Julian), thus Islamic years do not begin at the same time as Julian years. This calendar is not proleptic, as it does not allow dates before the first Islamic year.

There are two basic forms of the Islamic calendar, the tabular and the observed. The observed form cannot easily be used by computers as it relies on human observation of the new moon. The tabular calendar, implemented here, is an arithmetic approximation of the observed form that follows relatively simple rules.

You should choose an epoch based on which external system you wish to be compatible with. The epoch beginning on July 16th is the more common one for the tabular calendar, so using Civil would usually be a logical choice. However, Windows uses July 15th, so if you need to be compatible with other Windows systems, you may wish to use Astronomical. The fact that the Islamic calendar traditionally starts at dusk, a Julian day traditionally starts at noon, and all calendar systems in Noda Time start their days at midnight adds somewhat inevitable confusion to the mix, unfortunately.

The tabular form of the calendar defines 12 months of alternately 30 and 29 days. The last month is extended to 30 days in a leap year. Leap years occur according to a 30 year cycle. There are four recognised patterns of leap years in the 30 year cycle:

OriginLeap years
Kūshyār ibn Labbān2, 5, 7, 10, 13, 15, 18, 21, 24, 26, 29
al-Fazārī2, 5, 7, 10, 13, 16, 18, 21, 24, 26, 29
Fātimid (also known as Misri or Bohra)2, 5, 8, 10, 13, 16, 19, 21, 24, 27, 29
Habash al-Hasib2, 5, 8, 11, 13, 16, 19, 21, 24, 27, 30

The leap year pattern to use is determined from the first parameter to this factory method. The second parameter determines which epoch is used - the "astronomical" or "Thursday" epoch (July 15th 622CE) or the "civil" or "Friday" epoch (July 16th 622CE).

This implementation defines a day as midnight to midnight exactly as per the ISO calendar. This correct start of day is at sunset on the previous day, however this cannot readily be modelled and has been ignored.

GetMaxYearOfEra(Era)

Returns the maximum valid year-of-era in the given era.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int GetMaxYearOfEra(Era era)
Parameters
Type Name Description
Era era The era in which to find the greatest year
Returns
Type Description
int The maximum valid year in the given era.
Remarks
Note that depending on the calendar system, it's possible that only part of the returned year falls within the given era. It is also possible that the returned value represents the earliest year of the era rather than the latest year. (See the BC era in the Gregorian calendar, for example.)
Exceptions
Type Condition
ArgumentException era is not an era used in this calendar.

GetMinYearOfEra(Era)

Returns the minimum valid year-of-era in the given era.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int GetMinYearOfEra(Era era)
Parameters
Type Name Description
Era era The era in which to find the greatest year
Returns
Type Description
int The minimum valid year in the given era.
Remarks
Note that depending on the calendar system, it's possible that only part of the returned year falls within the given era. It is also possible that the returned value represents the latest year of the era rather than the earliest year. (See the BC era in the Gregorian calendar, for example.)
Exceptions
Type Condition
ArgumentException era is not an era used in this calendar.

GetMonthsInYear(int)

Returns the maximum valid month (inclusive) within this calendar in the given year.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int GetMonthsInYear(int year)
Parameters
Type Name Description
int year The year to consider.
Returns
Type Description
int The maximum month number within the given year.
Remarks
It is assumed that in all calendars, every month between 1 and this month number is valid for the given year. This does not necessarily mean that the first month of the year is 1, however. (See the Hebrew calendar system using the scriptural month numbering system for example.)
Exceptions
Type Condition
ArgumentOutOfRangeException The given year is invalid for this calendar. Note that some implementations may return a month rather than throw this exception (for example, if all years have the same number of months in this calendar system). Failure to throw an exception should not be treated as an indication that the year is valid.

IsLeapYear(int)

Returns whether or not the given year is a leap year in this calendar.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public bool IsLeapYear(int year)
Parameters
Type Name Description
int year The year to consider.
Returns
Type Description
bool True if the given year is a leap year; false otherwise.
Exceptions
Type Condition
ArgumentOutOfRangeException The given year is invalid for this calendar. Note that some implementations may return a value rather than throw this exception. Failure to throw an exception should not be treated as an indication that the year is valid.

ToString()

Converts this calendar system to text by simply returning its unique ID.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public override string ToString()
Returns
Type Description
string The ID of this calendar system.
Overrides