calendar.h

Go to the documentation of this file.

// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
********************************************************************************
*   Copyright (C) 1997-2014, International Business Machines
*   Corporation and others.  All Rights Reserved.
********************************************************************************
*
* File CALENDAR.H
*
* Modification History:
*
*   Date        Name        Description
*   04/22/97    aliu        Expanded and corrected comments and other header
*                           contents.
*   05/01/97    aliu        Made equals(), before(), after() arguments const.
*   05/20/97    aliu        Replaced fAreFieldsSet with fAreFieldsInSync and
*                           fAreAllFieldsSet.
*   07/27/98    stephen     Sync up with JDK 1.2
*   11/15/99    weiv        added YEAR_WOY and DOW_LOCAL
*                           to EDateFields
*    8/19/2002  srl         Removed Javaisms
*   11/07/2003  srl         Update, clean up documentation.
********************************************************************************
*/
 
#ifndef CALENDAR_H
#define CALENDAR_H
 
#include "unicode/utypes.h"
 
#if U_SHOW_CPLUSPLUS_API
 
#if !UCONFIG_NO_FORMATTING
 
#include "unicode/uobject.h"
#include "unicode/locid.h"
#include "unicode/timezone.h"
#include "unicode/ucal.h"
#include "unicode/umisc.h"
 
U_NAMESPACE_BEGIN
 
class ICUServiceFactory;
 
// Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
// it is a return type for a virtual method (@internal)
typedef int32_t UFieldResolutionTable[12][8];
 
class BasicTimeZone;
class U_I18N_API Calendar : public UObject {
public:
#ifndef U_FORCE_HIDE_DEPRECATED_API
    enum EDateFields {
#ifndef U_HIDE_DEPRECATED_API
/*
 * ERA may be defined on other platforms. To avoid any potential problems undefined it here.
 */
#ifdef ERA
#undef ERA
#endif
        ERA,                  // Example: 0..1
        YEAR,                 // Example: 1..big number
        MONTH,                // Example: 0..11
        WEEK_OF_YEAR,         // Example: 1..53
        WEEK_OF_MONTH,        // Example: 1..4
        DATE,                 // Example: 1..31
        DAY_OF_YEAR,          // Example: 1..365
        DAY_OF_WEEK,          // Example: 1..7
        DAY_OF_WEEK_IN_MONTH, // Example: 1..4, may be specified as -1
        AM_PM,                // Example: 0..1
        HOUR,                 // Example: 0..11
        HOUR_OF_DAY,          // Example: 0..23
        MINUTE,               // Example: 0..59
        SECOND,               // Example: 0..59
        MILLISECOND,          // Example: 0..999
        ZONE_OFFSET,          // Example: -12*U_MILLIS_PER_HOUR..12*U_MILLIS_PER_HOUR
        DST_OFFSET,           // Example: 0 or U_MILLIS_PER_HOUR
        YEAR_WOY,             // 'Y' Example: 1..big number - Year of Week of Year
        DOW_LOCAL,            // 'e' Example: 1..7 - Day of Week / Localized
 
        EXTENDED_YEAR,
        JULIAN_DAY,
        MILLISECONDS_IN_DAY,
        IS_LEAP_MONTH,
 
        FIELD_COUNT = UCAL_FIELD_COUNT // See ucal.h for other fields.
#endif /* U_HIDE_DEPRECATED_API */
    };
#endif  // U_FORCE_HIDE_DEPRECATED_API
 
#ifndef U_HIDE_DEPRECATED_API
    enum EDaysOfWeek {
        SUNDAY = 1,
        MONDAY,
        TUESDAY,
        WEDNESDAY,
        THURSDAY,
        FRIDAY,
        SATURDAY
    };
 
    enum EMonths {
        JANUARY,
        FEBRUARY,
        MARCH,
        APRIL,
        MAY,
        JUNE,
        JULY,
        AUGUST,
        SEPTEMBER,
        OCTOBER,
        NOVEMBER,
        DECEMBER,
        UNDECIMBER
    };
 
    enum EAmpm {
        AM,
        PM
    };
#endif  /* U_HIDE_DEPRECATED_API */
 
    virtual ~Calendar();
 
    virtual Calendar* clone() const = 0;
 
    static Calendar* U_EXPORT2 createInstance(UErrorCode& success);
 
    static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, UErrorCode& success);
 
    static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, UErrorCode& success);
 
    static Calendar* U_EXPORT2 createInstance(const Locale& aLocale, UErrorCode& success);
 
    static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, const Locale& aLocale, UErrorCode& success);
 
    static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, const Locale& aLocale, UErrorCode& success);
 
    static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
 
 
    static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* key,
                    const Locale& locale, UBool commonlyUsed, UErrorCode& status);
 
    static UDate U_EXPORT2 getNow(void);
 
    inline UDate getTime(UErrorCode& status) const { return getTimeInMillis(status); }
 
    inline void setTime(UDate date, UErrorCode& status) { setTimeInMillis(date, status); }
 
    virtual bool operator==(const Calendar& that) const;
 
    bool operator!=(const Calendar& that) const {return !operator==(that);}
 
    virtual UBool isEquivalentTo(const Calendar& other) const;
 
    UBool equals(const Calendar& when, UErrorCode& status) const;
 
    UBool before(const Calendar& when, UErrorCode& status) const;
 
    UBool after(const Calendar& when, UErrorCode& status) const;
 
#ifndef U_FORCE_HIDE_DEPRECATED_API
    virtual void add(EDateFields field, int32_t amount, UErrorCode& status);
#endif  // U_FORCE_HIDE_DEPRECATED_API
 
    virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& status);
 
#ifndef U_HIDE_DEPRECATED_API
    inline void roll(EDateFields field, UBool up, UErrorCode& status);
#endif  /* U_HIDE_DEPRECATED_API */
 
    inline void roll(UCalendarDateFields field, UBool up, UErrorCode& status);
 
#ifndef U_FORCE_HIDE_DEPRECATED_API
    virtual void roll(EDateFields field, int32_t amount, UErrorCode& status);
#endif  // U_FORCE_HIDE_DEPRECATED_API
 
    virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode& status);
 
#ifndef U_FORCE_HIDE_DEPRECATED_API
    virtual int32_t fieldDifference(UDate when, EDateFields field, UErrorCode& status);
#endif  // U_FORCE_HIDE_DEPRECATED_API
 
    virtual int32_t fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status);
 
    void adoptTimeZone(TimeZone* value);
 
    void setTimeZone(const TimeZone& zone);
 
    const TimeZone& getTimeZone(void) const;
 
    TimeZone* orphanTimeZone(void);
 
    virtual UBool inDaylightTime(UErrorCode& status) const = 0;
 
    void setLenient(UBool lenient);
 
    UBool isLenient(void) const;
 
    void setRepeatedWallTimeOption(UCalendarWallTimeOption option);
 
    UCalendarWallTimeOption getRepeatedWallTimeOption(void) const;
 
    void setSkippedWallTimeOption(UCalendarWallTimeOption option);
 
    UCalendarWallTimeOption getSkippedWallTimeOption(void) const;
 
    void setFirstDayOfWeek(UCalendarDaysOfWeek value);
 
#ifndef U_HIDE_DEPRECATED_API
    EDaysOfWeek getFirstDayOfWeek(void) const;
#endif  /* U_HIDE_DEPRECATED_API */
 
    UCalendarDaysOfWeek getFirstDayOfWeek(UErrorCode &status) const;
 
    void setMinimalDaysInFirstWeek(uint8_t value);
 
    uint8_t getMinimalDaysInFirstWeek(void) const;
 
#ifndef U_FORCE_HIDE_DEPRECATED_API
    virtual int32_t getMinimum(EDateFields field) const;
#endif  // U_FORCE_HIDE_DEPRECATED_API
 
    virtual int32_t getMinimum(UCalendarDateFields field) const;
 
#ifndef U_FORCE_HIDE_DEPRECATED_API
    virtual int32_t getMaximum(EDateFields field) const;
#endif  // U_FORCE_HIDE_DEPRECATED_API
 
    virtual int32_t getMaximum(UCalendarDateFields field) const;
 
#ifndef U_FORCE_HIDE_DEPRECATED_API
    virtual int32_t getGreatestMinimum(EDateFields field) const;
#endif  // U_FORCE_HIDE_DEPRECATED_API
 
    virtual int32_t getGreatestMinimum(UCalendarDateFields field) const;
 
#ifndef U_FORCE_HIDE_DEPRECATED_API
    virtual int32_t getLeastMaximum(EDateFields field) const;
#endif  // U_FORCE_HIDE_DEPRECATED_API
 
    virtual int32_t getLeastMaximum(UCalendarDateFields field) const;
 
#ifndef U_HIDE_DEPRECATED_API
    int32_t getActualMinimum(EDateFields field, UErrorCode& status) const;
#endif  /* U_HIDE_DEPRECATED_API */
 
    virtual int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& status) const;
 
    virtual int32_t getActualMaximum(UCalendarDateFields field, UErrorCode& status) const;
 
    int32_t get(UCalendarDateFields field, UErrorCode& status) const;
 
    UBool isSet(UCalendarDateFields field) const;
 
    void set(UCalendarDateFields field, int32_t value);
 
    void set(int32_t year, int32_t month, int32_t date);
 
    void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute);
 
    void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute, int32_t second);
 
    void clear(void);
 
    void clear(UCalendarDateFields field);
 
    virtual UClassID getDynamicClassID(void) const override = 0;
 
    virtual const char * getType() const = 0;
 
    virtual UCalendarWeekdayType getDayOfWeekType(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const;
 
    virtual int32_t getWeekendTransition(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const;
 
    virtual UBool isWeekend(UDate date, UErrorCode &status) const;
 
    virtual UBool isWeekend(void) const;
 
protected:
 
    Calendar(UErrorCode& success);
 
    Calendar(const Calendar& source);
 
    Calendar& operator=(const Calendar& right);
 
    Calendar(TimeZone* zone, const Locale& aLocale, UErrorCode& success);
 
    Calendar(const TimeZone& zone, const Locale& aLocale, UErrorCode& success);
 
    virtual void computeTime(UErrorCode& status);
 
    virtual void computeFields(UErrorCode& status);
 
    double getTimeInMillis(UErrorCode& status) const;
 
    void setTimeInMillis( double millis, UErrorCode& status );
 
    void complete(UErrorCode& status);
 
#ifndef U_HIDE_DEPRECATED_API
    inline int32_t internalGet(EDateFields field) const {return fFields[field];}
#endif  /* U_HIDE_DEPRECATED_API */
 
#ifndef U_HIDE_INTERNAL_API
    inline int32_t internalGet(UCalendarDateFields field, int32_t defaultValue) const {return fStamp[field]>kUnset ? fFields[field] : defaultValue;}
 
    inline int32_t internalGet(UCalendarDateFields field) const {return fFields[field];}
#endif  /* U_HIDE_INTERNAL_API */
 
#ifndef U_HIDE_DEPRECATED_API
    void internalSet(EDateFields field, int32_t value);
#endif  /* U_HIDE_DEPRECATED_API */
 
    inline void internalSet(UCalendarDateFields field, int32_t value);
 
    virtual void prepareGetActual(UCalendarDateFields field, UBool isMinimum, UErrorCode &status);
 
    enum ELimitType {
#ifndef U_HIDE_INTERNAL_API
      UCAL_LIMIT_MINIMUM = 0,
      UCAL_LIMIT_GREATEST_MINIMUM,
      UCAL_LIMIT_LEAST_MAXIMUM,
      UCAL_LIMIT_MAXIMUM,
      UCAL_LIMIT_COUNT
#endif  /* U_HIDE_INTERNAL_API */
    };
 
    virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const = 0;
 
    virtual int32_t getLimit(UCalendarDateFields field, ELimitType limitType) const;
 
 
    virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month,
                                                   UBool useMonth) const  = 0;
 
    virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const ;
 
    virtual int32_t handleGetYearLength(int32_t eyear) const;
 
 
    virtual int32_t handleGetExtendedYear() = 0;
 
    virtual int32_t handleComputeJulianDay(UCalendarDateFields bestField);
 
    virtual int32_t handleGetExtendedYearFromWeekFields(int32_t yearWoy, int32_t woy);
 
    virtual void validateField(UCalendarDateFields field, UErrorCode &status);
 
#ifndef U_HIDE_INTERNAL_API
    int32_t computeJulianDay();
 
    double computeMillisInDay();
 
    int32_t computeZoneOffset(double millis, double millisInDay, UErrorCode &ec);
 
 
    int32_t newestStamp(UCalendarDateFields start, UCalendarDateFields end, int32_t bestSoFar) const;
 
    static constexpr int32_t kResolveSTOP = -1;
    static constexpr int32_t kResolveRemap = 32;
 
    static const UFieldResolutionTable kDatePrecedence[];
 
    static const UFieldResolutionTable kYearPrecedence[];
 
    static const UFieldResolutionTable kDOWPrecedence[];
 
    UCalendarDateFields resolveFields(const UFieldResolutionTable *precedenceTable);
#endif  /* U_HIDE_INTERNAL_API */
 
 
    virtual const UFieldResolutionTable* getFieldResolutionTable() const;
 
#ifndef U_HIDE_INTERNAL_API
    UCalendarDateFields newerField(UCalendarDateFields defaultField, UCalendarDateFields alternateField) const;
#endif  /* U_HIDE_INTERNAL_API */
 
 
private:
    int32_t getActualHelper(UCalendarDateFields field, int32_t startValue, int32_t endValue, UErrorCode &status) const;
 
 
protected:
    UBool      fIsTimeSet;
 
    UBool      fAreFieldsSet;
 
    UBool      fAreAllFieldsSet;
 
    UBool fAreFieldsVirtuallySet;
 
    UDate        internalGetTime(void) const     { return fTime; }
 
    void        internalSetTime(UDate time)     { fTime = time; }
 
    int32_t     fFields[UCAL_FIELD_COUNT];
 
#ifndef U_FORCE_HIDE_DEPRECATED_API
    UBool      fIsSet[UCAL_FIELD_COUNT];
#endif  // U_FORCE_HIDE_DEPRECATED_API
 
    enum {
        kUnset                 = 0,
        kInternallySet,
        kMinimumUserStamp
    };
 
    int32_t        fStamp[UCAL_FIELD_COUNT];
 
    virtual void handleComputeFields(int32_t julianDay, UErrorCode &status);
 
#ifndef U_HIDE_INTERNAL_API
    int32_t getGregorianYear() const {
        return fGregorianYear;
    }
 
    int32_t getGregorianMonth() const {
        return fGregorianMonth;
    }
 
    int32_t getGregorianDayOfYear() const {
        return fGregorianDayOfYear;
    }
 
    int32_t getGregorianDayOfMonth() const {
      return fGregorianDayOfMonth;
    }
#endif  /* U_HIDE_INTERNAL_API */
 
    virtual int32_t getDefaultMonthInYear(int32_t eyear) ;
 
 
    virtual int32_t getDefaultDayInMonth(int32_t eyear, int32_t month);
 
    //-------------------------------------------------------------------------
    // Protected utility methods for use by subclasses.  These are very handy
    // for implementing add, roll, and computeFields.
    //-------------------------------------------------------------------------
 
    virtual void pinField(UCalendarDateFields field, UErrorCode& status);
 
    int32_t weekNumber(int32_t desiredDay, int32_t dayOfPeriod, int32_t dayOfWeek);
 
 
#ifndef U_HIDE_INTERNAL_API
    inline int32_t weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek);
 
    int32_t getLocalDOW();
#endif  /* U_HIDE_INTERNAL_API */
 
private:
 
    int32_t fNextStamp;// = MINIMUM_USER_STAMP;
 
    void recalculateStamp();
 
    UDate        fTime;
 
    UBool      fLenient;
 
    TimeZone*   fZone;
 
    UCalendarWallTimeOption fRepeatedWallTime;
 
    UCalendarWallTimeOption fSkippedWallTime;
 
    UCalendarDaysOfWeek fFirstDayOfWeek;
    uint8_t     fMinimalDaysInFirstWeek;
    UCalendarDaysOfWeek fWeekendOnset;
    int32_t fWeekendOnsetMillis;
    UCalendarDaysOfWeek fWeekendCease;
    int32_t fWeekendCeaseMillis;
 
    void        setWeekData(const Locale& desiredLocale, const char *type, UErrorCode& success);
 
    void updateTime(UErrorCode& status);
 
    int32_t fGregorianYear;
 
    int32_t fGregorianMonth;
 
    int32_t fGregorianDayOfYear;
 
    int32_t fGregorianDayOfMonth;
 
    /* calculations */
 
    void computeGregorianAndDOWFields(int32_t julianDay, UErrorCode &ec);
 
protected:
 
    void computeGregorianFields(int32_t julianDay, UErrorCode &ec);
 
private:
 
    void computeWeekFields(UErrorCode &ec);
 
 
    void validateFields(UErrorCode &status);
 
    void validateField(UCalendarDateFields field, int32_t min, int32_t max, UErrorCode& status);
 
 protected:
#ifndef U_HIDE_INTERNAL_API
    static uint8_t julianDayToDayOfWeek(double julian);
#endif  /* U_HIDE_INTERNAL_API */
 
 private:
    char validLocale[ULOC_FULLNAME_CAPACITY];
    char actualLocale[ULOC_FULLNAME_CAPACITY];
 
 public:
#if !UCONFIG_NO_SERVICE
#ifndef U_HIDE_INTERNAL_API
    static StringEnumeration* getAvailableLocales(void);
 
    static URegistryKey registerFactory(ICUServiceFactory* toAdopt, UErrorCode& status);
 
    static UBool unregister(URegistryKey key, UErrorCode& status);
#endif  /* U_HIDE_INTERNAL_API */
 
    friend class CalendarFactory;
 
    friend class CalendarService;
 
    friend class DefaultCalendarFactory;
#endif /* !UCONFIG_NO_SERVICE */
 
    virtual UBool haveDefaultCentury() const = 0;
 
    virtual UDate defaultCenturyStart() const = 0;
    virtual int32_t defaultCenturyStartYear() const = 0;
 
    Locale getLocale(ULocDataLocaleType type, UErrorCode &status) const;
 
    virtual int32_t getRelatedYear(UErrorCode &status) const;
 
    virtual void setRelatedYear(int32_t year);
 
#ifndef U_HIDE_INTERNAL_API
    const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;
#endif  /* U_HIDE_INTERNAL_API */
 
private:
    BasicTimeZone* getBasicTimeZone() const;
 
    UBool getImmediatePreviousZoneTransition(UDate base, UDate *transitionTime, UErrorCode& status) const;
 
public:
#ifndef U_HIDE_INTERNAL_API
    static Calendar * U_EXPORT2 makeInstance(
            const Locale &locale, UErrorCode &status);
 
    static void U_EXPORT2 getCalendarTypeFromLocale(
            const Locale &locale,
            char *typeBuffer,
            int32_t typeBufferSize,
            UErrorCode &status);
#endif  /* U_HIDE_INTERNAL_API */
};
 
// -------------------------------------
 
inline Calendar*
Calendar::createInstance(TimeZone* zone, UErrorCode& errorCode)
{
    // since the Locale isn't specified, use the default locale
    return createInstance(zone, Locale::getDefault(), errorCode);
}
 
// -------------------------------------
 
inline void
Calendar::roll(UCalendarDateFields field, UBool up, UErrorCode& status)
{
    roll(field, (int32_t)(up ? +1 : -1), status);
}
 
#ifndef U_HIDE_DEPRECATED_API
inline void
Calendar::roll(EDateFields field, UBool up, UErrorCode& status)
{
    roll((UCalendarDateFields) field, up, status);
}
#endif  /* U_HIDE_DEPRECATED_API */
 
 
// -------------------------------------
 
inline void
Calendar::internalSet(UCalendarDateFields field, int32_t value)
{
    fFields[field] = value;
    fStamp[field] = kInternallySet;
    fIsSet[field]     = true; // Remove later
}
 
 
#ifndef U_HIDE_INTERNAL_API
inline int32_t  Calendar::weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek)
{
  return weekNumber(dayOfPeriod, dayOfPeriod, dayOfWeek);
}
#endif  /* U_HIDE_INTERNAL_API */
 
U_NAMESPACE_END
 
#endif /* #if !UCONFIG_NO_FORMATTING */
 
#endif /* U_SHOW_CPLUSPLUS_API */
 
#endif // _CALENDAR