icuSources/i18n/hebrwcal.h

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