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
27U_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 */
86class 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 IslamicCalendar* 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
425U_NAMESPACE_END
426
427#endif
428#endif
429
430
431
432