jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ******************************************************************************* jpayne@69: * Copyright (C) 1996-2015, International Business Machines Corporation and jpayne@69: * others. All Rights Reserved. jpayne@69: ******************************************************************************* jpayne@69: */ jpayne@69: jpayne@69: #ifndef UCAL_H jpayne@69: #define UCAL_H jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: #include "unicode/uenum.h" jpayne@69: #include "unicode/uloc.h" jpayne@69: #include "unicode/localpointer.h" jpayne@69: jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C API: Calendar jpayne@69: * jpayne@69: *

Calendar C API

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

jpayne@69: * Types of UCalendar interpret a UDate jpayne@69: * according to the rules of a specific calendar system. The U_STABLE jpayne@69: * provides the enum UCalendarType with UCAL_TRADITIONAL and jpayne@69: * UCAL_GREGORIAN. jpayne@69: *

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

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

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

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

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

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

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

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

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

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

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

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

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

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

jpayne@69: * jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: jpayne@69: /** jpayne@69: * The time zone ID reserved for unknown time zone. jpayne@69: * It behaves like the GMT/UTC time zone but has the special ID "Etc/Unknown". jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: #define UCAL_UNKNOWN_ZONE_ID "Etc/Unknown" jpayne@69: jpayne@69: /** A calendar. jpayne@69: * For usage in C programs. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: typedef void* UCalendar; jpayne@69: jpayne@69: /** Possible types of UCalendars jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum UCalendarType { jpayne@69: /** jpayne@69: * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar, jpayne@69: * which may be the Gregorian calendar or some other calendar. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UCAL_TRADITIONAL, jpayne@69: /** jpayne@69: * A better name for UCAL_TRADITIONAL. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: UCAL_DEFAULT = UCAL_TRADITIONAL, jpayne@69: /** jpayne@69: * Unambiguously designates the Gregorian calendar for the locale. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UCAL_GREGORIAN jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef enum UCalendarType UCalendarType; jpayne@69: jpayne@69: /** Possible fields in a UCalendar jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum UCalendarDateFields { jpayne@69: /** jpayne@69: * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar. jpayne@69: * This is a calendar-specific value. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_ERA, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the year. This is a calendar-specific value. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_YEAR, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the month. This is a calendar-specific value. jpayne@69: * The first month of the year is jpayne@69: * JANUARY; the last depends on the number of months in a year. jpayne@69: * @see #UCAL_JANUARY jpayne@69: * @see #UCAL_FEBRUARY jpayne@69: * @see #UCAL_MARCH jpayne@69: * @see #UCAL_APRIL jpayne@69: * @see #UCAL_MAY jpayne@69: * @see #UCAL_JUNE jpayne@69: * @see #UCAL_JULY jpayne@69: * @see #UCAL_AUGUST jpayne@69: * @see #UCAL_SEPTEMBER jpayne@69: * @see #UCAL_OCTOBER jpayne@69: * @see #UCAL_NOVEMBER jpayne@69: * @see #UCAL_DECEMBER jpayne@69: * @see #UCAL_UNDECIMBER jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_MONTH, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * week number within the current year. The first week of the year, as jpayne@69: * defined by UCAL_FIRST_DAY_OF_WEEK and UCAL_MINIMAL_DAYS_IN_FIRST_WEEK jpayne@69: * attributes, has value 1. Subclasses define jpayne@69: * the value of UCAL_WEEK_OF_YEAR for days before the first week of jpayne@69: * the year. jpayne@69: * @see ucal_getAttribute jpayne@69: * @see ucal_setAttribute jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_WEEK_OF_YEAR, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * week number within the current month. The first week of the month, as jpayne@69: * defined by UCAL_FIRST_DAY_OF_WEEK and UCAL_MINIMAL_DAYS_IN_FIRST_WEEK jpayne@69: * attributes, has value 1. Subclasses define jpayne@69: * the value of WEEK_OF_MONTH for days before the first week of jpayne@69: * the month. jpayne@69: * @see ucal_getAttribute jpayne@69: * @see ucal_setAttribute jpayne@69: * @see #UCAL_FIRST_DAY_OF_WEEK jpayne@69: * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_WEEK_OF_MONTH, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * day of the month. This is a synonym for DAY_OF_MONTH. jpayne@69: * The first day of the month has value 1. jpayne@69: * @see #UCAL_DAY_OF_MONTH jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_DATE, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the day jpayne@69: * number within the current year. The first day of the year has value 1. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_DAY_OF_YEAR, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the day jpayne@69: * of the week. This field takes values SUNDAY, jpayne@69: * MONDAY, TUESDAY, WEDNESDAY, jpayne@69: * THURSDAY, FRIDAY, and SATURDAY. jpayne@69: * @see #UCAL_SUNDAY jpayne@69: * @see #UCAL_MONDAY jpayne@69: * @see #UCAL_TUESDAY jpayne@69: * @see #UCAL_WEDNESDAY jpayne@69: * @see #UCAL_THURSDAY jpayne@69: * @see #UCAL_FRIDAY jpayne@69: * @see #UCAL_SATURDAY jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_DAY_OF_WEEK, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * ordinal number of the day of the week within the current month. Together jpayne@69: * with the DAY_OF_WEEK field, this uniquely specifies a day jpayne@69: * within a month. Unlike WEEK_OF_MONTH and jpayne@69: * WEEK_OF_YEAR, this field's value does not depend on jpayne@69: * getFirstDayOfWeek() or jpayne@69: * getMinimalDaysInFirstWeek(). DAY_OF_MONTH 1 jpayne@69: * through 7 always correspond to DAY_OF_WEEK_IN_MONTH jpayne@69: * 1; 8 through 15 correspond to jpayne@69: * DAY_OF_WEEK_IN_MONTH 2, and so on. jpayne@69: * DAY_OF_WEEK_IN_MONTH 0 indicates the week before jpayne@69: * DAY_OF_WEEK_IN_MONTH 1. Negative values count back from the jpayne@69: * end of the month, so the last Sunday of a month is specified as jpayne@69: * DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1. Because jpayne@69: * negative values count backward they will usually be aligned differently jpayne@69: * within the month than positive values. For example, if a month has 31 jpayne@69: * days, DAY_OF_WEEK_IN_MONTH -1 will overlap jpayne@69: * DAY_OF_WEEK_IN_MONTH 5 and the end of 4. jpayne@69: * @see #UCAL_DAY_OF_WEEK jpayne@69: * @see #UCAL_WEEK_OF_MONTH jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_DAY_OF_WEEK_IN_MONTH, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating jpayne@69: * whether the HOUR is before or after noon. jpayne@69: * E.g., at 10:04:15.250 PM the AM_PM is PM. jpayne@69: * @see #UCAL_AM jpayne@69: * @see #UCAL_PM jpayne@69: * @see #UCAL_HOUR jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_AM_PM, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * hour of the morning or afternoon. HOUR is used for the 12-hour jpayne@69: * clock. jpayne@69: * E.g., at 10:04:15.250 PM the HOUR is 10. jpayne@69: * @see #UCAL_AM_PM jpayne@69: * @see #UCAL_HOUR_OF_DAY jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_HOUR, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * hour of the day. HOUR_OF_DAY is used for the 24-hour clock. jpayne@69: * E.g., at 10:04:15.250 PM the HOUR_OF_DAY is 22. jpayne@69: * @see #UCAL_HOUR jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_HOUR_OF_DAY, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * minute within the hour. jpayne@69: * E.g., at 10:04:15.250 PM the UCAL_MINUTE is 4. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_MINUTE, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * second within the minute. jpayne@69: * E.g., at 10:04:15.250 PM the UCAL_SECOND is 15. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_SECOND, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * millisecond within the second. jpayne@69: * E.g., at 10:04:15.250 PM the UCAL_MILLISECOND is 250. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_MILLISECOND, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * raw offset from GMT in milliseconds. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_ZONE_OFFSET, jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * daylight savings offset in milliseconds. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_DST_OFFSET, jpayne@69: jpayne@69: /** jpayne@69: * Field number jpayne@69: * indicating the extended year corresponding to the jpayne@69: * UCAL_WEEK_OF_YEAR field. This may be one greater or less jpayne@69: * than the value of UCAL_EXTENDED_YEAR. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_YEAR_WOY, jpayne@69: jpayne@69: /** jpayne@69: * Field number jpayne@69: * indicating the localized day of week. This will be a value from 1 jpayne@69: * to 7 inclusive, with 1 being the localized first day of the week. jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: UCAL_DOW_LOCAL, jpayne@69: jpayne@69: /** jpayne@69: * Year of this calendar system, encompassing all supra-year fields. For example, jpayne@69: * in Gregorian/Julian calendars, positive Extended Year values indicate years AD, jpayne@69: * 1 BC = 0 extended, 2 BC = -1 extended, and so on. jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: UCAL_EXTENDED_YEAR, jpayne@69: jpayne@69: /** jpayne@69: * Field number jpayne@69: * indicating the modified Julian day number. This is different from jpayne@69: * the conventional Julian day number in two regards. First, it jpayne@69: * demarcates days at local zone midnight, rather than noon GMT. jpayne@69: * Second, it is a local number; that is, it depends on the local time jpayne@69: * zone. It can be thought of as a single number that encompasses all jpayne@69: * the date-related fields. jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: UCAL_JULIAN_DAY, jpayne@69: jpayne@69: /** jpayne@69: * Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves exactly jpayne@69: * like a composite of all time-related fields, not including the zone fields. As such, jpayne@69: * it also reflects discontinuities of those fields on DST transition days. On a day jpayne@69: * of DST onset, it will jump forward. On a day of DST cessation, it will jump jpayne@69: * backward. This reflects the fact that it must be combined with the DST_OFFSET field jpayne@69: * to obtain a unique local time value. jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: UCAL_MILLISECONDS_IN_DAY, jpayne@69: jpayne@69: /** jpayne@69: * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for jpayne@69: * an example of this. jpayne@69: */ jpayne@69: UCAL_IS_LEAP_MONTH, jpayne@69: jpayne@69: /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, jpayne@69: * it is needed for layout of Calendar, DateFormat, and other objects */ jpayne@69: #ifndef U_FORCE_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * One more than the highest normal UCalendarDateFields value. jpayne@69: * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. jpayne@69: */ jpayne@69: UCAL_FIELD_COUNT, jpayne@69: #endif // U_FORCE_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /** jpayne@69: * Field number indicating the jpayne@69: * day of the month. This is a synonym for UCAL_DATE. jpayne@69: * The first day of the month has value 1. jpayne@69: * @see #UCAL_DATE jpayne@69: * Synonym for UCAL_DATE jpayne@69: * @stable ICU 2.8 jpayne@69: **/ jpayne@69: UCAL_DAY_OF_MONTH=UCAL_DATE jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef enum UCalendarDateFields UCalendarDateFields; jpayne@69: /** jpayne@69: * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients jpayne@69: * who create locale resources for the field of first-day-of-week should be aware of jpayne@69: * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY. jpayne@69: */ jpayne@69: /** Possible days of the week in a UCalendar jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum UCalendarDaysOfWeek { jpayne@69: /** Sunday */ jpayne@69: UCAL_SUNDAY = 1, jpayne@69: /** Monday */ jpayne@69: UCAL_MONDAY, jpayne@69: /** Tuesday */ jpayne@69: UCAL_TUESDAY, jpayne@69: /** Wednesday */ jpayne@69: UCAL_WEDNESDAY, jpayne@69: /** Thursday */ jpayne@69: UCAL_THURSDAY, jpayne@69: /** Friday */ jpayne@69: UCAL_FRIDAY, jpayne@69: /** Saturday */ jpayne@69: UCAL_SATURDAY jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek; jpayne@69: jpayne@69: /** Possible months in a UCalendar. Note: Calendar month is 0-based. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum UCalendarMonths { jpayne@69: /** January */ jpayne@69: UCAL_JANUARY, jpayne@69: /** February */ jpayne@69: UCAL_FEBRUARY, jpayne@69: /** March */ jpayne@69: UCAL_MARCH, jpayne@69: /** April */ jpayne@69: UCAL_APRIL, jpayne@69: /** May */ jpayne@69: UCAL_MAY, jpayne@69: /** June */ jpayne@69: UCAL_JUNE, jpayne@69: /** July */ jpayne@69: UCAL_JULY, jpayne@69: /** August */ jpayne@69: UCAL_AUGUST, jpayne@69: /** September */ jpayne@69: UCAL_SEPTEMBER, jpayne@69: /** October */ jpayne@69: UCAL_OCTOBER, jpayne@69: /** November */ jpayne@69: UCAL_NOVEMBER, jpayne@69: /** December */ jpayne@69: UCAL_DECEMBER, jpayne@69: /** Value of the UCAL_MONTH field indicating the jpayne@69: * thirteenth month of the year. Although the Gregorian calendar jpayne@69: * does not use this value, lunar calendars do. jpayne@69: */ jpayne@69: UCAL_UNDECIMBER jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef enum UCalendarMonths UCalendarMonths; jpayne@69: jpayne@69: /** Possible AM/PM values in a UCalendar jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum UCalendarAMPMs { jpayne@69: /** AM */ jpayne@69: UCAL_AM, jpayne@69: /** PM */ jpayne@69: UCAL_PM jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef enum UCalendarAMPMs UCalendarAMPMs; jpayne@69: jpayne@69: /** jpayne@69: * System time zone type constants used by filtering zones jpayne@69: * in ucal_openTimeZoneIDEnumeration. jpayne@69: * @see ucal_openTimeZoneIDEnumeration jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: enum USystemTimeZoneType { jpayne@69: /** jpayne@69: * Any system zones. jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: UCAL_ZONE_TYPE_ANY, jpayne@69: /** jpayne@69: * Canonical system zones. jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: UCAL_ZONE_TYPE_CANONICAL, jpayne@69: /** jpayne@69: * Canonical system zones associated with actual locations. jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: UCAL_ZONE_TYPE_CANONICAL_LOCATION jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 4.8 */ jpayne@69: typedef enum USystemTimeZoneType USystemTimeZoneType; jpayne@69: jpayne@69: /** jpayne@69: * Create an enumeration over system time zone IDs with the given jpayne@69: * filter conditions. jpayne@69: * @param zoneType The system time zone type. jpayne@69: * @param region The ISO 3166 two-letter country code or UN M.49 jpayne@69: * three-digit area code. When NULL, no filtering jpayne@69: * done by region. jpayne@69: * @param rawOffset An offset from GMT in milliseconds, ignoring the jpayne@69: * effect of daylight savings time, if any. When NULL, jpayne@69: * no filtering done by zone offset. jpayne@69: * @param ec A pointer to an UErrorCode to receive any errors jpayne@69: * @return an enumeration object that the caller must dispose of jpayne@69: * using enum_close(), or NULL upon failure. In case of failure, jpayne@69: * *ec will indicate the error. jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: U_STABLE UEnumeration* U_EXPORT2 jpayne@69: ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region, jpayne@69: const int32_t* rawOffset, UErrorCode* ec); jpayne@69: jpayne@69: /** jpayne@69: * Create an enumeration over all time zones. jpayne@69: * jpayne@69: * @param ec input/output error code jpayne@69: * jpayne@69: * @return an enumeration object that the caller must dispose of using jpayne@69: * uenum_close(), or NULL upon failure. In case of failure *ec will jpayne@69: * indicate the error. jpayne@69: * jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: U_STABLE UEnumeration* U_EXPORT2 jpayne@69: ucal_openTimeZones(UErrorCode* ec); jpayne@69: jpayne@69: /** jpayne@69: * Create an enumeration over all time zones associated with the given jpayne@69: * country. Some zones are affiliated with no country (e.g., "UTC"); jpayne@69: * these may also be retrieved, as a group. jpayne@69: * jpayne@69: * @param country the ISO 3166 two-letter country code, or NULL to jpayne@69: * retrieve zones not affiliated with any country jpayne@69: * jpayne@69: * @param ec input/output error code jpayne@69: * jpayne@69: * @return an enumeration object that the caller must dispose of using jpayne@69: * uenum_close(), or NULL upon failure. In case of failure *ec will jpayne@69: * indicate the error. jpayne@69: * jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: U_STABLE UEnumeration* U_EXPORT2 jpayne@69: ucal_openCountryTimeZones(const char* country, UErrorCode* ec); jpayne@69: jpayne@69: /** jpayne@69: * Return the default time zone. The default is determined initially jpayne@69: * by querying the host operating system. If the host system detection jpayne@69: * routines fail, or if they specify a TimeZone or TimeZone offset jpayne@69: * which is not recognized, then the special TimeZone "Etc/Unknown" jpayne@69: * is returned. jpayne@69: * jpayne@69: * The default may be changed with `ucal_setDefaultTimeZone()` or with jpayne@69: * the C++ TimeZone API, `TimeZone::adoptDefault(TimeZone*)`. jpayne@69: * jpayne@69: * @param result A buffer to receive the result, or NULL jpayne@69: * jpayne@69: * @param resultCapacity The capacity of the result buffer jpayne@69: * jpayne@69: * @param ec input/output error code jpayne@69: * jpayne@69: * @return The result string length, not including the terminating jpayne@69: * null jpayne@69: * jpayne@69: * @see #UCAL_UNKNOWN_ZONE_ID jpayne@69: * jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec); jpayne@69: jpayne@69: /** jpayne@69: * Set the default time zone. jpayne@69: * jpayne@69: * @param zoneID null-terminated time zone ID jpayne@69: * jpayne@69: * @param ec input/output error code jpayne@69: * jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec); jpayne@69: jpayne@69: #ifndef U_HIDE_DRAFT_API jpayne@69: jpayne@69: /** jpayne@69: * Return the current host time zone. The host time zone is detected from jpayne@69: * the current host system configuration by querying the host operating jpayne@69: * system. If the host system detection routines fail, or if they specify jpayne@69: * a TimeZone or TimeZone offset which is not recognized, then the special jpayne@69: * TimeZone "Etc/Unknown" is returned. jpayne@69: * jpayne@69: * Note that host time zone and the ICU default time zone can be different. jpayne@69: * jpayne@69: * The ICU default time zone does not change once initialized unless modified jpayne@69: * by calling `ucal_setDefaultTimeZone()` or with the C++ TimeZone API, jpayne@69: * `TimeZone::adoptDefault(TimeZone*)`. jpayne@69: * jpayne@69: * If the host operating system configuration has changed since ICU has jpayne@69: * initialized then the returned value can be different than the ICU default jpayne@69: * time zone, even if the default has not changed. jpayne@69: * jpayne@69: *

This function is not thread safe.

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

jpayne@69: * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown", jpayne@69: * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID jpayne@69: * UCAL_UNKNOWN_ZONE_ID ("Etc/Unknown") without any errors/warnings. If you want jpayne@69: * to check if a TimeZone ID is valid prior to this function, use ucal_getCanonicalTimeZoneID. jpayne@69: * jpayne@69: * @param zoneID The desired TimeZone ID. If 0, use the default time zone. jpayne@69: * @param len The length of zoneID, or -1 if null-terminated. jpayne@69: * @param locale The desired locale jpayne@69: * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian jpayne@69: * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the jpayne@69: * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the jpayne@69: * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale jpayne@69: * and then pass the locale to ucal_open with UCAL_DEFAULT as the type. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @return A pointer to a UCalendar, or 0 if an error occurred. jpayne@69: * @see #UCAL_UNKNOWN_ZONE_ID jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UCalendar* U_EXPORT2 jpayne@69: ucal_open(const UChar* zoneID, jpayne@69: int32_t len, jpayne@69: const char* locale, jpayne@69: UCalendarType type, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Close a UCalendar. jpayne@69: * Once closed, a UCalendar may no longer be used. jpayne@69: * @param cal The UCalendar to close. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_close(UCalendar *cal); jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * \class LocalUCalendarPointer jpayne@69: * "Smart pointer" class, closes a UCalendar via ucal_close(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close); jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * Open a copy of a UCalendar. jpayne@69: * This function performs a deep copy. jpayne@69: * @param cal The calendar to copy jpayne@69: * @param status A pointer to an UErrorCode to receive any errors. jpayne@69: * @return A pointer to a UCalendar identical to cal. jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: U_STABLE UCalendar* U_EXPORT2 jpayne@69: ucal_clone(const UCalendar* cal, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Set the TimeZone used by a UCalendar. jpayne@69: * A UCalendar uses a timezone for converting from Greenwich time to local time. jpayne@69: * @param cal The UCalendar to set. jpayne@69: * @param zoneID The desired TimeZone ID. If 0, use the default time zone. jpayne@69: * @param len The length of zoneID, or -1 if null-terminated. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_setTimeZone(UCalendar* cal, jpayne@69: const UChar* zoneID, jpayne@69: int32_t len, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Get the ID of the UCalendar's time zone. jpayne@69: * jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param result Receives the UCalendar's time zone ID. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param status Receives the status. jpayne@69: * @return The total buffer size needed; if greater than resultLength, the output was truncated. jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getTimeZoneID(const UCalendar *cal, jpayne@69: UChar *result, jpayne@69: int32_t resultLength, jpayne@69: UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Possible formats for a UCalendar's display name jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum UCalendarDisplayNameType { jpayne@69: /** Standard display name */ jpayne@69: UCAL_STANDARD, jpayne@69: /** Short standard display name */ jpayne@69: UCAL_SHORT_STANDARD, jpayne@69: /** Daylight savings display name */ jpayne@69: UCAL_DST, jpayne@69: /** Short daylight savings display name */ jpayne@69: UCAL_SHORT_DST jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef enum UCalendarDisplayNameType UCalendarDisplayNameType; jpayne@69: jpayne@69: /** jpayne@69: * Get the display name for a UCalendar's TimeZone. jpayne@69: * A display name is suitable for presentation to a user. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD, jpayne@69: * UCAL_DST, UCAL_SHORT_DST jpayne@69: * @param locale The desired locale for the display name. jpayne@69: * @param result A pointer to a buffer to receive the formatted number. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @return The total buffer size needed; if greater than resultLength, the output was truncated. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getTimeZoneDisplayName(const UCalendar* cal, jpayne@69: UCalendarDisplayNameType type, jpayne@69: const char* locale, jpayne@69: UChar* result, jpayne@69: int32_t resultLength, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Determine if a UCalendar is currently in daylight savings time. jpayne@69: * Daylight savings time is not used in all parts of the world. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @return TRUE if cal is currently in daylight savings time, FALSE otherwise jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UBool U_EXPORT2 jpayne@69: ucal_inDaylightTime(const UCalendar* cal, jpayne@69: UErrorCode* status ); jpayne@69: jpayne@69: /** jpayne@69: * Sets the GregorianCalendar change date. This is the point when the switch from jpayne@69: * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October jpayne@69: * 15, 1582. Previous to this time and date will be Julian dates. jpayne@69: * jpayne@69: * This function works only for Gregorian calendars. If the UCalendar is not jpayne@69: * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR jpayne@69: * error code is set. jpayne@69: * jpayne@69: * @param cal The calendar object. jpayne@69: * @param date The given Gregorian cutover date. jpayne@69: * @param pErrorCode Pointer to a standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * jpayne@69: * @see GregorianCalendar::setGregorianChange jpayne@69: * @see ucal_getGregorianChange jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Gets the Gregorian Calendar change date. This is the point when the switch from jpayne@69: * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October jpayne@69: * 15, 1582. Previous to this time and date will be Julian dates. jpayne@69: * jpayne@69: * This function works only for Gregorian calendars. If the UCalendar is not jpayne@69: * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR jpayne@69: * error code is set. jpayne@69: * jpayne@69: * @param cal The calendar object. jpayne@69: * @param pErrorCode Pointer to a standard ICU error code. Its input value must jpayne@69: * pass the U_SUCCESS() test, or else the function returns jpayne@69: * immediately. Check for U_FAILURE() on output or use with jpayne@69: * function chaining. (See User Guide for details.) jpayne@69: * @return The Gregorian cutover time for this calendar. jpayne@69: * jpayne@69: * @see GregorianCalendar::getGregorianChange jpayne@69: * @see ucal_setGregorianChange jpayne@69: * @stable ICU 3.6 jpayne@69: */ jpayne@69: U_STABLE UDate U_EXPORT2 jpayne@69: ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Types of UCalendar attributes jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum UCalendarAttribute { jpayne@69: /** jpayne@69: * Lenient parsing jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UCAL_LENIENT, jpayne@69: /** jpayne@69: * First day of week jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UCAL_FIRST_DAY_OF_WEEK, jpayne@69: /** jpayne@69: * Minimum number of days in first week jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, jpayne@69: /** jpayne@69: * The behavior for handling wall time repeating multiple times jpayne@69: * at negative time zone offset transitions jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: UCAL_REPEATED_WALL_TIME, jpayne@69: /** jpayne@69: * The behavior for handling skipped wall time at positive time jpayne@69: * zone offset transitions. jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: UCAL_SKIPPED_WALL_TIME jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef enum UCalendarAttribute UCalendarAttribute; jpayne@69: jpayne@69: /** jpayne@69: * Options for handling ambiguous wall time at time zone jpayne@69: * offset transitions. jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: enum UCalendarWallTimeOption { jpayne@69: /** jpayne@69: * An ambiguous wall time to be interpreted as the latest. jpayne@69: * This option is valid for UCAL_REPEATED_WALL_TIME and jpayne@69: * UCAL_SKIPPED_WALL_TIME. jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: UCAL_WALLTIME_LAST, jpayne@69: /** jpayne@69: * An ambiguous wall time to be interpreted as the earliest. jpayne@69: * This option is valid for UCAL_REPEATED_WALL_TIME and jpayne@69: * UCAL_SKIPPED_WALL_TIME. jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: UCAL_WALLTIME_FIRST, jpayne@69: /** jpayne@69: * An ambiguous wall time to be interpreted as the next valid jpayne@69: * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME. jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: UCAL_WALLTIME_NEXT_VALID jpayne@69: }; jpayne@69: /** @stable ICU 49 */ jpayne@69: typedef enum UCalendarWallTimeOption UCalendarWallTimeOption; jpayne@69: jpayne@69: /** jpayne@69: * Get a numeric attribute associated with a UCalendar. jpayne@69: * Numeric attributes include the first day of the week, or the minimal numbers jpayne@69: * of days in the first week of the month. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, jpayne@69: * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME jpayne@69: * @return The value of attr. jpayne@69: * @see ucal_setAttribute jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getAttribute(const UCalendar* cal, jpayne@69: UCalendarAttribute attr); jpayne@69: jpayne@69: /** jpayne@69: * Set a numeric attribute associated with a UCalendar. jpayne@69: * Numeric attributes include the first day of the week, or the minimal numbers jpayne@69: * of days in the first week of the month. jpayne@69: * @param cal The UCalendar to set. jpayne@69: * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, jpayne@69: * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME jpayne@69: * @param newValue The new value of attr. jpayne@69: * @see ucal_getAttribute jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_setAttribute(UCalendar* cal, jpayne@69: UCalendarAttribute attr, jpayne@69: int32_t newValue); jpayne@69: jpayne@69: /** jpayne@69: * Get a locale for which calendars are available. jpayne@69: * A UCalendar in a locale returned by this function will contain the correct jpayne@69: * day and month names for the locale. jpayne@69: * @param localeIndex The index of the desired locale. jpayne@69: * @return A locale for which calendars are available, or 0 if none. jpayne@69: * @see ucal_countAvailable jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE const char* U_EXPORT2 jpayne@69: ucal_getAvailable(int32_t localeIndex); jpayne@69: jpayne@69: /** jpayne@69: * Determine how many locales have calendars available. jpayne@69: * This function is most useful as determining the loop ending condition for jpayne@69: * calls to \ref ucal_getAvailable. jpayne@69: * @return The number of locales for which calendars are available. jpayne@69: * @see ucal_getAvailable jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_countAvailable(void); jpayne@69: jpayne@69: /** jpayne@69: * Get a UCalendar's current time in millis. jpayne@69: * The time is represented as milliseconds from the epoch. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @return The calendar's current time in millis. jpayne@69: * @see ucal_setMillis jpayne@69: * @see ucal_setDate jpayne@69: * @see ucal_setDateTime jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UDate U_EXPORT2 jpayne@69: ucal_getMillis(const UCalendar* cal, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Set a UCalendar's current time in millis. jpayne@69: * The time is represented as milliseconds from the epoch. jpayne@69: * @param cal The UCalendar to set. jpayne@69: * @param dateTime The desired date and time. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @see ucal_getMillis jpayne@69: * @see ucal_setDate jpayne@69: * @see ucal_setDateTime jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_setMillis(UCalendar* cal, jpayne@69: UDate dateTime, jpayne@69: UErrorCode* status ); jpayne@69: jpayne@69: /** jpayne@69: * Set a UCalendar's current date. jpayne@69: * The date is represented as a series of 32-bit integers. jpayne@69: * @param cal The UCalendar to set. jpayne@69: * @param year The desired year. jpayne@69: * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, jpayne@69: * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER jpayne@69: * @param date The desired day of the month. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @see ucal_getMillis jpayne@69: * @see ucal_setMillis jpayne@69: * @see ucal_setDateTime jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_setDate(UCalendar* cal, jpayne@69: int32_t year, jpayne@69: int32_t month, jpayne@69: int32_t date, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Set a UCalendar's current date. jpayne@69: * The date is represented as a series of 32-bit integers. jpayne@69: * @param cal The UCalendar to set. jpayne@69: * @param year The desired year. jpayne@69: * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, jpayne@69: * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER jpayne@69: * @param date The desired day of the month. jpayne@69: * @param hour The desired hour of day. jpayne@69: * @param minute The desired minute. jpayne@69: * @param second The desirec second. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @see ucal_getMillis jpayne@69: * @see ucal_setMillis jpayne@69: * @see ucal_setDate jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_setDateTime(UCalendar* cal, jpayne@69: int32_t year, jpayne@69: int32_t month, jpayne@69: int32_t date, jpayne@69: int32_t hour, jpayne@69: int32_t minute, jpayne@69: int32_t second, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Returns TRUE if two UCalendars are equivalent. Equivalent jpayne@69: * UCalendars will behave identically, but they may be set to jpayne@69: * different times. jpayne@69: * @param cal1 The first of the UCalendars to compare. jpayne@69: * @param cal2 The second of the UCalendars to compare. jpayne@69: * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UBool U_EXPORT2 jpayne@69: ucal_equivalentTo(const UCalendar* cal1, jpayne@69: const UCalendar* cal2); jpayne@69: jpayne@69: /** jpayne@69: * Add a specified signed amount to a particular field in a UCalendar. jpayne@69: * This can modify more significant fields in the calendar. jpayne@69: * Adding a positive value always means moving forward in time, so for the Gregorian calendar, jpayne@69: * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces jpayne@69: * the numeric value of the field itself). jpayne@69: * @param cal The UCalendar to which to add. jpayne@69: * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, jpayne@69: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, jpayne@69: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, jpayne@69: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. jpayne@69: * @param amount The signed amount to add to field. If the amount causes the value jpayne@69: * to exceed to maximum or minimum values for that field, other fields are modified jpayne@69: * to preserve the magnitude of the change. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @see ucal_roll jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_add(UCalendar* cal, jpayne@69: UCalendarDateFields field, jpayne@69: int32_t amount, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Add a specified signed amount to a particular field in a UCalendar. jpayne@69: * This will not modify more significant fields in the calendar. jpayne@69: * Rolling by a positive value always means moving forward in time (unless the limit of the jpayne@69: * field is reached, in which case it may pin or wrap), so for Gregorian calendar, jpayne@69: * starting with 100 BC and rolling the year by +1 results in 99 BC. jpayne@69: * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the jpayne@69: * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around. jpayne@69: * When eras only have a limit at one end, then attempting to roll the year past that limit will result in jpayne@69: * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time jpayne@69: * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for jpayne@69: * era 0 (that is the only way to represent years before the calendar epoch). jpayne@69: * @param cal The UCalendar to which to add. jpayne@69: * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, jpayne@69: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, jpayne@69: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, jpayne@69: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. jpayne@69: * @param amount The signed amount to add to field. If the amount causes the value jpayne@69: * to exceed to maximum or minimum values for that field, the field is pinned to a permissible jpayne@69: * value. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @see ucal_add jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_roll(UCalendar* cal, jpayne@69: UCalendarDateFields field, jpayne@69: int32_t amount, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Get the current value of a field from a UCalendar. jpayne@69: * All fields are represented as 32-bit integers. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, jpayne@69: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, jpayne@69: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, jpayne@69: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @return The value of the desired field. jpayne@69: * @see ucal_set jpayne@69: * @see ucal_isSet jpayne@69: * @see ucal_clearField jpayne@69: * @see ucal_clear jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_get(const UCalendar* cal, jpayne@69: UCalendarDateFields field, jpayne@69: UErrorCode* status ); jpayne@69: jpayne@69: /** jpayne@69: * Set the value of a field in a UCalendar. jpayne@69: * All fields are represented as 32-bit integers. jpayne@69: * @param cal The UCalendar to set. jpayne@69: * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, jpayne@69: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, jpayne@69: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, jpayne@69: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. jpayne@69: * @param value The desired value of field. jpayne@69: * @see ucal_get jpayne@69: * @see ucal_isSet jpayne@69: * @see ucal_clearField jpayne@69: * @see ucal_clear jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_set(UCalendar* cal, jpayne@69: UCalendarDateFields field, jpayne@69: int32_t value); jpayne@69: jpayne@69: /** jpayne@69: * Determine if a field in a UCalendar is set. jpayne@69: * All fields are represented as 32-bit integers. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, jpayne@69: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, jpayne@69: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, jpayne@69: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. jpayne@69: * @return TRUE if field is set, FALSE otherwise. jpayne@69: * @see ucal_get jpayne@69: * @see ucal_set jpayne@69: * @see ucal_clearField jpayne@69: * @see ucal_clear jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UBool U_EXPORT2 jpayne@69: ucal_isSet(const UCalendar* cal, jpayne@69: UCalendarDateFields field); jpayne@69: jpayne@69: /** jpayne@69: * Clear a field in a UCalendar. jpayne@69: * All fields are represented as 32-bit integers. jpayne@69: * @param cal The UCalendar containing the field to clear. jpayne@69: * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, jpayne@69: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, jpayne@69: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, jpayne@69: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. jpayne@69: * @see ucal_get jpayne@69: * @see ucal_set jpayne@69: * @see ucal_isSet jpayne@69: * @see ucal_clear jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_clearField(UCalendar* cal, jpayne@69: UCalendarDateFields field); jpayne@69: jpayne@69: /** jpayne@69: * Clear all fields in a UCalendar. jpayne@69: * All fields are represented as 32-bit integers. jpayne@69: * @param calendar The UCalendar to clear. jpayne@69: * @see ucal_get jpayne@69: * @see ucal_set jpayne@69: * @see ucal_isSet jpayne@69: * @see ucal_clearField jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ucal_clear(UCalendar* calendar); jpayne@69: jpayne@69: /** jpayne@69: * Possible limit values for a UCalendar jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: enum UCalendarLimitType { jpayne@69: /** Minimum value */ jpayne@69: UCAL_MINIMUM, jpayne@69: /** Maximum value */ jpayne@69: UCAL_MAXIMUM, jpayne@69: /** Greatest minimum value */ jpayne@69: UCAL_GREATEST_MINIMUM, jpayne@69: /** Leaest maximum value */ jpayne@69: UCAL_LEAST_MAXIMUM, jpayne@69: /** Actual minimum value */ jpayne@69: UCAL_ACTUAL_MINIMUM, jpayne@69: /** Actual maximum value */ jpayne@69: UCAL_ACTUAL_MAXIMUM jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 2.0 */ jpayne@69: typedef enum UCalendarLimitType UCalendarLimitType; jpayne@69: jpayne@69: /** jpayne@69: * Determine a limit for a field in a UCalendar. jpayne@69: * A limit is a maximum or minimum value for a field. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, jpayne@69: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, jpayne@69: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, jpayne@69: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. jpayne@69: * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM, jpayne@69: * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM jpayne@69: * @param status A pointer to an UErrorCode to receive any errors. jpayne@69: * @return The requested value. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getLimit(const UCalendar* cal, jpayne@69: UCalendarDateFields field, jpayne@69: UCalendarLimitType type, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** Get the locale for this calendar object. You can choose between valid and actual locale. jpayne@69: * @param cal The calendar object jpayne@69: * @param type type of the locale we're looking for (valid or actual) jpayne@69: * @param status error code for the operation jpayne@69: * @return the locale name jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: U_STABLE const char * U_EXPORT2 jpayne@69: ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Returns the timezone data version currently used by ICU. jpayne@69: * @param status error code for the operation jpayne@69: * @return the version string, such as "2007f" jpayne@69: * @stable ICU 3.8 jpayne@69: */ jpayne@69: U_STABLE const char * U_EXPORT2 jpayne@69: ucal_getTZDataVersion(UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Returns the canonical system timezone ID or the normalized jpayne@69: * custom time zone ID for the given time zone ID. jpayne@69: * @param id The input timezone ID to be canonicalized. jpayne@69: * @param len The length of id, or -1 if null-terminated. jpayne@69: * @param result The buffer receives the canonical system timezone ID jpayne@69: * or the custom timezone ID in normalized format. jpayne@69: * @param resultCapacity The capacity of the result buffer. jpayne@69: * @param isSystemID Receives if the given ID is a known system jpayne@69: * timezone ID. jpayne@69: * @param status Receives the status. When the given timezone ID jpayne@69: * is neither a known system time zone ID nor a jpayne@69: * valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR jpayne@69: * is set. jpayne@69: * @return The result string length, not including the terminating jpayne@69: * null. jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len, jpayne@69: UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status); jpayne@69: /** jpayne@69: * Get the resource keyword value string designating the calendar type for the UCalendar. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param status The error code for the operation. jpayne@69: * @return The resource keyword value string. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE const char * U_EXPORT2 jpayne@69: ucal_getType(const UCalendar *cal, UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Given a key and a locale, returns an array of string values in a preferred jpayne@69: * order that would make a difference. These are all and only those values where jpayne@69: * the open (creation) of the service with the locale formed from the input locale jpayne@69: * plus input keyword and that value has different behavior than creation with the jpayne@69: * input locale alone. jpayne@69: * @param key one of the keys supported by this service. For now, only jpayne@69: * "calendar" is supported. jpayne@69: * @param locale the locale jpayne@69: * @param commonlyUsed if set to true it will return only commonly used values jpayne@69: * with the given locale in preferred order. Otherwise, jpayne@69: * it will return all the available values for the locale. jpayne@69: * @param status error status jpayne@69: * @return a string enumeration over keyword values for the given key and the locale. jpayne@69: * @stable ICU 4.2 jpayne@69: */ jpayne@69: U_STABLE UEnumeration* U_EXPORT2 jpayne@69: ucal_getKeywordValuesForLocale(const char* key, jpayne@69: const char* locale, jpayne@69: UBool commonlyUsed, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: jpayne@69: /** Weekday types, as returned by ucal_getDayOfWeekType(). jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: enum UCalendarWeekdayType { jpayne@69: /** jpayne@69: * Designates a full weekday (no part of the day is included in the weekend). jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: UCAL_WEEKDAY, jpayne@69: /** jpayne@69: * Designates a full weekend day (the entire day is included in the weekend). jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: UCAL_WEEKEND, jpayne@69: /** jpayne@69: * Designates a day that starts as a weekday and transitions to the weekend. jpayne@69: * Call ucal_getWeekendTransition() to get the time of transition. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: UCAL_WEEKEND_ONSET, jpayne@69: /** jpayne@69: * Designates a day that starts as the weekend and transitions to a weekday. jpayne@69: * Call ucal_getWeekendTransition() to get the time of transition. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: UCAL_WEEKEND_CEASE jpayne@69: }; jpayne@69: jpayne@69: /** @stable ICU 4.4 */ jpayne@69: typedef enum UCalendarWeekdayType UCalendarWeekdayType; jpayne@69: jpayne@69: /** jpayne@69: * Returns whether the given day of the week is a weekday, a weekend day, jpayne@69: * or a day that transitions from one to the other, for the locale and jpayne@69: * calendar system associated with this UCalendar (the locale's region is jpayne@69: * often the most determinant factor). If a transition occurs at midnight, jpayne@69: * then the days before and after the transition will have the jpayne@69: * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time jpayne@69: * other than midnight, then the day of the transition will have jpayne@69: * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the jpayne@69: * function ucal_getWeekendTransition() will return the point of jpayne@69: * transition. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY). jpayne@69: * @param status The error code for the operation. jpayne@69: * @return The UCalendarWeekdayType for the day of the week. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE UCalendarWeekdayType U_EXPORT2 jpayne@69: ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Returns the time during the day at which the weekend begins or ends in jpayne@69: * this calendar system. If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET jpayne@69: * for the specified dayOfWeek, return the time at which the weekend begins. jpayne@69: * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek, jpayne@69: * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns jpayne@69: * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition jpayne@69: * (U_ILLEGAL_ARGUMENT_ERROR). jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param dayOfWeek The day of the week for which the weekend transition time is jpayne@69: * desired (UCAL_SUNDAY..UCAL_SATURDAY). jpayne@69: * @param status The error code for the operation. jpayne@69: * @return The milliseconds after midnight at which the weekend begins or ends. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Returns TRUE if the given UDate is in the weekend in jpayne@69: * this calendar system. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param date The UDate in question. jpayne@69: * @param status The error code for the operation. jpayne@69: * @return TRUE if the given UDate is in the weekend in jpayne@69: * this calendar system, FALSE otherwise. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE UBool U_EXPORT2 jpayne@69: ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Return the difference between the target time and the time this calendar object is currently set to. jpayne@69: * If the target time is after the current calendar setting, the the returned value will be positive. jpayne@69: * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH jpayne@69: * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the jpayne@69: * current calendar setting. jpayne@69: * jpayne@69: * As a side effect of this call, this calendar is advanced toward target by the given amount. That is, jpayne@69: * calling this function has the side effect of calling ucal_add on this calendar with the specified jpayne@69: * field and an amount equal to the return value from this function. jpayne@69: * jpayne@69: * A typical way of using this function is to call it first with the largest field of interest, then jpayne@69: * with progressively smaller fields. jpayne@69: * jpayne@69: * @param cal The UCalendar to compare and update. jpayne@69: * @param target The target date to compare to the current calendar setting. jpayne@69: * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, jpayne@69: * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, jpayne@69: * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, jpayne@69: * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. jpayne@69: * @param status A pointer to an UErrorCode to receive any errors jpayne@69: * @return The date difference for the specified field. jpayne@69: * @stable ICU 4.8 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getFieldDifference(UCalendar* cal, jpayne@69: UDate target, jpayne@69: UCalendarDateFields field, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Time zone transition types for ucal_getTimeZoneTransitionDate jpayne@69: * @stable ICU 50 jpayne@69: */ jpayne@69: enum UTimeZoneTransitionType { jpayne@69: /** jpayne@69: * Get the next transition after the current date, jpayne@69: * i.e. excludes the current date jpayne@69: * @stable ICU 50 jpayne@69: */ jpayne@69: UCAL_TZ_TRANSITION_NEXT, jpayne@69: /** jpayne@69: * Get the next transition on or after the current date, jpayne@69: * i.e. may include the current date jpayne@69: * @stable ICU 50 jpayne@69: */ jpayne@69: UCAL_TZ_TRANSITION_NEXT_INCLUSIVE, jpayne@69: /** jpayne@69: * Get the previous transition before the current date, jpayne@69: * i.e. excludes the current date jpayne@69: * @stable ICU 50 jpayne@69: */ jpayne@69: UCAL_TZ_TRANSITION_PREVIOUS, jpayne@69: /** jpayne@69: * Get the previous transition on or before the current date, jpayne@69: * i.e. may include the current date jpayne@69: * @stable ICU 50 jpayne@69: */ jpayne@69: UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE jpayne@69: }; jpayne@69: jpayne@69: typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */ jpayne@69: jpayne@69: /** jpayne@69: * Get the UDate for the next/previous time zone transition relative to jpayne@69: * the calendar's current date, in the time zone to which the calendar jpayne@69: * is currently set. If there is no known time zone transition of the jpayne@69: * requested type relative to the calendar's date, the function returns jpayne@69: * FALSE. jpayne@69: * @param cal The UCalendar to query. jpayne@69: * @param type The type of transition desired. jpayne@69: * @param transition A pointer to a UDate to be set to the transition time. jpayne@69: * If the function returns FALSE, the value set is unspecified. jpayne@69: * @param status A pointer to a UErrorCode to receive any errors. jpayne@69: * @return TRUE if a valid transition time is set in *transition, FALSE jpayne@69: * otherwise. jpayne@69: * @stable ICU 50 jpayne@69: */ jpayne@69: U_STABLE UBool U_EXPORT2 jpayne@69: ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type, jpayne@69: UDate* transition, UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Converts a system time zone ID to an equivalent Windows time zone ID. For example, jpayne@69: * Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles". jpayne@69: * jpayne@69: *

There are system time zones that cannot be mapped to Windows zones. When the input jpayne@69: * system time zone ID is unknown or unmappable to a Windows time zone, then this jpayne@69: * function returns 0 as the result length, but the operation itself remains successful jpayne@69: * (no error status set on return). jpayne@69: * jpayne@69: *

This implementation utilizes jpayne@69: * Zone-Tzid mapping data. The mapping data is updated time to time. To get the latest changes, jpayne@69: * please read the ICU user guide section jpayne@69: * Updating the Time Zone Data. jpayne@69: * jpayne@69: * @param id A system time zone ID. jpayne@69: * @param len The length of id, or -1 if null-terminated. jpayne@69: * @param winid A buffer to receive a Windows time zone ID. jpayne@69: * @param winidCapacity The capacity of the result buffer winid. jpayne@69: * @param status Receives the status. jpayne@69: * @return The result string length, not including the terminating null. jpayne@69: * @see ucal_getTimeZoneIDForWindowsID jpayne@69: * jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getWindowsTimeZoneID(const UChar* id, int32_t len, jpayne@69: UChar* winid, int32_t winidCapacity, UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Converts a Windows time zone ID to an equivalent system time zone ID jpayne@69: * for a region. For example, system time zone ID "America/Los_Angeles" is returned jpayne@69: * for input Windows ID "Pacific Standard Time" and region "US" (or null), jpayne@69: * "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and jpayne@69: * region "CA". jpayne@69: * jpayne@69: *

Not all Windows time zones can be mapped to system time zones. When the input jpayne@69: * Windows time zone ID is unknown or unmappable to a system time zone, then this jpayne@69: * function returns 0 as the result length, but the operation itself remains successful jpayne@69: * (no error status set on return). jpayne@69: * jpayne@69: *

This implementation utilizes jpayne@69: * Zone-Tzid mapping data. The mapping data is updated time to time. To get the latest changes, jpayne@69: * please read the ICU user guide section jpayne@69: * Updating the Time Zone Data. jpayne@69: * jpayne@69: * @param winid A Windows time zone ID. jpayne@69: * @param len The length of winid, or -1 if null-terminated. jpayne@69: * @param region A null-terminated region code, or NULL if no regional preference. jpayne@69: * @param id A buffer to receive a system time zone ID. jpayne@69: * @param idCapacity The capacity of the result buffer id. jpayne@69: * @param status Receives the status. jpayne@69: * @return The result string length, not including the terminating null. jpayne@69: * @see ucal_getWindowsTimeZoneID jpayne@69: * jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region, jpayne@69: UChar* id, int32_t idCapacity, UErrorCode* status); jpayne@69: jpayne@69: #endif /* #if !UCONFIG_NO_FORMATTING */ jpayne@69: jpayne@69: #endif