* 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} + * runtime. Use {@link icu::DateFormat} * to format dates. * *
@@ -137,6 +142,12 @@
* @stable ICU 2.0
*/
+/**
+ * The time zone ID reserved for unknown time zone.
+ * @stable ICU 4.8
+ */
+#define UCAL_UNKNOWN_ZONE_ID "Etc/Unknown"
+
/** A calendar.
* For usage in C programs.
* @stable ICU 2.0
@@ -147,9 +158,21 @@ typedef void* UCalendar;
* @stable ICU 2.0
*/
enum UCalendarType {
- /** A traditional calendar for the locale */
+ /**
+ * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar,
+ * which may be the Gregorian calendar or some other calendar.
+ * @stable ICU 2.0
+ */
UCAL_TRADITIONAL,
- /** The Gregorian calendar */
+ /**
+ * A better name for UCAL_TRADITIONAL.
+ * @stable ICU 4.2
+ */
+ UCAL_DEFAULT = UCAL_TRADITIONAL,
+ /**
+ * Unambiguously designates the Gregorian calendar for the locale.
+ * @stable ICU 2.0
+ */
UCAL_GREGORIAN
};
@@ -161,135 +184,264 @@ typedef enum UCalendarType UCalendarType;
*/
enum UCalendarDateFields {
/**
- * Era field
+ * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar.
+ * This is a calendar-specific value.
* @stable ICU 2.6
*/
UCAL_ERA,
+
/**
- * Year field
+ * Field number indicating the year. This is a calendar-specific value.
* @stable ICU 2.6
*/
UCAL_YEAR,
+
/**
- * Month field
+ * Field number indicating the month. This is a calendar-specific value.
+ * The first month of the year is
+ * JANUARY; the last depends on the number of months in a year.
+ * @see #UCAL_JANUARY
+ * @see #UCAL_FEBRUARY
+ * @see #UCAL_MARCH
+ * @see #UCAL_APRIL
+ * @see #UCAL_MAY
+ * @see #UCAL_JUNE
+ * @see #UCAL_JULY
+ * @see #UCAL_AUGUST
+ * @see #UCAL_SEPTEMBER
+ * @see #UCAL_OCTOBER
+ * @see #UCAL_NOVEMBER
+ * @see #UCAL_DECEMBER
+ * @see #UCAL_UNDECIMBER
* @stable ICU 2.6
*/
UCAL_MONTH,
+
/**
- * Week of year field
+ * Field number indicating the
+ * week number within the current year. The first week of the year, as
+ * defined by UCAL_FIRST_DAY_OF_WEEK and UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
+ * attributes, has value 1. Subclasses define
+ * the value of UCAL_WEEK_OF_YEAR for days before the first week of
+ * the year.
+ * @see ucal_getAttribute
+ * @see ucal_setAttribute
* @stable ICU 2.6
*/
UCAL_WEEK_OF_YEAR,
- /**
- * Week of month field
+
+ /**
+ * Field number indicating the
+ * week number within the current month. The first week of the month, as
+ * defined by UCAL_FIRST_DAY_OF_WEEK and UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
+ * attributes, has value 1. Subclasses define
+ * the value of WEEK_OF_MONTH for days before the first week of
+ * the month.
+ * @see ucal_getAttribute
+ * @see ucal_setAttribute
+ * @see #UCAL_FIRST_DAY_OF_WEEK
+ * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
* @stable ICU 2.6
*/
UCAL_WEEK_OF_MONTH,
- /**
- * Date field
+
+ /**
+ * Field number indicating the
+ * day of the month. This is a synonym for DAY_OF_MONTH.
+ * The first day of the month has value 1.
+ * @see #UCAL_DAY_OF_MONTH
* @stable ICU 2.6
*/
UCAL_DATE,
- /**
- * Day of year field
+
+ /**
+ * Field number indicating the day
+ * number within the current year. The first day of the year has value 1.
* @stable ICU 2.6
*/
UCAL_DAY_OF_YEAR,
- /**
- * Day of week field
+
+ /**
+ * Field number indicating the day
+ * of the week. This field takes values SUNDAY,
+ * MONDAY, TUESDAY, WEDNESDAY,
+ * THURSDAY, FRIDAY, and SATURDAY.
+ * @see #UCAL_SUNDAY
+ * @see #UCAL_MONDAY
+ * @see #UCAL_TUESDAY
+ * @see #UCAL_WEDNESDAY
+ * @see #UCAL_THURSDAY
+ * @see #UCAL_FRIDAY
+ * @see #UCAL_SATURDAY
* @stable ICU 2.6
*/
UCAL_DAY_OF_WEEK,
- /**
- * Day of week in month field
+
+ /**
+ * Field number indicating the
+ * ordinal number of the day of the week within the current month. Together
+ * with the DAY_OF_WEEK field, this uniquely specifies a day
+ * within a month. Unlike WEEK_OF_MONTH and
+ * WEEK_OF_YEAR, this field's value does not depend on
+ * getFirstDayOfWeek() or
+ * getMinimalDaysInFirstWeek(). DAY_OF_MONTH 1
+ * through 7 always correspond to DAY_OF_WEEK_IN_MONTH
+ * 1; 8 through 15 correspond to
+ * DAY_OF_WEEK_IN_MONTH 2, and so on.
+ * DAY_OF_WEEK_IN_MONTH 0 indicates the week before
+ * DAY_OF_WEEK_IN_MONTH 1. Negative values count back from the
+ * end of the month, so the last Sunday of a month is specified as
+ * DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1. Because
+ * negative values count backward they will usually be aligned differently
+ * within the month than positive values. For example, if a month has 31
+ * days, DAY_OF_WEEK_IN_MONTH -1 will overlap
+ * DAY_OF_WEEK_IN_MONTH 5 and the end of 4.
+ * @see #UCAL_DAY_OF_WEEK
+ * @see #UCAL_WEEK_OF_MONTH
* @stable ICU 2.6
*/
UCAL_DAY_OF_WEEK_IN_MONTH,
- /**
- * AM/PM field
+
+ /**
+ * Field number indicating
+ * whether the HOUR is before or after noon.
+ * E.g., at 10:04:15.250 PM the AM_PM is PM.
+ * @see #UCAL_AM
+ * @see #UCAL_PM
+ * @see #UCAL_HOUR
* @stable ICU 2.6
*/
UCAL_AM_PM,
- /**
- * Hour field
+
+ /**
+ * Field number indicating the
+ * hour of the morning or afternoon. HOUR is used for the 12-hour
+ * clock.
+ * E.g., at 10:04:15.250 PM the HOUR is 10.
+ * @see #UCAL_AM_PM
+ * @see #UCAL_HOUR_OF_DAY
* @stable ICU 2.6
*/
UCAL_HOUR,
- /**
- * Hour of day field
+
+ /**
+ * Field number indicating the
+ * hour of the day. HOUR_OF_DAY is used for the 24-hour clock.
+ * E.g., at 10:04:15.250 PM the HOUR_OF_DAY is 22.
+ * @see #UCAL_HOUR
* @stable ICU 2.6
*/
UCAL_HOUR_OF_DAY,
- /**
- * Minute field
+
+ /**
+ * Field number indicating the
+ * minute within the hour.
+ * E.g., at 10:04:15.250 PM the UCAL_MINUTE is 4.
* @stable ICU 2.6
*/
UCAL_MINUTE,
- /**
- * Second field
+
+ /**
+ * Field number indicating the
+ * second within the minute.
+ * E.g., at 10:04:15.250 PM the UCAL_SECOND is 15.
* @stable ICU 2.6
*/
UCAL_SECOND,
- /**
- * Millisecond field
+
+ /**
+ * Field number indicating the
+ * millisecond within the second.
+ * E.g., at 10:04:15.250 PM the UCAL_MILLISECOND is 250.
* @stable ICU 2.6
*/
UCAL_MILLISECOND,
- /**
- * Zone offset field
+
+ /**
+ * Field number indicating the
+ * raw offset from GMT in milliseconds.
* @stable ICU 2.6
*/
UCAL_ZONE_OFFSET,
- /**
- * DST offset field
+
+ /**
+ * Field number indicating the
+ * daylight savings offset in milliseconds.
* @stable ICU 2.6
*/
UCAL_DST_OFFSET,
- /**
- * Year / week of year
+
+ /**
+ * Field number
+ * indicating the extended year corresponding to the
+ * UCAL_WEEK_OF_YEAR field. This may be one greater or less
+ * than the value of UCAL_EXTENDED_YEAR.
* @stable ICU 2.6
*/
UCAL_YEAR_WOY,
- /**
- * Day of week, localized (1..7)
+
+ /**
+ * Field number
+ * indicating the localized day of week. This will be a value from 1
+ * to 7 inclusive, with 1 being the localized first day of the week.
* @stable ICU 2.6
*/
-#ifndef U_HIDE_DRAFT_API
-
UCAL_DOW_LOCAL,
+
/**
- * Year of this calendar system, encompassing all supra-year fields. For example, in Gregorian/Julian calendars, positive Extended Year values indicate years AD, 1 BC = 0 extended, 2 BC = -1 extended, and so on.
- * @draft ICU 2.8
+ * Year of this calendar system, encompassing all supra-year fields. For example,
+ * in Gregorian/Julian calendars, positive Extended Year values indicate years AD,
+ * 1 BC = 0 extended, 2 BC = -1 extended, and so on.
+ * @stable ICU 2.8
*/
- UCAL_EXTENDED_YEAR,
- /**
- * Modified Julian day number, encompassing all date-related fields. Demarcates at local midnight.
- * @draft ICU 2.8
+ UCAL_EXTENDED_YEAR,
+
+ /**
+ * Field number
+ * indicating the modified Julian day number. This is different from
+ * the conventional Julian day number in two regards. First, it
+ * demarcates days at local zone midnight, rather than noon GMT.
+ * Second, it is a local number; that is, it depends on the local time
+ * zone. It can be thought of as a single number that encompasses all
+ * the date-related fields.
+ * @stable ICU 2.8
*/
UCAL_JULIAN_DAY,
+
/**
- * Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves exactly like a composite of all time-related fields, not including the zone fields. As such, it also reflects discontinuities of those fields on DST transition days. On a day of DST onset, it will jump forward. On a day of DST cessation, it will jump backward. This reflects the fact that is must be combined with the DST_OFFSET field to obtain a unique local time value.
- * @draft ICU 2.8
+ * Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves exactly
+ * like a composite of all time-related fields, not including the zone fields. As such,
+ * it also reflects discontinuities of those fields on DST transition days. On a day
+ * of DST onset, it will jump forward. On a day of DST cessation, it will jump
+ * backward. This reflects the fact that it must be combined with the DST_OFFSET field
+ * to obtain a unique local time value.
+ * @stable ICU 2.8
*/
UCAL_MILLISECONDS_IN_DAY,
-#endif /* U_HIDE_DRAFT_API */
-
/**
- * Field count
- * @stable ICU 2.6
+ * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for
+ * an example of this.
*/
- UCAL_FIELD_COUNT,
+ UCAL_IS_LEAP_MONTH,
-#ifndef U_HIDE_DRAFT_API
+ /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API,
+ * it is needed for layout of Calendar, DateFormat, and other objects */
+ /**
+ * One more than the highest normal UCalendarDateFields value.
+ * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
+ */
+ UCAL_FIELD_COUNT,
- /**
+ /**
+ * Field number indicating the
+ * day of the month. This is a synonym for UCAL_DATE.
+ * The first day of the month has value 1.
+ * @see #UCAL_DATE
* Synonym for UCAL_DATE
- * @draft ICU 2.8
+ * @stable ICU 2.8
**/
UCAL_DAY_OF_MONTH=UCAL_DATE
-
-#endif /*U_HIDE_DRAFT_API*/
};
/** @stable ICU 2.0 */
@@ -350,7 +502,10 @@ enum UCalendarMonths {
UCAL_NOVEMBER,
/** December */
UCAL_DECEMBER,
- /** Undecimber */
+ /** Value of the UCAL_MONTH field indicating the
+ * thirteenth month of the year. Although the Gregorian calendar
+ * does not use this value, lunar calendars do.
+ */
UCAL_UNDECIMBER
};
@@ -370,6 +525,53 @@ enum UCalendarAMPMs {
/** @stable ICU 2.0 */
typedef enum UCalendarAMPMs UCalendarAMPMs;
+/**
+ * System time zone type constants used by filtering zones
+ * in ucal_openTimeZoneIDEnumeration.
+ * @see ucal_openTimeZoneIDEnumeration
+ * @stable ICU 4.8
+ */
+enum USystemTimeZoneType {
+ /**
+ * Any system zones.
+ * @stable ICU 4.8
+ */
+ UCAL_ZONE_TYPE_ANY,
+ /**
+ * Canonical system zones.
+ * @stable ICU 4.8
+ */
+ UCAL_ZONE_TYPE_CANONICAL,
+ /**
+ * Canonical system zones associated with actual locations.
+ * @stable ICU 4.8
+ */
+ UCAL_ZONE_TYPE_CANONICAL_LOCATION
+};
+
+/** @stable ICU 4.8 */
+typedef enum USystemTimeZoneType USystemTimeZoneType;
+
+/**
+ * Create an enumeration over system time zone IDs with the given
+ * filter conditions.
+ * @param zoneType The system time zone type.
+ * @param region The ISO 3166 two-letter country code or UN M.49
+ * three-digit area code. When NULL, no filtering
+ * done by region.
+ * @param rawOffset An offset from GMT in milliseconds, ignoring the
+ * effect of daylight savings time, if any. When NULL,
+ * no filtering done by zone offset.
+ * @param ec A pointer to an UErrorCode to receive any errors
+ * @return an enumeration object that the caller must dispose of
+ * using enum_close(), or NULL upon failure. In case of failure,
+ * *ec will indicate the error.
+ * @stable ICU 4.8
+ */
+U_STABLE UEnumeration* U_EXPORT2
+ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region,
+ const int32_t* rawOffset, UErrorCode* ec);
+
/**
* Create an enumeration over all time zones.
*
@@ -381,7 +583,7 @@ typedef enum UCalendarAMPMs UCalendarAMPMs;
*
* @stable ICU 2.6
*/
-U_DRAFT UEnumeration* U_EXPORT2
+U_STABLE UEnumeration* U_EXPORT2
ucal_openTimeZones(UErrorCode* ec);
/**
@@ -400,7 +602,7 @@ ucal_openTimeZones(UErrorCode* ec);
*
* @stable ICU 2.6
*/
-U_DRAFT UEnumeration* U_EXPORT2
+U_STABLE UEnumeration* U_EXPORT2
ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
/**
@@ -419,7 +621,7 @@ ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
*
* @stable ICU 2.6
*/
-U_DRAFT int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
/**
@@ -431,7 +633,7 @@ ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
*
* @stable ICU 2.6
*/
-U_DRAFT void U_EXPORT2
+U_STABLE void U_EXPORT2
ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
/**
@@ -450,7 +652,7 @@ ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
*
* @stable ICU 2.6
*/
-U_DRAFT int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
/**
@@ -466,12 +668,23 @@ ucal_getNow(void);
* Open a UCalendar.
* A UCalendar may be used to convert a millisecond value to a year,
* month, and day.
+ *
+ * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown",
+ * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID
+ * UCAL_UNKNOWN_ZONE_ID ("Etc/Unknown") without any errors/warnings. If you want
+ * to check if a TimeZone ID is valid prior to this function, use ucal_getCanonicalTimeZoneID.
+ *
* @param zoneID The desired TimeZone ID. If 0, use the default time zone.
* @param len The length of zoneID, or -1 if null-terminated.
* @param locale The desired locale
- * @param type The type of UCalendar to open.
+ * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
+ * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
+ * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
+ * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
+ * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
* @param status A pointer to an UErrorCode to receive any errors
* @return A pointer to a UCalendar, or 0 if an error occurred.
+ * @see #UCAL_UNKNOWN_ZONE_ID
* @stable ICU 2.0
*/
U_STABLE UCalendar* U_EXPORT2
@@ -490,6 +703,37 @@ ucal_open(const UChar* zoneID,
U_STABLE void U_EXPORT2
ucal_close(UCalendar *cal);
+#if U_SHOW_CPLUSPLUS_API
+
+U_NAMESPACE_BEGIN
+
+/**
+ * \class LocalUCalendarPointer
+ * "Smart pointer" class, closes a UCalendar via ucal_close().
+ * For most methods see the LocalPointerBase base class.
+ *
+ * @see LocalPointerBase
+ * @see LocalPointer
+ * @stable ICU 4.4
+ */
+U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
+
+U_NAMESPACE_END
+
+#endif // U_SHOW_CPLUSPLUS_API
+
+/**
+ * Open a copy of a UCalendar.
+ * This function performs a deep copy.
+ * @param cal The calendar to copy
+ * @param status A pointer to an UErrorCode to receive any errors.
+ * @return A pointer to a UCalendar identical to cal.
+ * @stable ICU 4.0
+ */
+U_STABLE UCalendar* U_EXPORT2
+ucal_clone(const UCalendar* cal,
+ UErrorCode* status);
+
/**
* Set the TimeZone used by a UCalendar.
* A UCalendar uses a timezone for converting from Greenwich time to local time.
@@ -505,6 +749,22 @@ ucal_setTimeZone(UCalendar* cal,
int32_t len,
UErrorCode* status);
+/**
+ * Get the ID of the UCalendar's time zone.
+ *
+ * @param cal The UCalendar to query.
+ * @param result Receives the UCalendar's time zone ID.
+ * @param resultLength The maximum size of result.
+ * @param status Receives the status.
+ * @return The total buffer size needed; if greater than resultLength, the output was truncated.
+ * @stable ICU 51
+ */
+U_STABLE int32_t U_EXPORT2
+ucal_getTimeZoneID(const UCalendar *cal,
+ UChar *result,
+ int32_t resultLength,
+ UErrorCode *status);
+
/**
* Possible formats for a UCalendar's display name
* @stable ICU 2.0
@@ -556,29 +816,126 @@ U_STABLE UBool U_EXPORT2
ucal_inDaylightTime(const UCalendar* cal,
UErrorCode* status );
+/**
+ * Sets the GregorianCalendar change date. This is the point when the switch from
+ * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
+ * 15, 1582. Previous to this time and date will be Julian dates.
+ *
+ * This function works only for Gregorian calendars. If the UCalendar is not
+ * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
+ * error code is set.
+ *
+ * @param cal The calendar object.
+ * @param date The given Gregorian cutover date.
+ * @param pErrorCode Pointer to a standard ICU error code. Its input value must
+ * pass the U_SUCCESS() test, or else the function returns
+ * immediately. Check for U_FAILURE() on output or use with
+ * function chaining. (See User Guide for details.)
+ *
+ * @see GregorianCalendar::setGregorianChange
+ * @see ucal_getGregorianChange
+ * @stable ICU 3.6
+ */
+U_STABLE void U_EXPORT2
+ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
+
+/**
+ * Gets the Gregorian Calendar change date. This is the point when the switch from
+ * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
+ * 15, 1582. Previous to this time and date will be Julian dates.
+ *
+ * This function works only for Gregorian calendars. If the UCalendar is not
+ * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
+ * error code is set.
+ *
+ * @param cal The calendar object.
+ * @param pErrorCode Pointer to a standard ICU error code. Its input value must
+ * pass the U_SUCCESS() test, or else the function returns
+ * immediately. Check for U_FAILURE() on output or use with
+ * function chaining. (See User Guide for details.)
+ * @return The Gregorian cutover time for this calendar.
+ *
+ * @see GregorianCalendar::getGregorianChange
+ * @see ucal_setGregorianChange
+ * @stable ICU 3.6
+ */
+U_STABLE UDate U_EXPORT2
+ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
+
/**
* Types of UCalendar attributes
* @stable ICU 2.0
*/
enum UCalendarAttribute {
- /** Lenient parsing */
+ /**
+ * Lenient parsing
+ * @stable ICU 2.0
+ */
UCAL_LENIENT,
- /** First day of week */
+ /**
+ * First day of week
+ * @stable ICU 2.0
+ */
UCAL_FIRST_DAY_OF_WEEK,
- /** Minimum number of days in first week */
- UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
+ /**
+ * Minimum number of days in first week
+ * @stable ICU 2.0
+ */
+ UCAL_MINIMAL_DAYS_IN_FIRST_WEEK,
+ /**
+ * The behavior for handling wall time repeating multiple times
+ * at negative time zone offset transitions
+ * @stable ICU 49
+ */
+ UCAL_REPEATED_WALL_TIME,
+ /**
+ * The behavior for handling skipped wall time at positive time
+ * zone offset transitions.
+ * @stable ICU 49
+ */
+ UCAL_SKIPPED_WALL_TIME
};
/** @stable ICU 2.0 */
typedef enum UCalendarAttribute UCalendarAttribute;
+/**
+ * Options for handling ambiguous wall time at time zone
+ * offset transitions.
+ * @stable ICU 49
+ */
+enum UCalendarWallTimeOption {
+ /**
+ * An ambiguous wall time to be interpreted as the latest.
+ * This option is valid for UCAL_REPEATED_WALL_TIME and
+ * UCAL_SKIPPED_WALL_TIME.
+ * @stable ICU 49
+ */
+ UCAL_WALLTIME_LAST,
+ /**
+ * An ambiguous wall time to be interpreted as the earliest.
+ * This option is valid for UCAL_REPEATED_WALL_TIME and
+ * UCAL_SKIPPED_WALL_TIME.
+ * @stable ICU 49
+ */
+ UCAL_WALLTIME_FIRST,
+ /**
+ * An ambiguous wall time to be interpreted as the next valid
+ * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME.
+ * @stable ICU 49
+ */
+ UCAL_WALLTIME_NEXT_VALID
+};
+/** @stable ICU 49 */
+typedef enum UCalendarWallTimeOption UCalendarWallTimeOption;
+
/**
* Get a numeric attribute associated with a UCalendar.
* Numeric attributes include the first day of the week, or the minimal numbers
* of days in the first week of the month.
* @param cal The UCalendar to query.
* @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
- * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
+ * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
* @return The value of attr.
* @see ucal_setAttribute
* @stable ICU 2.0
@@ -593,7 +950,7 @@ ucal_getAttribute(const UCalendar* cal,
* of days in the first week of the month.
* @param cal The UCalendar to set.
* @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
- * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
+ * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
* @param newValue The new value of attr.
* @see ucal_getAttribute
* @stable ICU 2.0
@@ -607,13 +964,13 @@ ucal_setAttribute(UCalendar* cal,
* Get a locale for which calendars are available.
* A UCalendar in a locale returned by this function will contain the correct
* day and month names for the locale.
- * @param index The index of the desired locale.
+ * @param localeIndex The index of the desired locale.
* @return A locale for which calendars are available, or 0 if none.
* @see ucal_countAvailable
* @stable ICU 2.0
*/
U_STABLE const char* U_EXPORT2
-ucal_getAvailable(int32_t index);
+ucal_getAvailable(int32_t localeIndex);
/**
* Determine how many locales have calendars available.
@@ -721,6 +1078,9 @@ ucal_equivalentTo(const UCalendar* cal1,
/**
* Add a specified signed amount to a particular field in a UCalendar.
* This can modify more significant fields in the calendar.
+ * 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 cal The UCalendar to which to add.
* @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
* UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
@@ -742,6 +1102,15 @@ ucal_add(UCalendar* cal,
/**
* Add a specified signed amount to a particular field in a UCalendar.
* This will not modify more significant fields in the calendar.
+ * Rolling by a positive value always means moving 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).
* @param cal The UCalendar to which to add.
* @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
* UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
@@ -893,45 +1262,355 @@ ucal_getLimit(const UCalendar* cal,
UCalendarLimitType type,
UErrorCode* status);
-#ifdef U_USE_UCAL_OBSOLETE_2_8
-/**
- * Get an available TimeZone ID.
- * A Timezone ID is a string of the form "America/Los Angeles".
- * @param rawOffset The desired GMT offset
- * @param index The index of the desired TimeZone.
- * @param status A pointer to an UErrorCode to receive any errors
- * @return The requested TimeZone ID, or 0 if not found
- * @see ucal_countAvailableTZIDs
- * @obsolete ICU 2.8. Use ucal_openTimeZoneEnumeration instead since this API will be removed in that release.
- */
-U_OBSOLETE const UChar* U_EXPORT2
-ucal_getAvailableTZIDs(int32_t rawOffset,
- int32_t index,
- UErrorCode* status);
-
-/**
- * Determine how many TimeZones exist with a certain offset.
- * This function is most useful as determining the loop ending condition for
- * calls to \ref ucal_getAvailableTZIDs.
- * @param rawOffset The desired GMT offset.
- * @return The number of TimeZones with rawOffset.
- * @see ucal_getAvailableTZIDs
- * @obsolete ICU 2.8. Use ucal_openTimeZoneEnumeration instead since this API will be removed in that release.
- */
-U_OBSOLETE int32_t U_EXPORT2
-ucal_countAvailableTZIDs(int32_t rawOffset);
-#endif
-
/** Get the locale for this calendar object. You can choose between valid and actual locale.
* @param cal The calendar object
* @param type type of the locale we're looking for (valid or actual)
* @param status error code for the operation
* @return the locale name
- * @draft ICU 2.8 likely to change in ICU 3.0, based on feedback
+ * @stable ICU 2.8
*/
-U_DRAFT const char * U_EXPORT2
+U_STABLE const char * U_EXPORT2
ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
+/**
+ * Returns the timezone data version currently used by ICU.
+ * @param status error code for the operation
+ * @return the version string, such as "2007f"
+ * @stable ICU 3.8
+ */
+U_STABLE const char * U_EXPORT2
+ucal_getTZDataVersion(UErrorCode* status);
+
+/**
+ * Returns the canonical system timezone ID or the normalized
+ * custom time zone ID for the given time zone ID.
+ * @param id The input timezone ID to be canonicalized.
+ * @param len The length of id, or -1 if null-terminated.
+ * @param result The buffer receives the canonical system timezone ID
+ * or the custom timezone ID in normalized format.
+ * @param resultCapacity The capacity of the result buffer.
+ * @param isSystemID Receives if the given ID is a known system
+ * timezone ID.
+ * @param status Receives the status. When the given timezone ID
+ * is neither a known system time zone ID nor a
+ * valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
+ * is set.
+ * @return The result string length, not including the terminating
+ * null.
+ * @stable ICU 4.0
+ */
+U_STABLE int32_t U_EXPORT2
+ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
+ UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
+/**
+ * Get the resource keyword value string designating the calendar type for the UCalendar.
+ * @param cal The UCalendar to query.
+ * @param status The error code for the operation.
+ * @return The resource keyword value string.
+ * @stable ICU 4.2
+ */
+U_STABLE const char * U_EXPORT2
+ucal_getType(const UCalendar *cal, UErrorCode* status);
+
+/**
+ * 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 error status
+ * @return a string enumeration over keyword values for the given key and the locale.
+ * @stable ICU 4.2
+ */
+U_STABLE UEnumeration* U_EXPORT2
+ucal_getKeywordValuesForLocale(const char* key,
+ const char* locale,
+ UBool commonlyUsed,
+ UErrorCode* status);
+
+
+/** Weekday types, as returned by ucal_getDayOfWeekType().
+ * @stable ICU 4.4
+ */
+enum UCalendarWeekdayType {
+ /**
+ * Designates a full weekday (no part of the day is included in the weekend).
+ * @stable ICU 4.4
+ */
+ UCAL_WEEKDAY,
+ /**
+ * Designates a full weekend day (the entire day is included in the weekend).
+ * @stable ICU 4.4
+ */
+ UCAL_WEEKEND,
+ /**
+ * Designates a day that starts as a weekday and transitions to the weekend.
+ * Call ucal_getWeekendTransition() to get the time of transition.
+ * @stable ICU 4.4
+ */
+ UCAL_WEEKEND_ONSET,
+ /**
+ * Designates a day that starts as the weekend and transitions to a weekday.
+ * Call ucal_getWeekendTransition() to get the time of transition.
+ * @stable ICU 4.4
+ */
+ UCAL_WEEKEND_CEASE
+};
+
+/** @stable ICU 4.4 */
+typedef enum UCalendarWeekdayType UCalendarWeekdayType;
+
+/**
+ * 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 UCalendar (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
+ * function ucal_getWeekendTransition() will return the point of
+ * transition.
+ * @param cal The UCalendar to query.
+ * @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
+ */
+U_STABLE UCalendarWeekdayType U_EXPORT2
+ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status);
+
+/**
+ * Returns the time during the day at which the weekend begins or ends in
+ * this calendar system. If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET
+ * for the specified dayOfWeek, return the time at which the weekend begins.
+ * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
+ * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns
+ * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
+ * (U_ILLEGAL_ARGUMENT_ERROR).
+ * @param cal The UCalendar to query.
+ * @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
+ */
+U_STABLE int32_t U_EXPORT2
+ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
+
+/**
+ * Returns TRUE if the given UDate is in the weekend in
+ * this calendar system.
+ * @param cal The UCalendar to query.
+ * @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
+ */
+U_STABLE UBool U_EXPORT2
+ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status);
+
+/**
+ * Return the difference between the target time and the time this calendar object is currently set to.
+ * If the target time is after the current calendar setting, the the returned value will be positive.
+ * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH
+ * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the
+ * current calendar setting.
+ *
+ * As a side effect of this call, this calendar is advanced toward target by the given amount. That is,
+ * calling this function has the side effect of calling ucal_add on this calendar with the specified
+ * field and an amount equal to the return value from this function.
+ *
+ * A typical way of using this function is to call it first with the largest field of interest, then
+ * with progressively smaller fields.
+ *
+ * @param cal The UCalendar to compare and update.
+ * @param target The target date to compare to the current calendar setting.
+ * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
+ * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
+ * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
+ * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
+ * @param status A pointer to an UErrorCode to receive any errors
+ * @return The date difference for the specified field.
+ * @stable ICU 4.8
+ */
+U_STABLE int32_t U_EXPORT2
+ucal_getFieldDifference(UCalendar* cal,
+ UDate target,
+ UCalendarDateFields field,
+ UErrorCode* status);
+
+/**
+ * Time zone transition types for ucal_getTimeZoneTransitionDate
+ * @stable ICU 50
+ */
+enum UTimeZoneTransitionType {
+ /**
+ * Get the next transition after the current date,
+ * i.e. excludes the current date
+ * @stable ICU 50
+ */
+ UCAL_TZ_TRANSITION_NEXT,
+ /**
+ * Get the next transition on or after the current date,
+ * i.e. may include the current date
+ * @stable ICU 50
+ */
+ UCAL_TZ_TRANSITION_NEXT_INCLUSIVE,
+ /**
+ * Get the previous transition before the current date,
+ * i.e. excludes the current date
+ * @stable ICU 50
+ */
+ UCAL_TZ_TRANSITION_PREVIOUS,
+ /**
+ * Get the previous transition on or before the current date,
+ * i.e. may include the current date
+ * @stable ICU 50
+ */
+ UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE
+};
+
+typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */
+
+/**
+* Get the UDate for the next/previous time zone transition relative to
+* the calendar's current date, in the time zone to which the calendar
+* is currently set. If there is no known time zone transition of the
+* requested type relative to the calendar's date, the function returns
+* FALSE.
+* @param cal The UCalendar to query.
+* @param type The type of transition desired.
+* @param transition A pointer to a UDate to be set to the transition time.
+* If the function returns FALSE, the value set is unspecified.
+* @param status A pointer to a UErrorCode to receive any errors.
+* @return TRUE if a valid transition time is set in *transition, FALSE
+* otherwise.
+* @stable ICU 50
+*/
+U_STABLE UBool U_EXPORT2
+ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type,
+ UDate* transition, UErrorCode* status);
+
+/**
+* Converts a system time zone ID to an equivalent Windows time zone ID. For example,
+* Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles".
+*
+*
There are system time zones that cannot be mapped to Windows zones. When the input +* system time zone ID is unknown or unmappable to a Windows time zone, then this +* function returns 0 as the result length, but the operation itself remains successful +* (no error status set on return). +* +*
This implementation utilizes
+* Zone-Tzid mapping data. The mapping data is updated time to time. To get the latest changes,
+* please read the ICU user guide section
+* Updating the Time Zone Data.
+*
+* @param id A system time zone ID.
+* @param len The length of id, or -1 if null-terminated.
+* @param winid A buffer to receive a Windows time zone ID.
+* @param winidCapacity The capacity of the result buffer winid.
+* @param status Receives the status.
+* @return The result string length, not including the terminating null.
+* @see ucal_getTimeZoneIDForWindowsID
+*
+* @stable ICU 52
+*/
+U_STABLE int32_t U_EXPORT2
+ucal_getWindowsTimeZoneID(const UChar* id, int32_t len,
+ UChar* winid, int32_t winidCapacity, UErrorCode* status);
+
+/**
+* Converts a Windows time zone ID to an equivalent system time zone ID
+* for a region. For example, system time zone ID "America/Los_Angeles" is returned
+* for input Windows ID "Pacific Standard Time" and region "US" (or null),
+* "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and
+* region "CA".
+*
+*
Not all Windows time zones can be mapped to system time zones. When the input +* Windows time zone ID is unknown or unmappable to a system time zone, then this +* function returns 0 as the result length, but the operation itself remains successful +* (no error status set on return). +* +*
This implementation utilizes
+* Zone-Tzid mapping data. The mapping data is updated time to time. To get the latest changes,
+* please read the ICU user guide section
+* Updating the Time Zone Data.
+*
+* @param winid A Windows time zone ID.
+* @param len The length of winid, or -1 if null-terminated.
+* @param region A null-terminated region code, or NULL if no regional preference.
+* @param id A buffer to receive a system time zone ID.
+* @param idCapacity The capacity of the result buffer id.
+* @param status Receives the status.
+* @return The result string length, not including the terminating null.
+* @see ucal_getWindowsTimeZoneID
+*
+* @stable ICU 52
+*/
+U_STABLE int32_t U_EXPORT2
+ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region,
+ UChar* id, int32_t idCapacity, UErrorCode* status);
+
+#ifndef U_HIDE_DRAFT_API
+/**
+ * Day periods
+ * @draft Apple
+ */
+typedef enum UADayPeriod {
+ UADAYPERIOD_MORNING1,
+ UADAYPERIOD_MORNING2,
+ UADAYPERIOD_AFTERNOON1,
+ UADAYPERIOD_AFTERNOON2,
+ UADAYPERIOD_EVENING1,
+ UADAYPERIOD_EVENING2,
+ UADAYPERIOD_NIGHT1,
+ UADAYPERIOD_NIGHT2,
+ UADAYPERIOD_MIDNIGHT, /* Should only get this for formatStyle TRUE */
+ UADAYPERIOD_NOON, /* Should only get this for formatStyle TRUE */
+ UADAYPERIOD_UNKNOWN
+} UADayPeriod;
+
+/**
+ * Get the locale-specific day period for a particular time of day.
+ * This comes from the dayPeriod CLDR data in ICU.
+ *
+ * @param locale
+ * The locale
+ * @param hour
+ * Hour of day, in range 0..23.
+ * @param minute
+ * Minute of the hour, in range 0..59. Currently does not affect dayPeriod
+ * selection if formatStyle is FALSE.
+ * @param formatStyle
+ * FALSE to get dayPeriods for selecting strings to be used "stand-alone"
+ * without a particular time of day, e.g. "Good morning", "Good afternoon",
+ * "Good evening".
+ * TRUE to get dayPeriods for selecting strings to be used when formatting
+ * a particular time of day, e.g. "12:00 noon", "3:00 PM".
+ * @param status
+ * A pointer to a UErrorCode to receive any errors. In-out parameter; if
+ * this indicates an error on input, the function will return immediately.
+ * @return
+ * The UADayPeriod (possibly UADAYPERIOD_UNKNOWN).
+ * @draft Apple
+ */
+U_DRAFT UADayPeriod U_EXPORT2
+uacal_getDayPeriod( const char* locale,
+ int32_t hour,
+ int32_t minute,
+ UBool formatStyle,
+ UErrorCode* status );
+
+#endif /* U_HIDE_DRAFT_API */
+
#endif /* #if !UCONFIG_NO_FORMATTING */
#endif