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();

    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() const;

    TimeZone* orphanTimeZone();

    virtual UBool inDaylightTime(UErrorCode& status) const;

    void setLenient(UBool lenient);

    UBool isLenient() const;

    void setRepeatedWallTimeOption(UCalendarWallTimeOption option);

    UCalendarWallTimeOption getRepeatedWallTimeOption() const;

    void setSkippedWallTimeOption(UCalendarWallTimeOption option);

    UCalendarWallTimeOption getSkippedWallTimeOption() const;

    void setFirstDayOfWeek(UCalendarDaysOfWeek value);

#ifndef U_HIDE_DEPRECATED_API

    EDaysOfWeek getFirstDayOfWeek() const;
#endif  /* U_HIDE_DEPRECATED_API */

    UCalendarDaysOfWeek getFirstDayOfWeek(UErrorCode &status) const;

    void setMinimalDaysInFirstWeek(uint8_t value);

    uint8_t getMinimalDaysInFirstWeek() 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 clear(UCalendarDateFields field);

    virtual UClassID getDynamicClassID() 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() const;

    virtual bool inTemporalLeapYear(UErrorCode& status) const;

    virtual const char* getTemporalMonthCode(UErrorCode& status) const;

    virtual void setTemporalMonthCode(const char* temporalMonth, UErrorCode& status);

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];}

    virtual bool isEra0CountingBackward() const { return false; }
#endif  /* U_HIDE_INTERNAL_API */

    virtual int32_t internalGetMonth(UErrorCode& status) const;

    virtual int32_t internalGetMonth(int32_t defaultValue, UErrorCode& status) const;

#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 int64_t handleComputeMonthStart(int32_t eyear, int32_t month,
                                            UBool useMonth, UErrorCode& status) const  = 0;

    virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month, UErrorCode& status) const ;

    virtual int32_t handleGetYearLength(int32_t eyear) const;


    virtual int32_t handleGetExtendedYear(UErrorCode& status) = 0;

    virtual int32_t handleComputeJulianDay(UCalendarDateFields bestField, UErrorCode &status);

    virtual int32_t handleGetExtendedYearFromWeekFields(int32_t yearWoy, int32_t woy, UErrorCode& status);

    virtual void validateField(UCalendarDateFields field, UErrorCode &status);

#ifndef U_HIDE_INTERNAL_API

    int32_t computeJulianDay(UErrorCode &status);

    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[];

    static const UFieldResolutionTable kMonthPrecedence[];

    UCalendarDateFields resolveFields(const UFieldResolutionTable *precedenceTable) const;
#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() 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, UErrorCode& status);


    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(UErrorCode& status);
#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(int32_t 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();

    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
}

#define DECLARE_OVERRIDE_SYSTEM_DEFAULT_CENTURY \
    virtual UBool haveDefaultCentury() const override; \
    virtual UDate defaultCenturyStart() const override; \
    virtual int32_t defaultCenturyStartYear() const override;

#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