icuSources/i18n/islamcal.h

   1 /*
   2  ********************************************************************************
   3  * Copyright (C) 2003-2009, International Business Machines Corporation
   4  * and others. All Rights Reserved.
   5  ******************************************************************************
   6  *
   7  * File ISLAMCAL.H
   8  *
   9  * Modification History:
  10  *
  11  *   Date        Name        Description
  12  *   10/14/2003  srl         ported from java IslamicCalendar
  13  *****************************************************************************
  14  */
  15
  16 #ifndef ISLAMCAL_H
  17 #define ISLAMCAL_H
  18
  19 #include "unicode/utypes.h"
  20
  21 #if !UCONFIG_NO_FORMATTING
  22
  23 #include "unicode/calendar.h"
  24
  25 U_NAMESPACE_BEGIN
  26
  27 /**
  28  * <code>IslamicCalendar</code> is a subclass of <code>Calendar</code>
  29  * that implements the Islamic civil and religious calendars.  It
  30  * is used as the civil calendar in most of the Arab world and the
  31  * liturgical calendar of the Islamic faith worldwide.  This calendar
  32  * is also known as the "Hijri" calendar, since it starts at the time
  33  * of Mohammed's emigration (or "hijra") to Medinah on Thursday,
  34  * July 15, 622 AD (Julian).
  35  * <p>
  36  * The Islamic calendar is strictly lunar, and thus an Islamic year of twelve
  37  * lunar months does not correspond to the solar year used by most other
  38  * calendar systems, including the Gregorian.  An Islamic year is, on average,
  39  * about 354 days long, so each successive Islamic year starts about 11 days
  40  * earlier in the corresponding Gregorian year.
  41  * <p>
  42  * Each month of the calendar starts when the new moon's crescent is visible
  43  * at sunset.  However, in order to keep the time fields in this class
  44  * synchronized with those of the other calendars and with local clock time,
  45  * we treat days and months as beginning at midnight,
  46  * roughly 6 hours after the corresponding sunset.
  47  * <p>
  48  * There are two main variants of the Islamic calendar in existence.  The first
  49  * is the <em>civil</em> calendar, which uses a fixed cycle of alternating 29-
  50  * and 30-day months, with a leap day added to the last month of 11 out of
  51  * every 30 years.  This calendar is easily calculated and thus predictable in
  52  * advance, so it is used as the civil calendar in a number of Arab countries.
  53  * This is the default behavior of a newly-created <code>IslamicCalendar</code>
  54  * object.
  55  * <p>
  56  * The Islamic <em>religious</em> calendar, however, is based on the <em>observation</em>
  57  * of the crescent moon.  It is thus affected by the position at which the
  58  * observations are made, seasonal variations in the time of sunset, the
  59  * eccentricities of the moon's orbit, and even the weather at the observation
  60  * site.  This makes it impossible to calculate in advance, and it causes the
  61  * start of a month in the religious calendar to differ from the civil calendar
  62  * by up to three days.
  63  * <p>
  64  * Using astronomical calculations for the position of the sun and moon, the
  65  * moon's illumination, and other factors, it is possible to determine the start
  66  * of a lunar month with a fairly high degree of certainty.  However, these
  67  * calculations are extremely complicated and thus slow, so most algorithms,
  68  * including the one used here, are only approximations of the true astronical
  69  * calculations.  At present, the approximations used in this class are fairly
  70  * simplistic; they will be improved in later versions of the code.
  71  * <p>
  72  * The {@link #setCivil setCivil} method determines
  73  * which approach is used to determine the start of a month.  By default, the
  74  * fixed-cycle civil calendar is used.  However, if <code>setCivil(false)</code>
  75  * is called, an approximation of the true lunar calendar will be used.
  76  *
  77  * @see GregorianCalendar
  78  *
  79  * @author Laura Werner
  80  * @author Alan Liu
  81  * @author Steven R. Loomis
  82  * @internal
  83  */
  84 class IslamicCalendar : public Calendar {
  85  public:
  86   //-------------------------------------------------------------------------
  87   // Constants...
  88   //-------------------------------------------------------------------------
  89   /**
  90    * Calendar type - civil or religious
  91    * @internal
  92    */
  93   enum ECivil {
  94     ASTRONOMICAL,
  95     CIVIL
  96   };
  97
  98   /**
  99    * Constants for the months
 100    * @internal
 101    */
 102   enum EMonths {
 103     /**
 104      * Constant for Muharram, the 1st month of the Islamic year.
 105      * @internal
 106      */
 107     MUHARRAM = 0,
 108
 109     /**
 110      * Constant for Safar, the 2nd month of the Islamic year.
 111      * @internal
 112      */
 113     SAFAR = 1,
 114
 115     /**
 116      * Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year.
 117      * @internal
 118      */
 119     RABI_1 = 2,
 120
 121     /**
 122      * Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year.
 123      * @internal
 124      */
 125     RABI_2 = 3,
 126
 127     /**
 128      * Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year.
 129      * @internal
 130      */
 131     JUMADA_1 = 4,
 132
 133     /**
 134      * Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year.
 135      * @internal
 136      */
 137     JUMADA_2 = 5,
 138
 139     /**
 140      * Constant for Rajab, the 7th month of the Islamic year.
 141      * @internal
 142      */
 143     RAJAB = 6,
 144
 145     /**
 146      * Constant for Sha'ban, the 8th month of the Islamic year.
 147      * @internal
 148      */
 149     SHABAN = 7,
 150
 151     /**
 152      * Constant for Ramadan, the 9th month of the Islamic year.
 153      * @internal
 154      */
 155     RAMADAN = 8,
 156
 157     /**
 158      * Constant for Shawwal, the 10th month of the Islamic year.
 159      * @internal
 160      */
 161     SHAWWAL = 9,
 162
 163     /**
 164      * Constant for Dhu al-Qi'dah, the 11th month of the Islamic year.
 165      * @internal
 166      */
 167     DHU_AL_QIDAH = 10,
 168
 169     /**
 170      * Constant for Dhu al-Hijjah, the 12th month of the Islamic year.
 171      * @internal
 172      */
 173     DHU_AL_HIJJAH = 11,
 174
 175     ISLAMIC_MONTH_MAX
 176   };
 177
 178
 179
 180   //-------------------------------------------------------------------------
 181   // Constructors...
 182   //-------------------------------------------------------------------------
 183
 184   /**
 185    * Constructs an IslamicCalendar based on the current time in the default time zone
 186    * with the given locale.
 187    *
 188    * @param aLocale  The given locale.
 189    * @param success  Indicates the status of IslamicCalendar object construction.
 190    *                 Returns U_ZERO_ERROR if constructed successfully.
 191    * @param beCivil  Whether the calendar should be civil (default-TRUE) or religious (FALSE)
 192    * @internal
 193    */
 194   IslamicCalendar(const Locale& aLocale, UErrorCode &success, ECivil beCivil = CIVIL);
 195
 196   /**
 197    * Copy Constructor
 198    * @internal
 199    */
 200   IslamicCalendar(const IslamicCalendar& other);
 201
 202   /**
 203    * Destructor.
 204    * @internal
 205    */
 206   virtual ~IslamicCalendar();
 207
 208   /**
 209    * Determines whether this object uses the fixed-cycle Islamic civil calendar
 210    * or an approximation of the religious, astronomical calendar.
 211    *
 212    * @param beCivil   <code>CIVIL</code> to use the civil calendar,
 213    *                  <code>ASTRONOMICAL</code> to use the astronomical calendar.
 214    * @internal
 215    */
 216   void setCivil(ECivil beCivil, UErrorCode &status);
 217
 218   /**
 219    * Returns <code>true</code> if this object is using the fixed-cycle civil
 220    * calendar, or <code>false</code> if using the religious, astronomical
 221    * calendar.
 222    * @internal
 223    */
 224   UBool isCivil();
 225
 226
 227   // TODO: copy c'tor, etc
 228
 229   // clone
 230   virtual Calendar* clone() const;
 231
 232  private:
 233   /**
 234    * Determine whether a year is a leap year in the Islamic civil calendar
 235    */
 236   static UBool civilLeapYear(int32_t year);
 237
 238   /**
 239    * Return the day # on which the given year starts.  Days are counted
 240    * from the Hijri epoch, origin 0.
 241    */
 242   int32_t yearStart(int32_t year);
 243
 244   /**
 245    * Return the day # on which the given month starts.  Days are counted
 246    * from the Hijri epoch, origin 0.
 247    *
 248    * @param year  The hijri year
 249    * @param year  The hijri month, 0-based
 250    */
 251   int32_t monthStart(int32_t year, int32_t month) const;
 252
 253   /**
 254    * Find the day number on which a particular month of the true/lunar
 255    * Islamic calendar starts.
 256    *
 257    * @param month The month in question, origin 0 from the Hijri epoch
 258    *
 259    * @return The day number on which the given month starts.
 260    */
 261   int32_t trueMonthStart(int32_t month) const;
 262
 263   /**
 264    * Return the "age" of the moon at the given time; this is the difference
 265    * in ecliptic latitude between the moon and the sun.  This method simply
 266    * calls CalendarAstronomer.moonAge, converts to degrees,
 267    * and adjusts the resultto be in the range [-180, 180].
 268    *
 269    * @param time  The time at which the moon's age is desired,
 270    *              in millis since 1/1/1970.
 271    */
 272   static double moonAge(UDate time, UErrorCode &status);
 273
 274   //-------------------------------------------------------------------------
 275   // Internal data....
 276   //
 277
 278   /**
 279    * <code>CIVIL</code> if this object uses the fixed-cycle Islamic civil calendar,
 280    * and <code>ASTRONOMICAL</code> if it approximates the true religious calendar using
 281    * astronomical calculations for the time of the new moon.
 282    */
 283   ECivil civil;
 284
 285   //----------------------------------------------------------------------
 286   // Calendar framework
 287   //----------------------------------------------------------------------
 288  protected:
 289   /**
 290    * @internal
 291    */
 292   virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const;
 293
 294   /**
 295    * Return the length (in days) of the given month.
 296    *
 297    * @param year  The hijri year
 298    * @param year  The hijri month, 0-based
 299    * @internal
 300    */
 301   virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const;
 302
 303   /**
 304    * Return the number of days in the given Islamic year
 305    * @internal
 306    */
 307   virtual int32_t handleGetYearLength(int32_t extendedYear) const;
 308
 309   //-------------------------------------------------------------------------
 310   // Functions for converting from field values to milliseconds....
 311   //-------------------------------------------------------------------------
 312
 313   // Return JD of start of given month/year
 314   /**
 315    * @internal
 316    */
 317   virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month, UBool useMonth) const;
 318
 319   //-------------------------------------------------------------------------
 320   // Functions for converting from milliseconds to field values
 321   //-------------------------------------------------------------------------
 322
 323   /**
 324    * @internal
 325    */
 326   virtual int32_t handleGetExtendedYear();
 327
 328   /**
 329    * Override Calendar to compute several fields specific to the Islamic
 330    * calendar system.  These are:
 331    *
 332    * <ul><li>ERA
 333    * <li>YEAR
 334    * <li>MONTH
 335    * <li>DAY_OF_MONTH
 336    * <li>DAY_OF_YEAR
 337    * <li>EXTENDED_YEAR</ul>
 338    *
 339    * The DAY_OF_WEEK and DOW_LOCAL fields are already set when this
 340    * method is called. The getGregorianXxx() methods return Gregorian
 341    * calendar equivalents for the given Julian day.
 342    * @internal
 343    */
 344   virtual void handleComputeFields(int32_t julianDay, UErrorCode &status);
 345
 346   // UObject stuff
 347  public:
 348   /**
 349    * @return   The class ID for this object. All objects of a given class have the
 350    *           same class ID. Objects of other classes have different class IDs.
 351    * @internal
 352    */
 353   virtual UClassID getDynamicClassID(void) const;
 354
 355   /**
 356    * Return the class ID for this class. This is useful only for comparing to a return
 357    * value from getDynamicClassID(). For example:
 358    *
 359    *      Base* polymorphic_pointer = createPolymorphicObject();
 360    *      if (polymorphic_pointer->getDynamicClassID() ==
 361    *          Derived::getStaticClassID()) ...
 362    *
 363    * @return   The class ID for all objects of this class.
 364    * @internal
 365    */
 366   U_I18N_API static UClassID U_EXPORT2 getStaticClassID(void);
 367
 368   /**
 369    * return the calendar type, "buddhist".
 370    *
 371    * @return calendar type
 372    * @internal
 373    */
 374   virtual const char * getType() const;
 375
 376  private:
 377   IslamicCalendar(); // default constructor not implemented
 378
 379   // Default century.
 380  protected:
 381
 382   /**
 383    * (Overrides Calendar) Return true if the current date for this Calendar is in
 384    * Daylight Savings Time. Recognizes DST_OFFSET, if it is set.
 385    *
 386    * @param status Fill-in parameter which receives the status of this operation.
 387    * @return   True if the current date for this Calendar is in Daylight Savings Time,
 388    *           false, otherwise.
 389    * @internal
 390    */
 391   virtual UBool inDaylightTime(UErrorCode& status) const;
 392
 393
 394   /**
 395    * Returns TRUE because the Islamic Calendar does have a default century
 396    * @internal
 397    */
 398   virtual UBool haveDefaultCentury() const;
 399
 400   /**
 401    * Returns the date of the start of the default century
 402    * @return start of century - in milliseconds since epoch, 1970
 403    * @internal
 404    */
 405   virtual UDate defaultCenturyStart() const;
 406
 407   /**
 408    * Returns the year in which the default century begins
 409    * @internal
 410    */
 411   virtual int32_t defaultCenturyStartYear() const;
 412
 413  private: // default century stuff.
 414   /**
 415    * The system maintains a static default century start date.  This is initialized
 416    * the first time it is used.  Before then, it is set to SYSTEM_DEFAULT_CENTURY to
 417    * indicate an uninitialized state.  Once the system default century date and year
 418    * are set, they do not change.
 419    */
 420   static UDate         fgSystemDefaultCenturyStart;
 421
 422   /**
 423    * See documentation for systemDefaultCenturyStart.
 424    */
 425   static int32_t          fgSystemDefaultCenturyStartYear;
 426
 427   /**
 428    * Default value that indicates the defaultCenturyStartYear is unitialized
 429    */
 430   static const int32_t    fgSystemDefaultCenturyYear;
 431
 432   /**
 433    * start of default century, as a date
 434    */
 435   static const UDate        fgSystemDefaultCentury;
 436
 437   /**
 438    * Returns the beginning date of the 100-year window that dates
 439    * with 2-digit years are considered to fall within.
 440    */
 441   UDate         internalGetDefaultCenturyStart(void) const;
 442
 443   /**
 444    * Returns the first year of the 100-year window that dates with
 445    * 2-digit years are considered to fall within.
 446    */
 447   int32_t          internalGetDefaultCenturyStartYear(void) const;
 448
 449   /**
 450    * Initializes the 100-year window that dates with 2-digit years
 451    * are considered to fall within so that its start date is 80 years
 452    * before the current time.
 453    */
 454   static void  initializeSystemDefaultCentury(void);
 455 };
 456
 457 U_NAMESPACE_END
 458
 459 #endif
 460 #endif
 461
 462
 463