Early Preview

This is currently very much a preview. Please feel free to try things out, but don't be upset if anything is not yet working. Feedback is welcome over on our GitHub Dicussions page.

class NodaTime.​CalendarSystem

Assembly: NodaTime

Inheritance: object → CalendarSystem

A calendar system maps the non-calendar-specific "local time line" to human concepts such as years, months and days.

Remarks

<para> 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. </para> <para> If you need to obtain a <see cref="T:NodaTime.CalendarSystem" /> instance, use one of the static properties or methods in this class, such as the <see cref="P:NodaTime.CalendarSystem.Iso" /> property or the <see cref="M:NodaTime.CalendarSystem.GetHebrewCalendar(NodaTime.Calendars.HebrewMonthNumbering)" /> method. </para> <para>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. </para>

Properties

Ids
Returns the IDs of all calendar systems available within Noda Time. The order of the keys is not guaranteed.
public static CalendarSystem
Iso
Returns a calendar system that follows the rules of the ISO-8601 standard, which is compatible with Gregorian for all modern dates.
Remarks As of Noda Time 2.0, this calendar system is equivalent to <see cref="P:NodaTime.CalendarSystem.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.
public static CalendarSystem
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.
Remarks <para>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.</para> <para>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’).</para> <para>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.</para> <para>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.</para>
public string
Id
Returns the unique identifier for this calendar system. This is provides full round-trip capability using <see cref="M:NodaTime.CalendarSystem.ForId(System.String)" /> to retrieve the calendar system from the identifier.
Remarks <para> A unique ID for a calendar is required when serializing types which include a <see cref="T:NodaTime.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. </para> <list type="table"> <listheader> <term>Calendar ID</term> <description>Equivalent factory method or property</description> </listheader> <item> <term>ISO</term> <description> <see cref="P:NodaTime.CalendarSystem.Iso" /> </description> </item> <item> <term>Gregorian</term> <description> <see cref="P:NodaTime.CalendarSystem.Gregorian" /> </description> </item> <item> <term>Coptic</term> <description> <see cref="P:NodaTime.CalendarSystem.Coptic" /> </description> </item> <item> <term>Badi</term> <description> <see cref="P:NodaTime.CalendarSystem.Badi" /> </description> </item> <item> <term>Julian</term> <description> <see cref="P:NodaTime.CalendarSystem.Julian" /> </description> </item> <item> <term>Hijri Civil-Indian</term> <description> <see cref="M:NodaTime.CalendarSystem.GetIslamicCalendar(NodaTime.Calendars.IslamicLeapYearPattern,NodaTime.Calendars.IslamicEpoch)" />(IslamicLeapYearPattern.Indian, IslamicEpoch.Civil)</description> </item> <item> <term>Hijri Civil-Base15</term> <description> <see cref="M:NodaTime.CalendarSystem.GetIslamicCalendar(NodaTime.Calendars.IslamicLeapYearPattern,NodaTime.Calendars.IslamicEpoch)" />(IslamicLeapYearPattern.Base15, IslamicEpoch.Civil)</description> </item> <item> <term>Hijri Civil-Base16</term> <description> <see cref="M:NodaTime.CalendarSystem.GetIslamicCalendar(NodaTime.Calendars.IslamicLeapYearPattern,NodaTime.Calendars.IslamicEpoch)" />(IslamicLeapYearPattern.Base16, IslamicEpoch.Civil)</description> </item> <item> <term>Hijri Civil-HabashAlHasib</term> <description> <see cref="M:NodaTime.CalendarSystem.GetIslamicCalendar(NodaTime.Calendars.IslamicLeapYearPattern,NodaTime.Calendars.IslamicEpoch)" />(IslamicLeapYearPattern.HabashAlHasib, IslamicEpoch.Civil)</description> </item> <item> <term>Hijri Astronomical-Indian</term> <description> <see cref="M:NodaTime.CalendarSystem.GetIslamicCalendar(NodaTime.Calendars.IslamicLeapYearPattern,NodaTime.Calendars.IslamicEpoch)" />(IslamicLeapYearPattern.Indian, IslamicEpoch.Astronomical)</description> </item> <item> <term>Hijri Astronomical-Base15</term> <description> <see cref="M:NodaTime.CalendarSystem.GetIslamicCalendar(NodaTime.Calendars.IslamicLeapYearPattern,NodaTime.Calendars.IslamicEpoch)" />(IslamicLeapYearPattern.Base15, IslamicEpoch.Astronomical)</description> </item> <item> <term>Hijri Astronomical-Base16</term> <description> <see cref="M:NodaTime.CalendarSystem.GetIslamicCalendar(NodaTime.Calendars.IslamicLeapYearPattern,NodaTime.Calendars.IslamicEpoch)" />(IslamicLeapYearPattern.Base16, IslamicEpoch.Astronomical)</description> </item> <item> <term>Hijri Astronomical-HabashAlHasib</term> <description> <see cref="M:NodaTime.CalendarSystem.GetIslamicCalendar(NodaTime.Calendars.IslamicLeapYearPattern,NodaTime.Calendars.IslamicEpoch)" />(IslamicLeapYearPattern.HabashAlHasib, IslamicEpoch.Astronomical)</description> </item> <item> <term>Persian Simple</term> <description> <see cref="P:NodaTime.CalendarSystem.PersianSimple" /> </description> </item> <item> <term>Persian Arithmetic</term> <description> <see cref="P:NodaTime.CalendarSystem.PersianArithmetic" /> </description> </item> <item> <term>Persian Algorithmic</term> <description> <see cref="P:NodaTime.CalendarSystem.PersianAstronomical" /> (see note)</description> </item> <item> <term>Um Al Qura</term> <description> <see cref="P:NodaTime.CalendarSystem.UmAlQura" />()</description> </item> <item> <term>Hebrew Civil</term> <description> <see cref="P:NodaTime.CalendarSystem.HebrewCivil" /> </description> </item> <item> <term>Hebrew Scriptural</term> <description> <see cref="P:NodaTime.CalendarSystem.HebrewScriptural" /> </description> </item> </list> <para> 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. </para>
public string
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.)
public int
MinYear
Gets the minimum valid year (inclusive) within this calendar.
public int
MaxYear
Gets the maximum valid year (inclusive) within this calendar.
Eras
Gets a read-only list of eras used in this calendar system.
public static CalendarSystem
Gregorian
Returns a Gregorian calendar system.
Remarks <para> 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. </para> <para> 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. </para>
public static CalendarSystem
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.
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.
public static CalendarSystem
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.
Remarks <para> 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. </para> <para> 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. </para>
public static CalendarSystem
IslamicBcl
Returns an Islamic calendar system equivalent to the one used by the BCL HijriCalendar.
Remarks This uses the <see cref="F:NodaTime.Calendars.IslamicLeapYearPattern.Base16" /> leap year pattern and the <see cref="F:NodaTime.Calendars.IslamicEpoch.Astronomical" /> epoch. This is equivalent to HijriCalendar when the <c>HijriCalendar.HijriAdjustment</c> is 0.
public static CalendarSystem
PersianSimple
Returns a Persian (also known as Solar Hijri) calendar system implementing the behaviour of the BCL <c>PersianCalendar</c> before .NET 4.6, and the sole Persian calendar in Noda Time 1.3.
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.
public static CalendarSystem
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.
Remarks This calendar is also known as the algorithmic Solar Hijri calendar.
public static CalendarSystem
PersianAstronomical
Returns a Persian (also known as Solar Hijri) calendar system implementing the behaviour of the BCL <c>PersianCalendar</c> from .NET 4.6 onwards (and Windows 10), and the astronomical system described in Wikipedia and Calendrical Calculations.
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.
public static CalendarSystem
HebrewCivil
Returns a Hebrew calendar system using the civil month numbering, equivalent to the one used by the BCL HebrewCalendar.
public static CalendarSystem
HebrewScriptural
Returns a Hebrew calendar system using the scriptural month numbering.
public static CalendarSystem
UmAlQura
Returns an Um Al Qura calendar system - an Islamic calendar system primarily used by Saudi Arabia.
Remarks This is a tabular calendar, relying on pregenerated data.

Methods

public static CalendarSystem
ForId​(string id)
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.
Returns The calendar system with the given ID.
id The ID of the calendar system. This is case-sensitive.
public static CalendarSystem
GetHebrewCalendar​(HebrewMonthNumbering monthNumbering)
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.
Returns A Hebrew calendar system for the given month numbering.
monthNumbering The month numbering system to use
Remarks <para>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.</para> <para>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). </para>
public static CalendarSystem
GetIslamicCalendar​(IslamicLeapYearPattern leapYearPattern, IslamicEpoch epoch)
Returns an Islamic, or Hijri, calendar system.
Returns A suitable Islamic calendar reference; the same reference may be returned by several calls as the object is immutable and thread-safe.
leapYearPattern The pattern of years in the 30-year cycle to consider as leap years
epoch The kind of epoch to use (astronomical or civil)
Remarks <para> 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). </para> <para> 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. </para> <para> 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. </para> <para>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 <see cref="F:NodaTime.Calendars.IslamicEpoch.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 <see cref="F:NodaTime.Calendars.IslamicEpoch.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.</para> <para> 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: </para> <list type="table"> <listheader> <term>Origin</term> <description>Leap years</description> </listheader> <item> <term>Kūshyār ibn Labbān</term> <description>2, 5, 7, 10, 13, 15, 18, 21, 24, 26, 29</description> </item> <item> <term>al-Fazārī</term> <description>2, 5, 7, 10, 13, 16, 18, 21, 24, 26, 29</description> </item> <item> <term>Fātimid (also known as Misri or Bohra)</term> <description>2, 5, 8, 10, 13, 16, 19, 21, 24, 27, 29</description> </item> <item> <term>Habash al-Hasib</term> <description>2, 5, 8, 11, 13, 16, 19, 21, 24, 27, 30</description> </item> </list> <para> 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). </para> <para> 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. </para>
public int
GetAbsoluteYear​(int yearOfEra, Era 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.
Returns The absolute year represented by the specified year of era.
yearOfEra The year within the era.
era The era in which to consider the year
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.
public int
GetMaxYearOfEra​(Era era)
Returns the maximum valid year-of-era in the given era.
Returns The maximum valid year in the given era.
era The era in which to find the greatest year
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.)
public int
GetMinYearOfEra​(Era era)
Returns the minimum valid year-of-era in the given era.
Returns The minimum valid year in the given era.
era The era in which to find the greatest year
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.)
public string
ToString​()
Converts this calendar system to text by simply returning its unique ID.
Returns The ID of this calendar system.
public int
GetDaysInYear​(int year)
Returns the number of days in the given year.
Returns The number of days in the given year.
year The year to determine the number of days in
public int
GetDaysInMonth​(int year, int month)
Returns the number of days in the given month within the given year.
Returns The number of days in the given month and year.
year The year in which to consider the month
month The month to determine the number of days in
public bool
IsLeapYear​(int year)
Returns whether or not the given year is a leap year in this calendar.
Returns True if the given year is a leap year; false otherwise.
year The year to consider.
public int
GetMonthsInYear​(int year)
Returns the maximum valid month (inclusive) within this calendar in the given year.
Returns The maximum month number within the given year.
year The year to consider.
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.)
public bool
Equals​(object obj)
Inherited from object
protected void
Finalize​()
Inherited from object
public int
GetHashCode​()
Inherited from object
GetType​()
Inherited from object
protected object
MemberwiseClone​()
Inherited from object