getIslamicCalendar static method

CalendarSystem getIslamicCalendar(
  1. IslamicLeapYearPattern leapYearPattern,
  2. IslamicEpoch epoch
)

Returns an Islamic, or Hijri, calendar system.

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 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 IslamicEpoch.Astronomical. The fact that the Islamic calendar traditionally starts at dusk, a Julian day traditionally starts at noon, and all calendar systems in Time Machine 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.

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

A suitable Islamic calendar reference; the same reference may be returned by several calls as the object is immutable and thread-safe.

Implementation

static CalendarSystem getIslamicCalendar(IslamicLeapYearPattern leapYearPattern, IslamicEpoch epoch)
{
  Preconditions.checkArgumentRange('leapYearPattern', leapYearPattern.index, 0, 3); //, 1, 4);
  Preconditions.checkArgumentRange('epoch', epoch.index, 0, 1); //, 1, 2);
  return _IslamicCalendars.byLeapYearPatternAndEpoch(leapYearPattern, epoch);
}