• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (C) 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 
432