IslamicCalendar is a subclass of Calendar
michael@0: * that implements the Islamic civil and religious calendars. It
michael@0: * is used as the civil calendar in most of the Arab world and the
michael@0: * liturgical calendar of the Islamic faith worldwide. This calendar
michael@0: * is also known as the "Hijri" calendar, since it starts at the time
michael@0: * of Mohammed's emigration (or "hijra") to Medinah on Thursday,
michael@0: * July 15, 622 AD (Julian).
michael@0: * michael@0: * The Islamic calendar is strictly lunar, and thus an Islamic year of twelve michael@0: * lunar months does not correspond to the solar year used by most other michael@0: * calendar systems, including the Gregorian. An Islamic year is, on average, michael@0: * about 354 days long, so each successive Islamic year starts about 11 days michael@0: * earlier in the corresponding Gregorian year. michael@0: *
michael@0: * Each month of the calendar starts when the new moon's crescent is visible michael@0: * at sunset. However, in order to keep the time fields in this class michael@0: * synchronized with those of the other calendars and with local clock time, michael@0: * we treat days and months as beginning at midnight, michael@0: * roughly 6 hours after the corresponding sunset. michael@0: *
michael@0: * There are two main variants of the Islamic calendar in existence. The first
michael@0: * is the civil calendar, which uses a fixed cycle of alternating 29-
michael@0: * and 30-day months, with a leap day added to the last month of 11 out of
michael@0: * every 30 years. This calendar is easily calculated and thus predictable in
michael@0: * advance, so it is used as the civil calendar in a number of Arab countries.
michael@0: * This is the default behavior of a newly-created IslamicCalendar
michael@0: * object.
michael@0: *
michael@0: * The Islamic religious calendar, however, is based on the observation michael@0: * of the crescent moon. It is thus affected by the position at which the michael@0: * observations are made, seasonal variations in the time of sunset, the michael@0: * eccentricities of the moon's orbit, and even the weather at the observation michael@0: * site. This makes it impossible to calculate in advance, and it causes the michael@0: * start of a month in the religious calendar to differ from the civil calendar michael@0: * by up to three days. michael@0: *
michael@0: * Using astronomical calculations for the position of the sun and moon, the michael@0: * moon's illumination, and other factors, it is possible to determine the start michael@0: * of a lunar month with a fairly high degree of certainty. However, these michael@0: * calculations are extremely complicated and thus slow, so most algorithms, michael@0: * including the one used here, are only approximations of the true astronical michael@0: * calculations. At present, the approximations used in this class are fairly michael@0: * simplistic; they will be improved in later versions of the code. michael@0: *
michael@0: * The {@link #setCivil setCivil} method determines
michael@0: * which approach is used to determine the start of a month. By default, the
michael@0: * fixed-cycle civil calendar is used. However, if setCivil(false)
michael@0: * is called, an approximation of the true lunar calendar will be used.
michael@0: *
michael@0: * @see GregorianCalendar
michael@0: *
michael@0: * @author Laura Werner
michael@0: * @author Alan Liu
michael@0: * @author Steven R. Loomis
michael@0: * @internal
michael@0: */
michael@0: class U_I18N_API IslamicCalendar : public Calendar {
michael@0: public:
michael@0: //-------------------------------------------------------------------------
michael@0: // Constants...
michael@0: //-------------------------------------------------------------------------
michael@0:
michael@0: /**
michael@0: * Calendar type - civil or religious or um alqura
michael@0: * @internal
michael@0: */
michael@0: enum ECalculationType {
michael@0: ASTRONOMICAL,
michael@0: CIVIL,
michael@0: UMALQURA,
michael@0: TBLA
michael@0: };
michael@0:
michael@0: /**
michael@0: * Constants for the months
michael@0: * @internal
michael@0: */
michael@0: enum EMonths {
michael@0: /**
michael@0: * Constant for Muharram, the 1st month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: MUHARRAM = 0,
michael@0:
michael@0: /**
michael@0: * Constant for Safar, the 2nd month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: SAFAR = 1,
michael@0:
michael@0: /**
michael@0: * Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: RABI_1 = 2,
michael@0:
michael@0: /**
michael@0: * Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: RABI_2 = 3,
michael@0:
michael@0: /**
michael@0: * Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: JUMADA_1 = 4,
michael@0:
michael@0: /**
michael@0: * Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: JUMADA_2 = 5,
michael@0:
michael@0: /**
michael@0: * Constant for Rajab, the 7th month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: RAJAB = 6,
michael@0:
michael@0: /**
michael@0: * Constant for Sha'ban, the 8th month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: SHABAN = 7,
michael@0:
michael@0: /**
michael@0: * Constant for Ramadan, the 9th month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: RAMADAN = 8,
michael@0:
michael@0: /**
michael@0: * Constant for Shawwal, the 10th month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: SHAWWAL = 9,
michael@0:
michael@0: /**
michael@0: * Constant for Dhu al-Qi'dah, the 11th month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: DHU_AL_QIDAH = 10,
michael@0:
michael@0: /**
michael@0: * Constant for Dhu al-Hijjah, the 12th month of the Islamic year.
michael@0: * @internal
michael@0: */
michael@0: DHU_AL_HIJJAH = 11,
michael@0:
michael@0: ISLAMIC_MONTH_MAX
michael@0: };
michael@0:
michael@0:
michael@0: //-------------------------------------------------------------------------
michael@0: // Constructors...
michael@0: //-------------------------------------------------------------------------
michael@0:
michael@0: /**
michael@0: * Constructs an IslamicCalendar based on the current time in the default time zone
michael@0: * with the given locale.
michael@0: *
michael@0: * @param aLocale The given locale.
michael@0: * @param success Indicates the status of IslamicCalendar object construction.
michael@0: * Returns U_ZERO_ERROR if constructed successfully.
michael@0: * @param type The Islamic calendar calculation type. The default value is CIVIL.
michael@0: * @internal
michael@0: */
michael@0: IslamicCalendar(const Locale& aLocale, UErrorCode &success, ECalculationType type = CIVIL);
michael@0:
michael@0: /**
michael@0: * Copy Constructor
michael@0: * @internal
michael@0: */
michael@0: IslamicCalendar(const IslamicCalendar& other);
michael@0:
michael@0: /**
michael@0: * Destructor.
michael@0: * @internal
michael@0: */
michael@0: virtual ~IslamicCalendar();
michael@0:
michael@0: /**
michael@0: * Sets Islamic calendar calculation type used by this instance.
michael@0: *
michael@0: * @param type The calendar calculation type, CIVIL to use the civil
michael@0: * calendar, ASTRONOMICAL to use the astronomical calendar.
michael@0: * @internal
michael@0: */
michael@0: void setCalculationType(ECalculationType type, UErrorCode &status);
michael@0:
michael@0: /**
michael@0: * Returns true if this object is using the fixed-cycle civil
michael@0: * calendar, or false if using the religious, astronomical
michael@0: * calendar.
michael@0: * @internal
michael@0: */
michael@0: UBool isCivil();
michael@0:
michael@0:
michael@0: // TODO: copy c'tor, etc
michael@0:
michael@0: // clone
michael@0: virtual Calendar* clone() const;
michael@0:
michael@0: private:
michael@0: /**
michael@0: * Determine whether a year is a leap year in the Islamic civil calendar
michael@0: */
michael@0: static UBool civilLeapYear(int32_t year);
michael@0:
michael@0: /**
michael@0: * Return the day # on which the given year starts. Days are counted
michael@0: * from the Hijri epoch, origin 0.
michael@0: */
michael@0: int32_t yearStart(int32_t year) const;
michael@0:
michael@0: /**
michael@0: * Return the day # on which the given month starts. Days are counted
michael@0: * from the Hijri epoch, origin 0.
michael@0: *
michael@0: * @param year The hijri year
michael@0: * @param year The hijri month, 0-based
michael@0: */
michael@0: int32_t monthStart(int32_t year, int32_t month) const;
michael@0:
michael@0: /**
michael@0: * Find the day number on which a particular month of the true/lunar
michael@0: * Islamic calendar starts.
michael@0: *
michael@0: * @param month The month in question, origin 0 from the Hijri epoch
michael@0: *
michael@0: * @return The day number on which the given month starts.
michael@0: */
michael@0: int32_t trueMonthStart(int32_t month) const;
michael@0:
michael@0: /**
michael@0: * Return the "age" of the moon at the given time; this is the difference
michael@0: * in ecliptic latitude between the moon and the sun. This method simply
michael@0: * calls CalendarAstronomer.moonAge, converts to degrees,
michael@0: * and adjusts the resultto be in the range [-180, 180].
michael@0: *
michael@0: * @param time The time at which the moon's age is desired,
michael@0: * in millis since 1/1/1970.
michael@0: */
michael@0: static double moonAge(UDate time, UErrorCode &status);
michael@0:
michael@0: //-------------------------------------------------------------------------
michael@0: // Internal data....
michael@0: //
michael@0:
michael@0: /**
michael@0: * CIVIL if this object uses the fixed-cycle Islamic civil calendar,
michael@0: * and ASTRONOMICAL if it approximates the true religious calendar using
michael@0: * astronomical calculations for the time of the new moon.
michael@0: */
michael@0: ECalculationType cType;
michael@0:
michael@0: //----------------------------------------------------------------------
michael@0: // Calendar framework
michael@0: //----------------------------------------------------------------------
michael@0: protected:
michael@0: /**
michael@0: * @internal
michael@0: */
michael@0: virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const;
michael@0:
michael@0: /**
michael@0: * Return the length (in days) of the given month.
michael@0: *
michael@0: * @param year The hijri year
michael@0: * @param year The hijri month, 0-based
michael@0: * @internal
michael@0: */
michael@0: virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const;
michael@0:
michael@0: /**
michael@0: * Return the number of days in the given Islamic year
michael@0: * @internal
michael@0: */
michael@0: virtual int32_t handleGetYearLength(int32_t extendedYear) const;
michael@0:
michael@0: //-------------------------------------------------------------------------
michael@0: // Functions for converting from field values to milliseconds....
michael@0: //-------------------------------------------------------------------------
michael@0:
michael@0: // Return JD of start of given month/year
michael@0: /**
michael@0: * @internal
michael@0: */
michael@0: virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month, UBool useMonth) const;
michael@0:
michael@0: //-------------------------------------------------------------------------
michael@0: // Functions for converting from milliseconds to field values
michael@0: //-------------------------------------------------------------------------
michael@0:
michael@0: /**
michael@0: * @internal
michael@0: */
michael@0: virtual int32_t handleGetExtendedYear();
michael@0:
michael@0: /**
michael@0: * Override Calendar to compute several fields specific to the Islamic
michael@0: * calendar system. These are:
michael@0: *
michael@0: *