/* ******************************************************************************** * Copyright (C) 1997-2002, 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 ******************************************************************************** */ #ifndef CALENDAR_H #define CALENDAR_H #include "unicode/utypes.h" #if !UCONFIG_NO_FORMATTING #include "unicode/uobject.h" #include "unicode/locid.h" #include "unicode/timezone.h" U_NAMESPACE_BEGIN /** * Calendar is an abstract base class for converting between * a UDate object and a set of integer fields such as * YEAR, MONTH, DAY, HOUR, * and so on. (A UDate object represents a specific instant in * time with millisecond precision. See * {@link UDate} * for information about the UDate class.) * *

* Subclasses of Calendar interpret a UDate * according to the rules of a specific calendar system. The JDK * provides one concrete subclass of Calendar: * GregorianCalendar. Future subclasses could represent * the various types of lunar calendars in use in many parts of the world. * *

* Like other locale-sensitive classes, Calendar provides a * static method, createInstance, for getting a generally useful * object of this type. Calendar's createInstance method currently * returns a GregorianCalendar object whose * time fields have been initialized with the current date and time: *

*
 * Calendar *rightNow = Calendar::createInstance(errCode);
 * 
*
* *

* A Calendar object can produce all the time field values * needed to implement the date-time formatting for a particular language * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional). * *

* When computing a UDate from time fields, two special circumstances * may arise: there may be insufficient information to compute the * UDate (such as only year and month but no day in the month), * or there may be inconsistent information (such as "Tuesday, July 15, 1996" * -- July 15, 1996 is actually a Monday). * *

* Insufficient information. The calendar will use default * information to specify the missing fields. This may vary by calendar; for * the Gregorian calendar, the default for a field is the same as that of the * start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. * *

* Inconsistent information. If fields conflict, the calendar * will give preference to fields set more recently. For example, when * determining the day, the calendar will look for one of the following * combinations of fields. The most recent combination, as determined by the * most recently set single field, will be used. * *

*
 * MONTH + DAY_OF_MONTH
 * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
 * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
 * DAY_OF_YEAR
 * DAY_OF_WEEK + WEEK_OF_YEAR
 * 
*
* * For the time of day: * *
*
 * HOUR_OF_DAY
 * AM_PM + HOUR
 * 
*
* *

* Note: for some non-Gregorian calendars, different * fields may be necessary for complete disambiguation. For example, a full * specification of the historial Arabic astronomical calendar requires year, * month, day-of-month and day-of-week in some cases. * *

* Note: There are certain possible ambiguities in * interpretation of certain singular times, which are resolved in the * following ways: *

    *
  1. 24:00:00 "belongs" to the following day. That is, * 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970 * *
  2. Although historically not precise, midnight also belongs to "am", * and noon belongs to "pm", so on the same day, * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm *
* *

* The date or time format strings are not part of the definition of a * calendar, as those must be modifiable or overridable by the user at * runtime. Use {@link DateFormat} * to format dates. * *

* Calendar provides an API for field "rolling", where fields * can be incremented or decremented, but wrap around. For example, rolling the * month up in the date December 12, 1996 results in * January 12, 1996. * *

* Calendar also provides a date arithmetic function for * adding the specified (signed) amount of time to a particular time field. * For example, subtracting 5 days from the date September 12, 1996 * results in September 7, 1996. * * @stable */ class U_I18N_API Calendar : public UObject { public: /** * Field IDs for date and time. Used to specify date/time fields. ERA is calendar * specific. Example ranges given are for illustration only; see specific Calendar * subclasses for actual ranges. * @stable */ enum EDateFields { 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 // here will go names for 'Y' and 'e' YEAR_WOY, // 'Y' Example: 1..big number DOW_LOCAL, // 'e' Example: 1..7 FIELD_COUNT, DAY_OF_MONTH = DATE // Synonyms }; /** * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients * who create locale resources for the field of first-day-of-week should be aware of * this. For instance, in US locale, first-day-of-week is set to 1, i.e., SUNDAY. * @stable */ enum EDaysOfWeek { SUNDAY = 1, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY }; /** * Useful constants for month. Note: Calendar month is 0-based. * @stable */ enum EMonths { JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER, UNDECIMBER }; /** * Useful constants for hour in 12-hour clock. Used in GregorianCalendar. * @stable */ enum EAmpm { AM, PM }; /** * destructor * @stable */ virtual ~Calendar(); /** * Create and return a polymorphic copy of this calendar. * * @return a polymorphic copy of this calendar. * @stable */ virtual Calendar* clone(void) const = 0; /** * Creates a Calendar using the default timezone and locale. Clients are responsible * for deleting the object returned. * * @param success Indicates the success/failure of Calendar creation. Filled in * with U_ZERO_ERROR if created successfully, set to a failure result * otherwise. * @return A Calendar if created successfully. NULL otherwise. * @stable */ static Calendar* createInstance(UErrorCode& success); /** * Creates a Calendar using the given timezone and the default locale. * The Calendar takes ownership of zoneToAdopt; the * client must not delete it. * * @param zoneToAdopt The given timezone to be adopted. * @param success Indicates the success/failure of Calendar creation. Filled in * with U_ZERO_ERROR if created successfully, set to a failure result * otherwise. * @return A Calendar if created successfully. NULL otherwise. * @stable */ static Calendar* createInstance(TimeZone* zoneToAdopt, UErrorCode& success); /** * Creates a Calendar using the given timezone and the default locale. The TimeZone * is _not_ adopted; the client is still responsible for deleting it. * * @param zone The timezone. * @param success Indicates the success/failure of Calendar creation. Filled in * with U_ZERO_ERROR if created successfully, set to a failure result * otherwise. * @return A Calendar if created successfully. NULL otherwise. * @stable */ static Calendar* createInstance(const TimeZone& zone, UErrorCode& success); /** * Creates a Calendar using the default timezone and the given locale. * * @param aLocale The given locale. * @param success Indicates the success/failure of Calendar creation. Filled in * with U_ZERO_ERROR if created successfully, set to a failure result * otherwise. * @return A Calendar if created successfully. NULL otherwise. * @stable */ static Calendar* createInstance(const Locale& aLocale, UErrorCode& success); /** * Creates a Calendar using the given timezone and given locale. * The Calendar takes ownership of zoneToAdopt; the * client must not delete it. * * @param zoneToAdopt The given timezone to be adopted. * @param aLocale The given locale. * @param success Indicates the success/failure of Calendar creation. Filled in * with U_ZERO_ERROR if created successfully, set to a failure result * otherwise. * @return A Calendar if created successfully. NULL otherwise. * @stable */ static Calendar* createInstance(TimeZone* zoneToAdopt, const Locale& aLocale, UErrorCode& success); /** * Gets a Calendar using the given timezone and given locale. The TimeZone * is _not_ adopted; the client is still responsible for deleting it. * * @param zoneToAdopt The given timezone to be adopted. * @param aLocale The given locale. * @param success Indicates the success/failure of Calendar creation. Filled in * with U_ZERO_ERROR if created successfully, set to a failure result * otherwise. * @return A Calendar if created successfully. NULL otherwise. * @stable */ static Calendar* createInstance(const TimeZone& zoneToAdopt, const Locale& aLocale, UErrorCode& success); /** * Returns a list of the locales for which Calendars are installed. * * @param count Number of locales returned. * @return An array of Locale objects representing the set of locales for which * Calendars are installed. The system retains ownership of this list; * the caller must NOT delete it. * @stable */ static const Locale* getAvailableLocales(int32_t& count); /** * Returns the current UTC (GMT) time measured in milliseconds since 0:00:00 on 1/1/70 * (derived from the system time). * * @return The current UTC time in milliseconds. * @stable */ static UDate getNow(void); /** * Gets this Calendar's time as milliseconds. May involve recalculation of time due * to previous calls to set time field values. The time specified is non-local UTC * (GMT) time. Although this method is const, this object may actually be changed * (semantically const). * * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @return The current time in UTC (GMT) time, or zero if the operation * failed. * @stable */ inline UDate getTime(UErrorCode& status) const { return getTimeInMillis(status); } /** * Sets this Calendar's current time with the given UDate. The time specified should * be in non-local UTC (GMT) time. * * @param date The given UDate in UTC (GMT) time. * @param status Output param set to success/failure code on exit. If any value * set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @stable */ inline void setTime(UDate date, UErrorCode& status) { setTimeInMillis(date, status); } /** * Compares the equality of two Calendar objects. Objects of different subclasses * are considered unequal. This comparison is very exacting; two Calendar objects * must be in exactly the same state to be considered equal. To compare based on the * represented time, use equals() instead. * * @param that The Calendar object to be compared with. * @return True if the given Calendar is the same as this Calendar; false * otherwise. * @stable */ virtual UBool operator==(const Calendar& that) const; /** * Compares the inequality of two Calendar objects. * * @param that The Calendar object to be compared with. * @return True if the given Calendar is not the same as this Calendar; false * otherwise. * @stable */ UBool operator!=(const Calendar& that) const {return !operator==(that);} /** * Returns TRUE if the given Calendar object is equivalent to this * one. An equivalent Calendar will behave exactly as this one * does, but it may be set to a different time. By contrast, for * the operator==() method to return TRUE, the other Calendar must * be set to the same time. * * @param other the Calendar to be compared with this Calendar * @draft ICU 2.4 */ virtual UBool isEquivalentTo(const Calendar& other) const; /** * Compares the Calendar time, whereas Calendar::operator== compares the equality of * Calendar objects. * * @param when The Calendar to be compared with this Calendar. Although this is a * const parameter, the object may be modified physically * (semantically const). * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @return True if the current time of this Calendar is equal to the time of * Calendar when; false otherwise. * @stable */ UBool equals(const Calendar& when, UErrorCode& status) const; /** * Returns true if this Calendar's current time is before "when"'s current time. * * @param when The Calendar to be compared with this Calendar. Although this is a * const parameter, the object may be modified physically * (semantically const). * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @return True if the current time of this Calendar is before the time of * Calendar when; false otherwise. * @stable */ UBool before(const Calendar& when, UErrorCode& status) const; /** * Returns true if this Calendar's current time is after "when"'s current time. * * @param when The Calendar to be compared with this Calendar. Although this is a * const parameter, the object may be modified physically * (semantically const). * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @return True if the current time of this Calendar is after the time of * Calendar when; false otherwise. * @stable */ UBool after(const Calendar& when, UErrorCode& status) const; /** * UDate Arithmetic function. Adds the specified (signed) amount of time to the given * time field, based on the calendar's rules. For example, to subtract 5 days from * the current time of the calendar, call add(Calendar::DATE, -5). When adding on * the month or Calendar::MONTH field, other fields like date might conflict and * need to be changed. For instance, adding 1 month on the date 01/31/96 will result * in 02/29/96. * * @param field Specifies which date field to modify. * @param amount The amount of time to be added to the field, in the natural unit * for that field (e.g., days for the day fields, hours for the hour * field.) * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @stable */ virtual void add(EDateFields field, int32_t amount, UErrorCode& status) = 0; /** * Time Field Rolling function. Rolls (up/down) a single unit of time on the given * time field. For example, to roll the current date up by one day, call * roll(Calendar::DATE, true). When rolling on the year or Calendar::YEAR field, it * will roll the year value in the range between getMinimum(Calendar::YEAR) and the * value returned by getMaximum(Calendar::YEAR). When rolling on the month or * Calendar::MONTH field, other fields like date might conflict and, need to be * changed. For instance, rolling the month up on the date 01/31/96 will result in * 02/29/96. Rolling up always means rolling forward in time; e.g., rolling the year * up on "100 BC" will result in "99 BC", for Gregorian calendar. When rolling on the * hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the hour value in the range * between 0 and 23, which is zero-based. *

* NOTE: Do not use this method -- use roll(EDateFields, int, UErrorCode&) instead. * * @param field The time field. * @param up Indicates if the value of the specified time field is to be rolled * up or rolled down. Use true if rolling up, false otherwise. * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @stable */ void roll(EDateFields field, UBool up, UErrorCode& status); /** * Time Field Rolling function. Rolls by the given amount on the given * time field. For example, to roll the current date up by one day, call * roll(Calendar::DATE, +1, status). When rolling on the month or * Calendar::MONTH field, other fields like date might conflict and, need to be * changed. For instance, rolling the month up on the date 01/31/96 will result in * 02/29/96. Rolling by a positive value always means rolling forward in time; * e.g., rolling the year by +1 on "100 BC" will result in "99 BC", for Gregorian * calendar. When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will * roll the hour value in the range between 0 and 23, which is zero-based. *

* The only difference between roll() and add() is that roll() does not change * the value of more significant fields when it reaches the minimum or maximum * of its range, whereas add() does. * * @param field The time field. * @param amount Indicates amount to roll. * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid, this will be set to * an error status. * @stable */ virtual void roll(EDateFields field, int32_t amount, UErrorCode& status) = 0; /** * Return the difference between the given time and the time this * calendar object is set to. If this calendar is set * before the given time, the returned value will be * positive. If this calendar is set after the given * time, the returned value will be negative. The * field parameter specifies the units of the return * value. For example, if fieldDifference(when, * Calendar::MONTH) returns 3, then this calendar is set to * 3 months before when, and possibly some addition * time less than one month. * *

As a side effect of this call, this calendar is advanced * toward when by the given amount. That is, calling * this method has the side effect of calling add(field, * n), where n is the return value. * *

Usage: To use this method, call it first with the largest * field of interest, then with progressively smaller fields. For * example: * *

     * int y = cal->fieldDifference(when, Calendar::YEAR, err);
     * int m = cal->fieldDifference(when, Calendar::MONTH, err);
     * int d = cal->fieldDifference(when, Calendar::DATE, err);
* * computes the difference between cal and * when in years, months, and days. * *

Note: fieldDifference() is * asymmetrical. That is, in the following code: * *

     * cal->setTime(date1, err);
     * int m1 = cal->fieldDifference(date2, Calendar::MONTH, err);
     * int d1 = cal->fieldDifference(date2, Calendar::DATE, err);
     * cal->setTime(date2, err);
     * int m2 = cal->fieldDifference(date1, Calendar::MONTH, err);
     * int d2 = cal->fieldDifference(date1, Calendar::DATE, err);
* * one might expect that m1 == -m2 && d1 == -d2. * However, this is not generally the case, because of * irregularities in the underlying calendar system (e.g., the * Gregorian calendar has a varying number of days per month). * * @param when the date to compare this calendar's time to * @param field the field in which to compute the result * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid, this will be set to * an error status. * @return the difference, either positive or negative, between * this calendar's time and when, in terms of * field. * @stable */ virtual int32_t fieldDifference(UDate when, EDateFields field, UErrorCode& status); /** * Sets the calendar's time zone to be the one passed in. The Calendar takes ownership * of the TimeZone; the caller is no longer responsible for deleting it. If the * given time zone is NULL, this function has no effect. * * @param value The given time zone. * @stable */ void adoptTimeZone(TimeZone* value); /** * Sets the calendar's time zone to be the same as the one passed in. The TimeZone * passed in is _not_ adopted; the client is still responsible for deleting it. * * @param value The given time zone. * @stable */ void setTimeZone(const TimeZone& zone); /** * Returns a reference to the time zone owned by this calendar. The returned reference * is only valid until clients make another call to adoptTimeZone or setTimeZone, * or this Calendar is destroyed. * * @return The time zone object associated with this calendar. * @stable */ const TimeZone& getTimeZone(void) const; /** * Returns the time zone owned by this calendar. The caller owns the returned object * and must delete it when done. After this call, the new time zone associated * with this Calendar is the default TimeZone as returned by TimeZone::createDefault(). * * @return The time zone object which was associated with this calendar. * @stable */ TimeZone* orphanTimeZone(void); /** * Queries if the current date for this Calendar is in Daylight Savings Time. * * @param status Fill-in parameter which receives the status of this operation. * @return True if the current date for this Calendar is in Daylight Savings Time, * false, otherwise. * @stable */ virtual UBool inDaylightTime(UErrorCode& status) const = 0; /** * Specifies whether or not date/time interpretation is to be lenient. With lenient * interpretation, a date such as "February 942, 1996" will be treated as being * equivalent to the 941st day after February 1, 1996. With strict interpretation, * such dates will cause an error when computing time from the time field values * representing the dates. * * @param lenient True specifies date/time interpretation to be lenient. * * @see DateFormat#setLenient * @stable */ void setLenient(UBool lenient); /** * Tells whether date/time interpretation is to be lenient. * * @return True tells that date/time interpretation is to be lenient. * @stable */ UBool isLenient(void) const; /** * Sets what the first day of the week is; e.g., Sunday in US, Monday in France. * * @param value The given first day of the week. * @stable */ void setFirstDayOfWeek(EDaysOfWeek value); /** * Gets what the first day of the week is; e.g., Sunday in US, Monday in France. * * @return The first day of the week. * @stable */ EDaysOfWeek getFirstDayOfWeek(void) const; /** * Sets what the minimal days required in the first week of the year are; For * example, if the first week is defined as one that contains the first day of the * first month of a year, call the method with value 1. If it must be a full week, * use value 7. * * @param value The given minimal days required in the first week of the year. * @stable */ void setMinimalDaysInFirstWeek(uint8_t value); /** * Gets what the minimal days required in the first week of the year are; e.g., if * the first week is defined as one that contains the first day of the first month * of a year, getMinimalDaysInFirstWeek returns 1. If the minimal days required must * be a full week, getMinimalDaysInFirstWeek returns 7. * * @return The minimal days required in the first week of the year. * @stable */ uint8_t getMinimalDaysInFirstWeek(void) const; /** * Gets the minimum value for the given time field. e.g., for Gregorian * DAY_OF_MONTH, 1. * * @param field The given time field. * @return The minimum value for the given time field. * @stable */ virtual int32_t getMinimum(EDateFields field) const = 0; /** * Gets the maximum value for the given time field. e.g. for Gregorian DAY_OF_MONTH, * 31. * * @param field The given time field. * @return The maximum value for the given time field. * @stable */ virtual int32_t getMaximum(EDateFields field) const = 0; /** * Gets the highest minimum value for the given field if varies. Otherwise same as * getMinimum(). For Gregorian, no difference. * * @param field The given time field. * @return The highest minimum value for the given time field. * @stable */ virtual int32_t getGreatestMinimum(EDateFields field) const = 0; /** * Gets the lowest maximum value for the given field if varies. Otherwise same as * getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28. * * @param field The given time field. * @return The lowest maximum value for the given time field. * @stable */ virtual int32_t getLeastMaximum(EDateFields field) const = 0; /** * Return the minimum value that this field could have, given the current date. * For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum(). * * The version of this function on Calendar uses an iterative algorithm to determine the * actual minimum value for the field. There is almost always a more efficient way to * accomplish this (in most cases, you can simply return getMinimum()). GregorianCalendar * overrides this function with a more efficient implementation. * * @param field the field to determine the minimum of * @param status Fill-in parameter which receives the status of this operation. * @return the minimum of the given field for the current date of this Calendar * @stable */ int32_t getActualMinimum(EDateFields field, UErrorCode& status) const; /** * Return the maximum value that this field could have, given the current date. * For example, with the date "Feb 3, 1997" and the DAY_OF_MONTH field, the actual * maximum would be 28; for "Feb 3, 1996" it s 29. Similarly for a Hebrew calendar, * for some years the actual maximum for MONTH is 12, and for others 13. * * The version of this function on Calendar uses an iterative algorithm to determine the * actual maximum value for the field. There is almost always a more efficient way to * accomplish this (in most cases, you can simply return getMaximum()). GregorianCalendar * overrides this function with a more efficient implementation. * * @param field the field to determine the maximum of * @param status Fill-in parameter which receives the status of this operation. * @return the maximum of the given field for the current date of this Calendar * @stable */ int32_t getActualMaximum(EDateFields field, UErrorCode& status) const; /** * Gets the value for a given time field. Recalculate the current time field values * if the time value has been changed by a call to setTime(). Return zero for unset * fields if any fields have been explicitly set by a call to set(). To force a * recomputation of all fields regardless of the previous state, call complete(). * This method is semantically const, but may alter the object in memory. * * @param field The given time field. * @param status Fill-in parameter which receives the status of the operation. * @return The value for the given time field, or zero if the field is unset, * and set() has been called for any other field. * @stable */ int32_t get(EDateFields field, UErrorCode& status) const; /** * Determines if the given time field has a value set. This can affect in the * resolving of time in Calendar. Unset fields have a value of zero, by definition. * * @param field The given time field. * @return True if the given time field has a value set; false otherwise. * @stable */ UBool isSet(EDateFields field) const; /** * Sets the given time field with the given value. * * @param field The given time field. * @param value The value to be set for the given time field. * @stable */ void set(EDateFields field, int32_t value); /** * Sets the values for the fields YEAR, MONTH, and DATE. Other field values are * retained; call clear() first if this is not desired. * * @param year The value used to set the YEAR time field. * @param month The value used to set the MONTH time field. Month value is 0-based. * e.g., 0 for January. * @param date The value used to set the DATE time field. * @stable */ void set(int32_t year, int32_t month, int32_t date); /** * Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, and MINUTE. Other * field values are retained; call clear() first if this is not desired. * * @param year The value used to set the YEAR time field. * @param month The value used to set the MONTH time field. Month value is * 0-based. E.g., 0 for January. * @param date The value used to set the DATE time field. * @param hour The value used to set the HOUR_OF_DAY time field. * @param minute The value used to set the MINUTE time field. * @stable */ void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute); /** * Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, MINUTE, and SECOND. * Other field values are retained; call clear() first if this is not desired. * * @param year The value used to set the YEAR time field. * @param month The value used to set the MONTH time field. Month value is * 0-based. E.g., 0 for January. * @param date The value used to set the DATE time field. * @param hour The value used to set the HOUR_OF_DAY time field. * @param minute The value used to set the MINUTE time field. * @param second The value used to set the SECOND time field. * @stable */ void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute, int32_t second); /** * Clears the values of all the time fields, making them both unset and assigning * them a value of zero. The field values will be determined during the next * resolving of time into time fields. * @stable */ void clear(void); /** * Clears the value in the given time field, both making it unset and assigning it a * value of zero. This field value will be determined during the next resolving of * time into time fields. * * @param field The time field to be cleared. * @stable */ void clear(EDateFields field); /** * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. This method is to * implement a simple version of RTTI, since not all C++ compilers support genuine * RTTI. Polymorphic operator==() and clone() methods call this method. *

* Concrete subclasses of Calendar must implement getDynamicClassID() and also a * static method and data member: * * static UClassID getStaticClassID() { return (UClassID)&fgClassID; } * static char fgClassID; * * @return The class ID for this object. All objects of a given class have the * same class ID. Objects of other classes have different class IDs. * @stable */ virtual UClassID getDynamicClassID(void) const = 0; protected: /** * Constructs a Calendar with the default time zone as returned by * TimeZone::createInstance(), and the default locale. * * @param success Indicates the status of Calendar object construction. Returns * U_ZERO_ERROR if constructed successfully. * @stable */ Calendar(UErrorCode& success); /** * Copy constructor * * @param source Calendar object to be copied from * @stable */ Calendar(const Calendar& source); /** * Default assignment operator * * @param right Calendar object to be copied * @stable */ Calendar& operator=(const Calendar& right); /** * Constructs a Calendar with the given time zone and locale. Clients are no longer * responsible for deleting the given time zone object after it's adopted. * * @param zone The given time zone. * @param aLocale The given locale. * @param success Indicates the status of Calendar object construction. Returns * U_ZERO_ERROR if constructed successfully. * @stable */ Calendar(TimeZone* zone, const Locale& aLocale, UErrorCode& success); /** * Constructs a Calendar with the given time zone and locale. * * @param zone The given time zone. * @param aLocale The given locale. * @param success Indicates the status of Calendar object construction. Returns * U_ZERO_ERROR if constructed successfully. * @stable */ Calendar(const TimeZone& zone, const Locale& aLocale, UErrorCode& success); /** * Converts Calendar's time field values to GMT as milliseconds. * * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @stable */ virtual void computeTime(UErrorCode& status) = 0; /** * Converts GMT as milliseconds to time field values. This allows you to sync up the * time field values with a new time that is set for the calendar. This method * does NOT recompute the time first; to recompute the time, then the fields, use * the method complete(). * * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @stable */ virtual void computeFields(UErrorCode& status) = 0; /** * Gets this Calendar's current time as a long. * * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @return the current time as UTC milliseconds from the epoch. * @stable */ double getTimeInMillis(UErrorCode& status) const; /** * Sets this Calendar's current time from the given long value. * @param millis the new time in UTC milliseconds from the epoch. * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @stable */ void setTimeInMillis( double millis, UErrorCode& status ); /** * Recomputes the current time from currently set fields, and then fills in any * unset fields in the time field list. * * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. * @stable */ void complete(UErrorCode& status); /** * Gets the value for a given time field. Subclasses can use this function to get * field values without forcing recomputation of time. * * @param field The given time field. * @return The value for the given time field. * @stable */ int32_t internalGet(EDateFields field) const {return fFields[field];} /** * Sets the value for a given time field. This is a fast internal method for * subclasses. It does not affect the areFieldsInSync, isTimeSet, or areAllFieldsSet * flags. * * @param field The given time field. * @param value The value for the given time field. * @stable */ void internalSet(EDateFields field, int32_t value); protected: /** * The flag which indicates if the current time is set in the calendar. * @stable */ UBool fIsTimeSet; /** * True if the fields are in sync with the currently set time of this Calendar. * If false, then the next attempt to get the value of a field will * force a recomputation of all fields from the current value of the time * field. *

* This should really be named areFieldsInSync, but the old name is retained * for backward compatibility. * @stable */ UBool fAreFieldsSet; /** * True if all of the fields have been set. This is initially false, and set to * true by computeFields(). * @stable */ UBool fAreAllFieldsSet; /** * Get the current time without recomputing. * * @return the current time without recomputing. * @stable */ UDate internalGetTime(void) const { return fTime; } /** * Set the current time without affecting flags or fields. * * @param time The time to be set * @return the current time without recomputing. * @stable */ void internalSetTime(UDate time) { fTime = time; } /** * The time fields containing values into which the millis is computed. * @stable */ int32_t fFields[FIELD_COUNT]; /** * The flags which tell if a specified time field for the calendar is set. * @stable */ UBool fIsSet[FIELD_COUNT]; /** Special values of stamp[] * @stable */ enum { kUnset = 0, kInternallySet, kMinimumUserStamp }; /** * Pseudo-time-stamps which specify when each field was set. There * are two special values, UNSET and INTERNALLY_SET. Values from * MINIMUM_USER_SET to Integer.MAX_VALUE are legal user set values. * @stable */ int32_t fStamp[FIELD_COUNT]; private: // The next available value for stampp[] int32_t fNextStamp;// = MINIMUM_USER_STAMP; /** * The current time set for the calendar. */ UDate fTime; /** * @see #setLenient */ UBool fLenient; /** * Time zone affects the time calculation done by Calendar. Calendar subclasses use * the time zone data to produce the local time. */ TimeZone* fZone; /** * Both firstDayOfWeek and minimalDaysInFirstWeek are locale-dependent. They are * used to figure out the week count for a specific date for a given locale. These * must be set when a Calendar is constructed. For example, in US locale, * firstDayOfWeek is SUNDAY; minimalDaysInFirstWeek is 1. They are used to figure * out the week count for a specific date for a given locale. These must be set when * a Calendar is constructed. */ EDaysOfWeek fFirstDayOfWeek; uint8_t fMinimalDaysInFirstWeek; /** * Sets firstDayOfWeek and minimalDaysInFirstWeek. Called at Calendar construction * time. * * @param desiredLocale The given locale. * @param success Indicates the status of setting the week count data from * the resource for the given locale. Returns U_ZERO_ERROR if * constructed successfully. */ void setWeekCountData(const Locale& desiredLocale, UErrorCode& success); /** * Recompute the time and update the status fields isTimeSet * and areFieldsSet. Callers should check isTimeSet and only * call this method if isTimeSet is false. * * @param status Output param set to success/failure code on exit. If any value * previously set in the time field is invalid or restricted by * leniency, this will be set to an error status. */ void updateTime(UErrorCode& status); /** * The resource tag for the resource where the week-count data is stored. */ static const char kDateTimeElements[]; }; // ------------------------------------- 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(EDateFields field, UBool up, UErrorCode& status) { roll(field, (int32_t)(up ? +1 : -1), status); } // ------------------------------------- /** * Fast method for subclasses. The caller must maintain fUserSetDSTOffset and * fUserSetZoneOffset, as well as the isSet[] array. */ inline void Calendar::internalSet(EDateFields field, int32_t value) { fFields[field] = value; } U_NAMESPACE_END #endif /* #if !UCONFIG_NO_FORMATTING */ #endif // _CALENDAR