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>The <a href="http://www.tondering.dk/claus/calendar.html"> 79 * Calendar FAQ</a></li> 80 * 81 * </ul> 82 * 83 * <p> 84 * This class should only be subclassed to implement variants of the Chinese lunar calendar.</p> 85 * <p> 86 * ChineseCalendar usually should be instantiated using 87 * {@link com.ibm.icu.util.Calendar#getInstance(ULocale)} passing in a <code>ULocale</code> 88 * with the tag <code>"@calendar=chinese"</code>.</p> 89 * 90 * @see com.ibm.icu.text.ChineseDateFormat 91 * @see com.ibm.icu.util.Calendar 92 * @author Alan Liu 93 * @internal 94 */ 95 class U_I18N_API ChineseCalendar : public Calendar { 96 public: 97 //------------------------------------------------------------------------- 98 // Constructors... 99 //------------------------------------------------------------------------- 100 101 /** 102 * Constructs a ChineseCalendar based on the current time in the default time zone 103 * with the given locale. 104 * 105 * @param aLocale The given locale. 106 * @param success Indicates the status of ChineseCalendar object construction. 107 * Returns U_ZERO_ERROR if constructed successfully. 108 * @internal 109 */ 110 ChineseCalendar(const Locale& aLocale, UErrorCode &success); 111 112 /** 113 * Returns true if the date is in a leap year. 114 * 115 * @param status ICU Error Code 116 * @return True if the date in the fields is in a Temporal proposal 117 * defined leap year. False otherwise. 118 */ 119 virtual bool inTemporalLeapYear(UErrorCode &status) const override; 120 121 /** 122 * Gets The Temporal monthCode value corresponding to the month for the date. 123 * The value is a string identifier that starts with the literal grapheme 124 * "M" followed by two graphemes representing the zero-padded month number 125 * of the current month in a normal (non-leap) year and suffixed by an 126 * optional literal grapheme "L" if this is a leap month in a lunisolar 127 * calendar. For Chinese calendars (including Dangi), the values are 128 * "M01" .. "M12" for non-leap year, and "M01" .. "M12" with one of 129 * "M01L" .. "M12L" for leap year. 130 * 131 * @param status ICU Error Code 132 * @return One of 24 possible strings in 133 * {"M01" .. "M12", "M01L" .. "M12L"}. 134 * @draft ICU 73 135 */ 136 virtual const char* getTemporalMonthCode(UErrorCode &status) const override; 137 138 /** 139 * Sets The Temporal monthCode which is a string identifier that starts 140 * with the literal grapheme "M" followed by two graphemes representing 141 * the zero-padded month number of the current month in a normal 142 * (non-leap) year and suffixed by an optional literal grapheme "L" if this 143 * is a leap month in a lunisolar calendar. For Chinese calendars, the values 144 * are "M01" .. "M12" for non-leap years, and "M01" .. "M12" plus one in 145 * "M01L" .. "M12L" for leap year. 146 * 147 * @param temporalMonth The value to be set for temporal monthCode. One of 148 * 24 possible strings in {"M01" .. "M12", "M01L" .. "M12L"}. 149 * @param status ICU Error Code 150 * 151 * @draft ICU 73 152 */ 153 virtual void setTemporalMonthCode(const char* code, UErrorCode& status) override; 154 155 protected: 156 157 /** 158 * Constructs a ChineseCalendar based on the current time in the default time zone 159 * with the given locale, using the specified epoch year and time zone for 160 * astronomical calculations. 161 * 162 * @param aLocale The given locale. 163 * @param epochYear The epoch year to use for calculation. 164 * @param zoneAstroCalc The TimeZone to use for astronomical calculations. If null, 165 * will be set appropriately for Chinese calendar (UTC + 8:00). 166 * @param success Indicates the status of ChineseCalendar object construction; 167 * if successful, will not be changed to an error value. 168 * @internal 169 */ 170 ChineseCalendar(const Locale& aLocale, int32_t epochYear, const TimeZone* zoneAstroCalc, UErrorCode &success); 171 172 public: 173 /** 174 * Copy Constructor 175 * @internal 176 */ 177 ChineseCalendar(const ChineseCalendar& other); 178 179 /** 180 * Destructor. 181 * @internal 182 */ 183 virtual ~ChineseCalendar(); 184 185 // clone 186 virtual ChineseCalendar* clone() const override; 187 188 private: 189 190 //------------------------------------------------------------------------- 191 // Internal data.... 192 //------------------------------------------------------------------------- 193 194 // There is a leap month between the Winter Solstice before and after the 195 // current date.This is different from leap year because in some year, such as 196 // 1813 and 2033, the leap month is after the Winter Solstice of that year. So 197 // this value could be false for a date prior to the Winter Solstice of that 198 // year but that year still has a leap month and therefor is a leap year. 199 UBool hasLeapMonthBetweenWinterSolstices; 200 int32_t fEpochYear; // Start year of this Chinese calendar instance. 201 const TimeZone* fZoneAstroCalc; // Zone used for the astronomical calculation 202 // of this Chinese calendar instance. 203 204 //---------------------------------------------------------------------- 205 // Calendar framework 206 //---------------------------------------------------------------------- 207 208 protected: 209 virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const override; 210 virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const override; 211 virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month, UBool useMonth) const override; 212 virtual int32_t handleGetExtendedYear() override; 213 virtual void handleComputeFields(int32_t julianDay, UErrorCode &status) override; 214 virtual const UFieldResolutionTable* getFieldResolutionTable() const override; 215 216 public: 217 virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode &status) override; 218 virtual void add(EDateFields field, int32_t amount, UErrorCode &status) override; 219 virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode &status) override; 220 virtual void roll(EDateFields field, int32_t amount, UErrorCode &status) override; 221 222 /** 223 * @return The related Gregorian year; will be obtained by modifying the value 224 * obtained by get from UCAL_EXTENDED_YEAR field 225 * @internal 226 */ 227 virtual int32_t getRelatedYear(UErrorCode &status) const override; 228 229 /** 230 * @param year The related Gregorian year to set; will be modified as necessary then 231 * set in UCAL_EXTENDED_YEAR field 232 * @internal 233 */ 234 virtual void setRelatedYear(int32_t year) override; 235 236 //---------------------------------------------------------------------- 237 // Internal methods & astronomical calculations 238 //---------------------------------------------------------------------- 239 240 private: 241 242 static const UFieldResolutionTable CHINESE_DATE_PRECEDENCE[]; 243 244 double daysToMillis(double days) const; 245 double millisToDays(double millis) const; 246 virtual int32_t winterSolstice(int32_t gyear) const; 247 virtual int32_t newMoonNear(double days, UBool after) const; 248 virtual int32_t synodicMonthsBetween(int32_t day1, int32_t day2) const; 249 virtual int32_t majorSolarTerm(int32_t days) const; 250 virtual UBool hasNoMajorSolarTerm(int32_t newMoon) const; 251 virtual UBool isLeapMonthBetween(int32_t newMoon1, int32_t newMoon2) const; 252 virtual void computeChineseFields(int32_t days, int32_t gyear, 253 int32_t gmonth, UBool setAllFields); 254 virtual int32_t newYear(int32_t gyear) const; 255 virtual void offsetMonth(int32_t newMoon, int32_t dom, int32_t delta, UErrorCode& status); 256 const TimeZone* getChineseCalZoneAstroCalc() const; 257 258 // UObject stuff 259 public: 260 /** 261 * @return The class ID for this object. All objects of a given class have the 262 * same class ID. Objects of other classes have different class IDs. 263 * @internal 264 */ 265 virtual UClassID getDynamicClassID() const override; 266 267 /** 268 * Return the class ID for this class. This is useful only for comparing to a return 269 * value from getDynamicClassID(). For example: 270 * 271 * Base* polymorphic_pointer = createPolymorphicObject(); 272 * if (polymorphic_pointer->getDynamicClassID() == 273 * Derived::getStaticClassID()) ... 274 * 275 * @return The class ID for all objects of this class. 276 * @internal 277 */ 278 static UClassID U_EXPORT2 getStaticClassID(); 279 280 /** 281 * return the calendar type, "chinese". 282 * 283 * @return calendar type 284 * @internal 285 */ 286 virtual const char * getType() const override; 287 288 protected: 289 virtual int32_t internalGetMonth(int32_t defaultValue) const override; 290 291 virtual int32_t internalGetMonth() const override; 292 293 protected: 294 /** 295 * Returns true because the Islamic Calendar does have a default century 296 * @internal 297 */ 298 virtual UBool haveDefaultCentury() const override; 299 300 /** 301 * Returns the date of the start of the default century 302 * @return start of century - in milliseconds since epoch, 1970 303 * @internal 304 */ 305 virtual UDate defaultCenturyStart() const override; 306 307 /** 308 * Returns the year in which the default century begins 309 * @internal 310 */ 311 virtual int32_t defaultCenturyStartYear() const override; 312 313 private: // default century stuff. 314 315 /** 316 * Returns the beginning date of the 100-year window that dates 317 * with 2-digit years are considered to fall within. 318 */ 319 UDate internalGetDefaultCenturyStart() const; 320 321 /** 322 * Returns the first year of the 100-year window that dates with 323 * 2-digit years are considered to fall within. 324 */ 325 int32_t internalGetDefaultCenturyStartYear() const; 326 327 ChineseCalendar() = delete; // default constructor not implemented 328 }; 329 330 U_NAMESPACE_END 331 332 #endif 333 #endif 334