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 HEBRWCAL.H 10 * 11 * Modification History: 12 * 13 * Date Name Description 14 * 05/13/2003 srl copied from gregocal.h 15 * 11/26/2003 srl copied from buddhcal.h 16 ****************************************************************************** 17 */ 18 19 #ifndef HEBRWCAL_H 20 #define HEBRWCAL_H 21 22 #include "unicode/utypes.h" 23 24 #if !UCONFIG_NO_FORMATTING 25 26 #include "unicode/calendar.h" 27 #include "unicode/gregocal.h" 28 29 U_NAMESPACE_BEGIN 30 31 /** 32 * <code>HebrewCalendar</code> is a subclass of <code>Calendar</code> 33 * that that implements the traditional Hebrew calendar. 34 * This is the civil calendar in Israel and the liturgical calendar 35 * of the Jewish faith worldwide. 36 * <p> 37 * The Hebrew calendar is lunisolar and thus has a number of interesting 38 * properties that distinguish it from the Gregorian. Months start 39 * on the day of (an arithmetic approximation of) each new moon. Since the 40 * solar year (approximately 365.24 days) is not an even multiple of 41 * the lunar month (approximately 29.53 days) an extra "leap month" is 42 * inserted in 7 out of every 19 years. To make matters even more 43 * interesting, the start of a year can be delayed by up to three days 44 * in order to prevent certain holidays from falling on the Sabbath and 45 * to prevent certain illegal year lengths. Finally, the lengths of certain 46 * months can vary depending on the number of days in the year. 47 * <p> 48 * The leap month is known as "Adar 1" and is inserted between the 49 * months of Shevat and Adar in leap years. Since the leap month does 50 * not come at the end of the year, calculations involving 51 * month numbers are particularly complex. Users of this class should 52 * make sure to use the {@link #roll roll} and {@link #add add} methods 53 * rather than attempting to perform date arithmetic by manipulating 54 * the fields directly. 55 * <p> 56 * <b>Note:</b> In the traditional Hebrew calendar, days start at sunset. 57 * However, in order to keep the time fields in this class 58 * synchronized with those of the other calendars and with local clock time, 59 * we treat days and months as beginning at midnight, 60 * roughly 6 hours after the corresponding sunset. 61 * <p> 62 * If you are interested in more information on the rules behind the Hebrew 63 * calendar, see one of the following references: 64 * <ul> 65 * <li>"<a href="http://www.amazon.com/exec/obidos/ASIN/0521564743">Calendrical Calculations</a>", 66 * by Nachum Dershowitz & Edward Reingold, Cambridge University Press, 1997, pages 85-91. 67 * 68 * <li>Hebrew Calendar Science and Myths, 69 * <a href="http://www.geocities.com/Athens/1584/"> 70 * http://www.geocities.com/Athens/1584/</a> 71 * 72 * <li>The Calendar FAQ, 73 * <a href="http://www.faqs.org/faqs/calendars/faq/"> 74 * http://www.faqs.org/faqs/calendars/faq/</a> 75 * </ul> 76 * <p> 77 * @see com.ibm.icu.util.GregorianCalendar 78 * 79 * @author Laura Werner 80 * @author Alan Liu 81 * @author Steven R. Loomis 82 * <p> 83 * @internal 84 */ 85 class U_I18N_API HebrewCalendar : public Calendar { 86 public: 87 /** 88 * Useful constants for HebrewCalendar. 89 * @internal 90 */ 91 enum Month { 92 /** 93 * Constant for Tishri, the 1st month of the Hebrew year. 94 */ 95 TISHRI, 96 /** 97 * Constant for Heshvan, the 2nd month of the Hebrew year. 98 */ 99 HESHVAN, 100 /** 101 * Constant for Kislev, the 3rd month of the Hebrew year. 102 */ 103 KISLEV, 104 105 /** 106 * Constant for Tevet, the 4th month of the Hebrew year. 107 */ 108 TEVET, 109 110 /** 111 * Constant for Shevat, the 5th month of the Hebrew year. 112 */ 113 SHEVAT, 114 115 /** 116 * Constant for Adar I, the 6th month of the Hebrew year 117 * (present in leap years only). In non-leap years, the calendar 118 * jumps from Shevat (5th month) to Adar (7th month). 119 */ 120 ADAR_1, 121 122 /** 123 * Constant for the Adar, the 7th month of the Hebrew year. 124 */ 125 ADAR, 126 127 /** 128 * Constant for Nisan, the 8th month of the Hebrew year. 129 */ 130 NISAN, 131 132 /** 133 * Constant for Iyar, the 9th month of the Hebrew year. 134 */ 135 IYAR, 136 137 /** 138 * Constant for Sivan, the 10th month of the Hebrew year. 139 */ 140 SIVAN, 141 142 /** 143 * Constant for Tammuz, the 11th month of the Hebrew year. 144 */ 145 TAMUZ, 146 147 /** 148 * Constant for Av, the 12th month of the Hebrew year. 149 */ 150 AV, 151 152 /** 153 * Constant for Elul, the 13th month of the Hebrew year. 154 */ 155 ELUL 156 }; 157 158 /** 159 * Constructs a HebrewCalendar based on the current time in the default time zone 160 * with the given locale. 161 * 162 * @param aLocale The given locale. 163 * @param success Indicates the status of HebrewCalendar object construction. 164 * Returns U_ZERO_ERROR if constructed successfully. 165 * @internal 166 */ 167 HebrewCalendar(const Locale& aLocale, UErrorCode& success); 168 169 170 /** 171 * Destructor 172 * @internal 173 */ 174 virtual ~HebrewCalendar(); 175 176 /** 177 * Copy constructor 178 * @param source the object to be copied. 179 * @internal 180 */ 181 HebrewCalendar(const HebrewCalendar& source); 182 183 /** 184 * Create and return a polymorphic copy of this calendar. 185 * @return return a polymorphic copy of this calendar. 186 * @internal 187 */ 188 virtual HebrewCalendar* clone() const override; 189 190 public: 191 /** 192 * Override Calendar Returns a unique class ID POLYMORPHICALLY. Pure virtual 193 * override. This method is to implement a simple version of RTTI, since not all C++ 194 * compilers support genuine RTTI. Polymorphic operator==() and clone() methods call 195 * this method. 196 * 197 * @return The class ID for this object. All objects of a given class have the 198 * same class ID. Objects of other classes have different class IDs. 199 * @internal 200 */ 201 virtual UClassID getDynamicClassID() const override; 202 203 /** 204 * Return the class ID for this class. This is useful only for comparing to a return 205 * value from getDynamicClassID(). For example: 206 * 207 * Base* polymorphic_pointer = createPolymorphicObject(); 208 * if (polymorphic_pointer->getDynamicClassID() == 209 * Derived::getStaticClassID()) ... 210 * 211 * @return The class ID for all objects of this class. 212 * @internal 213 */ 214 static UClassID U_EXPORT2 getStaticClassID(); 215 216 /** 217 * return the calendar type, "hebrew". 218 * 219 * @return calendar type 220 * @internal 221 */ 222 virtual const char * getType() const override; 223 224 225 // Calendar API 226 public: 227 /** 228 * (Overrides Calendar) UDate Arithmetic function. Adds the specified (signed) amount 229 * of time to the given time field, based on the calendar's rules. For more 230 * information, see the documentation for Calendar::add(). 231 * 232 * @param field The time field. 233 * @param amount The amount of date or time to be added to the field. 234 * @param status Output param set to success/failure code on exit. If any value 235 * previously set in the time field is invalid, this will be set to 236 * an error status. 237 */ 238 virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& status) override; 239 /** 240 * @deprecated ICU 2.6 use UCalendarDateFields instead of EDateFields 241 */ 242 virtual void add(EDateFields field, int32_t amount, UErrorCode& status) override; 243 244 245 /** 246 * (Overrides Calendar) Rolls up or down by the given amount in the specified field. 247 * For more information, see the documentation for Calendar::roll(). 248 * 249 * @param field The time field. 250 * @param amount Indicates amount to roll. 251 * @param status Output param set to success/failure code on exit. If any value 252 * previously set in the time field is invalid, this will be set to 253 * an error status. 254 * @internal 255 */ 256 virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode& status) override; 257 258 /** 259 * (Overrides Calendar) Rolls up or down by the given amount in the specified field. 260 * For more information, see the documentation for Calendar::roll(). 261 * 262 * @param field The time field. 263 * @param amount Indicates amount to roll. 264 * @param status Output param set to success/failure code on exit. If any value 265 * previously set in the time field is invalid, this will be set to 266 * an error status. 267 * @deprecated ICU 2.6. Use roll(UCalendarDateFields field, int32_t amount, UErrorCode& status) instead. 268 ` */ 269 virtual void roll(EDateFields field, int32_t amount, UErrorCode& status) override; 270 271 /** 272 * @internal 273 */ 274 static UBool isLeapYear(int32_t year) ; 275 276 /** 277 * @return The related Gregorian year; will be obtained by modifying the value 278 * obtained by get from UCAL_EXTENDED_YEAR field 279 * @internal 280 */ 281 virtual int32_t getRelatedYear(UErrorCode &status) const override; 282 283 /** 284 * @param year The related Gregorian year to set; will be modified as necessary then 285 * set in UCAL_EXTENDED_YEAR field 286 * @internal 287 */ 288 virtual void setRelatedYear(int32_t year) override; 289 290 protected: 291 292 /** 293 * Subclass API for defining limits of different types. 294 * Subclasses must implement this method to return limits for the 295 * following fields: 296 * 297 * <pre>UCAL_ERA 298 * UCAL_YEAR 299 * UCAL_MONTH 300 * UCAL_WEEK_OF_YEAR 301 * UCAL_WEEK_OF_MONTH 302 * UCAL_DATE (DAY_OF_MONTH on Java) 303 * UCAL_DAY_OF_YEAR 304 * UCAL_DAY_OF_WEEK_IN_MONTH 305 * UCAL_YEAR_WOY 306 * UCAL_EXTENDED_YEAR</pre> 307 * 308 * @param field one of the above field numbers 309 * @param limitType one of <code>MINIMUM</code>, <code>GREATEST_MINIMUM</code>, 310 * <code>LEAST_MAXIMUM</code>, or <code>MAXIMUM</code> 311 * @internal 312 */ 313 virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const override; 314 315 /** 316 * Return the number of days in the given month of the given extended 317 * year of this calendar system. Subclasses should override this 318 * method if they can provide a more correct or more efficient 319 * implementation than the default implementation in Calendar. 320 * @internal 321 */ 322 virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month, UErrorCode& status) const override; 323 324 /** 325 * Return the number of days in the given extended year of this 326 * calendar system. Subclasses should override this method if they can 327 * provide a more correct or more efficient implementation than the 328 * default implementation in Calendar. 329 * @stable ICU 2.0 330 */ 331 virtual int32_t handleGetYearLength(int32_t eyear) const override; 332 /** 333 * Subclasses may override this method to compute several fields 334 * specific to each calendar system. These are: 335 * 336 * <ul><li>ERA 337 * <li>YEAR 338 * <li>MONTH 339 * <li>DAY_OF_MONTH 340 * <li>DAY_OF_YEAR 341 * <li>EXTENDED_YEAR</ul> 342 * 343 * <p>The GregorianCalendar implementation implements 344 * a calendar with the specified Julian/Gregorian cutover date. 345 * @internal 346 */ 347 virtual void handleComputeFields(int32_t julianDay, UErrorCode &status) override; 348 /** 349 * Return the extended year defined by the current fields. This will 350 * use the UCAL_EXTENDED_YEAR field or the UCAL_YEAR and supra-year fields (such 351 * as UCAL_ERA) specific to the calendar system, depending on which set of 352 * fields is newer. 353 * @param status 354 * @return the extended year 355 * @internal 356 */ 357 virtual int32_t handleGetExtendedYear(UErrorCode& status) override; 358 /** 359 * Return the Julian day number of day before the first day of the 360 * given month in the given extended year. Subclasses should override 361 * this method to implement their calendar system. 362 * @param eyear the extended year 363 * @param month the zero-based month, or 0 if useMonth is false 364 * @param useMonth if false, compute the day before the first day of 365 * the given year, otherwise, compute the day before the first day of 366 * the given month 367 * @param return the Julian day number of the day before the first 368 * day of the given month and year 369 * @internal 370 */ 371 virtual int64_t handleComputeMonthStart(int32_t eyear, int32_t month, 372 UBool useMonth, UErrorCode& status) const override; 373 374 375 /** 376 * Validate a single field of this calendar. 377 * Overrides Calendar::validateField(int) to provide 378 * special handling for month validation for Hebrew calendar. 379 * @internal 380 */ 381 virtual void validateField(UCalendarDateFields field, UErrorCode &status) override; 382 383 protected: 384 DECLARE_OVERRIDE_SYSTEM_DEFAULT_CENTURY 385 386 public: 387 /** 388 * Returns true if the date is in a leap year. 389 * 390 * @param status ICU Error Code 391 * @return True if the date in the fields is in a Temporal proposal 392 * defined leap year. False otherwise. 393 */ 394 virtual bool inTemporalLeapYear(UErrorCode& status) const override; 395 396 /** 397 * Gets The Temporal monthCode value corresponding to the month for the date. 398 * The value is a string identifier that starts with the literal grapheme 399 * "M" followed by two graphemes representing the zero-padded month number 400 * of the current month in a normal (non-leap) year and suffixed by an 401 * optional literal grapheme "L" if this is a leap month in a lunisolar 402 * calendar. For the Hebrew calendar, the values are "M01" .. "M12" for 403 * non-leap year, and "M01" .. "M05", "M05L", "M06" .. "M12" for leap year. 404 * 405 * @param status ICU Error Code 406 * @return One of 13 possible strings in {"M01".. "M05", "M05L", 407 * "M06" .. "M12"}. 408 * @draft ICU 73 409 */ 410 virtual const char* getTemporalMonthCode(UErrorCode& status) const override; 411 412 /** 413 * Sets The Temporal monthCode which is a string identifier that starts 414 * with the literal grapheme "M" followed by two graphemes representing 415 * the zero-padded month number of the current month in a normal 416 * (non-leap) year and suffixed by an optional literal grapheme "L" if this 417 * is a leap month in a lunisolar calendar. For Hebrew calendar, the values 418 * are "M01" .. "M12" for non-leap years, and "M01" .. "M05", "M05L", "M06" 419 * .. "M12" for leap year. 420 * 421 * @param temporalMonth The value to be set for temporal monthCode. 422 * @param status ICU Error Code 423 * 424 * @draft ICU 73 425 */ 426 virtual void setTemporalMonthCode(const char* code, UErrorCode& status ) override; 427 428 protected: 429 virtual int32_t internalGetMonth(UErrorCode& status) const override; 430 431 private: // Calendar-specific implementation 432 /** 433 * Finds the day # of the first day in the given Hebrew year. 434 * To do this, we want to calculate the time of the Tishri 1 new moon 435 * in that year. 436 * <p> 437 * The algorithm here is similar to ones described in a number of 438 * references, including: 439 * <ul> 440 * <li>"Calendrical Calculations", by Nachum Dershowitz & Edward Reingold, 441 * Cambridge University Press, 1997, pages 85-91. 442 * 443 * <li>Hebrew Calendar Science and Myths, 444 * <a href="http://www.geocities.com/Athens/1584/"> 445 * http://www.geocities.com/Athens/1584/</a> 446 * 447 * <li>The Calendar FAQ, 448 * <a href="http://www.faqs.org/faqs/calendars/faq/"> 449 * http://www.faqs.org/faqs/calendars/faq/</a> 450 * </ul> 451 * @param year extended year 452 * @return day number (JD) 453 * @internal 454 */ 455 static int32_t startOfYear(int32_t year, UErrorCode& status); 456 457 static int32_t absoluteDayToDayOfWeek(int32_t day) ; 458 459 /** 460 * @internal 461 */ 462 int32_t yearType(int32_t year) const; 463 464 /** 465 * @internal 466 */ 467 static int32_t monthsInYear(int32_t year) ; 468 }; 469 470 U_NAMESPACE_END 471 472 #endif /* #if !UCONFIG_NO_FORMATTING */ 473 474 #endif 475 //eof 476 477