Class 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
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
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
Declaration
public IList<Era> Eras { get; }
Property Value
Type | Description |
---|---|
IList<Era> | A read-only list of eras used in this calendar system. |
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.
Gregorian
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
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. |
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.
See Also
HebrewScriptural
Declaration
public static CalendarSystem HebrewScriptural { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | A Hebrew calendar system using the scriptural month numbering. |
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.
See Also
Id
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 ID | Equivalent 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
Declaration
public static IEnumerable<string> Ids { get; }
Property Value
Type | Description |
---|---|
IEnumerable<string> | The IDs of all calendar systems available within Noda Time. |
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.
IslamicBcl
Declaration
public static CalendarSystem IslamicBcl { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | An Islamic calendar system equivalent to the one used by the BCL. |
Remarks
HijriCalendar.HijriAdjustment
is 0.
See Also
Iso
Declaration
public static CalendarSystem Iso { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | The ISO calendar system. |
Remarks
Julian
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
MaxYear
Declaration
public int MaxYear { get; }
Property Value
Type | Description |
---|---|
int | The maximum valid year (inclusive) within this calendar. |
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.
MinYear
Declaration
public int MinYear { get; }
Property Value
Type | Description |
---|---|
int | The minimum valid year (inclusive) within this calendar. |
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.
Name
Declaration
public string Name { get; }
Property Value
Type | Description |
---|---|
string | The name of this calendar system. |
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.
PersianArithmetic
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
PersianAstronomical
PersianCalendar
from .NET 4.6 onwards (and Windows 10), and the astronomical
system described in Wikipedia and Calendrical Calculations.
Declaration
public static CalendarSystem PersianAstronomical { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | A Persian calendar system using astronomical calculations to determine leap years. |
Remarks
PersianSimple
PersianCalendar
before .NET 4.6, and the sole Persian calendar in Noda Time 1.3.
Declaration
public static CalendarSystem PersianSimple { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | A Persian calendar system using a simple 33-year leap cycle. |
Remarks
UmAlQura
Declaration
public static CalendarSystem UmAlQura { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | A calendar system for the Um Al Qura calendar. |
Remarks
Methods
ForId(string)
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. |
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.
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)
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
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)
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. |
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.
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException | The given year / month combination is invalid for this calendar. |
GetDaysInYear(int)
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. |
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.
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException | The given year is invalid for this calendar. |
GetHebrewCalendar(HebrewMonthNumbering)
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)
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:
Origin | Leap years |
---|---|
Kūshyār ibn Labbān | 2, 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-Hasib | 2, 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)
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
Exceptions
Type | Condition |
---|---|
ArgumentException | era is not an era used in this calendar. |
GetMinYearOfEra(Era)
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
Exceptions
Type | Condition |
---|---|
ArgumentException | era is not an era used in this calendar. |
GetMonthsInYear(int)
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
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)
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. |
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.
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()
Declaration
public override string ToString()
Returns
Type | Description |
---|---|
string | The ID of this calendar system. |
Overrides
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.