icuSources/i18n/islamcal.h

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