ICU 49.1.1  49.1.1
calendar.h
Go to the documentation of this file.
00001 /*
00002 ********************************************************************************
00003 *   Copyright (C) 1997-2012, International Business Machines
00004 *   Corporation and others.  All Rights Reserved.
00005 ********************************************************************************
00006 *
00007 * File CALENDAR.H
00008 *
00009 * Modification History:
00010 *
00011 *   Date        Name        Description
00012 *   04/22/97    aliu        Expanded and corrected comments and other header
00013 *                           contents.
00014 *   05/01/97    aliu        Made equals(), before(), after() arguments const.
00015 *   05/20/97    aliu        Replaced fAreFieldsSet with fAreFieldsInSync and
00016 *                           fAreAllFieldsSet.
00017 *   07/27/98    stephen     Sync up with JDK 1.2
00018 *   11/15/99    weiv        added YEAR_WOY and DOW_LOCAL
00019 *                           to EDateFields
00020 *    8/19/2002  srl         Removed Javaisms
00021 *   11/07/2003  srl         Update, clean up documentation.
00022 ********************************************************************************
00023 */
00024 
00025 #ifndef CALENDAR_H
00026 #define CALENDAR_H
00027 
00028 #include "unicode/utypes.h"
00029 
00034 #if !UCONFIG_NO_FORMATTING
00035 
00036 #include "unicode/uobject.h"
00037 #include "unicode/locid.h"
00038 #include "unicode/timezone.h"
00039 #include "unicode/ucal.h"
00040 #include "unicode/umisc.h"
00041 
00042 U_NAMESPACE_BEGIN
00043 
00044 class ICUServiceFactory;
00045 
00049 typedef int32_t UFieldResolutionTable[12][8];
00050 
00051 class BasicTimeZone;
00166 class U_I18N_API Calendar : public UObject {
00167 public:
00168 
00175     enum EDateFields {
00176 #ifndef U_HIDE_DEPRECATED_API
00177 /*
00178  * ERA may be defined on other platforms. To avoid any potential problems undefined it here.
00179  */
00180 #ifdef ERA
00181 #undef ERA
00182 #endif
00183         ERA,                  // Example: 0..1
00184         YEAR,                 // Example: 1..big number
00185         MONTH,                // Example: 0..11
00186         WEEK_OF_YEAR,         // Example: 1..53
00187         WEEK_OF_MONTH,        // Example: 1..4
00188         DATE,                 // Example: 1..31
00189         DAY_OF_YEAR,          // Example: 1..365
00190         DAY_OF_WEEK,          // Example: 1..7
00191         DAY_OF_WEEK_IN_MONTH, // Example: 1..4, may be specified as -1
00192         AM_PM,                // Example: 0..1
00193         HOUR,                 // Example: 0..11
00194         HOUR_OF_DAY,          // Example: 0..23
00195         MINUTE,               // Example: 0..59
00196         SECOND,               // Example: 0..59
00197         MILLISECOND,          // Example: 0..999
00198         ZONE_OFFSET,          // Example: -12*U_MILLIS_PER_HOUR..12*U_MILLIS_PER_HOUR
00199         DST_OFFSET,           // Example: 0 or U_MILLIS_PER_HOUR
00200         YEAR_WOY,             // 'Y' Example: 1..big number - Year of Week of Year
00201         DOW_LOCAL,            // 'e' Example: 1..7 - Day of Week / Localized
00202         
00203         EXTENDED_YEAR,
00204         JULIAN_DAY,
00205         MILLISECONDS_IN_DAY,
00206         IS_LEAP_MONTH,
00207 
00208         FIELD_COUNT = UCAL_FIELD_COUNT // See ucal.h for other fields.
00209 #endif /* U_HIDE_DEPRECATED_API */
00210     };
00211 
00212 #ifndef U_HIDE_DEPRECATED_API
00213 
00219     enum EDaysOfWeek {
00220         SUNDAY = 1,
00221         MONDAY,
00222         TUESDAY,
00223         WEDNESDAY,
00224         THURSDAY,
00225         FRIDAY,
00226         SATURDAY
00227     };
00228 
00233     enum EMonths {
00234         JANUARY,
00235         FEBRUARY,
00236         MARCH,
00237         APRIL,
00238         MAY,
00239         JUNE,
00240         JULY,
00241         AUGUST,
00242         SEPTEMBER,
00243         OCTOBER,
00244         NOVEMBER,
00245         DECEMBER,
00246         UNDECIMBER
00247     };
00248 
00253     enum EAmpm {
00254         AM,
00255         PM
00256     };
00257 #endif  /* U_HIDE_DEPRECATED_API */
00258 
00263     virtual ~Calendar();
00264 
00271     virtual Calendar* clone(void) const = 0;
00272 
00284     static Calendar* U_EXPORT2 createInstance(UErrorCode& success);
00285 
00298     static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, UErrorCode& success);
00299 
00311     static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, UErrorCode& success);
00312 
00323     static Calendar* U_EXPORT2 createInstance(const Locale& aLocale, UErrorCode& success);
00324 
00338     static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, const Locale& aLocale, UErrorCode& success);
00339 
00352     static Calendar* U_EXPORT2 createInstance(const TimeZone& zoneToAdopt, const Locale& aLocale, UErrorCode& success);
00353 
00363     static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
00364 
00365 
00382     static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* key,
00383                     const Locale& locale, UBool commonlyUsed, UErrorCode& status);
00384 
00392     static UDate U_EXPORT2 getNow(void);
00393 
00407     inline UDate getTime(UErrorCode& status) const { return getTimeInMillis(status); }
00408 
00419     inline void setTime(UDate date, UErrorCode& status) { setTimeInMillis(date, status); }
00420 
00432     virtual UBool operator==(const Calendar& that) const;
00433 
00442     UBool operator!=(const Calendar& that) const {return !operator==(that);}
00443 
00454     virtual UBool isEquivalentTo(const Calendar& other) const;
00455 
00470     UBool equals(const Calendar& when, UErrorCode& status) const;
00471 
00485     UBool before(const Calendar& when, UErrorCode& status) const;
00486 
00500     UBool after(const Calendar& when, UErrorCode& status) const;
00501 
00519     virtual void add(EDateFields field, int32_t amount, UErrorCode& status);
00520 
00538     virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& status);
00539 
00540 #ifndef U_HIDE_DEPRECATED_API
00541 
00564     inline void roll(EDateFields field, UBool up, UErrorCode& status);
00565 #endif  /* U_HIDE_DEPRECATED_API */
00566 
00590     inline void roll(UCalendarDateFields field, UBool up, UErrorCode& status);
00591 
00614     virtual void roll(EDateFields field, int32_t amount, UErrorCode& status);
00615 
00638     virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode& status);
00639 
00695     virtual int32_t fieldDifference(UDate when, EDateFields field, UErrorCode& status);
00696 
00752     virtual int32_t fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status);
00753 
00762     void adoptTimeZone(TimeZone* value);
00763 
00771     void setTimeZone(const TimeZone& zone);
00772 
00781     const TimeZone& getTimeZone(void) const;
00782 
00791     TimeZone* orphanTimeZone(void);
00792 
00801     virtual UBool inDaylightTime(UErrorCode& status) const = 0;
00802 
00815     void setLenient(UBool lenient);
00816 
00823     UBool isLenient(void) const;
00824 
00825 #ifndef U_HIDE_DRAFT_API
00826 
00846     void setRepeatedWallTimeOption(UCalendarWallTimeOption option);
00847 
00857     UCalendarWallTimeOption getRepeatedWallTimeOption(void) const;
00858 
00880     void setSkippedWallTimeOption(UCalendarWallTimeOption option);
00881 
00892     UCalendarWallTimeOption getSkippedWallTimeOption(void) const;
00893 #endif  /* U_HIDE_DRAFT_API */
00894 
00895 #ifndef U_HIDE_DEPRECATED_API
00896 
00902     void setFirstDayOfWeek(EDaysOfWeek value);
00903 #endif  /* U_HIDE_DEPRECATED_API */
00904 
00911     void setFirstDayOfWeek(UCalendarDaysOfWeek value);
00912 
00913 #ifndef U_HIDE_DEPRECATED_API
00914 
00920     EDaysOfWeek getFirstDayOfWeek(void) const;
00921 #endif  /* U_HIDE_DEPRECATED_API */
00922 
00930     UCalendarDaysOfWeek getFirstDayOfWeek(UErrorCode &status) const;
00931 
00941     void setMinimalDaysInFirstWeek(uint8_t value);
00942 
00952     uint8_t getMinimalDaysInFirstWeek(void) const;
00953 
00962     virtual int32_t getMinimum(EDateFields field) const;
00963 
00972     virtual int32_t getMinimum(UCalendarDateFields field) const;
00973 
00982     virtual int32_t getMaximum(EDateFields field) const;
00983 
00992     virtual int32_t getMaximum(UCalendarDateFields field) const;
00993 
01002     virtual int32_t getGreatestMinimum(EDateFields field) const;
01003 
01012     virtual int32_t getGreatestMinimum(UCalendarDateFields field) const;
01013 
01022     virtual int32_t getLeastMaximum(EDateFields field) const;
01023 
01032     virtual int32_t getLeastMaximum(UCalendarDateFields field) const;
01033 
01034 #ifndef U_HIDE_DEPRECATED_API
01035 
01049     int32_t getActualMinimum(EDateFields field, UErrorCode& status) const;
01050 #endif  /* U_HIDE_DEPRECATED_API */
01051 
01066     virtual int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& status) const;
01067 
01068 #ifndef U_HIDE_DEPRECATED_API
01069 
01085     int32_t getActualMaximum(EDateFields field, UErrorCode& status) const;
01086 #endif  /* U_HIDE_DEPRECATED_API */
01087 
01104     virtual int32_t getActualMaximum(UCalendarDateFields field, UErrorCode& status) const;
01105 
01106 #ifndef U_HIDE_DEPRECATED_API
01107 
01120     int32_t get(EDateFields field, UErrorCode& status) const;
01121 #endif  /* U_HIDE_DEPRECATED_API */
01122 
01136     int32_t get(UCalendarDateFields field, UErrorCode& status) const;
01137 
01138 #ifndef U_HIDE_DEPRECATED_API
01139 
01147     UBool isSet(EDateFields field) const;
01148 #endif  /* U_HIDE_DEPRECATED_API */
01149 
01158     UBool isSet(UCalendarDateFields field) const;
01159 
01160 #ifndef U_HIDE_DEPRECATED_API
01161 
01168     void set(EDateFields field, int32_t value);
01169 #endif  /* U_HIDE_DEPRECATED_API */
01170 
01178     void set(UCalendarDateFields field, int32_t value);
01179 
01190     void set(int32_t year, int32_t month, int32_t date);
01191 
01204     void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute);
01205 
01219     void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute, int32_t second);
01220 
01227     void clear(void);
01228 
01229 #ifndef U_HIDE_DEPRECATED_API
01230 
01238     void clear(EDateFields field);
01239 #endif  /* U_HIDE_DEPRECATED_API */
01240 
01249     void clear(UCalendarDateFields field);
01250 
01266     virtual UClassID getDynamicClassID(void) const = 0;
01267 
01300     virtual const char * getType() const = 0;
01301 
01317     virtual UCalendarWeekdayType getDayOfWeekType(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const;
01318 
01333     virtual int32_t getWeekendTransition(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const;
01334 
01344     virtual UBool isWeekend(UDate date, UErrorCode &status) const;
01345 
01353     virtual UBool isWeekend(void) const;
01354 
01355 protected:
01356 
01365     Calendar(UErrorCode& success);
01366 
01373     Calendar(const Calendar& source);
01374 
01381     Calendar& operator=(const Calendar& right);
01382 
01393     Calendar(TimeZone* zone, const Locale& aLocale, UErrorCode& success);
01394 
01404     Calendar(const TimeZone& zone, const Locale& aLocale, UErrorCode& success);
01405 
01414     virtual void computeTime(UErrorCode& status);
01415 
01427     virtual void computeFields(UErrorCode& status);
01428 
01438     double getTimeInMillis(UErrorCode& status) const;
01439 
01448     void setTimeInMillis( double millis, UErrorCode& status );
01449 
01459     void complete(UErrorCode& status);
01460 
01461 #ifndef U_HIDE_DEPRECATED_API
01462 
01470     inline int32_t internalGet(EDateFields field) const {return fFields[field];}
01471 #endif  /* U_HIDE_DEPRECATED_API */
01472 
01473 #ifndef U_HIDE_INTERNAL_API
01474 
01484     inline int32_t internalGet(UCalendarDateFields field, int32_t defaultValue) const {return fStamp[field]>kUnset ? fFields[field] : defaultValue;}
01485 
01494     inline int32_t internalGet(UCalendarDateFields field) const {return fFields[field];}
01495 #endif  /* U_HIDE_INTERNAL_API */
01496 
01497 #ifndef U_HIDE_DEPRECATED_API
01498 
01507     void internalSet(EDateFields field, int32_t value);
01508 #endif  /* U_HIDE_DEPRECATED_API */
01509 
01519     inline void internalSet(UCalendarDateFields field, int32_t value);
01520 
01527     virtual void prepareGetActual(UCalendarDateFields field, UBool isMinimum, UErrorCode &status);
01528 
01533     enum ELimitType {
01534       UCAL_LIMIT_MINIMUM = 0,
01535       UCAL_LIMIT_GREATEST_MINIMUM,
01536       UCAL_LIMIT_LEAST_MAXIMUM,
01537       UCAL_LIMIT_MAXIMUM,
01538       UCAL_LIMIT_COUNT
01539     };
01540 
01562     virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const = 0;
01563 
01571     virtual int32_t getLimit(UCalendarDateFields field, ELimitType limitType) const;
01572 
01573 
01587     virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month,
01588                                                    UBool useMonth) const  = 0;
01589 
01597     virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const ;
01598 
01606     virtual int32_t handleGetYearLength(int32_t eyear) const;
01607 
01608 
01617     virtual int32_t handleGetExtendedYear() = 0;
01618 
01627     virtual int32_t handleComputeJulianDay(UCalendarDateFields bestField);
01628 
01637     virtual int32_t handleGetExtendedYearFromWeekFields(int32_t yearWoy, int32_t woy);
01638 
01639 #ifndef U_HIDE_INTERNAL_API
01640 
01646     int32_t computeJulianDay();
01647 
01655     int32_t computeMillisInDay();
01656 
01666     int32_t computeZoneOffset(double millis, int32_t millisInDay, UErrorCode &ec);
01667 
01668 
01677     int32_t newestStamp(UCalendarDateFields start, UCalendarDateFields end, int32_t bestSoFar) const;
01678 
01684     enum {
01686       kResolveSTOP = -1,
01688       kResolveRemap = 32
01689     };
01690 
01696     static const UFieldResolutionTable kDatePrecedence[];
01697 
01703     static const UFieldResolutionTable kYearPrecedence[];
01704 
01710     static const UFieldResolutionTable kDOWPrecedence[];
01711 
01739     UCalendarDateFields resolveFields(const UFieldResolutionTable *precedenceTable);
01740 #endif  /* U_HIDE_INTERNAL_API */
01741 
01742 
01746     virtual const UFieldResolutionTable* getFieldResolutionTable() const;
01747 
01748 #ifndef U_HIDE_INTERNAL_API
01749 
01754     UCalendarDateFields newerField(UCalendarDateFields defaultField, UCalendarDateFields alternateField) const;
01755 #endif  /* U_HIDE_INTERNAL_API */
01756 
01757 
01758 private:
01767     int32_t getActualHelper(UCalendarDateFields field, int32_t startValue, int32_t endValue, UErrorCode &status) const;
01768 
01769 
01770 protected:
01775     UBool      fIsTimeSet;
01776 
01787     UBool      fAreFieldsSet;
01788 
01794     UBool      fAreAllFieldsSet;
01795 
01803     UBool fAreFieldsVirtuallySet;
01804 
01811     UDate        internalGetTime(void) const     { return fTime; }
01812 
01820     void        internalSetTime(UDate time)     { fTime = time; }
01821 
01826     int32_t     fFields[UCAL_FIELD_COUNT];
01827 
01832     UBool      fIsSet[UCAL_FIELD_COUNT];
01833 
01837     enum {
01838         kUnset                 = 0,
01839         kInternallySet,
01840         kMinimumUserStamp
01841     };
01842 
01849     int32_t        fStamp[UCAL_FIELD_COUNT];
01850 
01875     virtual void handleComputeFields(int32_t julianDay, UErrorCode &status);
01876 
01877 #ifndef U_HIDE_INTERNAL_API
01878 
01883     int32_t getGregorianYear() const {
01884         return fGregorianYear;
01885     }
01886 
01892     int32_t getGregorianMonth() const {
01893         return fGregorianMonth;
01894     }
01895 
01901     int32_t getGregorianDayOfYear() const {
01902         return fGregorianDayOfYear;
01903     }
01904 
01910     int32_t getGregorianDayOfMonth() const {
01911       return fGregorianDayOfMonth;
01912     }
01913 #endif  /* U_HIDE_INTERNAL_API */
01914 
01921     virtual int32_t getDefaultMonthInYear(int32_t eyear) ;
01922 
01923 
01931     virtual int32_t getDefaultDayInMonth(int32_t eyear, int32_t month);
01932 
01933     //-------------------------------------------------------------------------
01934     // Protected utility methods for use by subclasses.  These are very handy
01935     // for implementing add, roll, and computeFields.
01936     //-------------------------------------------------------------------------
01937 
01967     virtual void pinField(UCalendarDateFields field, UErrorCode& status);
01968 
02012     int32_t weekNumber(int32_t desiredDay, int32_t dayOfPeriod, int32_t dayOfWeek);
02013 
02014 
02015 #ifndef U_HIDE_INTERNAL_API
02016 
02046     inline int32_t weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek);
02047 
02052     int32_t getLocalDOW();
02053 #endif  /* U_HIDE_INTERNAL_API */
02054 
02055 private:
02056 
02060     int32_t fNextStamp;// = MINIMUM_USER_STAMP;
02061 
02066     void recalculateStamp();
02067 
02071     UDate        fTime;
02072 
02076     UBool      fLenient;
02077 
02082     TimeZone*   fZone;
02083 
02088     UCalendarWallTimeOption fRepeatedWallTime;
02089 
02094     UCalendarWallTimeOption fSkippedWallTime;
02095 
02104     UCalendarDaysOfWeek fFirstDayOfWeek;
02105     uint8_t     fMinimalDaysInFirstWeek;
02106     UCalendarDaysOfWeek fWeekendOnset;
02107     int32_t fWeekendOnsetMillis;
02108     UCalendarDaysOfWeek fWeekendCease;
02109     int32_t fWeekendCeaseMillis;
02110 
02121     void        setWeekData(const Locale& desiredLocale, const char *type, UErrorCode& success);
02122 
02132     void updateTime(UErrorCode& status);
02133 
02139     int32_t fGregorianYear;
02140 
02146     int32_t fGregorianMonth;
02147 
02153     int32_t fGregorianDayOfYear;
02154 
02160     int32_t fGregorianDayOfMonth;
02161 
02162     /* calculations */
02163 
02170     void computeGregorianAndDOWFields(int32_t julianDay, UErrorCode &ec);
02171 
02172 protected:
02173 
02181     void computeGregorianFields(int32_t julianDay, UErrorCode &ec);
02182 
02183 private:
02184 
02205     void computeWeekFields(UErrorCode &ec);
02206 
02207 
02216     void validateFields(UErrorCode &status);
02217 
02226     virtual void validateField(UCalendarDateFields field, UErrorCode &status);
02227 
02236     void validateField(UCalendarDateFields field, int32_t min, int32_t max, UErrorCode& status);
02237 
02238  protected:
02239 #ifndef U_HIDE_INTERNAL_API
02240 
02249     static uint8_t julianDayToDayOfWeek(double julian);
02250 #endif  /* U_HIDE_INTERNAL_API */
02251 
02252  private:
02253     char validLocale[ULOC_FULLNAME_CAPACITY];
02254     char actualLocale[ULOC_FULLNAME_CAPACITY];
02255 
02256  public:
02257 #if !UCONFIG_NO_SERVICE
02258 
02262 #ifndef U_HIDE_INTERNAL_API
02263 
02269     static StringEnumeration* getAvailableLocales(void);
02270 
02279     static URegistryKey registerFactory(ICUServiceFactory* toAdopt, UErrorCode& status);
02280 
02291     static UBool unregister(URegistryKey key, UErrorCode& status);
02292 #endif  /* U_HIDE_INTERNAL_API */
02293 
02298     friend class CalendarFactory;
02299 
02304     friend class CalendarService;
02305 
02310     friend class DefaultCalendarFactory;
02311 #endif /* !UCONFIG_NO_SERVICE */
02312 
02317     virtual UBool haveDefaultCentury() const = 0;
02318 
02323     virtual UDate defaultCenturyStart() const = 0;
02328     virtual int32_t defaultCenturyStartYear() const = 0;
02329 
02336     Locale getLocale(ULocDataLocaleType type, UErrorCode &status) const;
02337 
02338 #ifndef U_HIDE_INTERNAL_API
02339 
02345     const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;
02346 #endif  /* U_HIDE_INTERNAL_API */
02347 
02348 private:
02353     BasicTimeZone* getBasicTimeZone() const;
02354 };
02355 
02356 // -------------------------------------
02357 
02358 inline Calendar*
02359 Calendar::createInstance(TimeZone* zone, UErrorCode& errorCode)
02360 {
02361     // since the Locale isn't specified, use the default locale
02362     return createInstance(zone, Locale::getDefault(), errorCode);
02363 }
02364 
02365 // -------------------------------------
02366 
02367 inline void
02368 Calendar::roll(UCalendarDateFields field, UBool up, UErrorCode& status)
02369 {
02370     roll(field, (int32_t)(up ? +1 : -1), status);
02371 }
02372 
02373 #ifndef U_HIDE_DEPRECATED_API
02374 inline void
02375 Calendar::roll(EDateFields field, UBool up, UErrorCode& status)
02376 {
02377     roll((UCalendarDateFields) field, up, status);
02378 }
02379 #endif
02380 
02381 
02382 // -------------------------------------
02383 
02389 inline void
02390 Calendar::internalSet(UCalendarDateFields field, int32_t value)
02391 {
02392     fFields[field] = value;
02393     fStamp[field] = kInternallySet;
02394     fIsSet[field]     = TRUE; // Remove later
02395 }
02396 
02397 
02398 #ifndef U_HIDE_INTERNAL_API
02399 inline int32_t  Calendar::weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek)
02400 {
02401   return weekNumber(dayOfPeriod, dayOfPeriod, dayOfWeek);
02402 }
02403 #endif
02404 
02405 U_NAMESPACE_END
02406 
02407 #endif /* #if !UCONFIG_NO_FORMATTING */
02408 
02409 #endif // _CALENDAR