icuSources/i18n/islamcal.h

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