Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Updated the readme with additional information
  • Loading branch information
MohsenAlyafei authored Dec 29, 2023
1 parent c41b61c commit 6651b38
Showing 1 changed file with 17 additions and 15 deletions.
32 changes: 17 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,20 @@
[![JSDocs][jsdocs-src]][jsdocs-href]
[![License][license-src]][license-href]

A **Hijri Week Calendar** is an implementation of an ISO 8601 equivalent for the Hijri calendar. It is based on the [Hijri Calendar](https://en.wikipedia.org/wiki/Islamic_calendar) and the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. dates generated by this calendar are referred to as **Hijri Week Dates**.
A **Hijri Week Calendar** is an implementation of the ISO 8601 equivalent for the Hijri calendar. It is based on the [Hijri Calendar](https://en.wikipedia.org/wiki/Islamic_calendar) and the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard. dates generated by this calendar are referred to as **Hijri Week Dates**.

Since Hijri calendar is a lunar calendar, It was necessary to define a standard for it which has [different rules](#rules) than the ISO Gregorian calendar.
Since Hijri (islamic) calendars are lunar calendars, it was necessary to define a standard for them which has [slightly modified rules](#rules) from that of the ISO week based on the Gregorian calendar. Not withstanding the foregoing, the system shares many of the rules defined by the ISO 8601 making it compliant with the ISO standard.

This implementation aims to standardize rules across all varieties of Hijri calendars. For detailed information on specific compatibility requirements, please refer to the [Compatible Calendars](#compatible-calendars) section.
This implementation aims to standardise rules across all varieties of Hijri (islamic) calendars. For detailed information on specific compatibility requirements, please refer to the [Compatible Calendars](#compatible-calendars) section.

The implementation is an extension of the [`Calendar`](https://github.com/js-temporal/temporal-polyfill/blob/a44a1bb61c738a504023427c486ab0a315c7b9d3/lib/calendar.ts#L129C14-L129C22) class from [`Temporal`](https://github.com/js-temporal/temporal-polyfill)

# Rules

The proposed rules are designed to be applicable to all types of Hijri Calendars, not limited to just the tabular varieties. This includes compatibility with calendars such as the Umm al-Qura calendar. For more information on non-compatible calendars, see [Compatible Calendars](/#compatible-calendars) section.
The proposed rules (which follow the ISO week standards) are designed to be applicable to all types of Hijri (islamic) Calendars, not limited to just the tabular varieties. This includes compatibility with calendars such as the Umm al-Qura calendar. For more information on non-compatible calendars, see [Compatible Calendars](/#compatible-calendars) section.

1. **Week Definition**:
- The week starts on Saturday, designated as day 1, and ends on Friday, designated as day 7.
- A week is always 7 days long and starts on Saturday designated as day 1, and ends on Friday, designated as day 7. Note: Islamic weeks start on Saturday compared to ISO and Gregorian weeks which start on Monday.

2. **Weekday Numbering**:
- Days of the week are numbered sequentially from 1 (Saturday) to 7 (Friday).
Expand All @@ -29,20 +29,22 @@ The proposed rules are designed to be applicable to all types of Hijri Calendars
- A 'long year' consists of 51 weeks, totaling 357 days.

4. **Midweek Day**:
- Tuesday is always the middle day of the week, designated as day 4.
- Tuesday is always the middle day of the week, designated as day 4. This is similar to ISO mid-week day 4 which is Thursday.

5. **First Week Identification**:
- The first week of the Hijri week calendar year is identified by the inclusion of the 4th day of Muharram.
- The first week of the Hijri Week Calendar year (Week 01) is identified by the inclusion of the 4th day of Muharram (which is the 4th day of the starting Hijri year). This is similar to the ISO standard whereby 4th January falls exclusively in Week 01.

6. **4th Muharram Placement**:
- The 4th of Muharram occurs exclusively in the first week of the year in a Hijri week calendar.
- The 4th of Muharram of a Hijri year occurs exclusively in the first week (week 01) of the year in a Hijri Week Calendar.
- It does not appear in any other weeks, such as the 51st or 2nd weeks.

The above rule is compliant with the ISO standard.

7. **Week 51 Extension**:
- Week 51 may extend into the following year but only up to the 3rd of Muharram.
- Week 51 may extend into the following Hijri year but only up to the 3rd of Muharram.

8. **Week 50 Limitation**:
- Week 50 does not extend into the following year.
- Week 50 does not extend into the following Hijri year.
- Its latest possible day is the 29th of Dhu al-Hijjah.
- In rare cases, like in the Umm al-Qura calendar, week 50 may extend to this date, after which week 1 of the next year begins.

Expand All @@ -58,17 +60,17 @@ The proposed rules are designed to be applicable to all types of Hijri Calendars
To ensure compatibility with this implementation, a Hijri calendar must adhere to the following rules:

1. **Year Length**:
- A year must consist of either 354 or 355 days.
- A Hijri year must consist of either 354 or 355 days.

2. **Long and Short Years**:
- A common year (354 days) comprises 6 months of 29 days and 6 months of 30 days.
- A leap year (355 days) comprises 5 months of 29 days and 7 months of 30 days.
- A common Hijri year (354 days) comprises 6 months of 29 days and 6 months of 30 days.
- A leap Hijri year (355 days) comprises 5 months of 29 days and 7 months of 30 days.

Given these rules, the following calendars are **not compatible** with this implementation:
Given these rules, the following calendars are found as of today **incompatible** with this implementation:

- **Islamic Calendar**:
- This calendar calculates Hijri dates using arithmetic based on a formula with an offset to the Gregorian calendar. It provides approximate Hijri dates and is inaccurate for [approximately 3%](https://github.com/unicode-org/icu/blob/1a60a038e14f0c56f50052c03fe76c4933cda339/icu4c/source/i18n/islamcal.cpp#L562) of the years.
- Notably, it includes years of 353 days, such as in 17 AH, 325 AH, 992 AH, 3954 AH, and 4485 AH. These years have 7 months of 29 days and 5 months of 30 days, totaling 353 days, which violates the year length rule.
- Notably, it includes years of 353 days, such as in 17 AH, 325 AH, 992 AH, 3954 AH, and 4485 AH. These years have 7 months of 29 days and 5 months of 30 days, totaling 353 days, which violates the year length rule for Hijri calendars.

- **Rgsa-Islamic Calendar**:
- Although it claims to be based on lunar sightings, [this calendar is not practically implemented](https://github.com/unicode-org/icu/blob/1a60a038e14f0c56f50052c03fe76c4933cda339/icu4c/source/i18n/islamcal.h#L697) and essentially relies on the Islamic calendar mentioned above. As a result, it is incompatible with this implementation due to the same reasons.
Expand Down

0 comments on commit 6651b38

Please sign in to comment.