icuSources/i18n/chnsecal.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4  *****************************************************************************
   5  * Copyright (C) 2007-2013, International Business Machines Corporation
   6  * and others. All Rights Reserved.
   7  *****************************************************************************
   8  *
   9  * File CHNSECAL.H
  10  *
  11  * Modification History:
  12  *
  13  *   Date        Name        Description
  14  *   9/18/2007  ajmacher         ported from java ChineseCalendar
  15  *****************************************************************************
  16  */
  17
  18 #ifndef CHNSECAL_H
  19 #define CHNSECAL_H
  20
  21 #include "unicode/utypes.h"
  22
  23 #if !UCONFIG_NO_FORMATTING
  24
  25 #include "unicode/calendar.h"
  26 #include "unicode/timezone.h"
  27
  28 U_NAMESPACE_BEGIN
  29
  30 /**
  31  * <code>ChineseCalendar</code> is a concrete subclass of {@link Calendar}
  32  * that implements a traditional Chinese calendar.  The traditional Chinese
  33  * calendar is a lunisolar calendar: Each month starts on a new moon, and
  34  * the months are numbered according to solar events, specifically, to
  35  * guarantee that month 11 always contains the winter solstice.  In order
  36  * to accomplish this, leap months are inserted in certain years.  Leap
  37  * months are numbered the same as the month they follow.  The decision of
  38  * which month is a leap month depends on the relative movements of the sun
  39  * and moon.
  40  *
  41  * <p>This class defines one addition field beyond those defined by
  42  * <code>Calendar</code>: The <code>IS_LEAP_MONTH</code> field takes the
  43  * value of 0 for normal months, or 1 for leap months.
  44  *
  45  * <p>All astronomical computations are performed with respect to a time
  46  * zone of GMT+8:00 and a longitude of 120 degrees east.  Although some
  47  * calendars implement a historically more accurate convention of using
  48  * Beijing's local longitude (116 degrees 25 minutes east) and time zone
  49  * (GMT+7:45:40) for dates before 1929, we do not implement this here.
  50  *
  51  * <p>Years are counted in two different ways in the Chinese calendar.  The
  52  * first method is by sequential numbering from the 61st year of the reign
  53  * of Huang Di, 2637 BCE, which is designated year 1 on the Chinese
  54  * calendar.  The second method uses 60-year cycles from the same starting
  55  * point, which is designated year 1 of cycle 1.  In this class, the
  56  * <code>EXTENDED_YEAR</code> field contains the sequential year count.
  57  * The <code>ERA</code> field contains the cycle number, and the
  58  * <code>YEAR</code> field contains the year of the cycle, a value between
  59  * 1 and 60.
  60  *
  61  * <p>There is some variation in what is considered the starting point of
  62  * the calendar, with some sources starting in the first year of the reign
  63  * of Huang Di, rather than the 61st.  This gives continuous year numbers
  64  * 60 years greater and cycle numbers one greater than what this class
  65  * implements.
  66  *
  67  * <p>Because <code>ChineseCalendar</code> defines an additional field and
  68  * redefines the way the <code>ERA</code> field is used, it requires a new
  69  * format class, <code>ChineseDateFormat</code>.  As always, use the
  70  * methods <code>DateFormat.getXxxInstance(Calendar cal,...)</code> to
  71  * obtain a formatter for this calendar.
  72  *
  73  * <p>References:<ul>
  74  *
  75  * <li>Dershowitz and Reingold, <i>Calendrical Calculations</i>,
  76  * Cambridge University Press, 1997</li>
  77  *
  78  * <li>Helmer Aslaksen's
  79  * <a href="http://www.math.nus.edu.sg/aslaksen/calendar/chinese.shtml">
  80  * Chinese Calendar page</a></li>
  81  *
  82  * <li>The <a href="http://www.tondering.dk/claus/calendar.html">
  83  * Calendar FAQ</a></li>
  84  *
  85  * </ul>
  86  *
  87  * <p>
  88  * This class should only be subclassed to implement variants of the Chinese lunar calendar.</p>
  89  * <p>
  90  * ChineseCalendar usually should be instantiated using
  91  * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code>
  92  * with the tag <code>"@calendar=chinese"</code>.</p>
  93  *
  94  * @see com.ibm.icu.text.ChineseDateFormat
  95  * @see com.ibm.icu.util.Calendar
  96  * @author Alan Liu
  97  * @internal
  98  */
  99 class U_I18N_API ChineseCalendar : public Calendar {
 100  public:
 101   //-------------------------------------------------------------------------
 102   // Constructors...
 103   //-------------------------------------------------------------------------
 104
 105   /**
 106    * Constructs a ChineseCalendar based on the current time in the default time zone
 107    * with the given locale.
 108    *
 109    * @param aLocale  The given locale.
 110    * @param success  Indicates the status of ChineseCalendar object construction.
 111    *                 Returns U_ZERO_ERROR if constructed successfully.
 112    * @internal
 113    */
 114   ChineseCalendar(const Locale& aLocale, UErrorCode &success);
 115
 116  protected:
 117
 118    /**
 119    * Constructs a ChineseCalendar based on the current time in the default time zone
 120    * with the given locale, using the specified epoch year and time zone for
 121    * astronomical calculations.
 122    *
 123    * @param aLocale         The given locale.
 124    * @param epochYear       The epoch year to use for calculation.
 125    * @param zoneAstroCalc   The TimeZone to use for astronomical calculations. If null,
 126    *                        will be set appropriately for Chinese calendar (UTC + 8:00).
 127    * @param success         Indicates the status of ChineseCalendar object construction;
 128    *                        if successful, will not be changed to an error value.
 129    * @internal
 130    */
 131   ChineseCalendar(const Locale& aLocale, int32_t epochYear, const TimeZone* zoneAstroCalc, UErrorCode &success);
 132
 133  public:
 134   /**
 135    * Copy Constructor
 136    * @internal
 137    */
 138   ChineseCalendar(const ChineseCalendar& other);
 139
 140   /**
 141    * Destructor.
 142    * @internal
 143    */
 144   virtual ~ChineseCalendar();
 145
 146   // clone
 147   virtual Calendar* clone() const;
 148
 149  private:
 150
 151   //-------------------------------------------------------------------------
 152   // Internal data....
 153   //-------------------------------------------------------------------------
 154
 155   UBool isLeapYear;
 156   int32_t fEpochYear;   // Start year of this Chinese calendar instance.
 157   const TimeZone* fZoneAstroCalc;   // Zone used for the astronomical calculation
 158                                     // of this Chinese calendar instance.
 159
 160   //----------------------------------------------------------------------
 161   // Calendar framework
 162   //----------------------------------------------------------------------
 163
 164  protected:
 165   virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const;
 166   virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const;
 167   virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month, UBool useMonth) const;
 168   virtual int32_t handleGetExtendedYear();
 169   virtual void handleComputeFields(int32_t julianDay, UErrorCode &status);
 170   virtual const UFieldResolutionTable* getFieldResolutionTable() const;
 171
 172  public:
 173   virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode &status);
 174   virtual void add(EDateFields field, int32_t amount, UErrorCode &status);
 175   virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode &status);
 176   virtual void roll(EDateFields field, int32_t amount, UErrorCode &status);
 177
 178   //----------------------------------------------------------------------
 179   // Internal methods & astronomical calculations
 180   //----------------------------------------------------------------------
 181
 182  private:
 183
 184   static const UFieldResolutionTable CHINESE_DATE_PRECEDENCE[];
 185
 186   double daysToMillis(double days) const;
 187   double millisToDays(double millis) const;
 188   virtual int32_t winterSolstice(int32_t gyear) const;
 189   virtual int32_t newMoonNear(double days, UBool after) const;
 190   virtual int32_t synodicMonthsBetween(int32_t day1, int32_t day2) const;
 191   virtual int32_t majorSolarTerm(int32_t days) const;
 192   virtual UBool hasNoMajorSolarTerm(int32_t newMoon) const;
 193   virtual UBool isLeapMonthBetween(int32_t newMoon1, int32_t newMoon2) const;
 194   virtual void computeChineseFields(int32_t days, int32_t gyear,
 195                  int32_t gmonth, UBool setAllFields);
 196   virtual int32_t newYear(int32_t gyear) const;
 197   virtual void offsetMonth(int32_t newMoon, int32_t dom, int32_t delta);
 198   const TimeZone* getChineseCalZoneAstroCalc(void) const;
 199
 200   // UObject stuff
 201  public:
 202   /**
 203    * @return   The class ID for this object. All objects of a given class have the
 204    *           same class ID. Objects of other classes have different class IDs.
 205    * @internal
 206    */
 207   virtual UClassID getDynamicClassID(void) const;
 208
 209   /**
 210    * Return the class ID for this class. This is useful only for comparing to a return
 211    * value from getDynamicClassID(). For example:
 212    *
 213    *      Base* polymorphic_pointer = createPolymorphicObject();
 214    *      if (polymorphic_pointer->getDynamicClassID() ==
 215    *          Derived::getStaticClassID()) ...
 216    *
 217    * @return   The class ID for all objects of this class.
 218    * @internal
 219    */
 220   static UClassID U_EXPORT2 getStaticClassID(void);
 221
 222   /**
 223    * return the calendar type, "chinese".
 224    *
 225    * @return calendar type
 226    * @internal
 227    */
 228   virtual const char * getType() const;
 229
 230
 231  protected:
 232   /**
 233    * (Overrides Calendar) Return true if the current date for this Calendar is in
 234    * Daylight Savings Time. Recognizes DST_OFFSET, if it is set.
 235    *
 236    * @param status Fill-in parameter which receives the status of this operation.
 237    * @return   True if the current date for this Calendar is in Daylight Savings Time,
 238    *           false, otherwise.
 239    * @internal
 240    */
 241   virtual UBool inDaylightTime(UErrorCode& status) const;
 242
 243
 244   /**
 245    * Returns TRUE because the Islamic Calendar does have a default century
 246    * @internal
 247    */
 248   virtual UBool haveDefaultCentury() const;
 249
 250   /**
 251    * Returns the date of the start of the default century
 252    * @return start of century - in milliseconds since epoch, 1970
 253    * @internal
 254    */
 255   virtual UDate defaultCenturyStart() const;
 256
 257   /**
 258    * Returns the year in which the default century begins
 259    * @internal
 260    */
 261   virtual int32_t defaultCenturyStartYear() const;
 262
 263  private: // default century stuff.
 264
 265   /**
 266    * Returns the beginning date of the 100-year window that dates
 267    * with 2-digit years are considered to fall within.
 268    */
 269   UDate         internalGetDefaultCenturyStart(void) const;
 270
 271   /**
 272    * Returns the first year of the 100-year window that dates with
 273    * 2-digit years are considered to fall within.
 274    */
 275   int32_t          internalGetDefaultCenturyStartYear(void) const;
 276
 277   ChineseCalendar(); // default constructor not implemented
 278 };
 279
 280 U_NAMESPACE_END
 281
 282 #endif
 283 #endif