ICU 4.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
calendar.h
Go to the documentation of this file.
1 /*
2 ********************************************************************************
3 * Copyright (C) 1997-2009, 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 
165 class U_I18N_API Calendar : public UObject {
166 public:
167 
174  enum EDateFields {
175 #ifndef U_HIDE_DEPRECATED_API
176  ERA, // Example: 0..1
177  YEAR, // Example: 1..big number
178  MONTH, // Example: 0..11
179  WEEK_OF_YEAR, // Example: 1..53
180  WEEK_OF_MONTH, // Example: 1..4
181  DATE, // Example: 1..31
182  DAY_OF_YEAR, // Example: 1..365
183  DAY_OF_WEEK, // Example: 1..7
184  DAY_OF_WEEK_IN_MONTH, // Example: 1..4, may be specified as -1
185  AM_PM, // Example: 0..1
186  HOUR, // Example: 0..11
187  HOUR_OF_DAY, // Example: 0..23
188  MINUTE, // Example: 0..59
189  SECOND, // Example: 0..59
190  MILLISECOND, // Example: 0..999
191  ZONE_OFFSET, // Example: -12*U_MILLIS_PER_HOUR..12*U_MILLIS_PER_HOUR
192  DST_OFFSET, // Example: 0 or U_MILLIS_PER_HOUR
193  YEAR_WOY, // 'Y' Example: 1..big number - Year of Week of Year
194  DOW_LOCAL, // 'e' Example: 1..7 - Day of Week / Localized
195 
196  EXTENDED_YEAR,
197  JULIAN_DAY,
198  MILLISECONDS_IN_DAY,
199  IS_LEAP_MONTH,
200 
201  FIELD_COUNT = UCAL_FIELD_COUNT // See ucal.h for other fields.
202 #endif /* U_HIDE_DEPRECATED_API */
203  };
204 
211  enum EDaysOfWeek {
212 #ifndef U_HIDE_DEPRECATED_API
213  SUNDAY = 1,
214  MONDAY,
215  TUESDAY,
216  WEDNESDAY,
217  THURSDAY,
218  FRIDAY,
219  SATURDAY
220 #endif /* U_HIDE_DEPRECATED_API */
221  };
222 
227  enum EMonths {
228 #ifndef U_HIDE_DEPRECATED_API
229  JANUARY,
230  FEBRUARY,
231  MARCH,
232  APRIL,
233  MAY,
234  JUNE,
235  JULY,
236  AUGUST,
237  SEPTEMBER,
238  OCTOBER,
239  NOVEMBER,
240  DECEMBER,
241  UNDECIMBER
242 #endif /* U_HIDE_DEPRECATED_API */
243  };
244 
249  enum EAmpm {
250 #ifndef U_HIDE_DEPRECATED_API
251  AM,
252  PM
253 #endif /* U_HIDE_DEPRECATED_API */
254  };
255 
260  virtual ~Calendar();
261 
268  virtual Calendar* clone(void) const = 0;
269 
281  static Calendar* U_EXPORT2 createInstance(UErrorCode& success);
282 
295  static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, UErrorCode& success);
296 
308  static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, UErrorCode& success);
309 
320  static Calendar* U_EXPORT2 createInstance(const Locale& aLocale, UErrorCode& success);
321 
335  static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, const Locale& aLocale, UErrorCode& success);
336 
349  static Calendar* U_EXPORT2 createInstance(const TimeZone& zoneToAdopt, const Locale& aLocale, UErrorCode& success);
350 
360  static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
361 
362 
379  static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* key,
380  const Locale& locale, UBool commonlyUsed, UErrorCode& status);
381 
389  static UDate U_EXPORT2 getNow(void);
390 
404  inline UDate getTime(UErrorCode& status) const { return getTimeInMillis(status); }
405 
416  inline void setTime(UDate date, UErrorCode& status) { setTimeInMillis(date, status); }
417 
429  virtual UBool operator==(const Calendar& that) const;
430 
439  UBool operator!=(const Calendar& that) const {return !operator==(that);}
440 
451  virtual UBool isEquivalentTo(const Calendar& other) const;
452 
467  UBool equals(const Calendar& when, UErrorCode& status) const;
468 
482  UBool before(const Calendar& when, UErrorCode& status) const;
483 
497  UBool after(const Calendar& when, UErrorCode& status) const;
498 
516  virtual void add(EDateFields field, int32_t amount, UErrorCode& status);
517 
535  virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& status);
536 
560  inline void roll(EDateFields field, UBool up, UErrorCode& status);
561 
585  inline void roll(UCalendarDateFields field, UBool up, UErrorCode& status);
586 
609  virtual void roll(EDateFields field, int32_t amount, UErrorCode& status);
610 
633  virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode& status);
634 
690  virtual int32_t fieldDifference(UDate when, EDateFields field, UErrorCode& status);
691 
747  virtual int32_t fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status);
748 
757  void adoptTimeZone(TimeZone* value);
758 
766  void setTimeZone(const TimeZone& zone);
767 
776  const TimeZone& getTimeZone(void) const;
777 
786  TimeZone* orphanTimeZone(void);
787 
796  virtual UBool inDaylightTime(UErrorCode& status) const = 0;
797 
810  void setLenient(UBool lenient);
811 
818  UBool isLenient(void) const;
819 
826  void setFirstDayOfWeek(EDaysOfWeek value);
827 
834  void setFirstDayOfWeek(UCalendarDaysOfWeek value);
835 
842  EDaysOfWeek getFirstDayOfWeek(void) const;
843 
851  UCalendarDaysOfWeek getFirstDayOfWeek(UErrorCode &status) const;
852 
862  void setMinimalDaysInFirstWeek(uint8_t value);
863 
873  uint8_t getMinimalDaysInFirstWeek(void) const;
874 
883  virtual int32_t getMinimum(EDateFields field) const;
884 
893  virtual int32_t getMinimum(UCalendarDateFields field) const;
894 
903  virtual int32_t getMaximum(EDateFields field) const;
904 
913  virtual int32_t getMaximum(UCalendarDateFields field) const;
914 
923  virtual int32_t getGreatestMinimum(EDateFields field) const;
924 
933  virtual int32_t getGreatestMinimum(UCalendarDateFields field) const;
934 
943  virtual int32_t getLeastMaximum(EDateFields field) const;
944 
953  virtual int32_t getLeastMaximum(UCalendarDateFields field) const;
954 
969  int32_t getActualMinimum(EDateFields field, UErrorCode& status) const;
970 
985  virtual int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& status) const;
986 
1003  int32_t getActualMaximum(EDateFields field, UErrorCode& status) const;
1004 
1021  virtual int32_t getActualMaximum(UCalendarDateFields field, UErrorCode& status) const;
1022 
1036  int32_t get(EDateFields field, UErrorCode& status) const;
1037 
1051  int32_t get(UCalendarDateFields field, UErrorCode& status) const;
1052 
1061  UBool isSet(EDateFields field) const;
1062 
1071  UBool isSet(UCalendarDateFields field) const;
1072 
1080  void set(EDateFields field, int32_t value);
1081 
1089  void set(UCalendarDateFields field, int32_t value);
1090 
1101  void set(int32_t year, int32_t month, int32_t date);
1102 
1115  void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute);
1116 
1130  void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute, int32_t second);
1131 
1138  void clear(void);
1139 
1148  void clear(EDateFields field);
1149 
1158  void clear(UCalendarDateFields field);
1159 
1175  virtual UClassID getDynamicClassID(void) const = 0;
1176 
1185  virtual const char * getType() const = 0;
1186 
1187 protected:
1188 
1197  Calendar(UErrorCode& success);
1198 
1205  Calendar(const Calendar& source);
1206 
1213  Calendar& operator=(const Calendar& right);
1214 
1225  Calendar(TimeZone* zone, const Locale& aLocale, UErrorCode& success);
1226 
1236  Calendar(const TimeZone& zone, const Locale& aLocale, UErrorCode& success);
1237 
1246  virtual void computeTime(UErrorCode& status);
1247 
1259  virtual void computeFields(UErrorCode& status);
1260 
1270  double getTimeInMillis(UErrorCode& status) const;
1271 
1280  void setTimeInMillis( double millis, UErrorCode& status );
1281 
1291  void complete(UErrorCode& status);
1292 
1301  inline int32_t internalGet(EDateFields field) const {return fFields[field];}
1302 
1313  inline int32_t internalGet(UCalendarDateFields field, int32_t defaultValue) const {return fStamp[field]>kUnset ? fFields[field] : defaultValue;}
1314 
1323  inline int32_t internalGet(UCalendarDateFields field) const {return fFields[field];}
1324 
1334  void internalSet(EDateFields field, int32_t value);
1335 
1345  inline void internalSet(UCalendarDateFields field, int32_t value);
1346 
1353  virtual void prepareGetActual(UCalendarDateFields field, UBool isMinimum, UErrorCode &status);
1354 
1359  enum ELimitType {
1360  UCAL_LIMIT_MINIMUM = 0,
1361  UCAL_LIMIT_GREATEST_MINIMUM,
1362  UCAL_LIMIT_LEAST_MAXIMUM,
1363  UCAL_LIMIT_MAXIMUM,
1364  UCAL_LIMIT_COUNT
1365  };
1366 
1388  virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const = 0;
1389 
1397  virtual int32_t getLimit(UCalendarDateFields field, ELimitType limitType) const;
1398 
1399 
1413  virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month,
1414  UBool useMonth) const = 0;
1415 
1423  virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const ;
1424 
1432  virtual int32_t handleGetYearLength(int32_t eyear) const;
1433 
1434 
1443  virtual int32_t handleGetExtendedYear() = 0;
1444 
1453  virtual int32_t handleComputeJulianDay(UCalendarDateFields bestField);
1454 
1463  virtual int32_t handleGetExtendedYearFromWeekFields(int32_t yearWoy, int32_t woy);
1464 
1471  int32_t computeJulianDay();
1472 
1480  int32_t computeMillisInDay();
1481 
1491  int32_t computeZoneOffset(double millis, int32_t millisInDay, UErrorCode &ec);
1492 
1493 
1502  int32_t newestStamp(UCalendarDateFields start, UCalendarDateFields end, int32_t bestSoFar) const;
1503 
1509  enum {
1511  kResolveSTOP = -1,
1513  kResolveRemap = 32
1514  };
1515 
1521  static const UFieldResolutionTable kDatePrecedence[];
1522 
1528  static const UFieldResolutionTable kYearPrecedence[];
1529 
1535  static const UFieldResolutionTable kDOWPrecedence[];
1536 
1564  UCalendarDateFields resolveFields(const UFieldResolutionTable *precedenceTable);
1565 
1566 
1570  virtual const UFieldResolutionTable* getFieldResolutionTable() const;
1571 
1577  UCalendarDateFields newerField(UCalendarDateFields defaultField, UCalendarDateFields alternateField) const;
1578 
1579 
1580 private:
1589  int32_t getActualHelper(UCalendarDateFields field, int32_t startValue, int32_t endValue, UErrorCode &status) const;
1590 
1591 
1592 protected:
1598 
1610 
1617 
1626 
1633  UDate internalGetTime(void) const { return fTime; }
1634 
1642  void internalSetTime(UDate time) { fTime = time; }
1643 
1649 
1655 
1659  enum {
1660  kUnset = 0,
1661  kInternallySet,
1662  kMinimumUserStamp
1663  };
1664 
1672 
1697  virtual void handleComputeFields(int32_t julianDay, UErrorCode &status);
1698 
1705  return fGregorianYear;
1706  }
1707 
1714  return fGregorianMonth;
1715  }
1716 
1723  return fGregorianDayOfYear;
1724  }
1725 
1732  return fGregorianDayOfMonth;
1733  }
1734 
1741  virtual int32_t getDefaultMonthInYear(int32_t eyear) ;
1742 
1743 
1751  virtual int32_t getDefaultDayInMonth(int32_t eyear, int32_t month);
1752 
1753  //-------------------------------------------------------------------------
1754  // Protected utility methods for use by subclasses. These are very handy
1755  // for implementing add, roll, and computeFields.
1756  //-------------------------------------------------------------------------
1757 
1787  virtual void pinField(UCalendarDateFields field, UErrorCode& status);
1788 
1832  int32_t weekNumber(int32_t desiredDay, int32_t dayOfPeriod, int32_t dayOfWeek);
1833 
1834 
1865  inline int32_t weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek);
1866 
1871  int32_t getLocalDOW();
1872 
1873 private:
1874 
1878  int32_t fNextStamp;// = MINIMUM_USER_STAMP;
1879 
1883  UDate fTime;
1884 
1888  UBool fLenient;
1889 
1894  TimeZone* fZone;
1895 
1904  UCalendarDaysOfWeek fFirstDayOfWeek;
1905  uint8_t fMinimalDaysInFirstWeek;
1906 
1917  void setWeekCountData(const Locale& desiredLocale, const char *type, UErrorCode& success);
1918 
1928  void updateTime(UErrorCode& status);
1929 
1935  int32_t fGregorianYear;
1936 
1942  int32_t fGregorianMonth;
1943 
1949  int32_t fGregorianDayOfYear;
1950 
1956  int32_t fGregorianDayOfMonth;
1957 
1958  /* calculations */
1959 
1966  void computeGregorianAndDOWFields(int32_t julianDay, UErrorCode &ec);
1967 
1968  protected:
1969 
1977  void computeGregorianFields(int32_t julianDay, UErrorCode &ec);
1978 
1979  private:
1980 
2001  void computeWeekFields(UErrorCode &ec);
2002 
2003 
2012  void validateFields(UErrorCode &status);
2013 
2022  virtual void validateField(UCalendarDateFields field, UErrorCode &status);
2023 
2032  void validateField(UCalendarDateFields field, int32_t min, int32_t max, UErrorCode& status);
2033 
2034  protected:
2044  static uint8_t julianDayToDayOfWeek(double julian);
2045 
2046  private:
2047  char validLocale[ULOC_FULLNAME_CAPACITY];
2048  char actualLocale[ULOC_FULLNAME_CAPACITY];
2049 
2050  public:
2051 #if !UCONFIG_NO_SERVICE
2052 
2062  static StringEnumeration* getAvailableLocales(void);
2063 
2072  static URegistryKey registerFactory(ICUServiceFactory* toAdopt, UErrorCode& status);
2073 
2084  static UBool unregister(URegistryKey key, UErrorCode& status);
2085 
2090  friend class CalendarFactory;
2091 
2096  friend class CalendarService;
2097 
2102  friend class DefaultCalendarFactory;
2103 #endif /* !UCONFIG_NO_SERVICE */
2104 
2109  virtual UBool haveDefaultCentury() const = 0;
2110 
2115  virtual UDate defaultCenturyStart() const = 0;
2120  virtual int32_t defaultCenturyStartYear() const = 0;
2121 
2128  Locale getLocale(ULocDataLocaleType type, UErrorCode &status) const;
2129 
2136  const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;
2137 
2138 };
2139 
2140 // -------------------------------------
2141 
2142 inline Calendar*
2144 {
2145  // since the Locale isn't specified, use the default locale
2146  return createInstance(zone, Locale::getDefault(), errorCode);
2147 }
2148 
2149 // -------------------------------------
2150 
2151 inline void
2153 {
2154  roll(field, (int32_t)(up ? +1 : -1), status);
2155 }
2156 
2157 inline void
2159 {
2160  roll((UCalendarDateFields) field, up, status);
2161 }
2162 
2163 
2164 // -------------------------------------
2165 
2171 inline void
2173 {
2174  fFields[field] = value;
2175  fStamp[field] = kInternallySet;
2176  fIsSet[field] = TRUE; // Remove later
2177 }
2178 
2179 inline int32_t Calendar::weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek)
2180 {
2181  return weekNumber(dayOfPeriod, dayOfPeriod, dayOfWeek);
2182 }
2183 
2184 
2186 
2187 #endif /* #if !UCONFIG_NO_FORMATTING */
2188 
2189 #endif // _CALENDAR
int32_t getGregorianYear() const
Return the extended year on the Gregorian calendar as computed by computeGregorianFields().
Definition: calendar.h:1704
void roll(EDateFields field, UBool up, UErrorCode &status)
Time Field Rolling function.
Definition: calendar.h:2158
UCalendarDateFields
Possible fields in a UCalendar.
Definition: ucal.h:176
Calendar is an abstract base class for converting between a UDate object and a set of integer fields ...
Definition: calendar.h:165
C API: Calendar.
UBool fIsTimeSet
The flag which indicates if the current time is set in the calendar.
Definition: calendar.h:1597
void internalSetTime(UDate time)
Set the current time without affecting flags or fields.
Definition: calendar.h:1642
int32_t internalGet(EDateFields field) const
Gets the value for a given time field.
Definition: calendar.h:1301
EAmpm
Useful constants for hour in 12-hour clock.
Definition: calendar.h:249
C++ API: TimeZone object.
double UDate
Date and Time data type.
Definition: utypes.h:281
UBool fIsSet[UCAL_FIELD_COUNT]
The flags which tell if a specified time field for the calendar is set.
Definition: calendar.h:1654
int32_t getGregorianDayOfYear() const
Return the day of year (1-based) on the Gregorian calendar as computed by computeGregorianFields().
Definition: calendar.h:1722
int32_t weekNumber(int32_t desiredDay, int32_t dayOfPeriod, int32_t dayOfWeek)
Return the week number of a day, within a period.
C API:misc definitions.
int32_t getGregorianDayOfMonth() const
Return the day of month (1-based) on the Gregorian calendar as computed by computeGregorianFields().
Definition: calendar.h:1731
#define ULOC_FULLNAME_CAPACITY
Useful constant for the maximum size of the whole locale ID (including the terminating NULL and all k...
Definition: uloc.h:262
void internalSet(EDateFields field, int32_t value)
Sets the value for a given time field.
void setTime(UDate date, UErrorCode &status)
Sets this Calendar's current time with the given UDate.
Definition: calendar.h:416
unsigned char uint8_t
Define 64 bit limits.
Definition: pwin32.h:131
EDateFields
Field IDs for date and time.
Definition: calendar.h:174
#define U_I18N_API
Set to export library symbols from inside the i18n library, and to import them from outside...
Definition: utypes.h:475
#define U_NAMESPACE_BEGIN
This is used to begin a declaration of a public ICU C++ API.
Definition: uversion.h:183
ELimitType
Limit enums.
Definition: calendar.h:1359
UCalendarDaysOfWeek
Useful constant for days of week.
Definition: ucal.h:446
EDaysOfWeek
Useful constant for days of week.
Definition: calendar.h:211
UBool fAreFieldsVirtuallySet
True if all fields have been virtually set, but have not yet been computed.
Definition: calendar.h:1625
UDate internalGetTime(void) const
Get the current time without recomputing.
Definition: calendar.h:1633
UBool fAreAllFieldsSet
True if all of the fields have been set.
Definition: calendar.h:1616
#define TRUE
The TRUE value of a UBool.
Definition: umachine.h:212
#define U_EXPORT2
Definition: platform.h:338
int32_t fStamp[UCAL_FIELD_COUNT]
Pseudo-time-stamps which specify when each field was set.
Definition: calendar.h:1671
int32_t internalGet(UCalendarDateFields field) const
Gets the value for a given time field.
Definition: calendar.h:1323
C++ API: Common ICU base class UObject.
const void * URegistryKey
Opaque type returned by registerInstance, registerFactory and unregister for service registration...
Definition: umisc.h:55
int32_t internalGet(UCalendarDateFields field, int32_t defaultValue) const
Gets the value for a given time field.
Definition: calendar.h:1313
#define U_NAMESPACE_END
This is used to end a declaration of a public ICU C++ API If the compiler doesn't support namespaces...
Definition: uversion.h:184
UObject is the common ICU "boilerplate" class.
Definition: uobject.h:212
static const Locale & getDefault(void)
Common methods of getting the current default Locale.
void * UClassID
UClassID is used to identify classes without using RTTI, since RTTI is not yet supported by all C++ c...
Definition: utypes.h:339
UErrorCode
Error code to replace exception handling, so that the code is compatible with all C++ compilers...
Definition: utypes.h:593
TimeZone represents a time zone offset, and also figures out daylight savings.
Definition: timezone.h:122
Base class for 'pure' C++ implementations of uenum api.
Definition: strenum.h:55
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested...
Definition: uloc.h:314
C++ API: Locale ID object.
static Calendar * createInstance(UErrorCode &success)
Creates a Calendar using the default timezone and locale.
UBool fAreFieldsSet
True if the fields are in sync with the currently set time of this Calendar.
Definition: calendar.h:1609
Basic definitions for ICU, for both C and C++ APIs.
UDate getTime(UErrorCode &status) const
Gets this Calendar's time as milliseconds.
Definition: calendar.h:404
int32_t fFields[UCAL_FIELD_COUNT]
The time fields containing values into which the millis is computed.
Definition: calendar.h:1648
Field count.
Definition: ucal.h:423
UBool operator!=(const Calendar &that) const
Compares the inequality of two Calendar objects.
Definition: calendar.h:439
EMonths
Useful constants for month.
Definition: calendar.h:227
A Locale object represents a specific geographical, political, or cultural region.
Definition: locid.h:181
virtual UClassID getDynamicClassID() const =0
ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.
int32_t getGregorianMonth() const
Return the month (0-based) on the Gregorian calendar as computed by computeGregorianFields().
Definition: calendar.h:1713
int32_t UFieldResolutionTable[12][8]
Definition: calendar.h:44
signed int int32_t
Define 64 bit limits.
Definition: pwin32.h:143
int8_t UBool
The ICU boolean type.
Definition: umachine.h:208