ICU 49.1.1  49.1.1
calendar.h
Go to the documentation of this file.
1 /*
2 ********************************************************************************
3 * Copyright (C) 1997-2012, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 ********************************************************************************
6 *
7 * File CALENDAR.H
8 *
9 * Modification History:
10 *
11 * Date Name Description
12 * 04/22/97 aliu Expanded and corrected comments and other header
13 * contents.
14 * 05/01/97 aliu Made equals(), before(), after() arguments const.
15 * 05/20/97 aliu Replaced fAreFieldsSet with fAreFieldsInSync and
16 * fAreAllFieldsSet.
17 * 07/27/98 stephen Sync up with JDK 1.2
18 * 11/15/99 weiv added YEAR_WOY and DOW_LOCAL
19 * to EDateFields
20 * 8/19/2002 srl Removed Javaisms
21 * 11/07/2003 srl Update, clean up documentation.
22 ********************************************************************************
23 */
24 
25 #ifndef CALENDAR_H
26 #define CALENDAR_H
27 
28 #include "unicode/utypes.h"
29 
34 #if !UCONFIG_NO_FORMATTING
35 
36 #include "unicode/uobject.h"
37 #include "unicode/locid.h"
38 #include "unicode/timezone.h"
39 #include "unicode/ucal.h"
40 #include "unicode/umisc.h"
41 
43 
44 class ICUServiceFactory;
45 
49 typedef int32_t UFieldResolutionTable[12][8];
50 
51 class BasicTimeZone;
166 class U_I18N_API Calendar : public UObject {
167 public:
168 
175  enum EDateFields {
176 #ifndef U_HIDE_DEPRECATED_API
177 /*
178  * ERA may be defined on other platforms. To avoid any potential problems undefined it here.
179  */
180 #ifdef ERA
181 #undef ERA
182 #endif
183  ERA, // Example: 0..1
184  YEAR, // Example: 1..big number
185  MONTH, // Example: 0..11
186  WEEK_OF_YEAR, // Example: 1..53
187  WEEK_OF_MONTH, // Example: 1..4
188  DATE, // Example: 1..31
189  DAY_OF_YEAR, // Example: 1..365
190  DAY_OF_WEEK, // Example: 1..7
191  DAY_OF_WEEK_IN_MONTH, // Example: 1..4, may be specified as -1
192  AM_PM, // Example: 0..1
193  HOUR, // Example: 0..11
194  HOUR_OF_DAY, // Example: 0..23
195  MINUTE, // Example: 0..59
196  SECOND, // Example: 0..59
197  MILLISECOND, // Example: 0..999
198  ZONE_OFFSET, // Example: -12*U_MILLIS_PER_HOUR..12*U_MILLIS_PER_HOUR
199  DST_OFFSET, // Example: 0 or U_MILLIS_PER_HOUR
200  YEAR_WOY, // 'Y' Example: 1..big number - Year of Week of Year
201  DOW_LOCAL, // 'e' Example: 1..7 - Day of Week / Localized
202 
203  EXTENDED_YEAR,
204  JULIAN_DAY,
205  MILLISECONDS_IN_DAY,
206  IS_LEAP_MONTH,
207 
208  FIELD_COUNT = UCAL_FIELD_COUNT // See ucal.h for other fields.
209 #endif /* U_HIDE_DEPRECATED_API */
210  };
211 
212 #ifndef U_HIDE_DEPRECATED_API
213 
219  enum EDaysOfWeek {
220  SUNDAY = 1,
221  MONDAY,
222  TUESDAY,
223  WEDNESDAY,
224  THURSDAY,
225  FRIDAY,
226  SATURDAY
227  };
228 
233  enum EMonths {
234  JANUARY,
235  FEBRUARY,
236  MARCH,
237  APRIL,
238  MAY,
239  JUNE,
240  JULY,
241  AUGUST,
242  SEPTEMBER,
243  OCTOBER,
244  NOVEMBER,
245  DECEMBER,
246  UNDECIMBER
247  };
248 
253  enum EAmpm {
254  AM,
255  PM
256  };
257 #endif /* U_HIDE_DEPRECATED_API */
258 
263  virtual ~Calendar();
264 
271  virtual Calendar* clone(void) const = 0;
272 
284  static Calendar* U_EXPORT2 createInstance(UErrorCode& success);
285 
298  static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, UErrorCode& success);
299 
311  static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, UErrorCode& success);
312 
323  static Calendar* U_EXPORT2 createInstance(const Locale& aLocale, UErrorCode& success);
324 
338  static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, const Locale& aLocale, UErrorCode& success);
339 
352  static Calendar* U_EXPORT2 createInstance(const TimeZone& zoneToAdopt, const Locale& aLocale, UErrorCode& success);
353 
363  static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
364 
365 
382  static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* key,
383  const Locale& locale, UBool commonlyUsed, UErrorCode& status);
384 
392  static UDate U_EXPORT2 getNow(void);
393 
407  inline UDate getTime(UErrorCode& status) const { return getTimeInMillis(status); }
408 
419  inline void setTime(UDate date, UErrorCode& status) { setTimeInMillis(date, status); }
420 
432  virtual UBool operator==(const Calendar& that) const;
433 
442  UBool operator!=(const Calendar& that) const {return !operator==(that);}
443 
454  virtual UBool isEquivalentTo(const Calendar& other) const;
455 
470  UBool equals(const Calendar& when, UErrorCode& status) const;
471 
485  UBool before(const Calendar& when, UErrorCode& status) const;
486 
500  UBool after(const Calendar& when, UErrorCode& status) const;
501 
519  virtual void add(EDateFields field, int32_t amount, UErrorCode& status);
520 
538  virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& status);
539 
540 #ifndef U_HIDE_DEPRECATED_API
541 
564  inline void roll(EDateFields field, UBool up, UErrorCode& status);
565 #endif /* U_HIDE_DEPRECATED_API */
566 
590  inline void roll(UCalendarDateFields field, UBool up, UErrorCode& status);
591 
614  virtual void roll(EDateFields field, int32_t amount, UErrorCode& status);
615 
638  virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode& status);
639 
695  virtual int32_t fieldDifference(UDate when, EDateFields field, UErrorCode& status);
696 
752  virtual int32_t fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status);
753 
762  void adoptTimeZone(TimeZone* value);
763 
771  void setTimeZone(const TimeZone& zone);
772 
781  const TimeZone& getTimeZone(void) const;
782 
791  TimeZone* orphanTimeZone(void);
792 
801  virtual UBool inDaylightTime(UErrorCode& status) const = 0;
802 
815  void setLenient(UBool lenient);
816 
823  UBool isLenient(void) const;
824 
825 #ifndef U_HIDE_DRAFT_API
826 
846  void setRepeatedWallTimeOption(UCalendarWallTimeOption option);
847 
857  UCalendarWallTimeOption getRepeatedWallTimeOption(void) const;
858 
880  void setSkippedWallTimeOption(UCalendarWallTimeOption option);
881 
892  UCalendarWallTimeOption getSkippedWallTimeOption(void) const;
893 #endif /* U_HIDE_DRAFT_API */
894 
895 #ifndef U_HIDE_DEPRECATED_API
896 
902  void setFirstDayOfWeek(EDaysOfWeek value);
903 #endif /* U_HIDE_DEPRECATED_API */
904 
911  void setFirstDayOfWeek(UCalendarDaysOfWeek value);
912 
913 #ifndef U_HIDE_DEPRECATED_API
914 
920  EDaysOfWeek getFirstDayOfWeek(void) const;
921 #endif /* U_HIDE_DEPRECATED_API */
922 
930  UCalendarDaysOfWeek getFirstDayOfWeek(UErrorCode &status) const;
931 
941  void setMinimalDaysInFirstWeek(uint8_t value);
942 
952  uint8_t getMinimalDaysInFirstWeek(void) const;
953 
962  virtual int32_t getMinimum(EDateFields field) const;
963 
972  virtual int32_t getMinimum(UCalendarDateFields field) const;
973 
982  virtual int32_t getMaximum(EDateFields field) const;
983 
992  virtual int32_t getMaximum(UCalendarDateFields field) const;
993 
1002  virtual int32_t getGreatestMinimum(EDateFields field) const;
1003 
1012  virtual int32_t getGreatestMinimum(UCalendarDateFields field) const;
1013 
1022  virtual int32_t getLeastMaximum(EDateFields field) const;
1023 
1032  virtual int32_t getLeastMaximum(UCalendarDateFields field) const;
1033 
1034 #ifndef U_HIDE_DEPRECATED_API
1035 
1049  int32_t getActualMinimum(EDateFields field, UErrorCode& status) const;
1050 #endif /* U_HIDE_DEPRECATED_API */
1051 
1066  virtual int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& status) const;
1067 
1068 #ifndef U_HIDE_DEPRECATED_API
1069 
1085  int32_t getActualMaximum(EDateFields field, UErrorCode& status) const;
1086 #endif /* U_HIDE_DEPRECATED_API */
1087 
1104  virtual int32_t getActualMaximum(UCalendarDateFields field, UErrorCode& status) const;
1105 
1106 #ifndef U_HIDE_DEPRECATED_API
1107 
1120  int32_t get(EDateFields field, UErrorCode& status) const;
1121 #endif /* U_HIDE_DEPRECATED_API */
1122 
1136  int32_t get(UCalendarDateFields field, UErrorCode& status) const;
1137 
1138 #ifndef U_HIDE_DEPRECATED_API
1139 
1147  UBool isSet(EDateFields field) const;
1148 #endif /* U_HIDE_DEPRECATED_API */
1149 
1158  UBool isSet(UCalendarDateFields field) const;
1159 
1160 #ifndef U_HIDE_DEPRECATED_API
1161 
1168  void set(EDateFields field, int32_t value);
1169 #endif /* U_HIDE_DEPRECATED_API */
1170 
1178  void set(UCalendarDateFields field, int32_t value);
1179 
1190  void set(int32_t year, int32_t month, int32_t date);
1191 
1204  void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute);
1205 
1219  void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute, int32_t second);
1220 
1227  void clear(void);
1228 
1229 #ifndef U_HIDE_DEPRECATED_API
1230 
1238  void clear(EDateFields field);
1239 #endif /* U_HIDE_DEPRECATED_API */
1240 
1249  void clear(UCalendarDateFields field);
1250 
1266  virtual UClassID getDynamicClassID(void) const = 0;
1267 
1300  virtual const char * getType() const = 0;
1301 
1317  virtual UCalendarWeekdayType getDayOfWeekType(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const;
1318 
1333  virtual int32_t getWeekendTransition(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const;
1334 
1344  virtual UBool isWeekend(UDate date, UErrorCode &status) const;
1345 
1353  virtual UBool isWeekend(void) const;
1354 
1355 protected:
1356 
1365  Calendar(UErrorCode& success);
1366 
1373  Calendar(const Calendar& source);
1374 
1381  Calendar& operator=(const Calendar& right);
1382 
1393  Calendar(TimeZone* zone, const Locale& aLocale, UErrorCode& success);
1394 
1404  Calendar(const TimeZone& zone, const Locale& aLocale, UErrorCode& success);
1405 
1414  virtual void computeTime(UErrorCode& status);
1415 
1427  virtual void computeFields(UErrorCode& status);
1428 
1438  double getTimeInMillis(UErrorCode& status) const;
1439 
1448  void setTimeInMillis( double millis, UErrorCode& status );
1449 
1459  void complete(UErrorCode& status);
1460 
1461 #ifndef U_HIDE_DEPRECATED_API
1462 
1470  inline int32_t internalGet(EDateFields field) const {return fFields[field];}
1471 #endif /* U_HIDE_DEPRECATED_API */
1472 
1473 #ifndef U_HIDE_INTERNAL_API
1474 
1484  inline int32_t internalGet(UCalendarDateFields field, int32_t defaultValue) const {return fStamp[field]>kUnset ? fFields[field] : defaultValue;}
1485 
1494  inline int32_t internalGet(UCalendarDateFields field) const {return fFields[field];}
1495 #endif /* U_HIDE_INTERNAL_API */
1496 
1497 #ifndef U_HIDE_DEPRECATED_API
1498 
1507  void internalSet(EDateFields field, int32_t value);
1508 #endif /* U_HIDE_DEPRECATED_API */
1509 
1519  inline void internalSet(UCalendarDateFields field, int32_t value);
1520 
1527  virtual void prepareGetActual(UCalendarDateFields field, UBool isMinimum, UErrorCode &status);
1528 
1533  enum ELimitType {
1534  UCAL_LIMIT_MINIMUM = 0,
1535  UCAL_LIMIT_GREATEST_MINIMUM,
1536  UCAL_LIMIT_LEAST_MAXIMUM,
1537  UCAL_LIMIT_MAXIMUM,
1538  UCAL_LIMIT_COUNT
1539  };
1540 
1562  virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const = 0;
1563 
1571  virtual int32_t getLimit(UCalendarDateFields field, ELimitType limitType) const;
1572 
1573 
1587  virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month,
1588  UBool useMonth) const = 0;
1589 
1597  virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const ;
1598 
1606  virtual int32_t handleGetYearLength(int32_t eyear) const;
1607 
1608 
1617  virtual int32_t handleGetExtendedYear() = 0;
1618 
1627  virtual int32_t handleComputeJulianDay(UCalendarDateFields bestField);
1628 
1637  virtual int32_t handleGetExtendedYearFromWeekFields(int32_t yearWoy, int32_t woy);
1638 
1639 #ifndef U_HIDE_INTERNAL_API
1640 
1646  int32_t computeJulianDay();
1647 
1655  int32_t computeMillisInDay();
1656 
1666  int32_t computeZoneOffset(double millis, int32_t millisInDay, UErrorCode &ec);
1667 
1668 
1677  int32_t newestStamp(UCalendarDateFields start, UCalendarDateFields end, int32_t bestSoFar) const;
1678 
1684  enum {
1686  kResolveSTOP = -1,
1688  kResolveRemap = 32
1689  };
1690 
1696  static const UFieldResolutionTable kDatePrecedence[];
1697 
1703  static const UFieldResolutionTable kYearPrecedence[];
1704 
1710  static const UFieldResolutionTable kDOWPrecedence[];
1711 
1739  UCalendarDateFields resolveFields(const UFieldResolutionTable *precedenceTable);
1740 #endif /* U_HIDE_INTERNAL_API */
1741 
1742 
1746  virtual const UFieldResolutionTable* getFieldResolutionTable() const;
1747 
1748 #ifndef U_HIDE_INTERNAL_API
1749 
1754  UCalendarDateFields newerField(UCalendarDateFields defaultField, UCalendarDateFields alternateField) const;
1755 #endif /* U_HIDE_INTERNAL_API */
1756 
1757 
1758 private:
1767  int32_t getActualHelper(UCalendarDateFields field, int32_t startValue, int32_t endValue, UErrorCode &status) const;
1768 
1769 
1770 protected:
1776 
1788 
1795 
1804 
1811  UDate internalGetTime(void) const { return fTime; }
1812 
1820  void internalSetTime(UDate time) { fTime = time; }
1821 
1826  int32_t fFields[UCAL_FIELD_COUNT];
1827 
1833 
1837  enum {
1838  kUnset = 0,
1839  kInternallySet,
1840  kMinimumUserStamp
1841  };
1842 
1849  int32_t fStamp[UCAL_FIELD_COUNT];
1850 
1875  virtual void handleComputeFields(int32_t julianDay, UErrorCode &status);
1876 
1877 #ifndef U_HIDE_INTERNAL_API
1878 
1883  int32_t getGregorianYear() const {
1884  return fGregorianYear;
1885  }
1886 
1892  int32_t getGregorianMonth() const {
1893  return fGregorianMonth;
1894  }
1895 
1901  int32_t getGregorianDayOfYear() const {
1902  return fGregorianDayOfYear;
1903  }
1904 
1910  int32_t getGregorianDayOfMonth() const {
1911  return fGregorianDayOfMonth;
1912  }
1913 #endif /* U_HIDE_INTERNAL_API */
1914 
1921  virtual int32_t getDefaultMonthInYear(int32_t eyear) ;
1922 
1923 
1931  virtual int32_t getDefaultDayInMonth(int32_t eyear, int32_t month);
1932 
1933  //-------------------------------------------------------------------------
1934  // Protected utility methods for use by subclasses. These are very handy
1935  // for implementing add, roll, and computeFields.
1936  //-------------------------------------------------------------------------
1937 
1967  virtual void pinField(UCalendarDateFields field, UErrorCode& status);
1968 
2012  int32_t weekNumber(int32_t desiredDay, int32_t dayOfPeriod, int32_t dayOfWeek);
2013 
2014 
2015 #ifndef U_HIDE_INTERNAL_API
2016 
2046  inline int32_t weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek);
2047 
2052  int32_t getLocalDOW();
2053 #endif /* U_HIDE_INTERNAL_API */
2054 
2055 private:
2056 
2060  int32_t fNextStamp;// = MINIMUM_USER_STAMP;
2061 
2066  void recalculateStamp();
2067 
2071  UDate fTime;
2072 
2076  UBool fLenient;
2077 
2082  TimeZone* fZone;
2083 
2088  UCalendarWallTimeOption fRepeatedWallTime;
2089 
2094  UCalendarWallTimeOption fSkippedWallTime;
2095 
2104  UCalendarDaysOfWeek fFirstDayOfWeek;
2105  uint8_t fMinimalDaysInFirstWeek;
2106  UCalendarDaysOfWeek fWeekendOnset;
2107  int32_t fWeekendOnsetMillis;
2108  UCalendarDaysOfWeek fWeekendCease;
2109  int32_t fWeekendCeaseMillis;
2110 
2121  void setWeekData(const Locale& desiredLocale, const char *type, UErrorCode& success);
2122 
2132  void updateTime(UErrorCode& status);
2133 
2139  int32_t fGregorianYear;
2140 
2146  int32_t fGregorianMonth;
2147 
2153  int32_t fGregorianDayOfYear;
2154 
2160  int32_t fGregorianDayOfMonth;
2161 
2162  /* calculations */
2163 
2170  void computeGregorianAndDOWFields(int32_t julianDay, UErrorCode &ec);
2171 
2172 protected:
2173 
2181  void computeGregorianFields(int32_t julianDay, UErrorCode &ec);
2182 
2183 private:
2184 
2205  void computeWeekFields(UErrorCode &ec);
2206 
2207 
2216  void validateFields(UErrorCode &status);
2217 
2226  virtual void validateField(UCalendarDateFields field, UErrorCode &status);
2227 
2236  void validateField(UCalendarDateFields field, int32_t min, int32_t max, UErrorCode& status);
2237 
2238  protected:
2239 #ifndef U_HIDE_INTERNAL_API
2240 
2249  static uint8_t julianDayToDayOfWeek(double julian);
2250 #endif /* U_HIDE_INTERNAL_API */
2251 
2252  private:
2253  char validLocale[ULOC_FULLNAME_CAPACITY];
2254  char actualLocale[ULOC_FULLNAME_CAPACITY];
2255 
2256  public:
2257 #if !UCONFIG_NO_SERVICE
2258 
2262 #ifndef U_HIDE_INTERNAL_API
2263 
2269  static StringEnumeration* getAvailableLocales(void);
2270 
2279  static URegistryKey registerFactory(ICUServiceFactory* toAdopt, UErrorCode& status);
2280 
2291  static UBool unregister(URegistryKey key, UErrorCode& status);
2292 #endif /* U_HIDE_INTERNAL_API */
2293 
2298  friend class CalendarFactory;
2299 
2304  friend class CalendarService;
2305 
2310  friend class DefaultCalendarFactory;
2311 #endif /* !UCONFIG_NO_SERVICE */
2312 
2317  virtual UBool haveDefaultCentury() const = 0;
2318 
2323  virtual UDate defaultCenturyStart() const = 0;
2328  virtual int32_t defaultCenturyStartYear() const = 0;
2329 
2336  Locale getLocale(ULocDataLocaleType type, UErrorCode &status) const;
2337 
2338 #ifndef U_HIDE_INTERNAL_API
2339 
2345  const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;
2346 #endif /* U_HIDE_INTERNAL_API */
2347 
2348 private:
2353  BasicTimeZone* getBasicTimeZone() const;
2354 };
2355 
2356 // -------------------------------------
2357 
2358 inline Calendar*
2360 {
2361  // since the Locale isn't specified, use the default locale
2362  return createInstance(zone, Locale::getDefault(), errorCode);
2363 }
2364 
2365 // -------------------------------------
2366 
2367 inline void
2369 {
2370  roll(field, (int32_t)(up ? +1 : -1), status);
2371 }
2372 
2373 #ifndef U_HIDE_DEPRECATED_API
2374 inline void
2376 {
2377  roll((UCalendarDateFields) field, up, status);
2378 }
2379 #endif
2380 
2381 
2382 // -------------------------------------
2383 
2389 inline void
2391 {
2392  fFields[field] = value;
2393  fStamp[field] = kInternallySet;
2394  fIsSet[field] = TRUE; // Remove later
2395 }
2396 
2397 
2398 #ifndef U_HIDE_INTERNAL_API
2399 inline int32_t Calendar::weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek)
2400 {
2401  return weekNumber(dayOfPeriod, dayOfPeriod, dayOfWeek);
2402 }
2403 #endif
2404 
2406 
2407 #endif /* #if !UCONFIG_NO_FORMATTING */
2408 
2409 #endif // _CALENDAR