Add support for Islamic calendars

[elyoh]

This proposal formally defines an abstract Islamic calendar, which can be used to represent various in use forms of the Islamic calendar (as discussed in #1 ).

ISLAMIC

The Islamic calendar is a deterministic lunar Hijri calendar, based on a 30-year cycle. There are two possible epochs for this calendar. In the civil epoch, 1 Muḥarram 1 aligns with Julian day 16 July 622. In the astronomical epoch, 1 Muḥarram 1 aligns with Julian day 15 July 622.

Months have fixed lengths of 29 or 30 days, except for the twelth month, Dhū al-Ḥijja, which has an extra day in a leap year.

Permitted months are: Code	Name	Days
MUHAR	Muḥarram (المُحَرَّم)	30
SAFAR	Ṣafar (صَفَر)	29
RABIA	Rabī I (رَبيع الاوَّل)	30
RABIT	Rabī II (رَبيع الآخِر)	29
JUMAA	Jumādā I (جُمادى الأولى)	30
JUMAT	Jumādā II (جُمادى الآخِرة)	29
RAJAB	Rajab (رَجَب)	30
SHAAB	Sha‘bān (شَعبان)	29
RAMAD	Ramaḍān (رَمَضان)	30
SHAWW	Shawwāl (شَوّال)	29
DHUAQ	Dhū al-Qa‘da (ذو القَعدة)	30
DHUAH	Dhū al-Ḥijja (ذو الحِجّة)	29 (or 30 in a leap year)

In every 30-year cycle, 11 years are leap years. The determination of leap years depends on the variant in use.

The epoch marker BH (before Hijra) is permitted in this calendar; year y BH indicates a year y years before year 1. Thus, there is no year 0; year 1 BH was followed by year 1.

Note on variants

The determination of leap years follows one of four rules.

Variant	Leap years with 355 days in each 30-year cycle
I	2, 5, 7, 10, 13, 15, 18, 21, 24, 26, 29
II	2, 5, 7, 10, 13, 16, 18, 21, 24, 26, 29
III	2, 5, 8, 10, 13, 16, 19, 21, 24, 27, 29
IV	2, 5, 8, 11, 13, 16, 19, 21, 24, 26, 30

Note on epochs There are two possible epoch dates for each variant. Epoch type 'a' ("astronomical" or Thursday epoch): Julian day 15 July 622 Epoch type 'c' ("civil" or "Friday" epoch): Julian day 16 July 622

To support all of these variants, an ISLAMIC calendar escape could be suffixed by the variant and epoch. For example, ISLAMIC_II_C could be used to indicate a variant II Islamic tabular calendar with a civil epoch of Julian day 16 July 622. This particular form would match with the Microsoft .NET implementation of the calendar: (https://github.com/dotnet/runtime/blob/57bfe474518ab5b7cfe6bf7424a79ce3af9d6657/src/libraries/System.Private.CoreLib/src/System/Globalization/HijriCalendar.cs)

Thus 8 new calendars are proposed: g7:cal-ISLAMIC_I_A g7:cal-ISLAMIC_II_A g7:cal-ISLAMIC_III_A g7:cal-ISLAMIC_IV_A g7:cal-ISLAMIC_I_C g7:cal-ISLAMIC_II_C g7:cal-ISLAMIC_III_C g7:cal-ISLAMIC_IV_C

Further useful information can be found here: http://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types

[fisharebest]

To support all of these variants, an ISLAMIC calendar escape could be suffixed by the variant and epoch.

Are you saying that you must specify the variant, or that you can specify the variant. i.e.

• if the variant and epoch are unknown, can we use ISLAMIC?
• if the variant is known and epoch is unknown, can we use ISLAMIC_I, ISLAMIC_II, ISLAMIC_III, or ISLAMIC_IV?
• if the variant is unknown and epoch is known, can we use ISLAMIC_A or ISLAMIC_C?

[elyoh]

I feel this is something to be discussed.

The underlying issue is that if an Islamic date is to be used accurately in a calculation (for instance age at an event, determination of an anniversary), then the exact variant and epoch must be known, and therefore specified. If the variant and epoch are not known, then interpretation of an Islamic date may be out by up to three days (±1 day for the epoch, ±2 days for leap year variations).

If the both variant and type are known, then one of the 8 tags in the proposal would be appropriate as it allows for exact interpretation of the date.

If this level of accuracy is not required or the type / variant is not known in the source text, then a single ISLAMIC calendar escape would seem more appropriate, with a caveat that interpretation of such a date may differ by upto 3 days. I don't propose additional tags for epoch or variant unknown. Such dates would still only be interpretable to the nearest 1 or 2 days and would not really be much more useful than a generic ISLAMIC tag.

[fisharebest]

The underlying issue is that if an Islamic date is to be used accurately in a calculation

If we need to convert accurately between calendars, then we also need to know whether the event occured before or after sunset - Jewish/Islamic calendars start the new day at sunset, Gregorian calendars start the new day at midnight.

An alternative approach might be to combine the variant/type into the epoch marker:

• AH after Hijra (unknown variant/type - optional/default)
• AH-III-A after Hijra (known variant/type)
• BH before Hijra (unknown variant/type)
• BH-IV-C before Hijra (known variant/type)

[elyoh]

If we need to convert accurately between calendars, then we also need to know whether the event occured before or after sunset - Jewish/Islamic calendars start the new day at sunset, Gregorian calendars start the new day at midnight.

This is true, and another source of potential uncertainty in date interpretation.

An alternative approach might be to combine the variant/type into the epoch marker:

I feel uncomfortable with the idea of putting this information in the epoch marker. The epoch marker is really just an era name. In my view, it has no relationship to leap year rules and is not intended to directly convey what the epoch start date is. These things are constrained by the calendar.

My proposal is based on the principle that it is the role of the calendar tag to completely define the rules, arithmetic, and epoch(s) of the calendar. When the calendar tag is used in this way, it allows a parser to determine everything it needs to know about the calendar by examining a single tag (which also happens to be the first part of the date payload). This makes parsing much easier / efficient.