blob: e63be68538297f36650e738b854edec1ec63015c [file] [log] [blame]

Calendar C API

* * UCalendar C API is used for converting between a UDate object * and a set of integer fields such as UCAL_YEAR, UCAL_MONTH, * UCAL_DAY, UCAL_HOUR, and so on. * (A UDate object represents a specific instant in * time with millisecond precision. See UDate * for information about the UDate .) * *

* Types of UCalendar interpret a UDate * according to the rules of a specific calendar system. The C API * provides the enum UCalendarType with UCAL_TRADITIONAL and * UCAL_GREGORIAN. *

* Like other locale-sensitive C API, calendar API provides a * function, ucal_open(), which returns a pointer to * UCalendar whose time fields have been initialized * with the current date and time. We need to specify the type of * calendar to be opened and the timezoneId. * \htmlonly

\endhtmlonly *
* \code
* UCalendar *caldef;
* UChar *tzId;
* UErrorCode status;
* tzId=(UChar*)malloc(sizeof(UChar) * (strlen("PST") +1) );
* u_uastrcpy(tzId, "PST");
* caldef=ucal_open(tzID, u_strlen(tzID), NULL, UCAL_TRADITIONAL, &status);
* \endcode
*
* \htmlonly
\endhtmlonly * *

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

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

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

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

\endhtmlonly *
* \code
* UCAL_MONTH + UCAL_DAY_OF_MONTH
* UCAL_MONTH + UCAL_WEEK_OF_MONTH + UCAL_DAY_OF_WEEK
* UCAL_MONTH + UCAL_DAY_OF_WEEK_IN_MONTH + UCAL_DAY_OF_WEEK
* UCAL_DAY_OF_YEAR
* UCAL_DAY_OF_WEEK + UCAL_WEEK_OF_YEAR
* \endcode
*
* \htmlonly
\endhtmlonly * * For the time of day: * * \htmlonly
\endhtmlonly *
* \code
* UCAL_HOUR_OF_DAY
* UCAL_AM_PM + UCAL_HOUR
* \endcode
*
* \htmlonly
\endhtmlonly * *

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

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

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

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

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

* Calendar also provides a date arithmetic function for * adding the specified (signed) amount of time to a particular time field. * For example, subtracting 5 days from the date September 12, 1996 * results in September 7, 1996. * *

* The Japanese calendar uses a combination of era name and year number. * When an emperor of Japan abdicates and a new emperor ascends the throne, * a new era is declared and year number is reset to 1. Even if the date of * abdication is scheduled ahead of time, the new era name might not be * announced until just before the date. In such case, ICU4C may include * a start date of future era without actual era name, but not enabled * by default. ICU4C users who want to test the behavior of the future era * can enable the tentative era by: *

*
• Environment variable ICU_ENABLE_TENTATIVE_ERA=true.
• *
* * @stable ICU 2.0 */ /** * The time zone ID reserved for unknown time zone. * It behaves like the GMT/UTC time zone but has the special ID "Etc/Unknown". * @stable ICU 4.8 */ #define UCAL_UNKNOWN_ZONE_ID "Etc/Unknown" /** A calendar. * For usage in C programs. * @stable ICU 2.0 */ typedef void* UCalendar; /** Possible types of UCalendars * @stable ICU 2.0 */ enum UCalendarType { /** * 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, /** * 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 }; /** @stable ICU 2.0 */ typedef enum UCalendarType UCalendarType; /** Possible fields in a UCalendar * @stable ICU 2.0 */ enum UCalendarDateFields { /** * 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, /** * Field number indicating the year. This is a calendar-specific value. * @stable ICU 2.6 */ UCAL_YEAR, /** * 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, /** * 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, /** * 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, /** * 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, /** * 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, /** * 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, /** * 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, /** * 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, /** * 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, /** * 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, /** * 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, /** * 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, /** * 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, /** * Field number indicating the * raw offset from GMT in milliseconds. * @stable ICU 2.6 */ UCAL_ZONE_OFFSET, /** * Field number indicating the * daylight savings offset in milliseconds. * @stable ICU 2.6 */ UCAL_DST_OFFSET, /** * 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, /** * 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 */ 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. * @stable 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 it must be combined with the DST_OFFSET field * to obtain a unique local time value. * @stable ICU 2.8 */ UCAL_MILLISECONDS_IN_DAY, /** * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for * an example of this. */ UCAL_IS_LEAP_MONTH, /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, * it is needed for layout of Calendar, DateFormat, and other objects */ #ifndef U_FORCE_HIDE_DEPRECATED_API /** * 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, #endif // U_FORCE_HIDE_DEPRECATED_API /** * 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 * @stable ICU 2.8 **/ UCAL_DAY_OF_MONTH=UCAL_DATE }; /** @stable ICU 2.0 */ typedef enum UCalendarDateFields UCalendarDateFields; /** * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients * who create locale resources for the field of first-day-of-week should be aware of * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY. */ /** Possible days of the week in a UCalendar * @stable ICU 2.0 */ enum UCalendarDaysOfWeek { /** Sunday */ UCAL_SUNDAY = 1, /** Monday */ UCAL_MONDAY, /** Tuesday */ UCAL_TUESDAY, /** Wednesday */ UCAL_WEDNESDAY, /** Thursday */ UCAL_THURSDAY, /** Friday */ UCAL_FRIDAY, /** Saturday */ UCAL_SATURDAY }; /** @stable ICU 2.0 */ typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek; /** Possible months in a UCalendar. Note: Calendar month is 0-based. * @stable ICU 2.0 */ enum UCalendarMonths { /** January */ UCAL_JANUARY, /** February */ UCAL_FEBRUARY, /** March */ UCAL_MARCH, /** April */ UCAL_APRIL, /** May */ UCAL_MAY, /** June */ UCAL_JUNE, /** July */ UCAL_JULY, /** August */ UCAL_AUGUST, /** September */ UCAL_SEPTEMBER, /** October */ UCAL_OCTOBER, /** November */ UCAL_NOVEMBER, /** December */ UCAL_DECEMBER, /** 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 }; /** @stable ICU 2.0 */ typedef enum UCalendarMonths UCalendarMonths; /** Possible AM/PM values in a UCalendar * @stable ICU 2.0 */ enum UCalendarAMPMs { /** AM */ UCAL_AM, /** PM */ UCAL_PM }; /** @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_CAPI UEnumeration* U_EXPORT2 ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region, const int32_t* rawOffset, UErrorCode* ec); /** * Create an enumeration over all time zones. * * @param ec input/output error code * * @return an enumeration object that the caller must dispose of using * uenum_close(), or NULL upon failure. In case of failure *ec will * indicate the error. * * @stable ICU 2.6 */ U_CAPI UEnumeration* U_EXPORT2 ucal_openTimeZones(UErrorCode* ec); /** * Create an enumeration over all time zones associated with the given * country. Some zones are affiliated with no country (e.g., "UTC"); * these may also be retrieved, as a group. * * @param country the ISO 3166 two-letter country code, or NULL to * retrieve zones not affiliated with any country * * @param ec input/output error code * * @return an enumeration object that the caller must dispose of using * uenum_close(), or NULL upon failure. In case of failure *ec will * indicate the error. * * @stable ICU 2.6 */ U_CAPI UEnumeration* U_EXPORT2 ucal_openCountryTimeZones(const char* country, UErrorCode* ec); /** * Return the default time zone. The default is determined initially * by querying the host operating system. If the host system detection * routines fail, or if they specify a TimeZone or TimeZone offset * which is not recognized, then the special TimeZone "Etc/Unknown" * is returned. * * The default may be changed with ucal_setDefaultTimeZone() or with * the C++ TimeZone API, TimeZone::adoptDefault(TimeZone*). * * @param result A buffer to receive the result, or NULL * * @param resultCapacity The capacity of the result buffer * * @param ec input/output error code * * @return The result string length, not including the terminating * null * * @see #UCAL_UNKNOWN_ZONE_ID * * @stable ICU 2.6 */ U_CAPI int32_t U_EXPORT2 ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec); /** * Set the default time zone. * * @param zoneID null-terminated time zone ID * * @param ec input/output error code * * @stable ICU 2.6 */ U_CAPI void U_EXPORT2 ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec); /** * Return the current host time zone. The host time zone is detected from * the current host system configuration by querying the host operating * system. If the host system detection routines fail, or if they specify * a TimeZone or TimeZone offset which is not recognized, then the special * TimeZone "Etc/Unknown" is returned. * * Note that host time zone and the ICU default time zone can be different. * * The ICU default time zone does not change once initialized unless modified * by calling ucal_setDefaultTimeZone() or with the C++ TimeZone API, * TimeZone::adoptDefault(TimeZone*). * * If the host operating system configuration has changed since ICU has * initialized then the returned value can be different than the ICU default * time zone, even if the default has not changed. * *

This function is not thread safe.

* * @param result A buffer to receive the result, or NULL * @param resultCapacity The capacity of the result buffer * @param ec input/output error code * @return The result string length, not including the terminating * null * * @see #UCAL_UNKNOWN_ZONE_ID * * @stable ICU 65 */ U_CAPI int32_t U_EXPORT2 ucal_getHostTimeZone(UChar *result, int32_t resultCapacity, UErrorCode *ec); /** * Return the amount of time in milliseconds that the clock is * advanced during daylight savings time for the given time zone, or * zero if the time zone does not observe daylight savings time. * * @param zoneID null-terminated time zone ID * * @param ec input/output error code * * @return the number of milliseconds the time is advanced with * respect to standard time when the daylight savings rules are in * effect. This is always a non-negative number, most commonly either * 3,600,000 (one hour) or zero. * * @stable ICU 2.6 */ U_CAPI int32_t U_EXPORT2 ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec); /** * Get the current date and time. * The value returned is represented as milliseconds from the epoch. * @return The current date and time. * @stable ICU 2.0 */ U_CAPI UDate U_EXPORT2 ucal_getNow(void); /** * Open a UCalendar. * A UCalendar may be used to convert a millisecond value to a year, * month, and day. *