Noda Time
Show / Hide Table of Contents

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 net35-Client, PCL
Inheritance
Object
CalendarSystem
Inherited Members
Object.Equals(Object)
Object.Equals(Object, Object)
Object.ReferenceEquals(Object, Object)
Object.GetHashCode()
Object.GetType()
Object.MemberwiseClone()
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 GetGregorianCalendar(Int32) 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

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 net35-Client, PCL
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.

This calendar always has at least 4 days in the first week of the week-year.

Eras

Returns a read-only list of eras used in this calendar system.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public IList<Era> Eras { get; }
Property Value
Type Description
IList<Era>

Gregorian

Returns a Gregorian calendar system with at least 4 days in the first week of a week-year.
Since 1.4.x
Availability net35-Client, PCL
Declaration
public static CalendarSystem Gregorian { get; }
Property Value
Type Description
CalendarSystem A Gregorian calendar system with at least 4 days in the first week of a week-year. (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

Returns a Hebrew calendar system using the civil month numbering, equivalent to the one used by the BCL HebrewCalendar.
Since 1.4.x
Availability net35-Client, PCL
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.)
See Also
GetHebrewCalendar(HebrewMonthNumbering)

HebrewScriptural

Returns a Hebrew calendar system using the scriptural month numbering.
Since 1.4.x
Availability net35-Client, PCL
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.)
See Also
GetHebrewCalendar(HebrewMonthNumbering)

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 net35-Client, PCL
Declaration
public string Id { get; }
Property Value
Type Description
String
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
ISOIso
Gregorian 1GetGregorianCalendar(Int32)(1)
Gregorian 2GetGregorianCalendar(Int32)(2)
Gregorian 3GetGregorianCalendar(Int32)(3)
Gregorian 3GetGregorianCalendar(Int32)(4)
Gregorian 5GetGregorianCalendar(Int32)(5)
Gregorian 6GetGregorianCalendar(Int32)(6)
Gregorian 7GetGregorianCalendar(Int32)(7)
Coptic 1GetCopticCalendar(Int32)(1)
Coptic 2GetCopticCalendar(Int32)(2)
Coptic 3GetCopticCalendar(Int32)(3)
Coptic 4GetCopticCalendar(Int32)(4)
Coptic 5GetCopticCalendar(Int32)(5)
Coptic 6GetCopticCalendar(Int32)(6)
Coptic 7GetCopticCalendar(Int32)(7)
Julian 1GetJulianCalendar(Int32)(1)
Julian 2GetJulianCalendar(Int32)(2)
Julian 3GetJulianCalendar(Int32)(3)
Julian 4GetJulianCalendar(Int32)(4)
Julian 5GetJulianCalendar(Int32)(5)
Julian 6GetJulianCalendar(Int32)(6)
Julian 7GetJulianCalendar(Int32)(7)
Hijri Civil-IndianGetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Indian, IslamicEpoch.Civil)
Hijri Civil-Base15GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Base15, IslamicEpoch.Civil)
Hijri Civil-Base16GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Base16, IslamicEpoch.Civil)
Hijri Civil-HabashAlHasibGetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.HabashAlHasib, IslamicEpoch.Civil)
Hijri Astronomical-IndianGetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Indian, IslamicEpoch.Astronomical)
Hijri Astronomical-Base15GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Base15, IslamicEpoch.Astronomical)
Hijri Astronomical-Base16GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.Base16, IslamicEpoch.Astronomical)
Hijri Astronomical-HabashAlHasibGetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)(IslamicLeapYearPattern.HabashAlHasib, IslamicEpoch.Astronomical)
PersianGetPersianCalendar()
HebrewGetHebrewCalendar(HebrewMonthNumbering)

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 net35-Client, PCL
Declaration
public static IEnumerable<string> Ids { get; }
Property Value
Type Description
IEnumerable<String>

IslamicBcl

Returns an Islamic calendar system equivalent to the one used by the BCL HijriCalendar.
Since 1.4.x
Availability net35-Client, PCL
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
This uses the Base16 leap year pattern and the Astronomical epoch. This is equivalent to HijriCalendar when the HijriCalendar.HijriAdjustment is 0.
See Also
GetIslamicCalendar(IslamicLeapYearPattern, IslamicEpoch)

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 net35-Client, PCL
Declaration
public static CalendarSystem Iso { get; }
Property Value
Type Description
CalendarSystem
Remarks

When ISO does not define a field, but it can be determined (such as AM/PM) it is included.

With the exception of century related fields, the ISO calendar is exactly the same as the Gregorian calendar system. In the ISO system, centuries and year of century are zero based. For all years, the century is determined by dropping the last two digits of the year, ignoring sign. The year of century is the value of the last two year digits.

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 net35-Client, PCL
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
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

The maximum valid year (inclusive) within this calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int MaxYear { get; }
Property Value
Type Description
Int32

MinYear

The minimum valid year (inclusive) within this calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int MinYear { get; }
Property Value
Type Description
Int32

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, and other calendars specify the minimum number of days in the first week of a year.)
Since 1.0.x
Availability net35-Client, PCL
Declaration
public string Name { get; }
Property Value
Type Description
String

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 net35-Client, PCL
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
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.

UsesIsoDayOfWeek

Returns whether the day-of-week field refers to ISO days. If true, types such as LocalDateTime can use the IsoDayOfWeek property to avoid using magic numbers. This defaults to true, but can be overridden by specific calendars.
Since 1.0.x
Availability net35-Client, PCL
Declaration
[Obsolete("Removed in 2.0 as all calendar systems are deemed to use ISO days.")]
public bool UsesIsoDayOfWeek { get; }
Property Value
Type Description
Boolean

Methods

ForId(String)

Fetches a calendar system by its unique identifier. This provides full round-tripping of a calendar system. It is not guaranteed that calling this method twice with the same identifier will return identical references, but the references objects will be equal.
Since 1.0.x
Availability net35-Client, PCL
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
System.Collections.Generic.KeyNotFoundException No calendar system for the specified ID can be found.
See Also
Id

GetAbsoluteYear(Int32, 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 net35-Client, PCL
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
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.
ArgumentNullException era is null.

GetCopticCalendar(Int32)

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.0.x
Availability net35-Client, PCL
Declaration
[Obsolete("Use the Coptic property, then WeekYearRules for specific week-year rules for compatibility with 2.0.")]
public static CalendarSystem GetCopticCalendar(int minDaysInFirstWeek)
Parameters
Type Name Description
Int32 minDaysInFirstWeek The minimum number of days in the first week of the year. When computing the WeekOfWeekYear and WeekYear properties of a particular date, this is used to decide at what point the week year changes.
Returns
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.

GetDaysInMonth(Int32, Int32)

Returns the number of days in the given month within the given year.
Since 1.0.x
Availability net35-Client, PCL
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.
Exceptions
Type Condition
ArgumentOutOfRangeException The given year / month combination is invalid for this calendar.

GetGregorianCalendar(Int32)

Returns a pure proleptic Gregorian calendar system, which 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.
Since 1.0.x
Availability net35-Client, PCL
Declaration
[Obsolete("Use the Gregorian property, then WeekYearRules for specific week-year rules for compatibility with 2.0.")]
public static CalendarSystem GetGregorianCalendar(int minDaysInFirstWeek)
Parameters
Type Name Description
Int32 minDaysInFirstWeek The minimum number of days in the first week of the year. When computing the WeekOfWeekYear and WeekYear properties of a particular date, this is used to decide at what point the week year changes.
Returns
Type Description
CalendarSystem A suitable Gregorian calendar reference; the same reference may be returned by several calls as the object is immutable and thread-safe.
Remarks
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.

GetHebrewCalendar(HebrewMonthNumbering)

Returns a Hebrew calendar, as described at http://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 net35-Client, PCL
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 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)

Returns an Islamic, or Hijri, calendar system.
Since 1.0.x
Availability net35-Client, PCL
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 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:

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.

GetJulianCalendar(Int32)

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.0.x
Availability net35-Client, PCL
Declaration
[Obsolete("Use the Julian property, then WeekYearRules for specific week-year rules for compatibility with 2.0.")]
public static CalendarSystem GetJulianCalendar(int minDaysInFirstWeek)
Parameters
Type Name Description
Int32 minDaysInFirstWeek The minimum number of days in the first week of the year. When computing the WeekOfWeekYear and WeekYear properties of a particular date, this is used to decide at what point the week year changes.
Returns
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.

GetMaxMonth(Int32)

The maximum valid month (inclusive) within this calendar in the given year. It is assumed that all calendars start with month 1 and go up to this month number in any valid year.
Since 1.0.x
Availability net35-Client, PCL
Declaration
[Obsolete("Use GetMonthsInYear for compatibility with 2.0")]
public int GetMaxMonth(int year)
Parameters
Type Name Description
Int32 year The year to consider.
Returns
Type Description
Int32 The maximum month number within the given year.
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.

GetMaxYearOfEra(Era)

Returns the maximum valid year-of-era in the given era.
Since 1.0.x
Availability net35-Client, PCL
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.
Exceptions
Type Condition
ArgumentException era is not an era used in this calendar.
ArgumentNullException era is null.

GetMinYearOfEra(Era)

Returns the minimum valid year-of-era in the given era.
Since 1.0.x
Availability net35-Client, PCL
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.
Exceptions
Type Condition
ArgumentException era is not an era used in this calendar.
ArgumentNullException era is null.

GetMonthsInYear(Int32)

The number of months within this calendar in the given year. It is assumed that all calendars start with month 1 and go up to this month number in any valid year.
Since 1.4.x
Availability net35-Client, PCL
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.
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.

GetPersianCalendar()

Returns a Persian (also known as Solar Hijri) calendar system. This is the main calendar in Iran and Afghanistan, and is also used in some other countries where Persian is spoken.
Since 1.3.x
Availability net35-Client, PCL
Declaration
[Obsolete("Use the PersianSimple property for compatibility with 2.0.")]
public static CalendarSystem GetPersianCalendar()
Returns
Type Description
CalendarSystem A Persian calendar system.
Remarks
The true Persian calendar is an astronomical one, where leap years depend on vernal equinox. A complicated algorithmic alternative approach exists, proposed by Ahmad Birashk, but this isn't generally used in society. The implementation here is somewhat simpler, using a 33-year leap cycle, where years 1, 5, 9, 13, 17, 22, 26, and 30 in each cycle are leap years. This is the same approach taken by the BCL PersianCalendar class, and the dates of this implementation align exactly with the BCL implementation.

IsLeapYear(Int32)

Returns whether or not the given year is a leap year in this calendar.
Since 1.0.x
Availability net35-Client, PCL
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.
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 net35-Client, PCL
Declaration
public override string ToString()
Returns
Type Description
String The ID of this calendar system.
Overrides
System.Object.ToString()
In this article
Back to top Generated by DocFX