The Tor Browser: intl/icu/source/i18n/islamcal.h@fc2d59ddac77

     1 /*

     2  ********************************************************************************

     3  * Copyright (C) 2003-2013, 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  */

    16 #ifndef ISLAMCAL_H

    17 #define ISLAMCAL_H

    19 #include "unicode/utypes.h"

    21 #if !UCONFIG_NO_FORMATTING

    23 #include "unicode/calendar.h"

    25 U_NAMESPACE_BEGIN

    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 U_I18N_API IslamicCalendar : public Calendar {

    85  public:

    86   //-------------------------------------------------------------------------

    87   // Constants...

    88   //-------------------------------------------------------------------------

    90   /**

    91    * Calendar type - civil or religious or um alqura

    92    * @internal

    93    */

    94   enum ECalculationType {

    95     ASTRONOMICAL,

    96     CIVIL,

    97     UMALQURA,

    98     TBLA

    99   };

   101   /**

   102    * Constants for the months

   103    * @internal

   104    */

   105   enum EMonths {

   106     /**

   107      * Constant for Muharram, the 1st month of the Islamic year.

   108      * @internal

   109      */

   110     MUHARRAM = 0,

   112     /**

   113      * Constant for Safar, the 2nd month of the Islamic year.

   114      * @internal

   115      */

   116     SAFAR = 1,

   118     /**

   119      * Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year.

   120      * @internal

   121      */

   122     RABI_1 = 2,

   124     /**

   125      * Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year.

   126      * @internal

   127      */

   128     RABI_2 = 3,

   130     /**

   131      * Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year.

   132      * @internal

   133      */

   134     JUMADA_1 = 4,

   136     /**

   137      * Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year.

   138      * @internal

   139      */

   140     JUMADA_2 = 5,

   142     /**

   143      * Constant for Rajab, the 7th month of the Islamic year.

   144      * @internal

   145      */

   146     RAJAB = 6,

   148     /**

   149      * Constant for Sha'ban, the 8th month of the Islamic year.

   150      * @internal

   151      */

   152     SHABAN = 7,

   154     /**

   155      * Constant for Ramadan, the 9th month of the Islamic year.

   156      * @internal

   157      */

   158     RAMADAN = 8,

   160     /**

   161      * Constant for Shawwal, the 10th month of the Islamic year.

   162      * @internal

   163      */

   164     SHAWWAL = 9,

   166     /**

   167      * Constant for Dhu al-Qi'dah, the 11th month of the Islamic year.

   168      * @internal

   169      */

   170     DHU_AL_QIDAH = 10,

   172     /**

   173      * Constant for Dhu al-Hijjah, the 12th month of the Islamic year.

   174      * @internal

   175      */

   176     DHU_AL_HIJJAH = 11,

   178     ISLAMIC_MONTH_MAX

   179   };

   182   //-------------------------------------------------------------------------

   183   // Constructors...

   184   //-------------------------------------------------------------------------

   186   /**

   187    * Constructs an IslamicCalendar based on the current time in the default time zone

   188    * with the given locale.

   189    *

   190    * @param aLocale  The given locale.

   191    * @param success  Indicates the status of IslamicCalendar object construction.

   192    *                 Returns U_ZERO_ERROR if constructed successfully.

   193    * @param type     The Islamic calendar calculation type. The default value is CIVIL.

   194    * @internal

   195    */

   196   IslamicCalendar(const Locale& aLocale, UErrorCode &success, ECalculationType type = CIVIL);

   198   /**

   199    * Copy Constructor

   200    * @internal

   201    */

   202   IslamicCalendar(const IslamicCalendar& other);

   204   /**

   205    * Destructor.

   206    * @internal

   207    */

   208   virtual ~IslamicCalendar();

   210   /**

   211    * Sets Islamic calendar calculation type used by this instance.

   212    *

   213    * @param type    The calendar calculation type, <code>CIVIL</code> to use the civil

   214    *                calendar, <code>ASTRONOMICAL</code> to use the astronomical calendar.

   215    * @internal

   216    */

   217   void setCalculationType(ECalculationType type, UErrorCode &status);

   219   /**

   220    * Returns <code>true</code> if this object is using the fixed-cycle civil

   221    * calendar, or <code>false</code> if using the religious, astronomical

   222    * calendar.

   223    * @internal

   224    */

   225   UBool isCivil();

   228   // TODO: copy c'tor, etc

   230   // clone

   231   virtual Calendar* clone() const;

   233  private:

   234   /**

   235    * Determine whether a year is a leap year in the Islamic civil calendar

   236    */

   237   static UBool civilLeapYear(int32_t year);

   239   /**

   240    * Return the day # on which the given year starts.  Days are counted

   241    * from the Hijri epoch, origin 0.

   242    */

   243   int32_t yearStart(int32_t year) const;

   245   /**

   246    * Return the day # on which the given month starts.  Days are counted

   247    * from the Hijri epoch, origin 0.

   248    *

   249    * @param year  The hijri year

   250    * @param year  The hijri month, 0-based

   251    */

   252   int32_t monthStart(int32_t year, int32_t month) const;

   254   /**

   255    * Find the day number on which a particular month of the true/lunar

   256    * Islamic calendar starts.

   257    *

   258    * @param month The month in question, origin 0 from the Hijri epoch

   259    *

   260    * @return The day number on which the given month starts.

   261    */

   262   int32_t trueMonthStart(int32_t month) const;

   264   /**

   265    * Return the "age" of the moon at the given time; this is the difference

   266    * in ecliptic latitude between the moon and the sun.  This method simply

   267    * calls CalendarAstronomer.moonAge, converts to degrees,

   268    * and adjusts the resultto be in the range [-180, 180].

   269    *

   270    * @param time  The time at which the moon's age is desired,

   271    *              in millis since 1/1/1970.

   272    */

   273   static double moonAge(UDate time, UErrorCode &status);

   275   //-------------------------------------------------------------------------

   276   // Internal data....

   277   //

   279   /**

   280    * <code>CIVIL</code> if this object uses the fixed-cycle Islamic civil calendar,

   281    * and <code>ASTRONOMICAL</code> if it approximates the true religious calendar using

   282    * astronomical calculations for the time of the new moon.

   283    */

   284   ECalculationType cType;

   286   //----------------------------------------------------------------------

   287   // Calendar framework

   288   //----------------------------------------------------------------------

   289  protected:

   290   /**

   291    * @internal

   292    */

   293   virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const;

   295   /**

   296    * Return the length (in days) of the given month.

   297    *

   298    * @param year  The hijri year

   299    * @param year  The hijri month, 0-based

   300    * @internal

   301    */

   302   virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const;

   304   /**

   305    * Return the number of days in the given Islamic year

   306    * @internal

   307    */

   308   virtual int32_t handleGetYearLength(int32_t extendedYear) const;

   310   //-------------------------------------------------------------------------

   311   // Functions for converting from field values to milliseconds....

   312   //-------------------------------------------------------------------------

   314   // Return JD of start of given month/year

   315   /**

   316    * @internal

   317    */

   318   virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month, UBool useMonth) const;

   320   //-------------------------------------------------------------------------

   321   // Functions for converting from milliseconds to field values

   322   //-------------------------------------------------------------------------

   324   /**

   325    * @internal

   326    */

   327   virtual int32_t handleGetExtendedYear();

   329   /**

   330    * Override Calendar to compute several fields specific to the Islamic

   331    * calendar system.  These are:

   332    *

   333    * <ul><li>ERA

   334    * <li>YEAR

   335    * <li>MONTH

   336    * <li>DAY_OF_MONTH

   337    * <li>DAY_OF_YEAR

   338    * <li>EXTENDED_YEAR</ul>

   339    *

   340    * The DAY_OF_WEEK and DOW_LOCAL fields are already set when this

   341    * method is called. The getGregorianXxx() methods return Gregorian

   342    * calendar equivalents for the given Julian day.

   343    * @internal

   344    */

   345   virtual void handleComputeFields(int32_t julianDay, UErrorCode &status);

   347   // UObject stuff

   348  public:

   349   /**

   350    * @return   The class ID for this object. All objects of a given class have the

   351    *           same class ID. Objects of other classes have different class IDs.

   352    * @internal

   353    */

   354   virtual UClassID getDynamicClassID(void) const;

   356   /**

   357    * Return the class ID for this class. This is useful only for comparing to a return

   358    * value from getDynamicClassID(). For example:

   359    *

   360    *      Base* polymorphic_pointer = createPolymorphicObject();

   361    *      if (polymorphic_pointer->getDynamicClassID() ==

   362    *          Derived::getStaticClassID()) ...

   363    *

   364    * @return   The class ID for all objects of this class.

   365    * @internal

   366    */

   367   /*U_I18N_API*/ static UClassID U_EXPORT2 getStaticClassID(void);

   369   /**

   370    * return the calendar type, "buddhist".

   371    *

   372    * @return calendar type

   373    * @internal

   374    */

   375   virtual const char * getType() const;

   377  private:

   378   IslamicCalendar(); // default constructor not implemented

   380   // Default century.

   381  protected:

   383   /**

   384    * (Overrides Calendar) Return true if the current date for this Calendar is in

   385    * Daylight Savings Time. Recognizes DST_OFFSET, if it is set.

   386    *

   387    * @param status Fill-in parameter which receives the status of this operation.

   388    * @return   True if the current date for this Calendar is in Daylight Savings Time,

   389    *           false, otherwise.

   390    * @internal

   391    */

   392   virtual UBool inDaylightTime(UErrorCode& status) const;

   395   /**

   396    * Returns TRUE because the Islamic Calendar does have a default century

   397    * @internal

   398    */

   399   virtual UBool haveDefaultCentury() const;

   401   /**

   402    * Returns the date of the start of the default century

   403    * @return start of century - in milliseconds since epoch, 1970

   404    * @internal

   405    */

   406   virtual UDate defaultCenturyStart() const;

   408   /**

   409    * Returns the year in which the default century begins

   410    * @internal

   411    */

   412   virtual int32_t defaultCenturyStartYear() const;

   414  private:

   415   /**

   416    * Initializes the 100-year window that dates with 2-digit years

   417    * are considered to fall within so that its start date is 80 years

   418    * before the current time.

   419    */

   420   static void  initializeSystemDefaultCentury(void);

   421 };

   423 U_NAMESPACE_END

   425 #endif

   426 #endif

The Tor Browser / file revision

intl/icu/source/i18n/islamcal.h@fc2d59ddac77

intl/icu/source/i18n/islamcal.h