Observational Islamic Lunar Calendar

After coding the astro library, the next step was to implement the astronomical calculations in the Islamic Calendar. The arithmetical Islamic Calendar had already been defined in the KCalendarSystem API, to implement the astronomical calculations, functions like dateToJulianDay() and julianDayToDate() had to be modified.

The header file for defining the observational Islamic Lunar calendar is kcalendarsystemislamiclunar.h. It defines two classes:

KCalendarSystemIslamicLunar
Class definition in the public domain, publicly inherited from KCalendarSystem. It re-implements the virtual functions defined in the KCalendarSystem class. The re-implemented functions are defined in the public domain of the class.

virtual QString calendarType() const
Returns the calendar system type.

virtual QDate epoch() const
Returns a QDate holding the epoch of the calendar system. Islamic epoch is defined on 16th July 622 AD, which is Julian Day 1949440.

virtual QDate earliestValidDate() const
Returns the earliest date valid in this calendar system implementation, i.e. the epoch of the calendar system as the Islamic calendar is not proleptic.

virtual QDate latestValidDate() const
Returns the latest date valid in this calendar system implementation, i.e. 29th December 9999.

virtual bool isValid(int year, int month, int day) const
Returns whether a given date is valid in this calendar system.

virtual bool isValid(const QDate &date) const
Returns whether a given date is valid in this calendar system.

virtual bool isLeapYear(int year) const
Returns whether a given year is a leap year.

virtual bool isLeapYear(const QDate &date) const
Returns whether a given year(taken from the QDate) is a leap year.

virtual QString monthName(int month, int year, MonthNameFormat format = LongName) const
Gets specific calendar type month name for a given month number If an invalid month is specified, QString() is returned.

virtual QString monthName(const QDate &date, MonthNameFormat format = LongName) const
Gets specific calendar type month name for a given date.

virtual QString weekDayName(int weekDay, WeekDayNameFormat format = LongDayName) const
Gets specific calendar type week day name. If an invalid week day is specified, QString() is returned.

virtual QString weekDayName(const QDate &date, WeekDayNameFormat format = LongDayName) const
Gets specific calendar type week day name.

virtual int weekDayOfPray() const
Returns the weekday of pray for this calendar system, i.e. Friday.

virtual bool isLunar() const
Returns whether the calendar is lunar.

virtual bool isLunisolar() const
Returns whether the calendar is lunisolar.
virtual bool isSolar() const
Returns whether the calendar is solar.

virtual bool isProleptic() const
Returns whether the calendar is proleptic, i.e, supports dates before the epoch.

KCalendarSystemIslamicLunarPrivate
Class definition in the private domain, publicy inherited from KCalendarSystemPrivate. It re-implements the virtual functions defined in the KCalendarSystem class. The re-implemented functions are defined in the public domain of the class.

virtual KLocale::CalendarSystem calendarSystem() const
Returns the calendar type.

virtual void loadDefaultEraList()
Loads the era supported by this calendar system.

virtual int monthsInYear(int year) const
Returns the number of months in the year used by this calendar system.

virtual int daysInMonth(int year, int month) const
Returns the number of days in a month used by this calendar system.

virtual int daysInYear(int year) const
Returns the number of days in a year used by this calendar system.

virtual int daysInWeek() const
Returns the number of days in a week used by this calendar system.

virtual bool isLeapYear(int year) const
Checks whether a year is a leap year or not.

virtual bool hasLeapMonths() const
Returns true is this calendar system has leap months. The Islamic calendar doesn't have leap months.

virtual bool hasYearZero() const
Returns true is this calendar system uses year 0. The Islamic calendar doesn't have a year 0.

virtual int maxDaysInWeek() const
Returns the maximum number of days in a week in this calendar system, i.e, 7.

virtual int maxMonthsInYear() const
Returns the maximum number of months in a year in this calendar system, i.e. 12.

virtual int earliestValidYear() const
Returns the earliest valid year in this calendar system, i.e., year 1.

virtual int latestValidYear() const
Returns the latest valid year in this calendar system, i.e., year 9999.

virtual QString monthName(int month, int year, Locale::DateTimeComponentFormat format, bool possessive) const
Gets specific calendar type month name for a given month number If an invalid month is specified, QString() is returned.

virtual QString weekDayName(int weekDay, KLocale::DateTimeComponentFormat format) const
Gets specific calendar type weekday name for a given month number If an invalid weekday is specified, QString() is returned.

Astronomical Implementation
Re-implementations of the functions dateToJulianDay() and julianDayToDate() using the functions defined in the Astro Library.

bool julianDayToDate(int jd, int &year, int &month, int &day) const
Gets the date in this calendar system from the Julian day. The astro library function visibleCrescentBefore() is used to get the Julian day when the visible crescent was observed on or before the jd. The number of months elapsed since the Islamic epoch are then calculated and are used to get the year and month:

• Year = elapsedMonths/12 + 1
• Month = elapsedMonths%12 + 1
• Day = jd - day returned by visiblecrescentbefore() +1

The function returns false if it encounters an invalid date at any point during the calculations, otherwise it returns true.

bool dateToJulianDay(int &jd, int year, int month, int day) const
Gets the Julian day number corresponding to a given date in this calendar system. The astro library function visibleCrescentBefore() is used to get the Julian day when the visible crescent was observed on or before a particular date. The date passed as an argument to the visibleCrescentBefore() function is calculated as:

• Islamic epoch + the number of days elapsed since the start of the calendar to median of the current month

The Julian day is then calculated by adding to the value returned by the visibleCrescentBefore() function with the aforementioned argument.

The function returns false if it encounters an invalid date at any point during the calculations, otherwise it returns true.

The calculations for implementing the Islamic Lunar Calendar have been derived from the public domain Lisp code/Mathematical functions of Calendrical Calculations by Edward M. Reingold on the Illinois Institute of Technology website.