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
25U_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 */
84class 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
457U_NAMESPACE_END
458
459#endif
460#endif
461
462
463
464