UDate object
michael@0: * and a set of integer fields such as UCAL_YEAR, UCAL_MONTH,
michael@0: * UCAL_DAY, UCAL_HOUR, and so on.
michael@0: * (A UDate object represents a specific instant in
michael@0: * time with millisecond precision. See UDate
michael@0: * for information about the UDate .)
michael@0: *
michael@0: *
michael@0: * Types of UCalendar interpret a UDate
michael@0: * according to the rules of a specific calendar system. The U_STABLE
michael@0: * provides the enum UCalendarType with UCAL_TRADITIONAL and
michael@0: * UCAL_GREGORIAN.
michael@0: *
michael@0: * Like other locale-sensitive C API, calendar API provides a
michael@0: * function, ucal_open(), which returns a pointer to
michael@0: * UCalendar whose time fields have been initialized
michael@0: * with the current date and time. We need to specify the type of
michael@0: * calendar to be opened and the timezoneId.
michael@0: * \htmlonly
\endhtmlonly
michael@0: *
michael@0: * \code
michael@0: * UCalendar *caldef;
michael@0: * UChar *tzId;
michael@0: * UErrorCode status;
michael@0: * tzId=(UChar*)malloc(sizeof(UChar) * (strlen("PST") +1) );
michael@0: * u_uastrcpy(tzId, "PST");
michael@0: * caldef=ucal_open(tzID, u_strlen(tzID), NULL, UCAL_TRADITIONAL, &status);
michael@0: * \endcode
michael@0: *
michael@0: * \htmlonly\endhtmlonly
michael@0: *
michael@0: *
michael@0: * A UCalendar object can produce all the time field values
michael@0: * needed to implement the date-time formatting for a particular language
michael@0: * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
michael@0: *
michael@0: *
michael@0: * When computing a UDate from time fields, two special circumstances
michael@0: * may arise: there may be insufficient information to compute the
michael@0: * UDate (such as only year and month but no day in the month),
michael@0: * or there may be inconsistent information (such as "Tuesday, July 15, 1996"
michael@0: * -- July 15, 1996 is actually a Monday).
michael@0: *
michael@0: *
michael@0: * Insufficient information. The calendar will use default michael@0: * information to specify the missing fields. This may vary by calendar; for michael@0: * the Gregorian calendar, the default for a field is the same as that of the michael@0: * start of the epoch: i.e., UCAL_YEAR = 1970, UCAL_MONTH = JANUARY, UCAL_DATE = 1, etc. michael@0: * michael@0: *
michael@0: * Inconsistent information. If fields conflict, the calendar michael@0: * will give preference to fields set more recently. For example, when michael@0: * determining the day, the calendar will look for one of the following michael@0: * combinations of fields. The most recent combination, as determined by the michael@0: * most recently set single field, will be used. michael@0: * michael@0: * \htmlonly
\endhtmlonly michael@0: *\endhtmlonly michael@0: * michael@0: * For the time of day: michael@0: * michael@0: * \htmlonlymichael@0: * \code michael@0: * UCAL_MONTH + UCAL_DAY_OF_MONTH michael@0: * UCAL_MONTH + UCAL_WEEK_OF_MONTH + UCAL_DAY_OF_WEEK michael@0: * UCAL_MONTH + UCAL_DAY_OF_WEEK_IN_MONTH + UCAL_DAY_OF_WEEK michael@0: * UCAL_DAY_OF_YEAR michael@0: * UCAL_DAY_OF_WEEK + UCAL_WEEK_OF_YEAR michael@0: * \endcode michael@0: *michael@0: * \htmlonly
\endhtmlonly michael@0: *\endhtmlonly michael@0: * michael@0: *michael@0: * \code michael@0: * UCAL_HOUR_OF_DAY michael@0: * UCAL_AM_PM + UCAL_HOUR michael@0: * \endcode michael@0: *michael@0: * \htmlonly
michael@0: * Note: for some non-Gregorian calendars, different michael@0: * fields may be necessary for complete disambiguation. For example, a full michael@0: * specification of the historial Arabic astronomical calendar requires year, michael@0: * month, day-of-month and day-of-week in some cases. michael@0: * michael@0: *
michael@0: * Note: There are certain possible ambiguities in michael@0: * interpretation of certain singular times, which are resolved in the michael@0: * following ways: michael@0: *
michael@0: * The date or time format strings are not part of the definition of a michael@0: * calendar, as those must be modifiable or overridable by the user at michael@0: * runtime. Use {@link icu::DateFormat} michael@0: * to format dates. michael@0: * michael@0: *
michael@0: * Calendar provides an API for field "rolling", where fields
michael@0: * can be incremented or decremented, but wrap around. For example, rolling the
michael@0: * month up in the date December 12, 1996 results in
michael@0: * January 12, 1996.
michael@0: *
michael@0: *
michael@0: * Calendar also provides a date arithmetic function for
michael@0: * adding the specified (signed) amount of time to a particular time field.
michael@0: * For example, subtracting 5 days from the date September 12, 1996
michael@0: * results in September 7, 1996.
michael@0: *
michael@0: * @stable ICU 2.0
michael@0: */
michael@0:
michael@0: /**
michael@0: * The time zone ID reserved for unknown time zone.
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: #define UCAL_UNKNOWN_ZONE_ID "Etc/Unknown"
michael@0:
michael@0: /** A calendar.
michael@0: * For usage in C programs.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: typedef void* UCalendar;
michael@0:
michael@0: /** Possible types of UCalendars
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: enum UCalendarType {
michael@0: /**
michael@0: * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar,
michael@0: * which may be the Gregorian calendar or some other calendar.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: UCAL_TRADITIONAL,
michael@0: /**
michael@0: * A better name for UCAL_TRADITIONAL.
michael@0: * @stable ICU 4.2
michael@0: */
michael@0: UCAL_DEFAULT = UCAL_TRADITIONAL,
michael@0: /**
michael@0: * Unambiguously designates the Gregorian calendar for the locale.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: UCAL_GREGORIAN
michael@0: };
michael@0:
michael@0: /** @stable ICU 2.0 */
michael@0: typedef enum UCalendarType UCalendarType;
michael@0:
michael@0: /** Possible fields in a UCalendar
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: enum UCalendarDateFields {
michael@0: /**
michael@0: * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar.
michael@0: * This is a calendar-specific value.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_ERA,
michael@0:
michael@0: /**
michael@0: * Field number indicating the year. This is a calendar-specific value.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_YEAR,
michael@0:
michael@0: /**
michael@0: * Field number indicating the month. This is a calendar-specific value.
michael@0: * The first month of the year is
michael@0: * JANUARY; the last depends on the number of months in a year.
michael@0: * @see #UCAL_JANUARY
michael@0: * @see #UCAL_FEBRUARY
michael@0: * @see #UCAL_MARCH
michael@0: * @see #UCAL_APRIL
michael@0: * @see #UCAL_MAY
michael@0: * @see #UCAL_JUNE
michael@0: * @see #UCAL_JULY
michael@0: * @see #UCAL_AUGUST
michael@0: * @see #UCAL_SEPTEMBER
michael@0: * @see #UCAL_OCTOBER
michael@0: * @see #UCAL_NOVEMBER
michael@0: * @see #UCAL_DECEMBER
michael@0: * @see #UCAL_UNDECIMBER
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_MONTH,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * week number within the current year. The first week of the year, as
michael@0: * defined by UCAL_FIRST_DAY_OF_WEEK and UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
michael@0: * attributes, has value 1. Subclasses define
michael@0: * the value of UCAL_WEEK_OF_YEAR for days before the first week of
michael@0: * the year.
michael@0: * @see ucal_getAttribute
michael@0: * @see ucal_setAttribute
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_WEEK_OF_YEAR,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * week number within the current month. The first week of the month, as
michael@0: * defined by UCAL_FIRST_DAY_OF_WEEK and UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
michael@0: * attributes, has value 1. Subclasses define
michael@0: * the value of WEEK_OF_MONTH for days before the first week of
michael@0: * the month.
michael@0: * @see ucal_getAttribute
michael@0: * @see ucal_setAttribute
michael@0: * @see #UCAL_FIRST_DAY_OF_WEEK
michael@0: * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_WEEK_OF_MONTH,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * day of the month. This is a synonym for DAY_OF_MONTH.
michael@0: * The first day of the month has value 1.
michael@0: * @see #UCAL_DAY_OF_MONTH
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_DATE,
michael@0:
michael@0: /**
michael@0: * Field number indicating the day
michael@0: * number within the current year. The first day of the year has value 1.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_DAY_OF_YEAR,
michael@0:
michael@0: /**
michael@0: * Field number indicating the day
michael@0: * of the week. This field takes values SUNDAY,
michael@0: * MONDAY, TUESDAY, WEDNESDAY,
michael@0: * THURSDAY, FRIDAY, and SATURDAY.
michael@0: * @see #UCAL_SUNDAY
michael@0: * @see #UCAL_MONDAY
michael@0: * @see #UCAL_TUESDAY
michael@0: * @see #UCAL_WEDNESDAY
michael@0: * @see #UCAL_THURSDAY
michael@0: * @see #UCAL_FRIDAY
michael@0: * @see #UCAL_SATURDAY
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_DAY_OF_WEEK,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * ordinal number of the day of the week within the current month. Together
michael@0: * with the DAY_OF_WEEK field, this uniquely specifies a day
michael@0: * within a month. Unlike WEEK_OF_MONTH and
michael@0: * WEEK_OF_YEAR, this field's value does not depend on
michael@0: * getFirstDayOfWeek() or
michael@0: * getMinimalDaysInFirstWeek(). DAY_OF_MONTH 1
michael@0: * through 7 always correspond to DAY_OF_WEEK_IN_MONTH
michael@0: * 1; 8 through 15 correspond to
michael@0: * DAY_OF_WEEK_IN_MONTH 2, and so on.
michael@0: * DAY_OF_WEEK_IN_MONTH 0 indicates the week before
michael@0: * DAY_OF_WEEK_IN_MONTH 1. Negative values count back from the
michael@0: * end of the month, so the last Sunday of a month is specified as
michael@0: * DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1. Because
michael@0: * negative values count backward they will usually be aligned differently
michael@0: * within the month than positive values. For example, if a month has 31
michael@0: * days, DAY_OF_WEEK_IN_MONTH -1 will overlap
michael@0: * DAY_OF_WEEK_IN_MONTH 5 and the end of 4.
michael@0: * @see #UCAL_DAY_OF_WEEK
michael@0: * @see #UCAL_WEEK_OF_MONTH
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_DAY_OF_WEEK_IN_MONTH,
michael@0:
michael@0: /**
michael@0: * Field number indicating
michael@0: * whether the HOUR is before or after noon.
michael@0: * E.g., at 10:04:15.250 PM the AM_PM is PM.
michael@0: * @see #UCAL_AM
michael@0: * @see #UCAL_PM
michael@0: * @see #UCAL_HOUR
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_AM_PM,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * hour of the morning or afternoon. HOUR is used for the 12-hour
michael@0: * clock.
michael@0: * E.g., at 10:04:15.250 PM the HOUR is 10.
michael@0: * @see #UCAL_AM_PM
michael@0: * @see #UCAL_HOUR_OF_DAY
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_HOUR,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * hour of the day. HOUR_OF_DAY is used for the 24-hour clock.
michael@0: * E.g., at 10:04:15.250 PM the HOUR_OF_DAY is 22.
michael@0: * @see #UCAL_HOUR
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_HOUR_OF_DAY,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * minute within the hour.
michael@0: * E.g., at 10:04:15.250 PM the UCAL_MINUTE is 4.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_MINUTE,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * second within the minute.
michael@0: * E.g., at 10:04:15.250 PM the UCAL_SECOND is 15.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_SECOND,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * millisecond within the second.
michael@0: * E.g., at 10:04:15.250 PM the UCAL_MILLISECOND is 250.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_MILLISECOND,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * raw offset from GMT in milliseconds.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_ZONE_OFFSET,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * daylight savings offset in milliseconds.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_DST_OFFSET,
michael@0:
michael@0: /**
michael@0: * Field number
michael@0: * indicating the extended year corresponding to the
michael@0: * UCAL_WEEK_OF_YEAR field. This may be one greater or less
michael@0: * than the value of UCAL_EXTENDED_YEAR.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_YEAR_WOY,
michael@0:
michael@0: /**
michael@0: * Field number
michael@0: * indicating the localized day of week. This will be a value from 1
michael@0: * to 7 inclusive, with 1 being the localized first day of the week.
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_DOW_LOCAL,
michael@0:
michael@0: /**
michael@0: * Year of this calendar system, encompassing all supra-year fields. For example,
michael@0: * in Gregorian/Julian calendars, positive Extended Year values indicate years AD,
michael@0: * 1 BC = 0 extended, 2 BC = -1 extended, and so on.
michael@0: * @stable ICU 2.8
michael@0: */
michael@0: UCAL_EXTENDED_YEAR,
michael@0:
michael@0: /**
michael@0: * Field number
michael@0: * indicating the modified Julian day number. This is different from
michael@0: * the conventional Julian day number in two regards. First, it
michael@0: * demarcates days at local zone midnight, rather than noon GMT.
michael@0: * Second, it is a local number; that is, it depends on the local time
michael@0: * zone. It can be thought of as a single number that encompasses all
michael@0: * the date-related fields.
michael@0: * @stable ICU 2.8
michael@0: */
michael@0: UCAL_JULIAN_DAY,
michael@0:
michael@0: /**
michael@0: * Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves exactly
michael@0: * like a composite of all time-related fields, not including the zone fields. As such,
michael@0: * it also reflects discontinuities of those fields on DST transition days. On a day
michael@0: * of DST onset, it will jump forward. On a day of DST cessation, it will jump
michael@0: * backward. This reflects the fact that it must be combined with the DST_OFFSET field
michael@0: * to obtain a unique local time value.
michael@0: * @stable ICU 2.8
michael@0: */
michael@0: UCAL_MILLISECONDS_IN_DAY,
michael@0:
michael@0: /**
michael@0: * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for
michael@0: * an example of this.
michael@0: */
michael@0: UCAL_IS_LEAP_MONTH,
michael@0:
michael@0: /**
michael@0: * Field count
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: UCAL_FIELD_COUNT,
michael@0:
michael@0: /**
michael@0: * Field number indicating the
michael@0: * day of the month. This is a synonym for UCAL_DATE.
michael@0: * The first day of the month has value 1.
michael@0: * @see #UCAL_DATE
michael@0: * Synonym for UCAL_DATE
michael@0: * @stable ICU 2.8
michael@0: **/
michael@0: UCAL_DAY_OF_MONTH=UCAL_DATE
michael@0: };
michael@0:
michael@0: /** @stable ICU 2.0 */
michael@0: typedef enum UCalendarDateFields UCalendarDateFields;
michael@0: /**
michael@0: * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
michael@0: * who create locale resources for the field of first-day-of-week should be aware of
michael@0: * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
michael@0: */
michael@0: /** Possible days of the week in a UCalendar
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: enum UCalendarDaysOfWeek {
michael@0: /** Sunday */
michael@0: UCAL_SUNDAY = 1,
michael@0: /** Monday */
michael@0: UCAL_MONDAY,
michael@0: /** Tuesday */
michael@0: UCAL_TUESDAY,
michael@0: /** Wednesday */
michael@0: UCAL_WEDNESDAY,
michael@0: /** Thursday */
michael@0: UCAL_THURSDAY,
michael@0: /** Friday */
michael@0: UCAL_FRIDAY,
michael@0: /** Saturday */
michael@0: UCAL_SATURDAY
michael@0: };
michael@0:
michael@0: /** @stable ICU 2.0 */
michael@0: typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
michael@0:
michael@0: /** Possible months in a UCalendar. Note: Calendar month is 0-based.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: enum UCalendarMonths {
michael@0: /** January */
michael@0: UCAL_JANUARY,
michael@0: /** February */
michael@0: UCAL_FEBRUARY,
michael@0: /** March */
michael@0: UCAL_MARCH,
michael@0: /** April */
michael@0: UCAL_APRIL,
michael@0: /** May */
michael@0: UCAL_MAY,
michael@0: /** June */
michael@0: UCAL_JUNE,
michael@0: /** July */
michael@0: UCAL_JULY,
michael@0: /** August */
michael@0: UCAL_AUGUST,
michael@0: /** September */
michael@0: UCAL_SEPTEMBER,
michael@0: /** October */
michael@0: UCAL_OCTOBER,
michael@0: /** November */
michael@0: UCAL_NOVEMBER,
michael@0: /** December */
michael@0: UCAL_DECEMBER,
michael@0: /** Value of the UCAL_MONTH field indicating the
michael@0: * thirteenth month of the year. Although the Gregorian calendar
michael@0: * does not use this value, lunar calendars do.
michael@0: */
michael@0: UCAL_UNDECIMBER
michael@0: };
michael@0:
michael@0: /** @stable ICU 2.0 */
michael@0: typedef enum UCalendarMonths UCalendarMonths;
michael@0:
michael@0: /** Possible AM/PM values in a UCalendar
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: enum UCalendarAMPMs {
michael@0: /** AM */
michael@0: UCAL_AM,
michael@0: /** PM */
michael@0: UCAL_PM
michael@0: };
michael@0:
michael@0: /** @stable ICU 2.0 */
michael@0: typedef enum UCalendarAMPMs UCalendarAMPMs;
michael@0:
michael@0: /**
michael@0: * System time zone type constants used by filtering zones
michael@0: * in ucal_openTimeZoneIDEnumeration.
michael@0: * @see ucal_openTimeZoneIDEnumeration
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: enum USystemTimeZoneType {
michael@0: /**
michael@0: * Any system zones.
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: UCAL_ZONE_TYPE_ANY,
michael@0: /**
michael@0: * Canonical system zones.
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: UCAL_ZONE_TYPE_CANONICAL,
michael@0: /**
michael@0: * Canonical system zones associated with actual locations.
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: UCAL_ZONE_TYPE_CANONICAL_LOCATION
michael@0: };
michael@0:
michael@0: /** @stable ICU 4.8 */
michael@0: typedef enum USystemTimeZoneType USystemTimeZoneType;
michael@0:
michael@0: /**
michael@0: * Create an enumeration over system time zone IDs with the given
michael@0: * filter conditions.
michael@0: * @param zoneType The system time zone type.
michael@0: * @param region The ISO 3166 two-letter country code or UN M.49
michael@0: * three-digit area code. When NULL, no filtering
michael@0: * done by region.
michael@0: * @param rawOffset An offset from GMT in milliseconds, ignoring the
michael@0: * effect of daylight savings time, if any. When NULL,
michael@0: * no filtering done by zone offset.
michael@0: * @param ec A pointer to an UErrorCode to receive any errors
michael@0: * @return an enumeration object that the caller must dispose of
michael@0: * using enum_close(), or NULL upon failure. In case of failure,
michael@0: * *ec will indicate the error.
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: U_STABLE UEnumeration* U_EXPORT2
michael@0: ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region,
michael@0: const int32_t* rawOffset, UErrorCode* ec);
michael@0:
michael@0: /**
michael@0: * Create an enumeration over all time zones.
michael@0: *
michael@0: * @param ec input/output error code
michael@0: *
michael@0: * @return an enumeration object that the caller must dispose of using
michael@0: * uenum_close(), or NULL upon failure. In case of failure *ec will
michael@0: * indicate the error.
michael@0: *
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: U_STABLE UEnumeration* U_EXPORT2
michael@0: ucal_openTimeZones(UErrorCode* ec);
michael@0:
michael@0: /**
michael@0: * Create an enumeration over all time zones associated with the given
michael@0: * country. Some zones are affiliated with no country (e.g., "UTC");
michael@0: * these may also be retrieved, as a group.
michael@0: *
michael@0: * @param country the ISO 3166 two-letter country code, or NULL to
michael@0: * retrieve zones not affiliated with any country
michael@0: *
michael@0: * @param ec input/output error code
michael@0: *
michael@0: * @return an enumeration object that the caller must dispose of using
michael@0: * uenum_close(), or NULL upon failure. In case of failure *ec will
michael@0: * indicate the error.
michael@0: *
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: U_STABLE UEnumeration* U_EXPORT2
michael@0: ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
michael@0:
michael@0: /**
michael@0: * Return the default time zone. The default is determined initially
michael@0: * by querying the host operating system. It may be changed with
michael@0: * ucal_setDefaultTimeZone() or with the C++ TimeZone API.
michael@0: *
michael@0: * @param result A buffer to receive the result, or NULL
michael@0: *
michael@0: * @param resultCapacity The capacity of the result buffer
michael@0: *
michael@0: * @param ec input/output error code
michael@0: *
michael@0: * @return The result string length, not including the terminating
michael@0: * null
michael@0: *
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
michael@0:
michael@0: /**
michael@0: * Set the default time zone.
michael@0: *
michael@0: * @param zoneID null-terminated time zone ID
michael@0: *
michael@0: * @param ec input/output error code
michael@0: *
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
michael@0:
michael@0: /**
michael@0: * Return the amount of time in milliseconds that the clock is
michael@0: * advanced during daylight savings time for the given time zone, or
michael@0: * zero if the time zone does not observe daylight savings time.
michael@0: *
michael@0: * @param zoneID null-terminated time zone ID
michael@0: *
michael@0: * @param ec input/output error code
michael@0: *
michael@0: * @return the number of milliseconds the time is advanced with
michael@0: * respect to standard time when the daylight savings rules are in
michael@0: * effect. This is always a non-negative number, most commonly either
michael@0: * 3,600,000 (one hour) or zero.
michael@0: *
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
michael@0:
michael@0: /**
michael@0: * Get the current date and time.
michael@0: * The value returned is represented as milliseconds from the epoch.
michael@0: * @return The current date and time.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE UDate U_EXPORT2
michael@0: ucal_getNow(void);
michael@0:
michael@0: /**
michael@0: * Open a UCalendar.
michael@0: * A UCalendar may be used to convert a millisecond value to a year,
michael@0: * month, and day.
michael@0: *
michael@0: * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown",
michael@0: * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID
michael@0: * UCAL_UNKNOWN_ZONE_ID ("Etc/Unknown") without any errors/warnings. If you want
michael@0: * to check if a TimeZone ID is valid prior to this function, use ucal_getCanonicalTimeZoneID.
michael@0: *
michael@0: * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
michael@0: * @param len The length of zoneID, or -1 if null-terminated.
michael@0: * @param locale The desired locale
michael@0: * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
michael@0: * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
michael@0: * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
michael@0: * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
michael@0: * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return A pointer to a UCalendar, or 0 if an error occurred.
michael@0: * @see #UCAL_UNKNOWN_ZONE_ID
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE UCalendar* U_EXPORT2
michael@0: ucal_open(const UChar* zoneID,
michael@0: int32_t len,
michael@0: const char* locale,
michael@0: UCalendarType type,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Close a UCalendar.
michael@0: * Once closed, a UCalendar may no longer be used.
michael@0: * @param cal The UCalendar to close.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_close(UCalendar *cal);
michael@0:
michael@0: #if U_SHOW_CPLUSPLUS_API
michael@0:
michael@0: U_NAMESPACE_BEGIN
michael@0:
michael@0: /**
michael@0: * \class LocalUCalendarPointer
michael@0: * "Smart pointer" class, closes a UCalendar via ucal_close().
michael@0: * For most methods see the LocalPointerBase base class.
michael@0: *
michael@0: * @see LocalPointerBase
michael@0: * @see LocalPointer
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
michael@0:
michael@0: U_NAMESPACE_END
michael@0:
michael@0: #endif
michael@0:
michael@0: /**
michael@0: * Open a copy of a UCalendar.
michael@0: * This function performs a deep copy.
michael@0: * @param cal The calendar to copy
michael@0: * @param status A pointer to an UErrorCode to receive any errors.
michael@0: * @return A pointer to a UCalendar identical to cal.
michael@0: * @stable ICU 4.0
michael@0: */
michael@0: U_STABLE UCalendar* U_EXPORT2
michael@0: ucal_clone(const UCalendar* cal,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Set the TimeZone used by a UCalendar.
michael@0: * A UCalendar uses a timezone for converting from Greenwich time to local time.
michael@0: * @param cal The UCalendar to set.
michael@0: * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
michael@0: * @param len The length of zoneID, or -1 if null-terminated.
michael@0: * @param status A pointer to an UErrorCode to receive any errors.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_setTimeZone(UCalendar* cal,
michael@0: const UChar* zoneID,
michael@0: int32_t len,
michael@0: UErrorCode* status);
michael@0:
michael@0: #ifndef U_HIDE_DRAFT_API
michael@0: /**
michael@0: * Get the ID of the UCalendar's time zone.
michael@0: *
michael@0: * @param cal The UCalendar to query.
michael@0: * @param result Receives the UCalendar's time zone ID.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @param status Receives the status.
michael@0: * @return The total buffer size needed; if greater than resultLength, the output was truncated.
michael@0: * @draft ICU 51
michael@0: */
michael@0: U_DRAFT int32_t U_EXPORT2
michael@0: ucal_getTimeZoneID(const UCalendar *cal,
michael@0: UChar *result,
michael@0: int32_t resultLength,
michael@0: UErrorCode *status);
michael@0: #endif /* U_HIDE_DRAFT_API */
michael@0:
michael@0: /**
michael@0: * Possible formats for a UCalendar's display name
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: enum UCalendarDisplayNameType {
michael@0: /** Standard display name */
michael@0: UCAL_STANDARD,
michael@0: /** Short standard display name */
michael@0: UCAL_SHORT_STANDARD,
michael@0: /** Daylight savings display name */
michael@0: UCAL_DST,
michael@0: /** Short daylight savings display name */
michael@0: UCAL_SHORT_DST
michael@0: };
michael@0:
michael@0: /** @stable ICU 2.0 */
michael@0: typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
michael@0:
michael@0: /**
michael@0: * Get the display name for a UCalendar's TimeZone.
michael@0: * A display name is suitable for presentation to a user.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
michael@0: * UCAL_DST, UCAL_SHORT_DST
michael@0: * @param locale The desired locale for the display name.
michael@0: * @param result A pointer to a buffer to receive the formatted number.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The total buffer size needed; if greater than resultLength, the output was truncated.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_getTimeZoneDisplayName(const UCalendar* cal,
michael@0: UCalendarDisplayNameType type,
michael@0: const char* locale,
michael@0: UChar* result,
michael@0: int32_t resultLength,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Determine if a UCalendar is currently in daylight savings time.
michael@0: * Daylight savings time is not used in all parts of the world.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return TRUE if cal is currently in daylight savings time, FALSE otherwise
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE UBool U_EXPORT2
michael@0: ucal_inDaylightTime(const UCalendar* cal,
michael@0: UErrorCode* status );
michael@0:
michael@0: /**
michael@0: * Sets the GregorianCalendar change date. This is the point when the switch from
michael@0: * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
michael@0: * 15, 1582. Previous to this time and date will be Julian dates.
michael@0: *
michael@0: * This function works only for Gregorian calendars. If the UCalendar is not
michael@0: * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
michael@0: * error code is set.
michael@0: *
michael@0: * @param cal The calendar object.
michael@0: * @param date The given Gregorian cutover date.
michael@0: * @param pErrorCode Pointer to a standard ICU error code. Its input value must
michael@0: * pass the U_SUCCESS() test, or else the function returns
michael@0: * immediately. Check for U_FAILURE() on output or use with
michael@0: * function chaining. (See User Guide for details.)
michael@0: *
michael@0: * @see GregorianCalendar::setGregorianChange
michael@0: * @see ucal_getGregorianChange
michael@0: * @stable ICU 3.6
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
michael@0:
michael@0: /**
michael@0: * Gets the Gregorian Calendar change date. This is the point when the switch from
michael@0: * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
michael@0: * 15, 1582. Previous to this time and date will be Julian dates.
michael@0: *
michael@0: * This function works only for Gregorian calendars. If the UCalendar is not
michael@0: * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
michael@0: * error code is set.
michael@0: *
michael@0: * @param cal The calendar object.
michael@0: * @param pErrorCode Pointer to a standard ICU error code. Its input value must
michael@0: * pass the U_SUCCESS() test, or else the function returns
michael@0: * immediately. Check for U_FAILURE() on output or use with
michael@0: * function chaining. (See User Guide for details.)
michael@0: * @return The Gregorian cutover time for this calendar.
michael@0: *
michael@0: * @see GregorianCalendar::getGregorianChange
michael@0: * @see ucal_setGregorianChange
michael@0: * @stable ICU 3.6
michael@0: */
michael@0: U_STABLE UDate U_EXPORT2
michael@0: ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
michael@0:
michael@0: /**
michael@0: * Types of UCalendar attributes
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: enum UCalendarAttribute {
michael@0: /**
michael@0: * Lenient parsing
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: UCAL_LENIENT,
michael@0: /**
michael@0: * First day of week
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: UCAL_FIRST_DAY_OF_WEEK,
michael@0: /**
michael@0: * Minimum number of days in first week
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: UCAL_MINIMAL_DAYS_IN_FIRST_WEEK,
michael@0: /**
michael@0: * The behavior for handling wall time repeating multiple times
michael@0: * at negative time zone offset transitions
michael@0: * @stable ICU 49
michael@0: */
michael@0: UCAL_REPEATED_WALL_TIME,
michael@0: /**
michael@0: * The behavior for handling skipped wall time at positive time
michael@0: * zone offset transitions.
michael@0: * @stable ICU 49
michael@0: */
michael@0: UCAL_SKIPPED_WALL_TIME
michael@0: };
michael@0:
michael@0: /** @stable ICU 2.0 */
michael@0: typedef enum UCalendarAttribute UCalendarAttribute;
michael@0:
michael@0: /**
michael@0: * Options for handling ambiguous wall time at time zone
michael@0: * offset transitions.
michael@0: * @stable ICU 49
michael@0: */
michael@0: enum UCalendarWallTimeOption {
michael@0: /**
michael@0: * An ambiguous wall time to be interpreted as the latest.
michael@0: * This option is valid for UCAL_REPEATED_WALL_TIME and
michael@0: * UCAL_SKIPPED_WALL_TIME.
michael@0: * @stable ICU 49
michael@0: */
michael@0: UCAL_WALLTIME_LAST,
michael@0: /**
michael@0: * An ambiguous wall time to be interpreted as the earliest.
michael@0: * This option is valid for UCAL_REPEATED_WALL_TIME and
michael@0: * UCAL_SKIPPED_WALL_TIME.
michael@0: * @stable ICU 49
michael@0: */
michael@0: UCAL_WALLTIME_FIRST,
michael@0: /**
michael@0: * An ambiguous wall time to be interpreted as the next valid
michael@0: * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME.
michael@0: * @stable ICU 49
michael@0: */
michael@0: UCAL_WALLTIME_NEXT_VALID
michael@0: };
michael@0: /** @stable ICU 49 */
michael@0: typedef enum UCalendarWallTimeOption UCalendarWallTimeOption;
michael@0:
michael@0: /**
michael@0: * Get a numeric attribute associated with a UCalendar.
michael@0: * Numeric attributes include the first day of the week, or the minimal numbers
michael@0: * of days in the first week of the month.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
michael@0: * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
michael@0: * @return The value of attr.
michael@0: * @see ucal_setAttribute
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_getAttribute(const UCalendar* cal,
michael@0: UCalendarAttribute attr);
michael@0:
michael@0: /**
michael@0: * Set a numeric attribute associated with a UCalendar.
michael@0: * Numeric attributes include the first day of the week, or the minimal numbers
michael@0: * of days in the first week of the month.
michael@0: * @param cal The UCalendar to set.
michael@0: * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
michael@0: * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
michael@0: * @param newValue The new value of attr.
michael@0: * @see ucal_getAttribute
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_setAttribute(UCalendar* cal,
michael@0: UCalendarAttribute attr,
michael@0: int32_t newValue);
michael@0:
michael@0: /**
michael@0: * Get a locale for which calendars are available.
michael@0: * A UCalendar in a locale returned by this function will contain the correct
michael@0: * day and month names for the locale.
michael@0: * @param localeIndex The index of the desired locale.
michael@0: * @return A locale for which calendars are available, or 0 if none.
michael@0: * @see ucal_countAvailable
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE const char* U_EXPORT2
michael@0: ucal_getAvailable(int32_t localeIndex);
michael@0:
michael@0: /**
michael@0: * Determine how many locales have calendars available.
michael@0: * This function is most useful as determining the loop ending condition for
michael@0: * calls to \ref ucal_getAvailable.
michael@0: * @return The number of locales for which calendars are available.
michael@0: * @see ucal_getAvailable
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_countAvailable(void);
michael@0:
michael@0: /**
michael@0: * Get a UCalendar's current time in millis.
michael@0: * The time is represented as milliseconds from the epoch.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The calendar's current time in millis.
michael@0: * @see ucal_setMillis
michael@0: * @see ucal_setDate
michael@0: * @see ucal_setDateTime
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE UDate U_EXPORT2
michael@0: ucal_getMillis(const UCalendar* cal,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Set a UCalendar's current time in millis.
michael@0: * The time is represented as milliseconds from the epoch.
michael@0: * @param cal The UCalendar to set.
michael@0: * @param dateTime The desired date and time.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @see ucal_getMillis
michael@0: * @see ucal_setDate
michael@0: * @see ucal_setDateTime
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_setMillis(UCalendar* cal,
michael@0: UDate dateTime,
michael@0: UErrorCode* status );
michael@0:
michael@0: /**
michael@0: * Set a UCalendar's current date.
michael@0: * The date is represented as a series of 32-bit integers.
michael@0: * @param cal The UCalendar to set.
michael@0: * @param year The desired year.
michael@0: * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
michael@0: * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
michael@0: * @param date The desired day of the month.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @see ucal_getMillis
michael@0: * @see ucal_setMillis
michael@0: * @see ucal_setDateTime
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_setDate(UCalendar* cal,
michael@0: int32_t year,
michael@0: int32_t month,
michael@0: int32_t date,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Set a UCalendar's current date.
michael@0: * The date is represented as a series of 32-bit integers.
michael@0: * @param cal The UCalendar to set.
michael@0: * @param year The desired year.
michael@0: * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
michael@0: * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
michael@0: * @param date The desired day of the month.
michael@0: * @param hour The desired hour of day.
michael@0: * @param minute The desired minute.
michael@0: * @param second The desirec second.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @see ucal_getMillis
michael@0: * @see ucal_setMillis
michael@0: * @see ucal_setDate
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_setDateTime(UCalendar* cal,
michael@0: int32_t year,
michael@0: int32_t month,
michael@0: int32_t date,
michael@0: int32_t hour,
michael@0: int32_t minute,
michael@0: int32_t second,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Returns TRUE if two UCalendars are equivalent. Equivalent
michael@0: * UCalendars will behave identically, but they may be set to
michael@0: * different times.
michael@0: * @param cal1 The first of the UCalendars to compare.
michael@0: * @param cal2 The second of the UCalendars to compare.
michael@0: * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE UBool U_EXPORT2
michael@0: ucal_equivalentTo(const UCalendar* cal1,
michael@0: const UCalendar* cal2);
michael@0:
michael@0: /**
michael@0: * Add a specified signed amount to a particular field in a UCalendar.
michael@0: * This can modify more significant fields in the calendar.
michael@0: * Adding a positive value always means moving forward in time, so for the Gregorian calendar,
michael@0: * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
michael@0: * the numeric value of the field itself).
michael@0: * @param cal The UCalendar to which to add.
michael@0: * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
michael@0: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
michael@0: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
michael@0: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
michael@0: * @param amount The signed amount to add to field. If the amount causes the value
michael@0: * to exceed to maximum or minimum values for that field, other fields are modified
michael@0: * to preserve the magnitude of the change.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @see ucal_roll
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_add(UCalendar* cal,
michael@0: UCalendarDateFields field,
michael@0: int32_t amount,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Add a specified signed amount to a particular field in a UCalendar.
michael@0: * This will not modify more significant fields in the calendar.
michael@0: * Rolling by a positive value always means moving forward in time (unless the limit of the
michael@0: * field is reached, in which case it may pin or wrap), so for Gregorian calendar,
michael@0: * starting with 100 BC and rolling the year by +1 results in 99 BC.
michael@0: * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the
michael@0: * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around.
michael@0: * When eras only have a limit at one end, then attempting to roll the year past that limit will result in
michael@0: * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time
michael@0: * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for
michael@0: * era 0 (that is the only way to represent years before the calendar epoch).
michael@0: * @param cal The UCalendar to which to add.
michael@0: * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
michael@0: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
michael@0: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
michael@0: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
michael@0: * @param amount The signed amount to add to field. If the amount causes the value
michael@0: * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
michael@0: * value.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @see ucal_add
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_roll(UCalendar* cal,
michael@0: UCalendarDateFields field,
michael@0: int32_t amount,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Get the current value of a field from a UCalendar.
michael@0: * All fields are represented as 32-bit integers.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
michael@0: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
michael@0: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
michael@0: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The value of the desired field.
michael@0: * @see ucal_set
michael@0: * @see ucal_isSet
michael@0: * @see ucal_clearField
michael@0: * @see ucal_clear
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_get(const UCalendar* cal,
michael@0: UCalendarDateFields field,
michael@0: UErrorCode* status );
michael@0:
michael@0: /**
michael@0: * Set the value of a field in a UCalendar.
michael@0: * All fields are represented as 32-bit integers.
michael@0: * @param cal The UCalendar to set.
michael@0: * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
michael@0: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
michael@0: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
michael@0: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
michael@0: * @param value The desired value of field.
michael@0: * @see ucal_get
michael@0: * @see ucal_isSet
michael@0: * @see ucal_clearField
michael@0: * @see ucal_clear
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_set(UCalendar* cal,
michael@0: UCalendarDateFields field,
michael@0: int32_t value);
michael@0:
michael@0: /**
michael@0: * Determine if a field in a UCalendar is set.
michael@0: * All fields are represented as 32-bit integers.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
michael@0: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
michael@0: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
michael@0: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
michael@0: * @return TRUE if field is set, FALSE otherwise.
michael@0: * @see ucal_get
michael@0: * @see ucal_set
michael@0: * @see ucal_clearField
michael@0: * @see ucal_clear
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE UBool U_EXPORT2
michael@0: ucal_isSet(const UCalendar* cal,
michael@0: UCalendarDateFields field);
michael@0:
michael@0: /**
michael@0: * Clear a field in a UCalendar.
michael@0: * All fields are represented as 32-bit integers.
michael@0: * @param cal The UCalendar containing the field to clear.
michael@0: * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
michael@0: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
michael@0: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
michael@0: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
michael@0: * @see ucal_get
michael@0: * @see ucal_set
michael@0: * @see ucal_isSet
michael@0: * @see ucal_clear
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_clearField(UCalendar* cal,
michael@0: UCalendarDateFields field);
michael@0:
michael@0: /**
michael@0: * Clear all fields in a UCalendar.
michael@0: * All fields are represented as 32-bit integers.
michael@0: * @param calendar The UCalendar to clear.
michael@0: * @see ucal_get
michael@0: * @see ucal_set
michael@0: * @see ucal_isSet
michael@0: * @see ucal_clearField
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: ucal_clear(UCalendar* calendar);
michael@0:
michael@0: /**
michael@0: * Possible limit values for a UCalendar
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: enum UCalendarLimitType {
michael@0: /** Minimum value */
michael@0: UCAL_MINIMUM,
michael@0: /** Maximum value */
michael@0: UCAL_MAXIMUM,
michael@0: /** Greatest minimum value */
michael@0: UCAL_GREATEST_MINIMUM,
michael@0: /** Leaest maximum value */
michael@0: UCAL_LEAST_MAXIMUM,
michael@0: /** Actual minimum value */
michael@0: UCAL_ACTUAL_MINIMUM,
michael@0: /** Actual maximum value */
michael@0: UCAL_ACTUAL_MAXIMUM
michael@0: };
michael@0:
michael@0: /** @stable ICU 2.0 */
michael@0: typedef enum UCalendarLimitType UCalendarLimitType;
michael@0:
michael@0: /**
michael@0: * Determine a limit for a field in a UCalendar.
michael@0: * A limit is a maximum or minimum value for a field.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
michael@0: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
michael@0: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
michael@0: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
michael@0: * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM,
michael@0: * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
michael@0: * @param status A pointer to an UErrorCode to receive any errors.
michael@0: * @return The requested value.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_getLimit(const UCalendar* cal,
michael@0: UCalendarDateFields field,
michael@0: UCalendarLimitType type,
michael@0: UErrorCode* status);
michael@0:
michael@0: /** Get the locale for this calendar object. You can choose between valid and actual locale.
michael@0: * @param cal The calendar object
michael@0: * @param type type of the locale we're looking for (valid or actual)
michael@0: * @param status error code for the operation
michael@0: * @return the locale name
michael@0: * @stable ICU 2.8
michael@0: */
michael@0: U_STABLE const char * U_EXPORT2
michael@0: ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Returns the timezone data version currently used by ICU.
michael@0: * @param status error code for the operation
michael@0: * @return the version string, such as "2007f"
michael@0: * @stable ICU 3.8
michael@0: */
michael@0: U_STABLE const char * U_EXPORT2
michael@0: ucal_getTZDataVersion(UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Returns the canonical system timezone ID or the normalized
michael@0: * custom time zone ID for the given time zone ID.
michael@0: * @param id The input timezone ID to be canonicalized.
michael@0: * @param len The length of id, or -1 if null-terminated.
michael@0: * @param result The buffer receives the canonical system timezone ID
michael@0: * or the custom timezone ID in normalized format.
michael@0: * @param resultCapacity The capacity of the result buffer.
michael@0: * @param isSystemID Receives if the given ID is a known system
michael@0: * timezone ID.
michael@0: * @param status Recevies the status. When the given timezone ID
michael@0: * is neither a known system time zone ID nor a
michael@0: * valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
michael@0: * is set.
michael@0: * @return The result string length, not including the terminating
michael@0: * null.
michael@0: * @stable ICU 4.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
michael@0: UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
michael@0: /**
michael@0: * Get the resource keyword value string designating the calendar type for the UCalendar.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param status The error code for the operation.
michael@0: * @return The resource keyword value string.
michael@0: * @stable ICU 4.2
michael@0: */
michael@0: U_STABLE const char * U_EXPORT2
michael@0: ucal_getType(const UCalendar *cal, UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Given a key and a locale, returns an array of string values in a preferred
michael@0: * order that would make a difference. These are all and only those values where
michael@0: * the open (creation) of the service with the locale formed from the input locale
michael@0: * plus input keyword and that value has different behavior than creation with the
michael@0: * input locale alone.
michael@0: * @param key one of the keys supported by this service. For now, only
michael@0: * "calendar" is supported.
michael@0: * @param locale the locale
michael@0: * @param commonlyUsed if set to true it will return only commonly used values
michael@0: * with the given locale in preferred order. Otherwise,
michael@0: * it will return all the available values for the locale.
michael@0: * @param status error status
michael@0: * @return a string enumeration over keyword values for the given key and the locale.
michael@0: * @stable ICU 4.2
michael@0: */
michael@0: U_STABLE UEnumeration* U_EXPORT2
michael@0: ucal_getKeywordValuesForLocale(const char* key,
michael@0: const char* locale,
michael@0: UBool commonlyUsed,
michael@0: UErrorCode* status);
michael@0:
michael@0:
michael@0: /** Weekday types, as returned by ucal_getDayOfWeekType().
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: enum UCalendarWeekdayType {
michael@0: /**
michael@0: * Designates a full weekday (no part of the day is included in the weekend).
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: UCAL_WEEKDAY,
michael@0: /**
michael@0: * Designates a full weekend day (the entire day is included in the weekend).
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: UCAL_WEEKEND,
michael@0: /**
michael@0: * Designates a day that starts as a weekday and transitions to the weekend.
michael@0: * Call ucal_getWeekendTransition() to get the time of transition.
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: UCAL_WEEKEND_ONSET,
michael@0: /**
michael@0: * Designates a day that starts as the weekend and transitions to a weekday.
michael@0: * Call ucal_getWeekendTransition() to get the time of transition.
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: UCAL_WEEKEND_CEASE
michael@0: };
michael@0:
michael@0: /** @stable ICU 4.4 */
michael@0: typedef enum UCalendarWeekdayType UCalendarWeekdayType;
michael@0:
michael@0: /**
michael@0: * Returns whether the given day of the week is a weekday, a weekend day,
michael@0: * or a day that transitions from one to the other, for the locale and
michael@0: * calendar system associated with this UCalendar (the locale's region is
michael@0: * often the most determinant factor). If a transition occurs at midnight,
michael@0: * then the days before and after the transition will have the
michael@0: * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time
michael@0: * other than midnight, then the day of the transition will have
michael@0: * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the
michael@0: * function ucal_getWeekendTransition() will return the point of
michael@0: * transition.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY).
michael@0: * @param status The error code for the operation.
michael@0: * @return The UCalendarWeekdayType for the day of the week.
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: U_STABLE UCalendarWeekdayType U_EXPORT2
michael@0: ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Returns the time during the day at which the weekend begins or ends in
michael@0: * this calendar system. If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET
michael@0: * for the specified dayOfWeek, return the time at which the weekend begins.
michael@0: * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
michael@0: * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns
michael@0: * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
michael@0: * (U_ILLEGAL_ARGUMENT_ERROR).
michael@0: * @param cal The UCalendar to query.
michael@0: * @param dayOfWeek The day of the week for which the weekend transition time is
michael@0: * desired (UCAL_SUNDAY..UCAL_SATURDAY).
michael@0: * @param status The error code for the operation.
michael@0: * @return The milliseconds after midnight at which the weekend begins or ends.
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
michael@0:
michael@0: /**
michael@0: * Returns TRUE if the given UDate is in the weekend in
michael@0: * this calendar system.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param date The UDate in question.
michael@0: * @param status The error code for the operation.
michael@0: * @return TRUE if the given UDate is in the weekend in
michael@0: * this calendar system, FALSE otherwise.
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: U_STABLE UBool U_EXPORT2
michael@0: ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status);
michael@0:
michael@0: /**
michael@0: * Return the difference between the target time and the time this calendar object is currently set to.
michael@0: * If the target time is after the current calendar setting, the the returned value will be positive.
michael@0: * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH
michael@0: * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the
michael@0: * current calendar setting.
michael@0: *
michael@0: * As a side effect of this call, this calendar is advanced toward target by the given amount. That is,
michael@0: * calling this function has the side effect of calling ucal_add on this calendar with the specified
michael@0: * field and an amount equal to the return value from this function.
michael@0: *
michael@0: * A typical way of using this function is to call it first with the largest field of interest, then
michael@0: * with progressively smaller fields.
michael@0: *
michael@0: * @param cal The UCalendar to compare and update.
michael@0: * @param target The target date to compare to the current calendar setting.
michael@0: * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
michael@0: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
michael@0: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
michael@0: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The date difference for the specified field.
michael@0: * @stable ICU 4.8
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: ucal_getFieldDifference(UCalendar* cal,
michael@0: UDate target,
michael@0: UCalendarDateFields field,
michael@0: UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Time zone transition types for ucal_getTimeZoneTransitionDate
michael@0: * @stable ICU 50
michael@0: */
michael@0: enum UTimeZoneTransitionType {
michael@0: /**
michael@0: * Get the next transition after the current date,
michael@0: * i.e. excludes the current date
michael@0: * @stable ICU 50
michael@0: */
michael@0: UCAL_TZ_TRANSITION_NEXT,
michael@0: /**
michael@0: * Get the next transition on or after the current date,
michael@0: * i.e. may include the current date
michael@0: * @stable ICU 50
michael@0: */
michael@0: UCAL_TZ_TRANSITION_NEXT_INCLUSIVE,
michael@0: /**
michael@0: * Get the previous transition before the current date,
michael@0: * i.e. excludes the current date
michael@0: * @stable ICU 50
michael@0: */
michael@0: UCAL_TZ_TRANSITION_PREVIOUS,
michael@0: /**
michael@0: * Get the previous transition on or before the current date,
michael@0: * i.e. may include the current date
michael@0: * @stable ICU 50
michael@0: */
michael@0: UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE
michael@0: };
michael@0:
michael@0: typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */
michael@0:
michael@0: /**
michael@0: * Get the UDate for the next/previous time zone transition relative to
michael@0: * the calendar's current date, in the time zone to which the calendar
michael@0: * is currently set. If there is no known time zone transition of the
michael@0: * requested type relative to the calendar's date, the function returns
michael@0: * FALSE.
michael@0: * @param cal The UCalendar to query.
michael@0: * @param type The type of transition desired.
michael@0: * @param transition A pointer to a UDate to be set to the transition time.
michael@0: * If the function returns FALSE, the value set is unspecified.
michael@0: * @param status A pointer to a UErrorCode to receive any errors.
michael@0: * @return TRUE if a valid transition time is set in *transition, FALSE
michael@0: * otherwise.
michael@0: * @stable ICU 50
michael@0: */
michael@0: U_DRAFT UBool U_EXPORT2
michael@0: ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type,
michael@0: UDate* transition, UErrorCode* status);
michael@0:
michael@0: #ifndef U_HIDE_DRAFT_API
michael@0: /**
michael@0: * Converts a system time zone ID to an equivalent Windows time zone ID. For example,
michael@0: * Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles".
michael@0: *
michael@0: *
There are system time zones that cannot be mapped to Windows zones. When the input michael@0: * system time zone ID is unknown or unmappable to a Windows time zone, then this michael@0: * function returns 0 as the result length, but the operation itself remains successful michael@0: * (no error status set on return). michael@0: * michael@0: *
This implementation utilizes
michael@0: * Zone-Tzid mapping data. The mapping data is updated time to time. To get the latest changes,
michael@0: * please read the ICU user guide section
michael@0: * Updating the Time Zone Data.
michael@0: *
michael@0: * @param id A system time zone ID.
michael@0: * @param len The length of id, or -1 if null-terminated.
michael@0: * @param winid A buffer to receive a Windows time zone ID.
michael@0: * @param winidCapacity The capacity of the result buffer winid.
michael@0: * @param status Receives the status.
michael@0: * @return The result string length, not including the terminating null.
michael@0: * @see ucal_getTimeZoneIDForWindowsID
michael@0: *
michael@0: * @draft ICU 52
michael@0: */
michael@0: U_DRAFT int32_t U_EXPORT2
michael@0: ucal_getWindowsTimeZoneID(const UChar* id, int32_t len,
michael@0: UChar* winid, int32_t winidCapacity, UErrorCode* status);
michael@0:
michael@0: /**
michael@0: * Converts a Windows time zone ID to an equivalent system time zone ID
michael@0: * for a region. For example, system time zone ID "America/Los_Angeles" is returned
michael@0: * for input Windows ID "Pacific Standard Time" and region "US" (or null),
michael@0: * "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and
michael@0: * region "CA".
michael@0: *
michael@0: *
Not all Windows time zones can be mapped to system time zones. When the input michael@0: * Windows time zone ID is unknown or unmappable to a system time zone, then this michael@0: * function returns 0 as the result length, but the operation itself remains successful michael@0: * (no error status set on return). michael@0: * michael@0: *
This implementation utilizes
michael@0: * Zone-Tzid mapping data. The mapping data is updated time to time. To get the latest changes,
michael@0: * please read the ICU user guide section
michael@0: * Updating the Time Zone Data.
michael@0: *
michael@0: * @param winid A Windows time zone ID.
michael@0: * @param len The length of winid, or -1 if null-terminated.
michael@0: * @param region A null-terminated region code, or NULL if no regional preference.
michael@0: * @param id A buffer to receive a system time zone ID.
michael@0: * @param idCapacity The capacity of the result buffer id.
michael@0: * @param status Receives the status.
michael@0: * @return The result string length, not including the terminating null.
michael@0: * @see ucal_getWindowsTimeZoneID
michael@0: *
michael@0: * @draft ICU 52
michael@0: */
michael@0: U_DRAFT int32_t U_EXPORT2
michael@0: ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region,
michael@0: UChar* id, int32_t idCapacity, UErrorCode* status);
michael@0:
michael@0: #endif /* U_HIDE_DRAFT_API */
michael@0:
michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */
michael@0:
michael@0: #endif