X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/374ca955a76ecab1204ca8bfa63ff9238d998416..0f5d89e82340278ed3d7d50029f37cab2c41a57e:/icuSources/i18n/unicode/calendar.h diff --git a/icuSources/i18n/unicode/calendar.h b/icuSources/i18n/unicode/calendar.h index c9743587..e6689219 100644 --- a/icuSources/i18n/unicode/calendar.h +++ b/icuSources/i18n/unicode/calendar.h @@ -1,6 +1,8 @@ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html /* ******************************************************************************** -* Copyright (C) 1997-2004, International Business Machines +* Copyright (C) 1997-2014, International Business Machines * Corporation and others. All Rights Reserved. ******************************************************************************** * @@ -27,27 +29,29 @@ #include "unicode/utypes.h" +/** + * \file + * \brief C++ API: Calendar object + */ #if !UCONFIG_NO_FORMATTING #include "unicode/uobject.h" #include "unicode/locid.h" #include "unicode/timezone.h" #include "unicode/ucal.h" +#include "unicode/umisc.h" +#if U_SHOW_CPLUSPLUS_API U_NAMESPACE_BEGIN class ICUServiceFactory; -/** - * @internal - */ -typedef const void* URegistryKey; - /** * @internal */ typedef int32_t UFieldResolutionTable[12][8]; +class BasicTimeZone; /** * Calendar is an abstract base class for converting between * a UDate object and a set of integer fields such as @@ -85,11 +89,12 @@ typedef int32_t UFieldResolutionTable[12][8]; * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional). * *

- * When computing a UDate from time fields, two special circumstances + * When computing a UDate from time fields, some 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). + * there may be inconsistent information (such as "Tuesday, July 15, 1996" + * -- July 15, 1996 is actually a Monday), or the input time might be ambiguous + * because of time zone transition. * *

* Insufficient information. The calendar will use default @@ -124,6 +129,26 @@ typedef int32_t UFieldResolutionTable[12][8]; * \htmlonly\endhtmlonly * *

+ * Ambiguous Wall Clock Time. When time offset from UTC has + * changed, it produces an ambiguous time slot around the transition. For example, + * many US locations observe daylight saving time. On the date switching to daylight + * saving time in US, wall clock time jumps from 12:59 AM (standard) to 2:00 AM + * (daylight). Therefore, wall clock time from 1:00 AM to 1:59 AM do not exist on + * the date. When the input wall time fall into this missing time slot, the ICU + * Calendar resolves the time using the UTC offset before the transition by default. + * In this example, 1:30 AM is interpreted as 1:30 AM standard time (non-exist), + * so the final result will be 2:30 AM daylight time. + * + *

On the date switching back to standard time, wall clock time is moved back one + * hour at 2:00 AM. So wall clock time from 1:00 AM to 1:59 AM occur twice. In this + * case, the ICU Calendar resolves the time using the UTC offset after the transition + * by default. For example, 1:30 AM on the date is resolved as 1:30 AM standard time. + * + *

Ambiguous wall clock time resolution behaviors can be customized by Calendar APIs + * {@link #setRepeatedWallTimeOption} and {@link #setSkippedWallTimeOption}. + * These methods are available in ICU 49 or later versions. + * + *

* 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, @@ -160,6 +185,19 @@ typedef int32_t UFieldResolutionTable[12][8]; * For example, subtracting 5 days from the date September 12, 1996 * results in September 7, 1996. * + *

Supported range + * + *

The allowable range of Calendar has been + * narrowed. GregorianCalendar used to attempt to support + * the range of dates with millisecond values from + * Long.MIN_VALUE to Long.MAX_VALUE. + * The new Calendar protocol specifies the + * maximum range of supportable dates as those having Julian day numbers + * of -0x7F000000 to +0x7F000000. This + * corresponds to years from ~5,800,000 BCE to ~5,800,000 CE. Programmers + * should use the protected constants in Calendar to + * specify an extremely early or extremely late date.

+ * * @stable ICU 2.0 */ class U_I18N_API Calendar : public UObject { @@ -172,6 +210,13 @@ public: * @deprecated ICU 2.6. Use C enum UCalendarDateFields defined in ucal.h */ 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 @@ -192,9 +237,16 @@ public: 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 */ }; +#ifndef U_HIDE_DEPRECATED_API /** * 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 @@ -239,6 +291,7 @@ public: AM, PM }; +#endif /* U_HIDE_DEPRECATED_API */ /** * destructor @@ -325,7 +378,7 @@ public: * 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 zone The given timezone. * @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 @@ -333,7 +386,7 @@ public: * @return A Calendar if created successfully. NULL otherwise. * @stable ICU 2.0 */ - static Calendar* U_EXPORT2 createInstance(const TimeZone& zoneToAdopt, const Locale& aLocale, UErrorCode& success); + static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, const Locale& aLocale, UErrorCode& success); /** * Returns a list of the locales for which Calendars are installed. @@ -346,6 +399,26 @@ public: */ static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); + + /** + * Given a key and a locale, returns an array of string values in a preferred + * order that would make a difference. These are all and only those values where + * the open (creation) of the service with the locale formed from the input locale + * plus input keyword and that value has different behavior than creation with the + * input locale alone. + * @param key one of the keys supported by this service. For now, only + * "calendar" is supported. + * @param locale the locale + * @param commonlyUsed if set to true it will return only commonly used values + * with the given locale in preferred order. Otherwise, + * it will return all the available values for the locale. + * @param status ICU Error Code + * @return a string enumeration over keyword values for the given key and the locale. + * @stable ICU 4.2 + */ + static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* key, + const Locale& locale, UBool commonlyUsed, UErrorCode& status); + /** * Returns the current UTC (GMT) time measured in milliseconds since 0:00:00 on 1/1/70 * (derived from the system time). @@ -470,6 +543,9 @@ public: * 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. + * Adding a positive value always means moving forward in time, so for the Gregorian calendar, + * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces + * the numeric value of the field itself). * * @param field Specifies which date field to modify. * @param amount The amount of time to be added to the field, in the natural unit @@ -489,6 +565,9 @@ public: * 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. + * Adding a positive value always means moving forward in time, so for the Gregorian calendar, + * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces + * the numeric value of the field itself). * * @param field Specifies which date field to modify. * @param amount The amount of time to be added to the field, in the natural unit @@ -501,6 +580,7 @@ public: */ virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& status); +#ifndef U_HIDE_DEPRECATED_API /** * 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 @@ -509,10 +589,19 @@ public: * 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. + * 02/29/96. Rolling up always means rolling forward in time (unless the limit of the + * field is reached, in which case it may pin or wrap), so for Gregorian calendar, + * starting with 100 BC and rolling the year up results in 99 BC. + * When eras have a definite beginning and end (as in the Chinese calendar, or as in + * most eras in the Japanese calendar) then rolling the year past either limit of the + * era will cause the year to wrap around. When eras only have a limit at one end, + * then attempting to roll the year past that limit will result in pinning the year + * at that limit. Note that for most calendars in which era 0 years move forward in + * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to + * result in negative years for era 0 (that is the only way to represent years before + * the calendar epoch). + * 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. * @@ -525,6 +614,7 @@ public: * @deprecated ICU 2.6. Use roll(UCalendarDateFields field, UBool up, UErrorCode& status) instead. */ inline void roll(EDateFields field, UBool up, UErrorCode& status); +#endif /* U_HIDE_DEPRECATED_API */ /** * Time Field Rolling function. Rolls (up/down) a single unit of time on the given @@ -534,10 +624,19 @@ public: * 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. + * 02/29/96. Rolling up always means rolling forward in time (unless the limit of the + * field is reached, in which case it may pin or wrap), so for Gregorian calendar, + * starting with 100 BC and rolling the year up results in 99 BC. + * When eras have a definite beginning and end (as in the Chinese calendar, or as in + * most eras in the Japanese calendar) then rolling the year past either limit of the + * era will cause the year to wrap around. When eras only have a limit at one end, + * then attempting to roll the year past that limit will result in pinning the year + * at that limit. Note that for most calendars in which era 0 years move forward in + * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to + * result in negative years for era 0 (that is the only way to represent years before + * the calendar epoch). + * 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(UCalendarDateFields, int, UErrorCode&) instead. * @@ -557,10 +656,19 @@ public: * 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. + * 02/29/96. Rolling by a positive value always means rolling forward in time (unless + * the limit of the field is reached, in which case it may pin or wrap), so for + * Gregorian calendar, starting with 100 BC and rolling the year by + 1 results in 99 BC. + * When eras have a definite beginning and end (as in the Chinese calendar, or as in + * most eras in the Japanese calendar) then rolling the year past either limit of the + * era will cause the year to wrap around. When eras only have a limit at one end, + * then attempting to roll the year past that limit will result in pinning the year + * at that limit. Note that for most calendars in which era 0 years move forward in + * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to + * result in negative years for era 0 (that is the only way to represent years before + * the calendar epoch). + * 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 @@ -581,10 +689,19 @@ public: * 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. + * 02/29/96. Rolling by a positive value always means rolling forward in time (unless + * the limit of the field is reached, in which case it may pin or wrap), so for + * Gregorian calendar, starting with 100 BC and rolling the year by + 1 results in 99 BC. + * When eras have a definite beginning and end (as in the Chinese calendar, or as in + * most eras in the Japanese calendar) then rolling the year past either limit of the + * era will cause the year to wrap around. When eras only have a limit at one end, + * then attempting to roll the year past that limit will result in pinning the year + * at that limit. Note that for most calendars in which era 0 years move forward in + * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to + * result in negative years for era 0 (that is the only way to represent years before + * the calendar epoch). + * 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 @@ -784,6 +901,75 @@ public: */ UBool isLenient(void) const; + /** + * Sets the behavior for handling wall time repeating multiple times + * at negative time zone offset transitions. For example, 1:30 AM on + * November 6, 2011 in US Eastern time (Ameirca/New_York) occurs twice; + * 1:30 AM EDT, then 1:30 AM EST one hour later. When UCAL_WALLTIME_FIRST + * is used, the wall time 1:30AM in this example will be interpreted as 1:30 AM EDT + * (first occurrence). When UCAL_WALLTIME_LAST is used, it will be + * interpreted as 1:30 AM EST (last occurrence). The default value is + * UCAL_WALLTIME_LAST. + *

+ * Note:When UCAL_WALLTIME_NEXT_VALID is not a valid + * option for this. When the argument is neither UCAL_WALLTIME_FIRST + * nor UCAL_WALLTIME_LAST, this method has no effect and will keep + * the current setting. + * + * @param option the behavior for handling repeating wall time, either + * UCAL_WALLTIME_FIRST or UCAL_WALLTIME_LAST. + * @see #getRepeatedWallTimeOption + * @stable ICU 49 + */ + void setRepeatedWallTimeOption(UCalendarWallTimeOption option); + + /** + * Gets the behavior for handling wall time repeating multiple times + * at negative time zone offset transitions. + * + * @return the behavior for handling repeating wall time, either + * UCAL_WALLTIME_FIRST or UCAL_WALLTIME_LAST. + * @see #setRepeatedWallTimeOption + * @stable ICU 49 + */ + UCalendarWallTimeOption getRepeatedWallTimeOption(void) const; + + /** + * Sets the behavior for handling skipped wall time at positive time zone offset + * transitions. For example, 2:30 AM on March 13, 2011 in US Eastern time (America/New_York) + * does not exist because the wall time jump from 1:59 AM EST to 3:00 AM EDT. When + * UCAL_WALLTIME_FIRST is used, 2:30 AM is interpreted as 30 minutes before 3:00 AM + * EDT, therefore, it will be resolved as 1:30 AM EST. When UCAL_WALLTIME_LAST + * is used, 2:30 AM is interpreted as 31 minutes after 1:59 AM EST, therefore, it will be + * resolved as 3:30 AM EDT. When UCAL_WALLTIME_NEXT_VALID is used, 2:30 AM will + * be resolved as next valid wall time, that is 3:00 AM EDT. The default value is + * UCAL_WALLTIME_LAST. + *

+ * Note:This option is effective only when this calendar is lenient. + * When the calendar is strict, such non-existing wall time will cause an error. + * + * @param option the behavior for handling skipped wall time at positive time zone + * offset transitions, one of UCAL_WALLTIME_FIRST, UCAL_WALLTIME_LAST and + * UCAL_WALLTIME_NEXT_VALID. + * @see #getSkippedWallTimeOption + * + * @stable ICU 49 + */ + void setSkippedWallTimeOption(UCalendarWallTimeOption option); + + /** + * Gets the behavior for handling skipped wall time at positive time zone offset + * transitions. + * + * @return the behavior for handling skipped wall time, one of + * UCAL_WALLTIME_FIRST, UCAL_WALLTIME_LAST + * and UCAL_WALLTIME_NEXT_VALID. + * @see #setSkippedWallTimeOption + * @stable ICU 49 + */ + UCalendarWallTimeOption getSkippedWallTimeOption(void) const; + +#ifndef U_HIDE_DEPRECATED_API /** * Sets what the first day of the week is; e.g., Sunday in US, Monday in France. * @@ -791,6 +977,7 @@ public: * @deprecated ICU 2.6. Use setFirstDayOfWeek(UCalendarDaysOfWeek value) instead. */ void setFirstDayOfWeek(EDaysOfWeek value); +#endif /* U_HIDE_DEPRECATED_API */ /** * Sets what the first day of the week is; e.g., Sunday in US, Monday in France. @@ -800,6 +987,7 @@ public: */ void setFirstDayOfWeek(UCalendarDaysOfWeek value); +#ifndef U_HIDE_DEPRECATED_API /** * Gets what the first day of the week is; e.g., Sunday in US, Monday in France. * @@ -807,6 +995,7 @@ public: * @deprecated ICU 2.6 use the overload with error code */ EDaysOfWeek getFirstDayOfWeek(void) const; +#endif /* U_HIDE_DEPRECATED_API */ /** * Gets what the first day of the week is; e.g., Sunday in US, Monday in France. @@ -919,6 +1108,7 @@ public: */ virtual int32_t getLeastMaximum(UCalendarDateFields field) const; +#ifndef U_HIDE_DEPRECATED_API /** * 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(). @@ -934,6 +1124,7 @@ public: * @deprecated ICU 2.6. Use getActualMinimum(UCalendarDateFields field, UErrorCode& status) instead. */ int32_t getActualMinimum(EDateFields field, UErrorCode& status) const; +#endif /* U_HIDE_DEPRECATED_API */ /** * Return the minimum value that this field could have, given the current date. @@ -949,8 +1140,9 @@ public: * @return the minimum of the given field for the current date of this Calendar * @stable ICU 2.6. */ - int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& status) const; + virtual int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& status) const; +#ifndef U_HIDE_DEPRECATED_API /** * 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 @@ -968,6 +1160,7 @@ public: * @deprecated ICU 2.6. Use getActualMaximum(UCalendarDateFields field, UErrorCode& status) instead. */ int32_t getActualMaximum(EDateFields field, UErrorCode& status) const; +#endif /* U_HIDE_DEPRECATED_API */ /** * Return the maximum value that this field could have, given the current date. @@ -985,8 +1178,9 @@ public: * @return the maximum of the given field for the current date of this Calendar * @stable ICU 2.6. */ - int32_t getActualMaximum(UCalendarDateFields field, UErrorCode& status) const; + virtual int32_t getActualMaximum(UCalendarDateFields field, UErrorCode& status) const; +#ifndef U_HIDE_DEPRECATED_API /** * 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 @@ -1001,6 +1195,7 @@ public: * @deprecated ICU 2.6. Use get(UCalendarDateFields field, UErrorCode& status) instead. */ int32_t get(EDateFields field, UErrorCode& status) const; +#endif /* U_HIDE_DEPRECATED_API */ /** * Gets the value for a given time field. Recalculate the current time field values @@ -1017,6 +1212,7 @@ public: */ int32_t get(UCalendarDateFields field, UErrorCode& status) const; +#ifndef U_HIDE_DEPRECATED_API /** * 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. @@ -1026,6 +1222,7 @@ public: * @deprecated ICU 2.6. Use isSet(UCalendarDateFields field) instead. */ UBool isSet(EDateFields field) const; +#endif /* U_HIDE_DEPRECATED_API */ /** * Determines if the given time field has a value set. This can affect in the @@ -1037,6 +1234,7 @@ public: */ UBool isSet(UCalendarDateFields field) const; +#ifndef U_HIDE_DEPRECATED_API /** * Sets the given time field with the given value. * @@ -1045,6 +1243,7 @@ public: * @deprecated ICU 2.6. Use set(UCalendarDateFields field, int32_t value) instead. */ void set(EDateFields field, int32_t value); +#endif /* U_HIDE_DEPRECATED_API */ /** * Sets the given time field with the given value. @@ -1098,12 +1297,22 @@ public: /** * 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. + * them a value of zero (except for era in some cases, see below). The field values + * will be determined during the next resolving of time into time fields. + * + * This effectively results in the following: + * 1. Gregorian-like calendars (gregorian, iso8601, japanese, buddhist, roc) are set + * to a UDate value of 0, corresponding to the epoch date of gregorian + * January 1, 1970 CE at UTC 00:00:00. + * 2. Other calendars are set to the beginning of the first day of the first month of + * the current era. Note that for the chinese and dangi calendars, the era + * corresponds to the current 60-year stem-branch cycle, so there is a new era + * every 60 years. The current era began on gregorian February 2, 1984. * @stable ICU 2.0 */ void clear(void); +#ifndef U_HIDE_DEPRECATED_API /** * 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 @@ -1113,6 +1322,7 @@ public: * @deprecated ICU 2.6. Use clear(UCalendarDateFields field) instead. */ void clear(EDateFields field); +#endif /* U_HIDE_DEPRECATED_API */ /** * Clears the value in the given time field, both making it unset and assigning it a @@ -1142,15 +1352,93 @@ public: virtual UClassID getDynamicClassID(void) const = 0; /** - * Returns the resource key string used for this calendar type. - * For example, prepending "Eras_" to this string could return "Eras_japanese" - * or "Eras_gregorian". - * - * @returns static string, for example, "gregorian" or "japanese" - * @internal + * Returns the calendar type name string for this Calendar object. + * The returned string is the legacy ICU calendar attribute value, + * for example, "gregorian" or "japanese". + * + * See type="old type name" for the calendar attribute of locale IDs + * at http://www.unicode.org/reports/tr35/#Key_Type_Definitions + * + * Sample code for getting the LDML/BCP 47 calendar key value: + * \code + * const char *calType = cal->getType(); + * if (0 == strcmp(calType, "unknown")) { + * // deal with unknown calendar type + * } else { + * string localeID("root@calendar="); + * localeID.append(calType); + * char langTag[100]; + * UErrorCode errorCode = U_ZERO_ERROR; + * int32_t length = uloc_toLanguageTag(localeID.c_str(), langTag, (int32_t)sizeof(langTag), TRUE, &errorCode); + * if (U_FAILURE(errorCode)) { + * // deal with errors & overflow + * } + * string lang(langTag, length); + * size_t caPos = lang.find("-ca-"); + * lang.erase(0, caPos + 4); + * // lang now contains the LDML calendar type + * } + * \endcode + * + * @return legacy calendar type name string + * @stable ICU 49 */ virtual const char * getType() const = 0; + /** + * Returns whether the given day of the week is a weekday, a weekend day, + * or a day that transitions from one to the other, for the locale and + * calendar system associated with this Calendar (the locale's region is + * often the most determinant factor). If a transition occurs at midnight, + * then the days before and after the transition will have the + * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time + * other than midnight, then the day of the transition will have + * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the + * method getWeekendTransition() will return the point of + * transition. + * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY). + * @param status The error code for the operation. + * @return The UCalendarWeekdayType for the day of the week. + * @stable ICU 4.4 + */ + virtual UCalendarWeekdayType getDayOfWeekType(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const; + + /** + * Returns the time during the day at which the weekend begins or ends in + * this calendar system. If getDayOfWeekType() returns UCAL_WEEKEND_ONSET + * for the specified dayOfWeek, return the time at which the weekend begins. + * If getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek, + * return the time at which the weekend ends. If getDayOfWeekType() returns + * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition + * (U_ILLEGAL_ARGUMENT_ERROR). + * @param dayOfWeek The day of the week for which the weekend transition time is + * desired (UCAL_SUNDAY..UCAL_SATURDAY). + * @param status The error code for the operation. + * @return The milliseconds after midnight at which the weekend begins or ends. + * @stable ICU 4.4 + */ + virtual int32_t getWeekendTransition(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const; + + /** + * Returns TRUE if the given UDate is in the weekend in + * this calendar system. + * @param date The UDate in question. + * @param status The error code for the operation. + * @return TRUE if the given UDate is in the weekend in + * this calendar system, FALSE otherwise. + * @stable ICU 4.4 + */ + virtual UBool isWeekend(UDate date, UErrorCode &status) const; + + /** + * Returns TRUE if this Calendar's current date-time is in the weekend in + * this calendar system. + * @return TRUE if this Calendar's current date-time is in the weekend in + * this calendar system, FALSE otherwise. + * @stable ICU 4.4 + */ + virtual UBool isWeekend(void) const; + protected: /** @@ -1257,6 +1545,7 @@ protected: */ void complete(UErrorCode& status); +#ifndef U_HIDE_DEPRECATED_API /** * Gets the value for a given time field. Subclasses can use this function to get * field values without forcing recomputation of time. @@ -1266,7 +1555,9 @@ protected: * @deprecated ICU 2.6. Use internalGet(UCalendarDateFields field) instead. */ inline int32_t internalGet(EDateFields field) const {return fFields[field];} +#endif /* U_HIDE_DEPRECATED_API */ +#ifndef U_HIDE_INTERNAL_API /** * Gets the value for a given time field. Subclasses can use this function to get * field values without forcing recomputation of time. If the field's stamp is UNSET, @@ -1288,7 +1579,9 @@ protected: * @internal */ inline int32_t internalGet(UCalendarDateFields field) const {return fFields[field];} +#endif /* U_HIDE_INTERNAL_API */ +#ifndef U_HIDE_DEPRECATED_API /** * 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 @@ -1299,6 +1592,7 @@ protected: * @deprecated ICU 2.6. Use internalSet(UCalendarDateFields field, int32_t value) instead. */ void internalSet(EDateFields field, int32_t value); +#endif /* U_HIDE_DEPRECATED_API */ /** * Sets the value for a given time field. This is a fast internal method for @@ -1324,11 +1618,13 @@ protected: * @internal */ 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 */ }; /** @@ -1424,11 +1720,22 @@ protected: * (YEAR_WOY and WEEK_OF_YEAR) to an extended year in the case * where YEAR, EXTENDED_YEAR are not set. * The Calendar implementation assumes yearWoy is in extended gregorian form - * @internal * @return the extended year, UCAL_EXTENDED_YEAR + * @internal */ virtual int32_t handleGetExtendedYearFromWeekFields(int32_t yearWoy, int32_t woy); + /** + * Validate a single field of this calendar. Subclasses should + * override this method to validate any calendar-specific fields. + * Generic fields can be handled by + * Calendar::validateField(). + * @see #validateField(int, int, int, int&) + * @internal + */ + virtual void validateField(UCalendarDateFields field, UErrorCode &status); + +#ifndef U_HIDE_INTERNAL_API /** * Compute the Julian day from fields. Will determine whether to use * the JULIAN_DAY field directly, or other fields. @@ -1444,7 +1751,7 @@ protected: * reflects local zone wall time. * @internal */ - int32_t computeMillisInDay(); + double computeMillisInDay(); /** * This method can assume EXTENDED_YEAR has been set. @@ -1455,7 +1762,7 @@ protected: * when this function fails. * @internal */ - int32_t computeZoneOffset(double millis, int32_t millisInDay, UErrorCode &ec); + int32_t computeZoneOffset(double millis, double millisInDay, UErrorCode &ec); /** @@ -1529,6 +1836,7 @@ protected: * @internal */ UCalendarDateFields resolveFields(const UFieldResolutionTable *precedenceTable); +#endif /* U_HIDE_INTERNAL_API */ /** @@ -1536,12 +1844,14 @@ protected: */ virtual const UFieldResolutionTable* getFieldResolutionTable() const; +#ifndef U_HIDE_INTERNAL_API /** * Return the field that is newer, either defaultField, or * alternateField. If neither is newer or neither is set, return defaultField. * @internal */ UCalendarDateFields newerField(UCalendarDateFields defaultField, UCalendarDateFields alternateField) const; +#endif /* U_HIDE_INTERNAL_API */ private: @@ -1587,7 +1897,7 @@ protected: * computed. This occurs only in setTimeInMillis(). A calendar set * to this state will compute all fields from the time if it becomes * necessary, but otherwise will delay such computation. - * @draft ICU 3.0 + * @stable ICU 3.0 */ UBool fAreFieldsVirtuallySet; @@ -1663,10 +1973,10 @@ protected: */ virtual void handleComputeFields(int32_t julianDay, UErrorCode &status); +#ifndef U_HIDE_INTERNAL_API /** * Return the extended year on the Gregorian calendar as computed by * computeGregorianFields(). - * @see #computeGregorianFields * @internal */ int32_t getGregorianYear() const { @@ -1676,7 +1986,6 @@ protected: /** * Return the month (0-based) on the Gregorian calendar as computed by * computeGregorianFields(). - * @see #computeGregorianFields * @internal */ int32_t getGregorianMonth() const { @@ -1686,7 +1995,6 @@ protected: /** * Return the day of year (1-based) on the Gregorian calendar as * computed by computeGregorianFields(). - * @see #computeGregorianFields * @internal */ int32_t getGregorianDayOfYear() const { @@ -1696,28 +2004,30 @@ protected: /** * Return the day of month (1-based) on the Gregorian calendar as * computed by computeGregorianFields(). - * @see #computeGregorianFields * @internal */ int32_t getGregorianDayOfMonth() const { return fGregorianDayOfMonth; } +#endif /* U_HIDE_INTERNAL_API */ /** * Called by computeJulianDay. Returns the default month (0-based) for the year, * taking year and era into account. Defaults to 0 for Gregorian, which doesn't care. - * @internal + * @param eyear The extended year * @internal */ - virtual int32_t getDefaultMonthInYear() ; + virtual int32_t getDefaultMonthInYear(int32_t eyear) ; /** * Called by computeJulianDay. Returns the default day (1-based) for the month, * taking currently-set year and era into account. Defaults to 1 for Gregorian. + * @param eyear the extended year + * @param month the month in the year * @internal */ - virtual int32_t getDefaultDayInMonth(int32_t /*month*/); + virtual int32_t getDefaultDayInMonth(int32_t eyear, int32_t month); //------------------------------------------------------------------------- // Protected utility methods for use by subclasses. These are very handy @@ -1796,11 +2106,12 @@ protected: * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} * is more than one. * - * @draft ICU 2.8 + * @stable ICU 2.8 */ int32_t weekNumber(int32_t desiredDay, int32_t dayOfPeriod, int32_t dayOfWeek); +#ifndef U_HIDE_INTERNAL_API /** * Return the week number of a day, within a period. This may be the week number in * a year, or the week number in a month. Usually this will be a value >= 1, but if @@ -1838,6 +2149,7 @@ protected: * @internal */ int32_t getLocalDOW(); +#endif /* U_HIDE_INTERNAL_API */ private: @@ -1846,6 +2158,12 @@ private: */ int32_t fNextStamp;// = MINIMUM_USER_STAMP; + /** + * Recalculates the time stamp array (fStamp). + * Resets fNextStamp to lowest next stamp value. + */ + void recalculateStamp(); + /** * The current time set for the calendar. */ @@ -1858,10 +2176,22 @@ private: /** * Time zone affects the time calculation done by Calendar. Calendar subclasses use - * the time zone data to produce the local time. + * the time zone data to produce the local time. Always set; never NULL. */ TimeZone* fZone; + /** + * Option for rpeated wall time + * @see #setRepeatedWallTimeOption + */ + UCalendarWallTimeOption fRepeatedWallTime; + + /** + * Option for skipped wall time + * @see #setSkippedWallTimeOption + */ + UCalendarWallTimeOption fSkippedWallTime; + /** * 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 @@ -1872,6 +2202,10 @@ private: */ UCalendarDaysOfWeek fFirstDayOfWeek; uint8_t fMinimalDaysInFirstWeek; + UCalendarDaysOfWeek fWeekendOnset; + int32_t fWeekendOnsetMillis; + UCalendarDaysOfWeek fWeekendCease; + int32_t fWeekendCeaseMillis; /** * Sets firstDayOfWeek and minimalDaysInFirstWeek. Called at Calendar construction @@ -1883,7 +2217,7 @@ private: * the resource for the given locale. Returns U_ZERO_ERROR if * constructed successfully. */ - void setWeekCountData(const Locale& desiredLocale, const char *type, UErrorCode& success); + void setWeekData(const Locale& desiredLocale, const char *type, UErrorCode& success); /** * Recompute the time and update the status fields isTimeSet @@ -1896,38 +2230,31 @@ private: */ void updateTime(UErrorCode& status); - /** - * The resource tag for the resource where the week-count data is stored. - */ - static const char kDateTimeElements[]; - - /** - * The resource tag where the default calendar is stored. - */ - static const char kDefaultCalendar[]; - - /** * The Gregorian year, as computed by computeGregorianFields() and * returned by getGregorianYear(). + * @see #computeGregorianFields */ int32_t fGregorianYear; /** * The Gregorian month, as computed by computeGregorianFields() and * returned by getGregorianMonth(). + * @see #computeGregorianFields */ int32_t fGregorianMonth; /** * The Gregorian day of the year, as computed by * computeGregorianFields() and returned by getGregorianDayOfYear(). + * @see #computeGregorianFields */ int32_t fGregorianDayOfYear; /** * The Gregorian day of the month, as computed by * computeGregorianFields() and returned by getGregorianDayOfMonth(). + * @see #computeGregorianFields */ int32_t fGregorianDayOfMonth; @@ -1941,18 +2268,19 @@ private: */ void computeGregorianAndDOWFields(int32_t julianDay, UErrorCode &ec); +protected: + /** * Compute the Gregorian calendar year, month, and day of month from the * Julian day. These values are not stored in fields, but in member * variables gregorianXxx. They are used for time zone computations and by * subclasses that are Gregorian derivatives. Subclasses may call this * method to perform a Gregorian calendar millis->fields computation. - * To perform a Gregorian calendar fields->millis computation, call - * computeGregorianMonthStart(). - * @see #computeGregorianMonthStart */ void computeGregorianFields(int32_t julianDay, UErrorCode &ec); +private: + /** * Compute the fields WEEK_OF_YEAR, YEAR_WOY, WEEK_OF_MONTH, * DAY_OF_WEEK_IN_MONTH, and DOW_LOCAL from EXTENDED_YEAR, YEAR, @@ -1986,16 +2314,6 @@ private: */ void validateFields(UErrorCode &status); - /** - * Validate a single field of this calendar. Subclasses should - * override this method to validate any calendar-specific fields. - * Generic fields can be handled by - * Calendar.validateField(). - * @see #validateField(int, int, int, int&) - * @internal - */ - virtual void validateField(UCalendarDateFields field, UErrorCode &status); - /** * Validate a single field of this calendar given its minimum and * maximum allowed value. If the field is out of range, @@ -2007,6 +2325,7 @@ private: void validateField(UCalendarDateFields field, int32_t min, int32_t max, UErrorCode& status); protected: +#ifndef U_HIDE_INTERNAL_API /** * Convert a quasi Julian date to the day of the week. The Julian date used here is * not a true Julian date, since it is measured from midnight, not noon. Return @@ -2017,6 +2336,7 @@ private: * @internal */ static uint8_t julianDayToDayOfWeek(double julian); +#endif /* U_HIDE_INTERNAL_API */ private: char validLocale[ULOC_FULLNAME_CAPACITY]; @@ -2028,6 +2348,7 @@ private: * INTERNAL FOR 2.6 -- Registration. */ +#ifndef U_HIDE_INTERNAL_API /** * Return a StringEnumeration over the locales available at the time of the call, * including registered locales. @@ -2039,6 +2360,11 @@ private: /** * Register a new Calendar factory. The factory will be adopted. * INTERNAL in 2.6 + * + * Because ICU may choose to cache Calendars internally, this must + * be called at application startup, prior to any calls to + * Calendar::createInstance to avoid undefined behavior. + * * @param toAdopt the factory instance to be adopted * @param status the in/out status code, no special meanings are assigned * @return a registry key that can be used to unregister this factory @@ -2051,12 +2377,18 @@ private: * register call. Key becomes invalid after a successful call and should not be used again. * The CalendarFactory corresponding to the key will be deleted. * INTERNAL in 2.6 + * + * Because ICU may choose to cache Calendars internally, this should + * be called during application shutdown, after all calls to + * Calendar::createInstance to avoid undefined behavior. + * * @param key the registry key returned by a previous call to registerFactory * @param status the in/out status code, no special meanings are assigned * @return TRUE if the factory for the key was successfully unregistered * @internal */ static UBool unregister(URegistryKey key, UErrorCode& status); +#endif /* U_HIDE_INTERNAL_API */ /** * Multiple Calendar Implementation @@ -2078,19 +2410,19 @@ private: #endif /* !UCONFIG_NO_SERVICE */ /** - * @internal * @return TRUE if this calendar has a default century (i.e. 03 -> 2003) + * @internal */ virtual UBool haveDefaultCentury() const = 0; /** - * @internal * @return the start of the default century, as a UDate + * @internal */ virtual UDate defaultCenturyStart() const = 0; /** - * @internal * @return the beginning year of the default century, as a year + * @internal */ virtual int32_t defaultCenturyStartYear() const = 0; @@ -2098,10 +2430,25 @@ private: * @param type type of the locale we're looking for (valid or actual) * @param status error code for the operation * @return the locale - * @draft ICU 2.8 likely to change in ICU 3.0, based on feedback + * @stable ICU 2.8 */ Locale getLocale(ULocDataLocaleType type, UErrorCode &status) const; + /** + * @return The related Gregorian year; will be obtained by modifying the value + * obtained by get from UCAL_EXTENDED_YEAR field + * @internal + */ + virtual int32_t getRelatedYear(UErrorCode &status) const; + + /** + * @param year The related Gregorian year to set; will be modified as necessary then + * set in UCAL_EXTENDED_YEAR field + * @internal + */ + virtual void setRelatedYear(int32_t year); + +#ifndef U_HIDE_INTERNAL_API /** Get the locale for this calendar object. You can choose between valid and actual locale. * @param type type of the locale we're looking for (valid or actual) * @param status error code for the operation @@ -2109,7 +2456,53 @@ private: * @internal */ const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const; +#endif /* U_HIDE_INTERNAL_API */ + +private: + /** + * Cast TimeZone used by this object to BasicTimeZone, or NULL if the TimeZone + * is not an instance of BasicTimeZone. + */ + BasicTimeZone* getBasicTimeZone() const; + /** + * Find the previous zone transtion near the given time. + * @param base The base time, inclusive + * @param transitionTime Receives the result time + * @param status The error status + * @return TRUE if a transition is found. + */ + UBool getImmediatePreviousZoneTransition(UDate base, UDate *transitionTime, UErrorCode& status) const; + +public: +#ifndef U_HIDE_INTERNAL_API + /** + * Creates a new Calendar from a Locale for the cache. + * This method does not set the time or timezone in returned calendar. + * @param locale the locale. + * @param status any error returned here. + * @return the new Calendar object with no time or timezone set. + * @internal For ICU use only. + */ + static Calendar * U_EXPORT2 makeInstance( + const Locale &locale, UErrorCode &status); + + /** + * Get the calendar type for given locale. + * @param locale the locale + * @param typeBuffer calendar type returned here + * @param typeBufferSize The size of typeBuffer in bytes. If the type + * can't fit in the buffer, this method sets status to + * U_BUFFER_OVERFLOW_ERROR + * @param status error, if any, returned here. + * @internal For ICU use only. + */ + static void U_EXPORT2 getCalendarTypeFromLocale( + const Locale &locale, + char *typeBuffer, + int32_t typeBufferSize, + UErrorCode &status); +#endif /* U_HIDE_INTERNAL_API */ }; // ------------------------------------- @@ -2129,11 +2522,13 @@ 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 */ // ------------------------------------- @@ -2151,19 +2546,16 @@ Calendar::internalSet(UCalendarDateFields field, int32_t value) fIsSet[field] = TRUE; // Remove later } -inline void -Calendar::internalSet(EDateFields field, int32_t value) -{ - internalSet((UCalendarDateFields) field, value); -} +#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 // U_SHOW_CPLUSPLUS_API #endif /* #if !UCONFIG_NO_FORMATTING */