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 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 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 457 U_NAMESPACE_END 458 459 #endif 460 #endif 461 462 463 464