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

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>

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 ID	Equivalent factory method
ISO	Iso
Gregorian 1	GetGregorianCalendar(Int32)(1)
Gregorian 2	GetGregorianCalendar(Int32)(2)
Gregorian 3	GetGregorianCalendar(Int32)(3)
Gregorian 3	GetGregorianCalendar(Int32)(4)
Gregorian 5	GetGregorianCalendar(Int32)(5)
Gregorian 6	GetGregorianCalendar(Int32)(6)
Gregorian 7	GetGregorianCalendar(Int32)(7)
Coptic 1	GetCopticCalendar(Int32)(1)
Coptic 2	GetCopticCalendar(Int32)(2)
Coptic 3	GetCopticCalendar(Int32)(3)
Coptic 4	GetCopticCalendar(Int32)(4)
Coptic 5	GetCopticCalendar(Int32)(5)
Coptic 6	GetCopticCalendar(Int32)(6)
Coptic 7	GetCopticCalendar(Int32)(7)
Julian 1	GetJulianCalendar(Int32)(1)
Julian 2	GetJulianCalendar(Int32)(2)
Julian 3	GetJulianCalendar(Int32)(3)
Julian 4	GetJulianCalendar(Int32)(4)
Julian 5	GetJulianCalendar(Int32)(5)
Julian 6	GetJulianCalendar(Int32)(6)
Julian 7	GetJulianCalendar(Int32)(7)
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)

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>

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.

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

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

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
System.ArgumentNullException	era is null.
ArgumentOutOfRangeException	yearOfEra is out of the range of years for the given era.
ArgumentException	era is not an era used in this calendar.

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

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

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.

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:

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.

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

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

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
System.ArgumentNullException	era is null.
ArgumentException	era is not an era used in this calendar.

GetMinYearOfEra(Era)

Returns the minimum valid year-of-era in the given era.

Since 1.0.x

Availability 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
System.ArgumentNullException	era is null.
ArgumentException	era is not an era used in this calendar.

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()