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
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. (The value returned is never null.) |
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. (The value returned is never null.) |
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. (The value returned is never null.) |
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. (The value returned is never null.) |
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. (The value returned is never null.) |
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. (The value returned is never null.) |
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 |
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 Astronomical | PersianAstronomical |
Um Al Qura | UmAlQura() |
Hebrew Civil | HebrewCivil |
Hebrew Scriptural | HebrewScriptural |
Ids
Declaration
public static IEnumerable<string> Ids { get; }
Property Value
Type | Description |
---|---|
IEnumerable<String> | The IDs of all calendar systems available within Noda Time. (The value returned is never null.) |
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. (The value returned is never null.) |
Remarks
HijriCalendar.HijriAdjustment
is 0.
See Also
Iso
Declaration
public static CalendarSystem Iso { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | The ISO calendar system. (The value returned is never null.) |
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. (The value returned is never null.) |
Remarks
MaxYear
Declaration
public int MaxYear { get; }
Property Value
Type | Description |
---|---|
Int32 | 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 |
---|---|
Int32 | 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. (The value returned is never null.) |
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
PersianCalendar
from .NET 4.6 onwards (and Windows 10), and the astronomical
system described in Wikipedia and Calendrical Calculations.
Declaration
public static CalendarSystem PersianArithmetic { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | A Persian calendar system using astronomical calculations to determine leap years. (The value returned is never null.) |
Remarks
PersianAstronomical
Declaration
public static CalendarSystem PersianAstronomical { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | A Persian calendar system using cycles-within-cycles of years to determine leap years. (The value returned is never null.) |
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. (The value returned is never null.) |
Remarks
UmAlQura
Declaration
public static CalendarSystem UmAlQura { get; }
Property Value
Type | Description |
---|---|
CalendarSystem | A calendar system for the Um Al Qura calendar. (The value returned is never null.) |
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. (The value returned is never null.) |
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. |
ArgumentNullException | id is null. |
See Also
GetAbsoluteYear(Int32, Era)
Declaration
public int GetAbsoluteYear(int yearOfEra, Era era)
Parameters
Type | Name | Description |
---|---|---|
Int32 | yearOfEra | The year within the era. |
Era | era | The era in which to consider the year |
Returns
Type | Description |
---|---|
Int32 | 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. |
ArgumentNullException | era is null. |
GetDaysInMonth(Int32, Int32)
Declaration
public int GetDaysInMonth(int year, int month)
Parameters
Type | Name | Description |
---|---|---|
Int32 | year | The year in which to consider the month |
Int32 | month | The month to determine the number of days in |
Returns
Type | Description |
---|---|
Int32 | 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(Int32)
Declaration
public int GetDaysInYear(int year)
Parameters
Type | Name | Description |
---|---|---|
Int32 | year | The year to determine the number of days in |
Returns
Type | Description |
---|---|
Int32 | 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. (The value returned is never null.) |
Remarks
Please note that in version 1.3.0 of Noda Time, 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 http://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. (The value returned is never null.) |
Remarks
This returns a tablular 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 |
---|---|
Int32 | The maximum valid year in the given era. |
Remarks
Exceptions
Type | Condition |
---|---|
ArgumentException | era is not an era used in this calendar. |
ArgumentNullException | era is null. |
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 |
---|---|
Int32 | The minimum valid year in the given eraera. |
Remarks
Exceptions
Type | Condition |
---|---|
ArgumentException | era is not an era used in this calendar. |
ArgumentNullException | era is null. |
GetMonthsInYear(Int32)
Declaration
public int GetMonthsInYear(int year)
Parameters
Type | Name | Description |
---|---|---|
Int32 | year | The year to consider. |
Returns
Type | Description |
---|---|
Int32 | 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(Int32)
Declaration
public bool IsLeapYear(int year)
Parameters
Type | Name | Description |
---|---|---|
Int32 | year | The year to consider. |
Returns
Type | Description |
---|---|
Boolean | 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.