Home | History | Annotate | Download | only in unicode
      1 /*
      2  *******************************************************************************
      3  * Copyright (C) 1996-2015, International Business Machines Corporation and
      4  * others. All Rights Reserved.
      5  *******************************************************************************
      6  */
      7 
      8 #ifndef UCAL_H
      9 #define UCAL_H
     10 
     11 #include "unicode/utypes.h"
     12 #include "unicode/uenum.h"
     13 #include "unicode/uloc.h"
     14 #include "unicode/localpointer.h"
     15 
     16 #if !UCONFIG_NO_FORMATTING
     17 
     18 /**
     19  * \file
     20  * \brief C API: Calendar
     21  *
     22  * <h2>Calendar C API</h2>
     23  *
     24  * UCalendar C API is used  for converting between a <code>UDate</code> object
     25  * and a set of integer fields such as <code>UCAL_YEAR</code>, <code>UCAL_MONTH</code>,
     26  * <code>UCAL_DAY</code>, <code>UCAL_HOUR</code>, and so on.
     27  * (A <code>UDate</code> object represents a specific instant in
     28  * time with millisecond precision. See UDate
     29  * for information about the <code>UDate</code> .)
     30  *
     31  * <p>
     32  * Types of <code>UCalendar</code> interpret a <code>UDate</code>
     33  * according to the rules of a specific calendar system. The U_STABLE
     34  * provides the enum UCalendarType with UCAL_TRADITIONAL and
     35  * UCAL_GREGORIAN.
     36  * <p>
     37  * Like other locale-sensitive C API, calendar API  provides a
     38  * function, <code>ucal_open()</code>, which returns a pointer to
     39  * <code>UCalendar</code> whose time fields have been initialized
     40  * with the current date and time. We need to specify the type of
     41  * calendar to be opened and the  timezoneId.
     42  * \htmlonly<blockquote>\endhtmlonly
     43  * <pre>
     44  * \code
     45  * UCalendar *caldef;
     46  * UChar *tzId;
     47  * UErrorCode status;
     48  * tzId=(UChar*)malloc(sizeof(UChar) * (strlen("PST") +1) );
     49  * u_uastrcpy(tzId, "PST");
     50  * caldef=ucal_open(tzID, u_strlen(tzID), NULL, UCAL_TRADITIONAL, &status);
     51  * \endcode
     52  * </pre>
     53  * \htmlonly</blockquote>\endhtmlonly
     54  *
     55  * <p>
     56  * A <code>UCalendar</code> object can produce all the time field values
     57  * needed to implement the date-time formatting for a particular language
     58  * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
     59  *
     60  * <p>
     61  * When computing a <code>UDate</code> from time fields, two special circumstances
     62  * may arise: there may be insufficient information to compute the
     63  * <code>UDate</code> (such as only year and month but no day in the month),
     64  * or there may be inconsistent information (such as "Tuesday, July 15, 1996"
     65  * -- July 15, 1996 is actually a Monday).
     66  *
     67  * <p>
     68  * <strong>Insufficient information.</strong> The calendar will use default
     69  * information to specify the missing fields. This may vary by calendar; for
     70  * the Gregorian calendar, the default for a field is the same as that of the
     71  * start of the epoch: i.e., UCAL_YEAR = 1970, UCAL_MONTH = JANUARY, UCAL_DATE = 1, etc.
     72  *
     73  * <p>
     74  * <strong>Inconsistent information.</strong> If fields conflict, the calendar
     75  * will give preference to fields set more recently. For example, when
     76  * determining the day, the calendar will look for one of the following
     77  * combinations of fields.  The most recent combination, as determined by the
     78  * most recently set single field, will be used.
     79  *
     80  * \htmlonly<blockquote>\endhtmlonly
     81  * <pre>
     82  * \code
     83  * UCAL_MONTH + UCAL_DAY_OF_MONTH
     84  * UCAL_MONTH + UCAL_WEEK_OF_MONTH + UCAL_DAY_OF_WEEK
     85  * UCAL_MONTH + UCAL_DAY_OF_WEEK_IN_MONTH + UCAL_DAY_OF_WEEK
     86  * UCAL_DAY_OF_YEAR
     87  * UCAL_DAY_OF_WEEK + UCAL_WEEK_OF_YEAR
     88  * \endcode
     89  * </pre>
     90  * \htmlonly</blockquote>\endhtmlonly
     91  *
     92  * For the time of day:
     93  *
     94  * \htmlonly<blockquote>\endhtmlonly
     95  * <pre>
     96  * \code
     97  * UCAL_HOUR_OF_DAY
     98  * UCAL_AM_PM + UCAL_HOUR
     99  * \endcode
    100  * </pre>
    101  * \htmlonly</blockquote>\endhtmlonly
    102  *
    103  * <p>
    104  * <strong>Note:</strong> for some non-Gregorian calendars, different
    105  * fields may be necessary for complete disambiguation. For example, a full
    106  * specification of the historial Arabic astronomical calendar requires year,
    107  * month, day-of-month <em>and</em> day-of-week in some cases.
    108  *
    109  * <p>
    110  * <strong>Note:</strong> There are certain possible ambiguities in
    111  * interpretation of certain singular times, which are resolved in the
    112  * following ways:
    113  * <ol>
    114  *     <li> 24:00:00 "belongs" to the following day. That is,
    115  *          23:59 on Dec 31, 1969 &lt; 24:00 on Jan 1, 1970 &lt; 24:01:00 on Jan 1, 1970
    116  *
    117  *     <li> Although historically not precise, midnight also belongs to "am",
    118  *          and noon belongs to "pm", so on the same day,
    119  *          12:00 am (midnight) &lt; 12:01 am, and 12:00 pm (noon) &lt; 12:01 pm
    120  * </ol>
    121  *
    122  * <p>
    123  * The date or time format strings are not part of the definition of a
    124  * calendar, as those must be modifiable or overridable by the user at
    125  * runtime. Use {@link icu::DateFormat}
    126  * to format dates.
    127  *
    128  * <p>
    129  * <code>Calendar</code> provides an API for field "rolling", where fields
    130  * can be incremented or decremented, but wrap around. For example, rolling the
    131  * month up in the date <code>December 12, <b>1996</b></code> results in
    132  * <code>January 12, <b>1996</b></code>.
    133  *
    134  * <p>
    135  * <code>Calendar</code> also provides a date arithmetic function for
    136  * adding the specified (signed) amount of time to a particular time field.
    137  * For example, subtracting 5 days from the date <code>September 12, 1996</code>
    138  * results in <code>September 7, 1996</code>.
    139  *
    140  * @stable ICU 2.0
    141  */
    142 
    143 /**
    144  * The time zone ID reserved for unknown time zone.
    145  * @stable ICU 4.8
    146  */
    147 #define UCAL_UNKNOWN_ZONE_ID "Etc/Unknown"
    148 
    149 /** A calendar.
    150  *  For usage in C programs.
    151  * @stable ICU 2.0
    152  */
    153 typedef void* UCalendar;
    154 
    155 /** Possible types of UCalendars
    156  * @stable ICU 2.0
    157  */
    158 enum UCalendarType {
    159   /**
    160    * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar,
    161    * which may be the Gregorian calendar or some other calendar.
    162    * @stable ICU 2.0
    163    */
    164   UCAL_TRADITIONAL,
    165   /**
    166    * A better name for UCAL_TRADITIONAL.
    167    * @stable ICU 4.2
    168    */
    169   UCAL_DEFAULT = UCAL_TRADITIONAL,
    170   /**
    171    * Unambiguously designates the Gregorian calendar for the locale.
    172    * @stable ICU 2.0
    173    */
    174   UCAL_GREGORIAN
    175 };
    176 
    177 /** @stable ICU 2.0 */
    178 typedef enum UCalendarType UCalendarType;
    179 
    180 /** Possible fields in a UCalendar
    181  * @stable ICU 2.0
    182  */
    183 enum UCalendarDateFields {
    184   /**
    185    * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar.
    186    * This is a calendar-specific value.
    187    * @stable ICU 2.6
    188    */
    189   UCAL_ERA,
    190 
    191   /**
    192    * Field number indicating the year. This is a calendar-specific value.
    193    * @stable ICU 2.6
    194    */
    195   UCAL_YEAR,
    196 
    197   /**
    198    * Field number indicating the month. This is a calendar-specific value.
    199    * The first month of the year is
    200    * <code>JANUARY</code>; the last depends on the number of months in a year.
    201    * @see #UCAL_JANUARY
    202    * @see #UCAL_FEBRUARY
    203    * @see #UCAL_MARCH
    204    * @see #UCAL_APRIL
    205    * @see #UCAL_MAY
    206    * @see #UCAL_JUNE
    207    * @see #UCAL_JULY
    208    * @see #UCAL_AUGUST
    209    * @see #UCAL_SEPTEMBER
    210    * @see #UCAL_OCTOBER
    211    * @see #UCAL_NOVEMBER
    212    * @see #UCAL_DECEMBER
    213    * @see #UCAL_UNDECIMBER
    214    * @stable ICU 2.6
    215    */
    216   UCAL_MONTH,
    217 
    218   /**
    219    * Field number indicating the
    220    * week number within the current year.  The first week of the year, as
    221    * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
    222    * attributes, has value 1.  Subclasses define
    223    * the value of <code>UCAL_WEEK_OF_YEAR</code> for days before the first week of
    224    * the year.
    225    * @see ucal_getAttribute
    226    * @see ucal_setAttribute
    227    * @stable ICU 2.6
    228    */
    229   UCAL_WEEK_OF_YEAR,
    230 
    231  /**
    232    * Field number indicating the
    233    * week number within the current month.  The first week of the month, as
    234    * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
    235    * attributes, has value 1.  Subclasses define
    236    * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
    237    * the month.
    238    * @see ucal_getAttribute
    239    * @see ucal_setAttribute
    240    * @see #UCAL_FIRST_DAY_OF_WEEK
    241    * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
    242    * @stable ICU 2.6
    243    */
    244   UCAL_WEEK_OF_MONTH,
    245 
    246  /**
    247    * Field number indicating the
    248    * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
    249    * The first day of the month has value 1.
    250    * @see #UCAL_DAY_OF_MONTH
    251    * @stable ICU 2.6
    252    */
    253   UCAL_DATE,
    254 
    255  /**
    256    * Field number indicating the day
    257    * number within the current year.  The first day of the year has value 1.
    258    * @stable ICU 2.6
    259    */
    260   UCAL_DAY_OF_YEAR,
    261 
    262  /**
    263    * Field number indicating the day
    264    * of the week.  This field takes values <code>SUNDAY</code>,
    265    * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
    266    * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
    267    * @see #UCAL_SUNDAY
    268    * @see #UCAL_MONDAY
    269    * @see #UCAL_TUESDAY
    270    * @see #UCAL_WEDNESDAY
    271    * @see #UCAL_THURSDAY
    272    * @see #UCAL_FRIDAY
    273    * @see #UCAL_SATURDAY
    274    * @stable ICU 2.6
    275    */
    276   UCAL_DAY_OF_WEEK,
    277 
    278  /**
    279    * Field number indicating the
    280    * ordinal number of the day of the week within the current month. Together
    281    * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
    282    * within a month.  Unlike <code>WEEK_OF_MONTH</code> and
    283    * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
    284    * <code>getFirstDayOfWeek()</code> or
    285    * <code>getMinimalDaysInFirstWeek()</code>.  <code>DAY_OF_MONTH 1</code>
    286    * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
    287    * 1</code>; <code>8</code> through <code>15</code> correspond to
    288    * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
    289    * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
    290    * <code>DAY_OF_WEEK_IN_MONTH 1</code>.  Negative values count back from the
    291    * end of the month, so the last Sunday of a month is specified as
    292    * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>.  Because
    293    * negative values count backward they will usually be aligned differently
    294    * within the month than positive values.  For example, if a month has 31
    295    * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
    296    * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
    297    * @see #UCAL_DAY_OF_WEEK
    298    * @see #UCAL_WEEK_OF_MONTH
    299    * @stable ICU 2.6
    300    */
    301   UCAL_DAY_OF_WEEK_IN_MONTH,
    302 
    303  /**
    304    * Field number indicating
    305    * whether the <code>HOUR</code> is before or after noon.
    306    * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
    307    * @see #UCAL_AM
    308    * @see #UCAL_PM
    309    * @see #UCAL_HOUR
    310    * @stable ICU 2.6
    311    */
    312   UCAL_AM_PM,
    313 
    314  /**
    315    * Field number indicating the
    316    * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour
    317    * clock.
    318    * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
    319    * @see #UCAL_AM_PM
    320    * @see #UCAL_HOUR_OF_DAY
    321    * @stable ICU 2.6
    322    */
    323   UCAL_HOUR,
    324 
    325  /**
    326    * Field number indicating the
    327    * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
    328    * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
    329    * @see #UCAL_HOUR
    330    * @stable ICU 2.6
    331    */
    332   UCAL_HOUR_OF_DAY,
    333 
    334  /**
    335    * Field number indicating the
    336    * minute within the hour.
    337    * E.g., at 10:04:15.250 PM the <code>UCAL_MINUTE</code> is 4.
    338    * @stable ICU 2.6
    339    */
    340   UCAL_MINUTE,
    341 
    342  /**
    343    * Field number indicating the
    344    * second within the minute.
    345    * E.g., at 10:04:15.250 PM the <code>UCAL_SECOND</code> is 15.
    346    * @stable ICU 2.6
    347    */
    348   UCAL_SECOND,
    349 
    350  /**
    351    * Field number indicating the
    352    * millisecond within the second.
    353    * E.g., at 10:04:15.250 PM the <code>UCAL_MILLISECOND</code> is 250.
    354    * @stable ICU 2.6
    355    */
    356   UCAL_MILLISECOND,
    357 
    358  /**
    359    * Field number indicating the
    360    * raw offset from GMT in milliseconds.
    361    * @stable ICU 2.6
    362    */
    363   UCAL_ZONE_OFFSET,
    364 
    365  /**
    366    * Field number indicating the
    367    * daylight savings offset in milliseconds.
    368    * @stable ICU 2.6
    369    */
    370   UCAL_DST_OFFSET,
    371 
    372  /**
    373    * Field number
    374    * indicating the extended year corresponding to the
    375    * <code>UCAL_WEEK_OF_YEAR</code> field.  This may be one greater or less
    376    * than the value of <code>UCAL_EXTENDED_YEAR</code>.
    377    * @stable ICU 2.6
    378    */
    379   UCAL_YEAR_WOY,
    380 
    381  /**
    382    * Field number
    383    * indicating the localized day of week.  This will be a value from 1
    384    * to 7 inclusive, with 1 being the localized first day of the week.
    385    * @stable ICU 2.6
    386    */
    387   UCAL_DOW_LOCAL,
    388 
    389   /**
    390    * Year of this calendar system, encompassing all supra-year fields. For example,
    391    * in Gregorian/Julian calendars, positive Extended Year values indicate years AD,
    392    *  1 BC = 0 extended, 2 BC = -1 extended, and so on.
    393    * @stable ICU 2.8
    394    */
    395   UCAL_EXTENDED_YEAR,
    396 
    397  /**
    398    * Field number
    399    * indicating the modified Julian day number.  This is different from
    400    * the conventional Julian day number in two regards.  First, it
    401    * demarcates days at local zone midnight, rather than noon GMT.
    402    * Second, it is a local number; that is, it depends on the local time
    403    * zone.  It can be thought of as a single number that encompasses all
    404    * the date-related fields.
    405    * @stable ICU 2.8
    406    */
    407   UCAL_JULIAN_DAY,
    408 
    409   /**
    410    * Ranges from 0 to 23:59:59.999 (regardless of DST).  This field behaves <em>exactly</em>
    411    * like a composite of all time-related fields, not including the zone fields.  As such,
    412    * it also reflects discontinuities of those fields on DST transition days.  On a day
    413    * of DST onset, it will jump forward.  On a day of DST cessation, it will jump
    414    * backward.  This reflects the fact that it must be combined with the DST_OFFSET field
    415    * to obtain a unique local time value.
    416    * @stable ICU 2.8
    417    */
    418   UCAL_MILLISECONDS_IN_DAY,
    419 
    420   /**
    421    * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for
    422    * an example of this.
    423    */
    424   UCAL_IS_LEAP_MONTH,
    425 
    426   /**
    427    * Field count
    428    * @stable ICU 2.6
    429    */
    430   UCAL_FIELD_COUNT,
    431 
    432  /**
    433    * Field number indicating the
    434    * day of the month. This is a synonym for <code>UCAL_DATE</code>.
    435    * The first day of the month has value 1.
    436    * @see #UCAL_DATE
    437    * Synonym for UCAL_DATE
    438    * @stable ICU 2.8
    439    **/
    440   UCAL_DAY_OF_MONTH=UCAL_DATE
    441 };
    442 
    443 /** @stable ICU 2.0 */
    444 typedef enum UCalendarDateFields UCalendarDateFields;
    445     /**
    446      * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
    447      * who create locale resources for the field of first-day-of-week should be aware of
    448      * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
    449      */
    450 /** Possible days of the week in a UCalendar
    451  * @stable ICU 2.0
    452  */
    453 enum UCalendarDaysOfWeek {
    454   /** Sunday */
    455   UCAL_SUNDAY = 1,
    456   /** Monday */
    457   UCAL_MONDAY,
    458   /** Tuesday */
    459   UCAL_TUESDAY,
    460   /** Wednesday */
    461   UCAL_WEDNESDAY,
    462   /** Thursday */
    463   UCAL_THURSDAY,
    464   /** Friday */
    465   UCAL_FRIDAY,
    466   /** Saturday */
    467   UCAL_SATURDAY
    468 };
    469 
    470 /** @stable ICU 2.0 */
    471 typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
    472 
    473 /** Possible months in a UCalendar. Note: Calendar month is 0-based.
    474  * @stable ICU 2.0
    475  */
    476 enum UCalendarMonths {
    477   /** January */
    478   UCAL_JANUARY,
    479   /** February */
    480   UCAL_FEBRUARY,
    481   /** March */
    482   UCAL_MARCH,
    483   /** April */
    484   UCAL_APRIL,
    485   /** May */
    486   UCAL_MAY,
    487   /** June */
    488   UCAL_JUNE,
    489   /** July */
    490   UCAL_JULY,
    491   /** August */
    492   UCAL_AUGUST,
    493   /** September */
    494   UCAL_SEPTEMBER,
    495   /** October */
    496   UCAL_OCTOBER,
    497   /** November */
    498   UCAL_NOVEMBER,
    499   /** December */
    500   UCAL_DECEMBER,
    501   /** Value of the <code>UCAL_MONTH</code> field indicating the
    502     * thirteenth month of the year. Although the Gregorian calendar
    503     * does not use this value, lunar calendars do.
    504     */
    505   UCAL_UNDECIMBER
    506 };
    507 
    508 /** @stable ICU 2.0 */
    509 typedef enum UCalendarMonths UCalendarMonths;
    510 
    511 /** Possible AM/PM values in a UCalendar
    512  * @stable ICU 2.0
    513  */
    514 enum UCalendarAMPMs {
    515     /** AM */
    516   UCAL_AM,
    517   /** PM */
    518   UCAL_PM
    519 };
    520 
    521 /** @stable ICU 2.0 */
    522 typedef enum UCalendarAMPMs UCalendarAMPMs;
    523 
    524 /**
    525  * System time zone type constants used by filtering zones
    526  * in ucal_openTimeZoneIDEnumeration.
    527  * @see ucal_openTimeZoneIDEnumeration
    528  * @stable ICU 4.8
    529  */
    530 enum USystemTimeZoneType {
    531     /**
    532      * Any system zones.
    533      * @stable ICU 4.8
    534      */
    535     UCAL_ZONE_TYPE_ANY,
    536     /**
    537      * Canonical system zones.
    538      * @stable ICU 4.8
    539      */
    540     UCAL_ZONE_TYPE_CANONICAL,
    541     /**
    542      * Canonical system zones associated with actual locations.
    543      * @stable ICU 4.8
    544      */
    545     UCAL_ZONE_TYPE_CANONICAL_LOCATION
    546 };
    547 
    548 /** @stable ICU 4.8 */
    549 typedef enum USystemTimeZoneType USystemTimeZoneType;
    550 
    551 /**
    552  * Create an enumeration over system time zone IDs with the given
    553  * filter conditions.
    554  * @param zoneType  The system time zone type.
    555  * @param region    The ISO 3166 two-letter country code or UN M.49
    556  *                  three-digit area code.  When NULL, no filtering
    557  *                  done by region.
    558  * @param rawOffset An offset from GMT in milliseconds, ignoring the
    559  *                  effect of daylight savings time, if any. When NULL,
    560  *                  no filtering done by zone offset.
    561  * @param ec        A pointer to an UErrorCode to receive any errors
    562  * @return  an enumeration object that the caller must dispose of
    563  *          using enum_close(), or NULL upon failure. In case of failure,
    564  *          *ec will indicate the error.
    565  * @stable ICU 4.8
    566  */
    567 U_STABLE UEnumeration* U_EXPORT2
    568 ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region,
    569                                 const int32_t* rawOffset, UErrorCode* ec);
    570 
    571 /**
    572  * Create an enumeration over all time zones.
    573  *
    574  * @param ec input/output error code
    575  *
    576  * @return an enumeration object that the caller must dispose of using
    577  * uenum_close(), or NULL upon failure. In case of failure *ec will
    578  * indicate the error.
    579  *
    580  * @stable ICU 2.6
    581  */
    582 U_STABLE UEnumeration* U_EXPORT2
    583 ucal_openTimeZones(UErrorCode* ec);
    584 
    585 /**
    586  * Create an enumeration over all time zones associated with the given
    587  * country. Some zones are affiliated with no country (e.g., "UTC");
    588  * these may also be retrieved, as a group.
    589  *
    590  * @param country the ISO 3166 two-letter country code, or NULL to
    591  * retrieve zones not affiliated with any country
    592  *
    593  * @param ec input/output error code
    594  *
    595  * @return an enumeration object that the caller must dispose of using
    596  * uenum_close(), or NULL upon failure. In case of failure *ec will
    597  * indicate the error.
    598  *
    599  * @stable ICU 2.6
    600  */
    601 U_STABLE UEnumeration* U_EXPORT2
    602 ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
    603 
    604 /**
    605  * Return the default time zone. The default is determined initially
    606  * by querying the host operating system. It may be changed with
    607  * ucal_setDefaultTimeZone() or with the C++ TimeZone API.
    608  *
    609  * @param result A buffer to receive the result, or NULL
    610  *
    611  * @param resultCapacity The capacity of the result buffer
    612  *
    613  * @param ec input/output error code
    614  *
    615  * @return The result string length, not including the terminating
    616  * null
    617  *
    618  * @stable ICU 2.6
    619  */
    620 U_STABLE int32_t U_EXPORT2
    621 ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
    622 
    623 /**
    624  * Set the default time zone.
    625  *
    626  * @param zoneID null-terminated time zone ID
    627  *
    628  * @param ec input/output error code
    629  *
    630  * @stable ICU 2.6
    631  */
    632 U_STABLE void U_EXPORT2
    633 ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
    634 
    635 /**
    636  * Return the amount of time in milliseconds that the clock is
    637  * advanced during daylight savings time for the given time zone, or
    638  * zero if the time zone does not observe daylight savings time.
    639  *
    640  * @param zoneID null-terminated time zone ID
    641  *
    642  * @param ec input/output error code
    643  *
    644  * @return the number of milliseconds the time is advanced with
    645  * respect to standard time when the daylight savings rules are in
    646  * effect. This is always a non-negative number, most commonly either
    647  * 3,600,000 (one hour) or zero.
    648  *
    649  * @stable ICU 2.6
    650  */
    651 U_STABLE int32_t U_EXPORT2
    652 ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
    653 
    654 /**
    655  * Get the current date and time.
    656  * The value returned is represented as milliseconds from the epoch.
    657  * @return The current date and time.
    658  * @stable ICU 2.0
    659  */
    660 U_STABLE UDate U_EXPORT2
    661 ucal_getNow(void);
    662 
    663 /**
    664  * Open a UCalendar.
    665  * A UCalendar may be used to convert a millisecond value to a year,
    666  * month, and day.
    667  * <p>
    668  * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown",
    669  * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID
    670  * <code>UCAL_UNKNOWN_ZONE_ID</code> ("Etc/Unknown") without any errors/warnings.  If you want
    671  * to check if a TimeZone ID is valid prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>.
    672  *
    673  * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
    674  * @param len The length of zoneID, or -1 if null-terminated.
    675  * @param locale The desired locale
    676  * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
    677  * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
    678  * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
    679  * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
    680  * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
    681  * @param status A pointer to an UErrorCode to receive any errors
    682  * @return A pointer to a UCalendar, or 0 if an error occurred.
    683  * @see #UCAL_UNKNOWN_ZONE_ID
    684  * @stable ICU 2.0
    685  */
    686 U_STABLE UCalendar* U_EXPORT2
    687 ucal_open(const UChar*   zoneID,
    688           int32_t        len,
    689           const char*    locale,
    690           UCalendarType  type,
    691           UErrorCode*    status);
    692 
    693 /**
    694  * Close a UCalendar.
    695  * Once closed, a UCalendar may no longer be used.
    696  * @param cal The UCalendar to close.
    697  * @stable ICU 2.0
    698  */
    699 U_STABLE void U_EXPORT2
    700 ucal_close(UCalendar *cal);
    701 
    702 #if U_SHOW_CPLUSPLUS_API
    703 
    704 U_NAMESPACE_BEGIN
    705 
    706 /**
    707  * \class LocalUCalendarPointer
    708  * "Smart pointer" class, closes a UCalendar via ucal_close().
    709  * For most methods see the LocalPointerBase base class.
    710  *
    711  * @see LocalPointerBase
    712  * @see LocalPointer
    713  * @stable ICU 4.4
    714  */
    715 U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
    716 
    717 U_NAMESPACE_END
    718 
    719 #endif
    720 
    721 /**
    722  * Open a copy of a UCalendar.
    723  * This function performs a deep copy.
    724  * @param cal The calendar to copy
    725  * @param status A pointer to an UErrorCode to receive any errors.
    726  * @return A pointer to a UCalendar identical to cal.
    727  * @stable ICU 4.0
    728  */
    729 U_STABLE UCalendar* U_EXPORT2
    730 ucal_clone(const UCalendar* cal,
    731            UErrorCode*      status);
    732 
    733 /**
    734  * Set the TimeZone used by a UCalendar.
    735  * A UCalendar uses a timezone for converting from Greenwich time to local time.
    736  * @param cal The UCalendar to set.
    737  * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
    738  * @param len The length of zoneID, or -1 if null-terminated.
    739  * @param status A pointer to an UErrorCode to receive any errors.
    740  * @stable ICU 2.0
    741  */
    742 U_STABLE void U_EXPORT2
    743 ucal_setTimeZone(UCalendar*    cal,
    744                  const UChar*  zoneID,
    745                  int32_t       len,
    746                  UErrorCode*   status);
    747 
    748 /**
    749  * Get the ID of the UCalendar's time zone.
    750  *
    751  * @param cal           The UCalendar to query.
    752  * @param result        Receives the UCalendar's time zone ID.
    753  * @param resultLength  The maximum size of result.
    754  * @param status        Receives the status.
    755  * @return              The total buffer size needed; if greater than resultLength, the output was truncated.
    756  * @stable ICU 51
    757  */
    758 U_STABLE int32_t U_EXPORT2
    759 ucal_getTimeZoneID(const UCalendar *cal,
    760                    UChar *result,
    761                    int32_t resultLength,
    762                    UErrorCode *status);
    763 
    764 /**
    765  * Possible formats for a UCalendar's display name
    766  * @stable ICU 2.0
    767  */
    768 enum UCalendarDisplayNameType {
    769   /** Standard display name */
    770   UCAL_STANDARD,
    771   /** Short standard display name */
    772   UCAL_SHORT_STANDARD,
    773   /** Daylight savings display name */
    774   UCAL_DST,
    775   /** Short daylight savings display name */
    776   UCAL_SHORT_DST
    777 };
    778 
    779 /** @stable ICU 2.0 */
    780 typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
    781 
    782 /**
    783  * Get the display name for a UCalendar's TimeZone.
    784  * A display name is suitable for presentation to a user.
    785  * @param cal          The UCalendar to query.
    786  * @param type         The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
    787  *                     UCAL_DST, UCAL_SHORT_DST
    788  * @param locale       The desired locale for the display name.
    789  * @param result       A pointer to a buffer to receive the formatted number.
    790  * @param resultLength The maximum size of result.
    791  * @param status       A pointer to an UErrorCode to receive any errors
    792  * @return             The total buffer size needed; if greater than resultLength, the output was truncated.
    793  * @stable ICU 2.0
    794  */
    795 U_STABLE int32_t U_EXPORT2
    796 ucal_getTimeZoneDisplayName(const UCalendar*          cal,
    797                             UCalendarDisplayNameType  type,
    798                             const char*               locale,
    799                             UChar*                    result,
    800                             int32_t                   resultLength,
    801                             UErrorCode*               status);
    802 
    803 /**
    804  * Determine if a UCalendar is currently in daylight savings time.
    805  * Daylight savings time is not used in all parts of the world.
    806  * @param cal The UCalendar to query.
    807  * @param status A pointer to an UErrorCode to receive any errors
    808  * @return TRUE if cal is currently in daylight savings time, FALSE otherwise
    809  * @stable ICU 2.0
    810  */
    811 U_STABLE UBool U_EXPORT2
    812 ucal_inDaylightTime(const UCalendar*  cal,
    813                     UErrorCode*       status );
    814 
    815 /**
    816  * Sets the GregorianCalendar change date. This is the point when the switch from
    817  * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
    818  * 15, 1582. Previous to this time and date will be Julian dates.
    819  *
    820  * This function works only for Gregorian calendars. If the UCalendar is not
    821  * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
    822  * error code is set.
    823  *
    824  * @param cal        The calendar object.
    825  * @param date       The given Gregorian cutover date.
    826  * @param pErrorCode Pointer to a standard ICU error code. Its input value must
    827  *                   pass the U_SUCCESS() test, or else the function returns
    828  *                   immediately. Check for U_FAILURE() on output or use with
    829  *                   function chaining. (See User Guide for details.)
    830  *
    831  * @see GregorianCalendar::setGregorianChange
    832  * @see ucal_getGregorianChange
    833  * @stable ICU 3.6
    834  */
    835 U_STABLE void U_EXPORT2
    836 ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
    837 
    838 /**
    839  * Gets the Gregorian Calendar change date. This is the point when the switch from
    840  * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
    841  * 15, 1582. Previous to this time and date will be Julian dates.
    842  *
    843  * This function works only for Gregorian calendars. If the UCalendar is not
    844  * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
    845  * error code is set.
    846  *
    847  * @param cal        The calendar object.
    848  * @param pErrorCode Pointer to a standard ICU error code. Its input value must
    849  *                   pass the U_SUCCESS() test, or else the function returns
    850  *                   immediately. Check for U_FAILURE() on output or use with
    851  *                   function chaining. (See User Guide for details.)
    852  * @return   The Gregorian cutover time for this calendar.
    853  *
    854  * @see GregorianCalendar::getGregorianChange
    855  * @see ucal_setGregorianChange
    856  * @stable ICU 3.6
    857  */
    858 U_STABLE UDate U_EXPORT2
    859 ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
    860 
    861 /**
    862  * Types of UCalendar attributes
    863  * @stable ICU 2.0
    864  */
    865 enum UCalendarAttribute {
    866   /**
    867    * Lenient parsing
    868    * @stable ICU 2.0
    869    */
    870   UCAL_LENIENT,
    871   /**
    872    * First day of week
    873    * @stable ICU 2.0
    874    */
    875   UCAL_FIRST_DAY_OF_WEEK,
    876   /**
    877    * Minimum number of days in first week
    878    * @stable ICU 2.0
    879    */
    880   UCAL_MINIMAL_DAYS_IN_FIRST_WEEK,
    881   /**
    882    * The behavior for handling wall time repeating multiple times
    883    * at negative time zone offset transitions
    884    * @stable ICU 49
    885    */
    886   UCAL_REPEATED_WALL_TIME,
    887   /**
    888    * The behavior for handling skipped wall time at positive time
    889    * zone offset transitions.
    890    * @stable ICU 49
    891    */
    892   UCAL_SKIPPED_WALL_TIME
    893 };
    894 
    895 /** @stable ICU 2.0 */
    896 typedef enum UCalendarAttribute UCalendarAttribute;
    897 
    898 /**
    899  * Options for handling ambiguous wall time at time zone
    900  * offset transitions.
    901  * @stable ICU 49
    902  */
    903 enum UCalendarWallTimeOption {
    904     /**
    905      * An ambiguous wall time to be interpreted as the latest.
    906      * This option is valid for UCAL_REPEATED_WALL_TIME and
    907      * UCAL_SKIPPED_WALL_TIME.
    908      * @stable ICU 49
    909      */
    910     UCAL_WALLTIME_LAST,
    911     /**
    912      * An ambiguous wall time to be interpreted as the earliest.
    913      * This option is valid for UCAL_REPEATED_WALL_TIME and
    914      * UCAL_SKIPPED_WALL_TIME.
    915      * @stable ICU 49
    916      */
    917     UCAL_WALLTIME_FIRST,
    918     /**
    919      * An ambiguous wall time to be interpreted as the next valid
    920      * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME.
    921      * @stable ICU 49
    922      */
    923     UCAL_WALLTIME_NEXT_VALID
    924 };
    925 /** @stable ICU 49 */
    926 typedef enum UCalendarWallTimeOption UCalendarWallTimeOption;
    927 
    928 /**
    929  * Get a numeric attribute associated with a UCalendar.
    930  * Numeric attributes include the first day of the week, or the minimal numbers
    931  * of days in the first week of the month.
    932  * @param cal The UCalendar to query.
    933  * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
    934  * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
    935  * @return The value of attr.
    936  * @see ucal_setAttribute
    937  * @stable ICU 2.0
    938  */
    939 U_STABLE int32_t U_EXPORT2
    940 ucal_getAttribute(const UCalendar*    cal,
    941                   UCalendarAttribute  attr);
    942 
    943 /**
    944  * Set a numeric attribute associated with a UCalendar.
    945  * Numeric attributes include the first day of the week, or the minimal numbers
    946  * of days in the first week of the month.
    947  * @param cal The UCalendar to set.
    948  * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
    949  * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
    950  * @param newValue The new value of attr.
    951  * @see ucal_getAttribute
    952  * @stable ICU 2.0
    953  */
    954 U_STABLE void U_EXPORT2
    955 ucal_setAttribute(UCalendar*          cal,
    956                   UCalendarAttribute  attr,
    957                   int32_t             newValue);
    958 
    959 /**
    960  * Get a locale for which calendars are available.
    961  * A UCalendar in a locale returned by this function will contain the correct
    962  * day and month names for the locale.
    963  * @param localeIndex The index of the desired locale.
    964  * @return A locale for which calendars are available, or 0 if none.
    965  * @see ucal_countAvailable
    966  * @stable ICU 2.0
    967  */
    968 U_STABLE const char* U_EXPORT2
    969 ucal_getAvailable(int32_t localeIndex);
    970 
    971 /**
    972  * Determine how many locales have calendars available.
    973  * This function is most useful as determining the loop ending condition for
    974  * calls to \ref ucal_getAvailable.
    975  * @return The number of locales for which calendars are available.
    976  * @see ucal_getAvailable
    977  * @stable ICU 2.0
    978  */
    979 U_STABLE int32_t U_EXPORT2
    980 ucal_countAvailable(void);
    981 
    982 /**
    983  * Get a UCalendar's current time in millis.
    984  * The time is represented as milliseconds from the epoch.
    985  * @param cal The UCalendar to query.
    986  * @param status A pointer to an UErrorCode to receive any errors
    987  * @return The calendar's current time in millis.
    988  * @see ucal_setMillis
    989  * @see ucal_setDate
    990  * @see ucal_setDateTime
    991  * @stable ICU 2.0
    992  */
    993 U_STABLE UDate U_EXPORT2
    994 ucal_getMillis(const UCalendar*  cal,
    995                UErrorCode*       status);
    996 
    997 /**
    998  * Set a UCalendar's current time in millis.
    999  * The time is represented as milliseconds from the epoch.
   1000  * @param cal The UCalendar to set.
   1001  * @param dateTime The desired date and time.
   1002  * @param status A pointer to an UErrorCode to receive any errors
   1003  * @see ucal_getMillis
   1004  * @see ucal_setDate
   1005  * @see ucal_setDateTime
   1006  * @stable ICU 2.0
   1007  */
   1008 U_STABLE void U_EXPORT2
   1009 ucal_setMillis(UCalendar*   cal,
   1010                UDate        dateTime,
   1011                UErrorCode*  status );
   1012 
   1013 /**
   1014  * Set a UCalendar's current date.
   1015  * The date is represented as a series of 32-bit integers.
   1016  * @param cal The UCalendar to set.
   1017  * @param year The desired year.
   1018  * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
   1019  * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
   1020  * @param date The desired day of the month.
   1021  * @param status A pointer to an UErrorCode to receive any errors
   1022  * @see ucal_getMillis
   1023  * @see ucal_setMillis
   1024  * @see ucal_setDateTime
   1025  * @stable ICU 2.0
   1026  */
   1027 U_STABLE void U_EXPORT2
   1028 ucal_setDate(UCalendar*   cal,
   1029              int32_t      year,
   1030              int32_t      month,
   1031              int32_t      date,
   1032              UErrorCode*  status);
   1033 
   1034 /**
   1035  * Set a UCalendar's current date.
   1036  * The date is represented as a series of 32-bit integers.
   1037  * @param cal The UCalendar to set.
   1038  * @param year The desired year.
   1039  * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
   1040  * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
   1041  * @param date The desired day of the month.
   1042  * @param hour The desired hour of day.
   1043  * @param minute The desired minute.
   1044  * @param second The desirec second.
   1045  * @param status A pointer to an UErrorCode to receive any errors
   1046  * @see ucal_getMillis
   1047  * @see ucal_setMillis
   1048  * @see ucal_setDate
   1049  * @stable ICU 2.0
   1050  */
   1051 U_STABLE void U_EXPORT2
   1052 ucal_setDateTime(UCalendar*   cal,
   1053                  int32_t      year,
   1054                  int32_t      month,
   1055                  int32_t      date,
   1056                  int32_t      hour,
   1057                  int32_t      minute,
   1058                  int32_t      second,
   1059                  UErrorCode*  status);
   1060 
   1061 /**
   1062  * Returns TRUE if two UCalendars are equivalent.  Equivalent
   1063  * UCalendars will behave identically, but they may be set to
   1064  * different times.
   1065  * @param cal1 The first of the UCalendars to compare.
   1066  * @param cal2 The second of the UCalendars to compare.
   1067  * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise.
   1068  * @stable ICU 2.0
   1069  */
   1070 U_STABLE UBool U_EXPORT2
   1071 ucal_equivalentTo(const UCalendar*  cal1,
   1072                   const UCalendar*  cal2);
   1073 
   1074 /**
   1075  * Add a specified signed amount to a particular field in a UCalendar.
   1076  * This can modify more significant fields in the calendar.
   1077  * Adding a positive value always means moving forward in time, so for the Gregorian calendar,
   1078  * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
   1079  * the numeric value of the field itself).
   1080  * @param cal The UCalendar to which to add.
   1081  * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1082  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1083  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1084  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1085  * @param amount The signed amount to add to field. If the amount causes the value
   1086  * to exceed to maximum or minimum values for that field, other fields are modified
   1087  * to preserve the magnitude of the change.
   1088  * @param status A pointer to an UErrorCode to receive any errors
   1089  * @see ucal_roll
   1090  * @stable ICU 2.0
   1091  */
   1092 U_STABLE void U_EXPORT2
   1093 ucal_add(UCalendar*           cal,
   1094          UCalendarDateFields  field,
   1095          int32_t              amount,
   1096          UErrorCode*          status);
   1097 
   1098 /**
   1099  * Add a specified signed amount to a particular field in a UCalendar.
   1100  * This will not modify more significant fields in the calendar.
   1101  * Rolling by a positive value always means moving forward in time (unless the limit of the
   1102  * field is reached, in which case it may pin or wrap), so for Gregorian calendar,
   1103  * starting with 100 BC and rolling the year by +1 results in 99 BC.
   1104  * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the
   1105  * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around.
   1106  * When eras only have a limit at one end, then attempting to roll the year past that limit will result in
   1107  * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time
   1108  * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for
   1109  * era 0 (that is the only way to represent years before the calendar epoch).
   1110  * @param cal The UCalendar to which to add.
   1111  * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1112  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1113  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1114  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1115  * @param amount The signed amount to add to field. If the amount causes the value
   1116  * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
   1117  * value.
   1118  * @param status A pointer to an UErrorCode to receive any errors
   1119  * @see ucal_add
   1120  * @stable ICU 2.0
   1121  */
   1122 U_STABLE void U_EXPORT2
   1123 ucal_roll(UCalendar*           cal,
   1124           UCalendarDateFields  field,
   1125           int32_t              amount,
   1126           UErrorCode*          status);
   1127 
   1128 /**
   1129  * Get the current value of a field from a UCalendar.
   1130  * All fields are represented as 32-bit integers.
   1131  * @param cal The UCalendar to query.
   1132  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1133  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1134  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1135  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1136  * @param status A pointer to an UErrorCode to receive any errors
   1137  * @return The value of the desired field.
   1138  * @see ucal_set
   1139  * @see ucal_isSet
   1140  * @see ucal_clearField
   1141  * @see ucal_clear
   1142  * @stable ICU 2.0
   1143  */
   1144 U_STABLE int32_t U_EXPORT2
   1145 ucal_get(const UCalendar*     cal,
   1146          UCalendarDateFields  field,
   1147          UErrorCode*          status );
   1148 
   1149 /**
   1150  * Set the value of a field in a UCalendar.
   1151  * All fields are represented as 32-bit integers.
   1152  * @param cal The UCalendar to set.
   1153  * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1154  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1155  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1156  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1157  * @param value The desired value of field.
   1158  * @see ucal_get
   1159  * @see ucal_isSet
   1160  * @see ucal_clearField
   1161  * @see ucal_clear
   1162  * @stable ICU 2.0
   1163  */
   1164 U_STABLE void U_EXPORT2
   1165 ucal_set(UCalendar*           cal,
   1166          UCalendarDateFields  field,
   1167          int32_t              value);
   1168 
   1169 /**
   1170  * Determine if a field in a UCalendar is set.
   1171  * All fields are represented as 32-bit integers.
   1172  * @param cal The UCalendar to query.
   1173  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1174  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1175  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1176  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1177  * @return TRUE if field is set, FALSE otherwise.
   1178  * @see ucal_get
   1179  * @see ucal_set
   1180  * @see ucal_clearField
   1181  * @see ucal_clear
   1182  * @stable ICU 2.0
   1183  */
   1184 U_STABLE UBool U_EXPORT2
   1185 ucal_isSet(const UCalendar*     cal,
   1186            UCalendarDateFields  field);
   1187 
   1188 /**
   1189  * Clear a field in a UCalendar.
   1190  * All fields are represented as 32-bit integers.
   1191  * @param cal The UCalendar containing the field to clear.
   1192  * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1193  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1194  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1195  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1196  * @see ucal_get
   1197  * @see ucal_set
   1198  * @see ucal_isSet
   1199  * @see ucal_clear
   1200  * @stable ICU 2.0
   1201  */
   1202 U_STABLE void U_EXPORT2
   1203 ucal_clearField(UCalendar*           cal,
   1204                 UCalendarDateFields  field);
   1205 
   1206 /**
   1207  * Clear all fields in a UCalendar.
   1208  * All fields are represented as 32-bit integers.
   1209  * @param calendar The UCalendar to clear.
   1210  * @see ucal_get
   1211  * @see ucal_set
   1212  * @see ucal_isSet
   1213  * @see ucal_clearField
   1214  * @stable ICU 2.0
   1215  */
   1216 U_STABLE void U_EXPORT2
   1217 ucal_clear(UCalendar* calendar);
   1218 
   1219 /**
   1220  * Possible limit values for a UCalendar
   1221  * @stable ICU 2.0
   1222  */
   1223 enum UCalendarLimitType {
   1224   /** Minimum value */
   1225   UCAL_MINIMUM,
   1226   /** Maximum value */
   1227   UCAL_MAXIMUM,
   1228   /** Greatest minimum value */
   1229   UCAL_GREATEST_MINIMUM,
   1230   /** Leaest maximum value */
   1231   UCAL_LEAST_MAXIMUM,
   1232   /** Actual minimum value */
   1233   UCAL_ACTUAL_MINIMUM,
   1234   /** Actual maximum value */
   1235   UCAL_ACTUAL_MAXIMUM
   1236 };
   1237 
   1238 /** @stable ICU 2.0 */
   1239 typedef enum UCalendarLimitType UCalendarLimitType;
   1240 
   1241 /**
   1242  * Determine a limit for a field in a UCalendar.
   1243  * A limit is a maximum or minimum value for a field.
   1244  * @param cal The UCalendar to query.
   1245  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1246  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1247  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1248  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1249  * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM,
   1250  * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
   1251  * @param status A pointer to an UErrorCode to receive any errors.
   1252  * @return The requested value.
   1253  * @stable ICU 2.0
   1254  */
   1255 U_STABLE int32_t U_EXPORT2
   1256 ucal_getLimit(const UCalendar*     cal,
   1257               UCalendarDateFields  field,
   1258               UCalendarLimitType   type,
   1259               UErrorCode*          status);
   1260 
   1261 /** Get the locale for this calendar object. You can choose between valid and actual locale.
   1262  *  @param cal The calendar object
   1263  *  @param type type of the locale we're looking for (valid or actual)
   1264  *  @param status error code for the operation
   1265  *  @return the locale name
   1266  *  @stable ICU 2.8
   1267  */
   1268 U_STABLE const char * U_EXPORT2
   1269 ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
   1270 
   1271 /**
   1272  * Returns the timezone data version currently used by ICU.
   1273  * @param status error code for the operation
   1274  * @return the version string, such as "2007f"
   1275  * @stable ICU 3.8
   1276  */
   1277 U_STABLE const char * U_EXPORT2
   1278 ucal_getTZDataVersion(UErrorCode* status);
   1279 
   1280 /**
   1281  * Returns the canonical system timezone ID or the normalized
   1282  * custom time zone ID for the given time zone ID.
   1283  * @param id        The input timezone ID to be canonicalized.
   1284  * @param len       The length of id, or -1 if null-terminated.
   1285  * @param result    The buffer receives the canonical system timezone ID
   1286  *                  or the custom timezone ID in normalized format.
   1287  * @param resultCapacity    The capacity of the result buffer.
   1288  * @param isSystemID        Receives if the given ID is a known system
   1289      *                      timezone ID.
   1290  * @param status    Receives the status.  When the given timezone ID
   1291  *                  is neither a known system time zone ID nor a
   1292  *                  valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
   1293  *                  is set.
   1294  * @return          The result string length, not including the terminating
   1295  *                  null.
   1296  * @stable ICU 4.0
   1297  */
   1298 U_STABLE int32_t U_EXPORT2
   1299 ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
   1300                             UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
   1301 /**
   1302  * Get the resource keyword value string designating the calendar type for the UCalendar.
   1303  * @param cal The UCalendar to query.
   1304  * @param status The error code for the operation.
   1305  * @return The resource keyword value string.
   1306  * @stable ICU 4.2
   1307  */
   1308 U_STABLE const char * U_EXPORT2
   1309 ucal_getType(const UCalendar *cal, UErrorCode* status);
   1310 
   1311 /**
   1312  * Given a key and a locale, returns an array of string values in a preferred
   1313  * order that would make a difference. These are all and only those values where
   1314  * the open (creation) of the service with the locale formed from the input locale
   1315  * plus input keyword and that value has different behavior than creation with the
   1316  * input locale alone.
   1317  * @param key           one of the keys supported by this service.  For now, only
   1318  *                      "calendar" is supported.
   1319  * @param locale        the locale
   1320  * @param commonlyUsed  if set to true it will return only commonly used values
   1321  *                      with the given locale in preferred order.  Otherwise,
   1322  *                      it will return all the available values for the locale.
   1323  * @param status error status
   1324  * @return a string enumeration over keyword values for the given key and the locale.
   1325  * @stable ICU 4.2
   1326  */
   1327 U_STABLE UEnumeration* U_EXPORT2
   1328 ucal_getKeywordValuesForLocale(const char* key,
   1329                                const char* locale,
   1330                                UBool commonlyUsed,
   1331                                UErrorCode* status);
   1332 
   1333 
   1334 /** Weekday types, as returned by ucal_getDayOfWeekType().
   1335  * @stable ICU 4.4
   1336  */
   1337 enum UCalendarWeekdayType {
   1338   /**
   1339    * Designates a full weekday (no part of the day is included in the weekend).
   1340    * @stable ICU 4.4
   1341    */
   1342   UCAL_WEEKDAY,
   1343   /**
   1344    * Designates a full weekend day (the entire day is included in the weekend).
   1345    * @stable ICU 4.4
   1346    */
   1347   UCAL_WEEKEND,
   1348   /**
   1349    * Designates a day that starts as a weekday and transitions to the weekend.
   1350    * Call ucal_getWeekendTransition() to get the time of transition.
   1351    * @stable ICU 4.4
   1352    */
   1353   UCAL_WEEKEND_ONSET,
   1354   /**
   1355    * Designates a day that starts as the weekend and transitions to a weekday.
   1356    * Call ucal_getWeekendTransition() to get the time of transition.
   1357    * @stable ICU 4.4
   1358    */
   1359   UCAL_WEEKEND_CEASE
   1360 };
   1361 
   1362 /** @stable ICU 4.4 */
   1363 typedef enum UCalendarWeekdayType UCalendarWeekdayType;
   1364 
   1365 /**
   1366  * Returns whether the given day of the week is a weekday, a weekend day,
   1367  * or a day that transitions from one to the other, for the locale and
   1368  * calendar system associated with this UCalendar (the locale's region is
   1369  * often the most determinant factor). If a transition occurs at midnight,
   1370  * then the days before and after the transition will have the
   1371  * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time
   1372  * other than midnight, then the day of the transition will have
   1373  * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the
   1374  * function ucal_getWeekendTransition() will return the point of
   1375  * transition.
   1376  * @param cal The UCalendar to query.
   1377  * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY).
   1378  * @param status The error code for the operation.
   1379  * @return The UCalendarWeekdayType for the day of the week.
   1380  * @stable ICU 4.4
   1381  */
   1382 U_STABLE UCalendarWeekdayType U_EXPORT2
   1383 ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status);
   1384 
   1385 /**
   1386  * Returns the time during the day at which the weekend begins or ends in
   1387  * this calendar system.  If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET
   1388  * for the specified dayOfWeek, return the time at which the weekend begins.
   1389  * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
   1390  * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns
   1391  * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
   1392  * (U_ILLEGAL_ARGUMENT_ERROR).
   1393  * @param cal The UCalendar to query.
   1394  * @param dayOfWeek The day of the week for which the weekend transition time is
   1395  * desired (UCAL_SUNDAY..UCAL_SATURDAY).
   1396  * @param status The error code for the operation.
   1397  * @return The milliseconds after midnight at which the weekend begins or ends.
   1398  * @stable ICU 4.4
   1399  */
   1400 U_STABLE int32_t U_EXPORT2
   1401 ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
   1402 
   1403 /**
   1404  * Returns TRUE if the given UDate is in the weekend in
   1405  * this calendar system.
   1406  * @param cal The UCalendar to query.
   1407  * @param date The UDate in question.
   1408  * @param status The error code for the operation.
   1409  * @return TRUE if the given UDate is in the weekend in
   1410  * this calendar system, FALSE otherwise.
   1411  * @stable ICU 4.4
   1412  */
   1413 U_STABLE UBool U_EXPORT2
   1414 ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status);
   1415 
   1416 /**
   1417  * Return the difference between the target time and the time this calendar object is currently set to.
   1418  * If the target time is after the current calendar setting, the the returned value will be positive.
   1419  * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH
   1420  * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the
   1421  * current calendar setting.
   1422  *
   1423  * As a side effect of this call, this calendar is advanced toward target by the given amount. That is,
   1424  * calling this function has the side effect of calling ucal_add on this calendar with the specified
   1425  * field and an amount equal to the return value from this function.
   1426  *
   1427  * A typical way of using this function is to call it first with the largest field of interest, then
   1428  * with progressively smaller fields.
   1429  *
   1430  * @param cal The UCalendar to compare and update.
   1431  * @param target The target date to compare to the current calendar setting.
   1432  * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1433  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1434  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1435  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1436  * @param status A pointer to an UErrorCode to receive any errors
   1437  * @return The date difference for the specified field.
   1438  * @stable ICU 4.8
   1439  */
   1440 U_STABLE int32_t U_EXPORT2
   1441 ucal_getFieldDifference(UCalendar* cal,
   1442                         UDate target,
   1443                         UCalendarDateFields field,
   1444                         UErrorCode* status);
   1445 
   1446 /**
   1447  * Time zone transition types for ucal_getTimeZoneTransitionDate
   1448  * @stable ICU 50
   1449  */
   1450 enum UTimeZoneTransitionType {
   1451     /**
   1452      * Get the next transition after the current date,
   1453      * i.e. excludes the current date
   1454      * @stable ICU 50
   1455      */
   1456     UCAL_TZ_TRANSITION_NEXT,
   1457     /**
   1458      * Get the next transition on or after the current date,
   1459      * i.e. may include the current date
   1460      * @stable ICU 50
   1461      */
   1462     UCAL_TZ_TRANSITION_NEXT_INCLUSIVE,
   1463     /**
   1464      * Get the previous transition before the current date,
   1465      * i.e. excludes the current date
   1466      * @stable ICU 50
   1467      */
   1468     UCAL_TZ_TRANSITION_PREVIOUS,
   1469     /**
   1470      * Get the previous transition on or before the current date,
   1471      * i.e. may include the current date
   1472      * @stable ICU 50
   1473      */
   1474     UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE
   1475 };
   1476 
   1477 typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */
   1478 
   1479 /**
   1480 * Get the UDate for the next/previous time zone transition relative to
   1481 * the calendar's current date, in the time zone to which the calendar
   1482 * is currently set. If there is no known time zone transition of the
   1483 * requested type relative to the calendar's date, the function returns
   1484 * FALSE.
   1485 * @param cal The UCalendar to query.
   1486 * @param type The type of transition desired.
   1487 * @param transition A pointer to a UDate to be set to the transition time.
   1488 *         If the function returns FALSE, the value set is unspecified.
   1489 * @param status A pointer to a UErrorCode to receive any errors.
   1490 * @return TRUE if a valid transition time is set in *transition, FALSE
   1491 *         otherwise.
   1492 * @stable ICU 50
   1493 */
   1494 U_STABLE UBool U_EXPORT2
   1495 ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type,
   1496                                UDate* transition, UErrorCode* status);
   1497 
   1498 /**
   1499 * Converts a system time zone ID to an equivalent Windows time zone ID. For example,
   1500 * Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles".
   1501 *
   1502 * <p>There are system time zones that cannot be mapped to Windows zones. When the input
   1503 * system time zone ID is unknown or unmappable to a Windows time zone, then this
   1504 * function returns 0 as the result length, but the operation itself remains successful
   1505 * (no error status set on return).
   1506 *
   1507 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
   1508 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
   1509 * please read the ICU user guide section <a href="http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data">
   1510 * Updating the Time Zone Data</a>.
   1511 *
   1512 * @param id            A system time zone ID.
   1513 * @param len           The length of <code>id</code>, or -1 if null-terminated.
   1514 * @param winid         A buffer to receive a Windows time zone ID.
   1515 * @param winidCapacity The capacity of the result buffer <code>winid</code>.
   1516 * @param status        Receives the status.
   1517 * @return              The result string length, not including the terminating null.
   1518 * @see ucal_getTimeZoneIDForWindowsID
   1519 *
   1520 * @stable ICU 52
   1521 */
   1522 U_STABLE int32_t U_EXPORT2
   1523 ucal_getWindowsTimeZoneID(const UChar* id, int32_t len,
   1524                             UChar* winid, int32_t winidCapacity, UErrorCode* status);
   1525 
   1526 /**
   1527 * Converts a Windows time zone ID to an equivalent system time zone ID
   1528 * for a region. For example, system time zone ID "America/Los_Angeles" is returned
   1529 * for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>),
   1530 * "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and
   1531 * region "CA".
   1532 *
   1533 * <p>Not all Windows time zones can be mapped to system time zones. When the input
   1534 * Windows time zone ID is unknown or unmappable to a system time zone, then this
   1535 * function returns 0 as the result length, but the operation itself remains successful
   1536 * (no error status set on return).
   1537 *
   1538 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
   1539 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
   1540 * please read the ICU user guide section <a href="http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data">
   1541 * Updating the Time Zone Data</a>.
   1542 *
   1543 * @param winid         A Windows time zone ID.
   1544 * @param len           The length of <code>winid</code>, or -1 if null-terminated.
   1545 * @param region        A null-terminated region code, or <code>NULL</code> if no regional preference.
   1546 * @param id            A buffer to receive a system time zone ID.
   1547 * @param idCapacity    The capacity of the result buffer <code>id</code>.
   1548 * @param status        Receives the status.
   1549 * @return              The result string length, not including the terminating null.
   1550 * @see ucal_getWindowsTimeZoneID
   1551 *
   1552 * @stable ICU 52
   1553 */
   1554 U_STABLE int32_t U_EXPORT2
   1555 ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region,
   1556                                 UChar* id, int32_t idCapacity, UErrorCode* status);
   1557 
   1558 #endif /* #if !UCONFIG_NO_FORMATTING */
   1559 
   1560 #endif
   1561