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 */ 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 25 U_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 */ 84 class U_I18N_API IslamicCalendar : public Calendar { 85 public: 86 //------------------------------------------------------------------------- 87 // Constants... 88 //------------------------------------------------------------------------- 89 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 }; 100 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, 111 112 /** 113 * Constant for Safar, the 2nd month of the Islamic year. 114 * @internal 115 */ 116 SAFAR = 1, 117 118 /** 119 * Constant for Rabi' al-awwal (or Rabi' I), the 3rd month of the Islamic year. 120 * @internal 121 */ 122 RABI_1 = 2, 123 124 /** 125 * Constant for Rabi' al-thani or (Rabi' II), the 4th month of the Islamic year. 126 * @internal 127 */ 128 RABI_2 = 3, 129 130 /** 131 * Constant for Jumada al-awwal or (Jumada I), the 5th month of the Islamic year. 132 * @internal 133 */ 134 JUMADA_1 = 4, 135 136 /** 137 * Constant for Jumada al-thani or (Jumada II), the 6th month of the Islamic year. 138 * @internal 139 */ 140 JUMADA_2 = 5, 141 142 /** 143 * Constant for Rajab, the 7th month of the Islamic year. 144 * @internal 145 */ 146 RAJAB = 6, 147 148 /** 149 * Constant for Sha'ban, the 8th month of the Islamic year. 150 * @internal 151 */ 152 SHABAN = 7, 153 154 /** 155 * Constant for Ramadan, the 9th month of the Islamic year. 156 * @internal 157 */ 158 RAMADAN = 8, 159 160 /** 161 * Constant for Shawwal, the 10th month of the Islamic year. 162 * @internal 163 */ 164 SHAWWAL = 9, 165 166 /** 167 * Constant for Dhu al-Qi'dah, the 11th month of the Islamic year. 168 * @internal 169 */ 170 DHU_AL_QIDAH = 10, 171 172 /** 173 * Constant for Dhu al-Hijjah, the 12th month of the Islamic year. 174 * @internal 175 */ 176 DHU_AL_HIJJAH = 11, 177 178 ISLAMIC_MONTH_MAX 179 }; 180 181 182 //------------------------------------------------------------------------- 183 // Constructors... 184 //------------------------------------------------------------------------- 185 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); 197 198 /** 199 * Copy Constructor 200 * @internal 201 */ 202 IslamicCalendar(const IslamicCalendar& other); 203 204 /** 205 * Destructor. 206 * @internal 207 */ 208 virtual ~IslamicCalendar(); 209 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); 218 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(); 226 227 228 // TODO: copy c'tor, etc 229 230 // clone 231 virtual Calendar* clone() const; 232 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); 238 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; 244 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; 253 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; 263 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); 274 275 //------------------------------------------------------------------------- 276 // Internal data.... 277 // 278 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; 285 286 //---------------------------------------------------------------------- 287 // Calendar framework 288 //---------------------------------------------------------------------- 289 protected: 290 /** 291 * @internal 292 */ 293 virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const; 294 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; 303 304 /** 305 * Return the number of days in the given Islamic year 306 * @internal 307 */ 308 virtual int32_t handleGetYearLength(int32_t extendedYear) const; 309 310 //------------------------------------------------------------------------- 311 // Functions for converting from field values to milliseconds.... 312 //------------------------------------------------------------------------- 313 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; 319 320 //------------------------------------------------------------------------- 321 // Functions for converting from milliseconds to field values 322 //------------------------------------------------------------------------- 323 324 /** 325 * @internal 326 */ 327 virtual int32_t handleGetExtendedYear(); 328 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); 346 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; 355 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); 368 369 /** 370 * return the calendar type, "buddhist". 371 * 372 * @return calendar type 373 * @internal 374 */ 375 virtual const char * getType() const; 376 377 private: 378 IslamicCalendar(); // default constructor not implemented 379 380 // Default century. 381 protected: 382 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; 393 394 395 /** 396 * Returns TRUE because the Islamic Calendar does have a default century 397 * @internal 398 */ 399 virtual UBool haveDefaultCentury() const; 400 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; 407 408 /** 409 * Returns the year in which the default century begins 410 * @internal 411 */ 412 virtual int32_t defaultCenturyStartYear() const; 413 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 }; 422 423 U_NAMESPACE_END 424 425 #endif 426 #endif 427 428 429 430