Home | History | Annotate | Download | only in unicode
      1 /*
      2  *******************************************************************************
      3  * Copyright (C) 1996-2010, 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 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 /** A calendar.
    144  *  For usage in C programs.
    145  * @stable ICU 2.0
    146  */
    147 typedef void* UCalendar;
    148 
    149 /** Possible types of UCalendars
    150  * @stable ICU 2.0
    151  */
    152 enum UCalendarType {
    153   /**
    154    * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar,
    155    * which may be the Gregorian calendar or some other calendar.
    156    * @stable ICU 2.0
    157    */
    158   UCAL_TRADITIONAL,
    159   /**
    160    * A better name for UCAL_TRADITIONAL.
    161    * @draft ICU 4.2
    162    */
    163   UCAL_DEFAULT = UCAL_TRADITIONAL,
    164   /**
    165    * Unambiguously designates the Gregorian calendar for the locale.
    166    * @stable ICU 2.0
    167    */
    168   UCAL_GREGORIAN
    169 };
    170 
    171 /** @stable ICU 2.0 */
    172 typedef enum UCalendarType UCalendarType;
    173 
    174 /** Possible fields in a UCalendar
    175  * @stable ICU 2.0
    176  */
    177 enum UCalendarDateFields {
    178   /**
    179    * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar.
    180    * This is a calendar-specific value.
    181    * @stable ICU 2.6
    182    */
    183   UCAL_ERA,
    184 
    185   /**
    186    * Field number indicating the year. This is a calendar-specific value.
    187    * @stable ICU 2.6
    188    */
    189   UCAL_YEAR,
    190 
    191   /**
    192    * Field number indicating the month. This is a calendar-specific value.
    193    * The first month of the year is
    194    * <code>JANUARY</code>; the last depends on the number of months in a year.
    195    * @see #UCAL_JANUARY
    196    * @see #UCAL_FEBRUARY
    197    * @see #UCAL_MARCH
    198    * @see #UCAL_APRIL
    199    * @see #UCAL_MAY
    200    * @see #UCAL_JUNE
    201    * @see #UCAL_JULY
    202    * @see #UCAL_AUGUST
    203    * @see #UCAL_SEPTEMBER
    204    * @see #UCAL_OCTOBER
    205    * @see #UCAL_NOVEMBER
    206    * @see #UCAL_DECEMBER
    207    * @see #UCAL_UNDECIMBER
    208    * @stable ICU 2.6
    209    */
    210   UCAL_MONTH,
    211 
    212   /**
    213    * Field number indicating the
    214    * week number within the current year.  The first week of the year, as
    215    * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
    216    * attributes, has value 1.  Subclasses define
    217    * the value of <code>UCAL_WEEK_OF_YEAR</code> for days before the first week of
    218    * the year.
    219    * @see ucal_getAttribute
    220    * @see ucal_setAttribute
    221    * @stable ICU 2.6
    222    */
    223   UCAL_WEEK_OF_YEAR,
    224 
    225  /**
    226    * Field number indicating the
    227    * week number within the current month.  The first week of the month, as
    228    * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
    229    * attributes, has value 1.  Subclasses define
    230    * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
    231    * the month.
    232    * @see ucal_getAttribute
    233    * @see ucal_setAttribute
    234    * @see #UCAL_FIRST_DAY_OF_WEEK
    235    * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
    236    * @stable ICU 2.6
    237    */
    238   UCAL_WEEK_OF_MONTH,
    239 
    240  /**
    241    * Field number indicating the
    242    * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
    243    * The first day of the month has value 1.
    244    * @see #UCAL_DAY_OF_MONTH
    245    * @stable ICU 2.6
    246    */
    247   UCAL_DATE,
    248 
    249  /**
    250    * Field number indicating the day
    251    * number within the current year.  The first day of the year has value 1.
    252    * @stable ICU 2.6
    253    */
    254   UCAL_DAY_OF_YEAR,
    255 
    256  /**
    257    * Field number indicating the day
    258    * of the week.  This field takes values <code>SUNDAY</code>,
    259    * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
    260    * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
    261    * @see #UCAL_SUNDAY
    262    * @see #UCAL_MONDAY
    263    * @see #UCAL_TUESDAY
    264    * @see #UCAL_WEDNESDAY
    265    * @see #UCAL_THURSDAY
    266    * @see #UCAL_FRIDAY
    267    * @see #UCAL_SATURDAY
    268    * @stable ICU 2.6
    269    */
    270   UCAL_DAY_OF_WEEK,
    271 
    272  /**
    273    * Field number indicating the
    274    * ordinal number of the day of the week within the current month. Together
    275    * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
    276    * within a month.  Unlike <code>WEEK_OF_MONTH</code> and
    277    * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
    278    * <code>getFirstDayOfWeek()</code> or
    279    * <code>getMinimalDaysInFirstWeek()</code>.  <code>DAY_OF_MONTH 1</code>
    280    * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
    281    * 1</code>; <code>8</code> through <code>15</code> correspond to
    282    * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
    283    * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
    284    * <code>DAY_OF_WEEK_IN_MONTH 1</code>.  Negative values count back from the
    285    * end of the month, so the last Sunday of a month is specified as
    286    * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>.  Because
    287    * negative values count backward they will usually be aligned differently
    288    * within the month than positive values.  For example, if a month has 31
    289    * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
    290    * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
    291    * @see #UCAL_DAY_OF_WEEK
    292    * @see #UCAL_WEEK_OF_MONTH
    293    * @stable ICU 2.6
    294    */
    295   UCAL_DAY_OF_WEEK_IN_MONTH,
    296 
    297  /**
    298    * Field number indicating
    299    * whether the <code>HOUR</code> is before or after noon.
    300    * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
    301    * @see #UCAL_AM
    302    * @see #UCAL_PM
    303    * @see #UCAL_HOUR
    304    * @stable ICU 2.6
    305    */
    306   UCAL_AM_PM,
    307 
    308  /**
    309    * Field number indicating the
    310    * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour
    311    * clock.
    312    * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
    313    * @see #UCAL_AM_PM
    314    * @see #UCAL_HOUR_OF_DAY
    315    * @stable ICU 2.6
    316    */
    317   UCAL_HOUR,
    318 
    319  /**
    320    * Field number indicating the
    321    * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
    322    * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
    323    * @see #UCAL_HOUR
    324    * @stable ICU 2.6
    325    */
    326   UCAL_HOUR_OF_DAY,
    327 
    328  /**
    329    * Field number indicating the
    330    * minute within the hour.
    331    * E.g., at 10:04:15.250 PM the <code>UCAL_MINUTE</code> is 4.
    332    * @stable ICU 2.6
    333    */
    334   UCAL_MINUTE,
    335 
    336  /**
    337    * Field number indicating the
    338    * second within the minute.
    339    * E.g., at 10:04:15.250 PM the <code>UCAL_SECOND</code> is 15.
    340    * @stable ICU 2.6
    341    */
    342   UCAL_SECOND,
    343 
    344  /**
    345    * Field number indicating the
    346    * millisecond within the second.
    347    * E.g., at 10:04:15.250 PM the <code>UCAL_MILLISECOND</code> is 250.
    348    * @stable ICU 2.6
    349    */
    350   UCAL_MILLISECOND,
    351 
    352  /**
    353    * Field number indicating the
    354    * raw offset from GMT in milliseconds.
    355    * @stable ICU 2.6
    356    */
    357   UCAL_ZONE_OFFSET,
    358 
    359  /**
    360    * Field number indicating the
    361    * daylight savings offset in milliseconds.
    362    * @stable ICU 2.6
    363    */
    364   UCAL_DST_OFFSET,
    365 
    366  /**
    367    * Field number
    368    * indicating the extended year corresponding to the
    369    * <code>UCAL_WEEK_OF_YEAR</code> field.  This may be one greater or less
    370    * than the value of <code>UCAL_EXTENDED_YEAR</code>.
    371    * @stable ICU 2.6
    372    */
    373   UCAL_YEAR_WOY,
    374 
    375  /**
    376    * Field number
    377    * indicating the localized day of week.  This will be a value from 1
    378    * to 7 inclusive, with 1 being the localized first day of the week.
    379    * @stable ICU 2.6
    380    */
    381   UCAL_DOW_LOCAL,
    382 
    383   /**
    384    * Year of this calendar system, encompassing all supra-year fields. For example,
    385    * in Gregorian/Julian calendars, positive Extended Year values indicate years AD,
    386    *  1 BC = 0 extended, 2 BC = -1 extended, and so on.
    387    * @stable ICU 2.8
    388    */
    389   UCAL_EXTENDED_YEAR,
    390 
    391  /**
    392    * Field number
    393    * indicating the modified Julian day number.  This is different from
    394    * the conventional Julian day number in two regards.  First, it
    395    * demarcates days at local zone midnight, rather than noon GMT.
    396    * Second, it is a local number; that is, it depends on the local time
    397    * zone.  It can be thought of as a single number that encompasses all
    398    * the date-related fields.
    399    * @stable ICU 2.8
    400    */
    401   UCAL_JULIAN_DAY,
    402 
    403   /**
    404    * Ranges from 0 to 23:59:59.999 (regardless of DST).  This field behaves <em>exactly</em>
    405    * like a composite of all time-related fields, not including the zone fields.  As such,
    406    * it also reflects discontinuities of those fields on DST transition days.  On a day
    407    * of DST onset, it will jump forward.  On a day of DST cessation, it will jump
    408    * backward.  This reflects the fact that it must be combined with the DST_OFFSET field
    409    * to obtain a unique local time value.
    410    * @stable ICU 2.8
    411    */
    412   UCAL_MILLISECONDS_IN_DAY,
    413 
    414   /**
    415    * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for
    416    * an example of this.
    417    */
    418   UCAL_IS_LEAP_MONTH,
    419 
    420   /**
    421    * Field count
    422    * @stable ICU 2.6
    423    */
    424   UCAL_FIELD_COUNT,
    425 
    426  /**
    427    * Field number indicating the
    428    * day of the month. This is a synonym for <code>UCAL_DATE</code>.
    429    * The first day of the month has value 1.
    430    * @see #UCAL_DATE
    431    * Synonym for UCAL_DATE
    432    * @stable ICU 2.8
    433    **/
    434   UCAL_DAY_OF_MONTH=UCAL_DATE
    435 };
    436 
    437 /** @stable ICU 2.0 */
    438 typedef enum UCalendarDateFields UCalendarDateFields;
    439     /**
    440      * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
    441      * who create locale resources for the field of first-day-of-week should be aware of
    442      * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
    443      */
    444 /** Possible days of the week in a UCalendar
    445  * @stable ICU 2.0
    446  */
    447 enum UCalendarDaysOfWeek {
    448   /** Sunday */
    449   UCAL_SUNDAY = 1,
    450   /** Monday */
    451   UCAL_MONDAY,
    452   /** Tuesday */
    453   UCAL_TUESDAY,
    454   /** Wednesday */
    455   UCAL_WEDNESDAY,
    456   /** Thursday */
    457   UCAL_THURSDAY,
    458   /** Friday */
    459   UCAL_FRIDAY,
    460   /** Saturday */
    461   UCAL_SATURDAY
    462 };
    463 
    464 /** @stable ICU 2.0 */
    465 typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
    466 
    467 /** Possible months in a UCalendar. Note: Calendar month is 0-based.
    468  * @stable ICU 2.0
    469  */
    470 enum UCalendarMonths {
    471   /** January */
    472   UCAL_JANUARY,
    473   /** February */
    474   UCAL_FEBRUARY,
    475   /** March */
    476   UCAL_MARCH,
    477   /** April */
    478   UCAL_APRIL,
    479   /** May */
    480   UCAL_MAY,
    481   /** June */
    482   UCAL_JUNE,
    483   /** July */
    484   UCAL_JULY,
    485   /** August */
    486   UCAL_AUGUST,
    487   /** September */
    488   UCAL_SEPTEMBER,
    489   /** October */
    490   UCAL_OCTOBER,
    491   /** November */
    492   UCAL_NOVEMBER,
    493   /** December */
    494   UCAL_DECEMBER,
    495   /** Value of the <code>UCAL_MONTH</code> field indicating the
    496     * thirteenth month of the year. Although the Gregorian calendar
    497     * does not use this value, lunar calendars do.
    498     */
    499   UCAL_UNDECIMBER
    500 };
    501 
    502 /** @stable ICU 2.0 */
    503 typedef enum UCalendarMonths UCalendarMonths;
    504 
    505 /** Possible AM/PM values in a UCalendar
    506  * @stable ICU 2.0
    507  */
    508 enum UCalendarAMPMs {
    509     /** AM */
    510   UCAL_AM,
    511   /** PM */
    512   UCAL_PM
    513 };
    514 
    515 /** @stable ICU 2.0 */
    516 typedef enum UCalendarAMPMs UCalendarAMPMs;
    517 
    518 /**
    519  * Create an enumeration over all time zones.
    520  *
    521  * @param ec input/output error code
    522  *
    523  * @return an enumeration object that the caller must dispose of using
    524  * uenum_close(), or NULL upon failure. In case of failure *ec will
    525  * indicate the error.
    526  *
    527  * @stable ICU 2.6
    528  */
    529 U_STABLE UEnumeration* U_EXPORT2
    530 ucal_openTimeZones(UErrorCode* ec);
    531 
    532 /**
    533  * Create an enumeration over all time zones associated with the given
    534  * country. Some zones are affiliated with no country (e.g., "UTC");
    535  * these may also be retrieved, as a group.
    536  *
    537  * @param country the ISO 3166 two-letter country code, or NULL to
    538  * retrieve zones not affiliated with any country
    539  *
    540  * @param ec input/output error code
    541  *
    542  * @return an enumeration object that the caller must dispose of using
    543  * uenum_close(), or NULL upon failure. In case of failure *ec will
    544  * indicate the error.
    545  *
    546  * @stable ICU 2.6
    547  */
    548 U_STABLE UEnumeration* U_EXPORT2
    549 ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
    550 
    551 /**
    552  * Return the default time zone. The default is determined initially
    553  * by querying the host operating system. It may be changed with
    554  * ucal_setDefaultTimeZone() or with the C++ TimeZone API.
    555  *
    556  * @param result A buffer to receive the result, or NULL
    557  *
    558  * @param resultCapacity The capacity of the result buffer
    559  *
    560  * @param ec input/output error code
    561  *
    562  * @return The result string length, not including the terminating
    563  * null
    564  *
    565  * @stable ICU 2.6
    566  */
    567 U_STABLE int32_t U_EXPORT2
    568 ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
    569 
    570 /**
    571  * Set the default time zone.
    572  *
    573  * @param zoneID null-terminated time zone ID
    574  *
    575  * @param ec input/output error code
    576  *
    577  * @stable ICU 2.6
    578  */
    579 U_STABLE void U_EXPORT2
    580 ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
    581 
    582 /**
    583  * Return the amount of time in milliseconds that the clock is
    584  * advanced during daylight savings time for the given time zone, or
    585  * zero if the time zone does not observe daylight savings time.
    586  *
    587  * @param zoneID null-terminated time zone ID
    588  *
    589  * @param ec input/output error code
    590  *
    591  * @return the number of milliseconds the time is advanced with
    592  * respect to standard time when the daylight savings rules are in
    593  * effect. This is always a non-negative number, most commonly either
    594  * 3,600,000 (one hour) or zero.
    595  *
    596  * @stable ICU 2.6
    597  */
    598 U_STABLE int32_t U_EXPORT2
    599 ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
    600 
    601 /**
    602  * Get the current date and time.
    603  * The value returned is represented as milliseconds from the epoch.
    604  * @return The current date and time.
    605  * @stable ICU 2.0
    606  */
    607 U_STABLE UDate U_EXPORT2
    608 ucal_getNow(void);
    609 
    610 /**
    611  * Open a UCalendar.
    612  * A UCalendar may be used to convert a millisecond value to a year,
    613  * month, and day.
    614  * <p>
    615  * Note: When unknown TimeZone ID is specified, the UCalendar returned
    616  * by the function is initialized with GMT ("Etc/GMT") without any
    617  * errors/warnings.  If you want to check if a TimeZone ID is valid,
    618  * use ucal_getCanonicalTimeZoneID prior to this function.
    619  *
    620  * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
    621  * @param len The length of zoneID, or -1 if null-terminated.
    622  * @param locale The desired locale
    623  * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
    624  * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
    625  * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
    626  * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
    627  * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
    628  * @param status A pointer to an UErrorCode to receive any errors
    629  * @return A pointer to a UCalendar, or 0 if an error occurred.
    630  * @stable ICU 2.0
    631  */
    632 U_STABLE UCalendar* U_EXPORT2
    633 ucal_open(const UChar*   zoneID,
    634           int32_t        len,
    635           const char*    locale,
    636           UCalendarType  type,
    637           UErrorCode*    status);
    638 
    639 /**
    640  * Close a UCalendar.
    641  * Once closed, a UCalendar may no longer be used.
    642  * @param cal The UCalendar to close.
    643  * @stable ICU 2.0
    644  */
    645 U_STABLE void U_EXPORT2
    646 ucal_close(UCalendar *cal);
    647 
    648 #if U_SHOW_CPLUSPLUS_API
    649 
    650 U_NAMESPACE_BEGIN
    651 
    652 /**
    653  * \class LocalUCalendarPointer
    654  * "Smart pointer" class, closes a UCalendar via ucal_close().
    655  * For most methods see the LocalPointerBase base class.
    656  *
    657  * @see LocalPointerBase
    658  * @see LocalPointer
    659  * @draft ICU 4.4
    660  */
    661 U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
    662 
    663 U_NAMESPACE_END
    664 
    665 #endif
    666 
    667 /**
    668  * Open a copy of a UCalendar.
    669  * This function performs a deep copy.
    670  * @param cal The calendar to copy
    671  * @param status A pointer to an UErrorCode to receive any errors.
    672  * @return A pointer to a UCalendar identical to cal.
    673  * @stable ICU 4.0
    674  */
    675 U_STABLE UCalendar* U_EXPORT2
    676 ucal_clone(const UCalendar* cal,
    677            UErrorCode*      status);
    678 
    679 /**
    680  * Set the TimeZone used by a UCalendar.
    681  * A UCalendar uses a timezone for converting from Greenwich time to local time.
    682  * @param cal The UCalendar to set.
    683  * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
    684  * @param len The length of zoneID, or -1 if null-terminated.
    685  * @param status A pointer to an UErrorCode to receive any errors.
    686  * @stable ICU 2.0
    687  */
    688 U_STABLE void U_EXPORT2
    689 ucal_setTimeZone(UCalendar*    cal,
    690                  const UChar*  zoneID,
    691                  int32_t       len,
    692                  UErrorCode*   status);
    693 
    694 /**
    695  * Possible formats for a UCalendar's display name
    696  * @stable ICU 2.0
    697  */
    698 enum UCalendarDisplayNameType {
    699   /** Standard display name */
    700   UCAL_STANDARD,
    701   /** Short standard display name */
    702   UCAL_SHORT_STANDARD,
    703   /** Daylight savings display name */
    704   UCAL_DST,
    705   /** Short daylight savings display name */
    706   UCAL_SHORT_DST
    707 };
    708 
    709 /** @stable ICU 2.0 */
    710 typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
    711 
    712 /**
    713  * Get the display name for a UCalendar's TimeZone.
    714  * A display name is suitable for presentation to a user.
    715  * @param cal          The UCalendar to query.
    716  * @param type         The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
    717  *                     UCAL_DST, UCAL_SHORT_DST
    718  * @param locale       The desired locale for the display name.
    719  * @param result       A pointer to a buffer to receive the formatted number.
    720  * @param resultLength The maximum size of result.
    721  * @param status       A pointer to an UErrorCode to receive any errors
    722  * @return             The total buffer size needed; if greater than resultLength, the output was truncated.
    723  * @stable ICU 2.0
    724  */
    725 U_STABLE int32_t U_EXPORT2
    726 ucal_getTimeZoneDisplayName(const UCalendar*          cal,
    727                             UCalendarDisplayNameType  type,
    728                             const char*               locale,
    729                             UChar*                    result,
    730                             int32_t                   resultLength,
    731                             UErrorCode*               status);
    732 
    733 /**
    734  * Determine if a UCalendar is currently in daylight savings time.
    735  * Daylight savings time is not used in all parts of the world.
    736  * @param cal The UCalendar to query.
    737  * @param status A pointer to an UErrorCode to receive any errors
    738  * @return TRUE if cal is currently in daylight savings time, FALSE otherwise
    739  * @stable ICU 2.0
    740  */
    741 U_STABLE UBool U_EXPORT2
    742 ucal_inDaylightTime(const UCalendar*  cal,
    743                     UErrorCode*       status );
    744 
    745 /**
    746  * Sets the GregorianCalendar change date. This is the point when the switch from
    747  * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
    748  * 15, 1582. Previous to this time and date will be Julian dates.
    749  *
    750  * This function works only for Gregorian calendars. If the UCalendar is not
    751  * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
    752  * error code is set.
    753  *
    754  * @param cal        The calendar object.
    755  * @param date       The given Gregorian cutover date.
    756  * @param pErrorCode Pointer to a standard ICU error code. Its input value must
    757  *                   pass the U_SUCCESS() test, or else the function returns
    758  *                   immediately. Check for U_FAILURE() on output or use with
    759  *                   function chaining. (See User Guide for details.)
    760  *
    761  * @see GregorianCalendar::setGregorianChange
    762  * @see ucal_getGregorianChange
    763  * @stable ICU 3.6
    764  */
    765 U_STABLE void U_EXPORT2
    766 ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
    767 
    768 /**
    769  * Gets the Gregorian Calendar change date. This is the point when the switch from
    770  * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
    771  * 15, 1582. Previous to this time and date will be Julian dates.
    772  *
    773  * This function works only for Gregorian calendars. If the UCalendar is not
    774  * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
    775  * error code is set.
    776  *
    777  * @param cal        The calendar object.
    778  * @param pErrorCode Pointer to a standard ICU error code. Its input value must
    779  *                   pass the U_SUCCESS() test, or else the function returns
    780  *                   immediately. Check for U_FAILURE() on output or use with
    781  *                   function chaining. (See User Guide for details.)
    782  * @return   The Gregorian cutover time for this calendar.
    783  *
    784  * @see GregorianCalendar::getGregorianChange
    785  * @see ucal_setGregorianChange
    786  * @stable ICU 3.6
    787  */
    788 U_STABLE UDate U_EXPORT2
    789 ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
    790 
    791 /**
    792  * Types of UCalendar attributes
    793  * @stable ICU 2.0
    794  */
    795 enum UCalendarAttribute {
    796     /** Lenient parsing */
    797   UCAL_LENIENT,
    798   /** First day of week */
    799   UCAL_FIRST_DAY_OF_WEEK,
    800   /** Minimum number of days in first week */
    801   UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
    802 };
    803 
    804 /** @stable ICU 2.0 */
    805 typedef enum UCalendarAttribute UCalendarAttribute;
    806 
    807 /**
    808  * Get a numeric attribute associated with a UCalendar.
    809  * Numeric attributes include the first day of the week, or the minimal numbers
    810  * of days in the first week of the month.
    811  * @param cal The UCalendar to query.
    812  * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
    813  * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
    814  * @return The value of attr.
    815  * @see ucal_setAttribute
    816  * @stable ICU 2.0
    817  */
    818 U_STABLE int32_t U_EXPORT2
    819 ucal_getAttribute(const UCalendar*    cal,
    820                   UCalendarAttribute  attr);
    821 
    822 /**
    823  * Set a numeric attribute associated with a UCalendar.
    824  * Numeric attributes include the first day of the week, or the minimal numbers
    825  * of days in the first week of the month.
    826  * @param cal The UCalendar to set.
    827  * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
    828  * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
    829  * @param newValue The new value of attr.
    830  * @see ucal_getAttribute
    831  * @stable ICU 2.0
    832  */
    833 U_STABLE void U_EXPORT2
    834 ucal_setAttribute(UCalendar*          cal,
    835                   UCalendarAttribute  attr,
    836                   int32_t             newValue);
    837 
    838 /**
    839  * Get a locale for which calendars are available.
    840  * A UCalendar in a locale returned by this function will contain the correct
    841  * day and month names for the locale.
    842  * @param localeIndex The index of the desired locale.
    843  * @return A locale for which calendars are available, or 0 if none.
    844  * @see ucal_countAvailable
    845  * @stable ICU 2.0
    846  */
    847 U_STABLE const char* U_EXPORT2
    848 ucal_getAvailable(int32_t localeIndex);
    849 
    850 /**
    851  * Determine how many locales have calendars available.
    852  * This function is most useful as determining the loop ending condition for
    853  * calls to \ref ucal_getAvailable.
    854  * @return The number of locales for which calendars are available.
    855  * @see ucal_getAvailable
    856  * @stable ICU 2.0
    857  */
    858 U_STABLE int32_t U_EXPORT2
    859 ucal_countAvailable(void);
    860 
    861 /**
    862  * Get a UCalendar's current time in millis.
    863  * The time is represented as milliseconds from the epoch.
    864  * @param cal The UCalendar to query.
    865  * @param status A pointer to an UErrorCode to receive any errors
    866  * @return The calendar's current time in millis.
    867  * @see ucal_setMillis
    868  * @see ucal_setDate
    869  * @see ucal_setDateTime
    870  * @stable ICU 2.0
    871  */
    872 U_STABLE UDate U_EXPORT2
    873 ucal_getMillis(const UCalendar*  cal,
    874                UErrorCode*       status);
    875 
    876 /**
    877  * Set a UCalendar's current time in millis.
    878  * The time is represented as milliseconds from the epoch.
    879  * @param cal The UCalendar to set.
    880  * @param dateTime The desired date and time.
    881  * @param status A pointer to an UErrorCode to receive any errors
    882  * @see ucal_getMillis
    883  * @see ucal_setDate
    884  * @see ucal_setDateTime
    885  * @stable ICU 2.0
    886  */
    887 U_STABLE void U_EXPORT2
    888 ucal_setMillis(UCalendar*   cal,
    889                UDate        dateTime,
    890                UErrorCode*  status );
    891 
    892 /**
    893  * Set a UCalendar's current date.
    894  * The date is represented as a series of 32-bit integers.
    895  * @param cal The UCalendar to set.
    896  * @param year The desired year.
    897  * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
    898  * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
    899  * @param date The desired day of the month.
    900  * @param status A pointer to an UErrorCode to receive any errors
    901  * @see ucal_getMillis
    902  * @see ucal_setMillis
    903  * @see ucal_setDateTime
    904  * @stable ICU 2.0
    905  */
    906 U_STABLE void U_EXPORT2
    907 ucal_setDate(UCalendar*   cal,
    908              int32_t      year,
    909              int32_t      month,
    910              int32_t      date,
    911              UErrorCode*  status);
    912 
    913 /**
    914  * Set a UCalendar's current date.
    915  * The date is represented as a series of 32-bit integers.
    916  * @param cal The UCalendar to set.
    917  * @param year The desired year.
    918  * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
    919  * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
    920  * @param date The desired day of the month.
    921  * @param hour The desired hour of day.
    922  * @param minute The desired minute.
    923  * @param second The desirec second.
    924  * @param status A pointer to an UErrorCode to receive any errors
    925  * @see ucal_getMillis
    926  * @see ucal_setMillis
    927  * @see ucal_setDate
    928  * @stable ICU 2.0
    929  */
    930 U_STABLE void U_EXPORT2
    931 ucal_setDateTime(UCalendar*   cal,
    932                  int32_t      year,
    933                  int32_t      month,
    934                  int32_t      date,
    935                  int32_t      hour,
    936                  int32_t      minute,
    937                  int32_t      second,
    938                  UErrorCode*  status);
    939 
    940 /**
    941  * Returns TRUE if two UCalendars are equivalent.  Equivalent
    942  * UCalendars will behave identically, but they may be set to
    943  * different times.
    944  * @param cal1 The first of the UCalendars to compare.
    945  * @param cal2 The second of the UCalendars to compare.
    946  * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise.
    947  * @stable ICU 2.0
    948  */
    949 U_STABLE UBool U_EXPORT2
    950 ucal_equivalentTo(const UCalendar*  cal1,
    951                   const UCalendar*  cal2);
    952 
    953 /**
    954  * Add a specified signed amount to a particular field in a UCalendar.
    955  * This can modify more significant fields in the calendar.
    956  * @param cal The UCalendar to which to add.
    957  * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
    958  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
    959  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
    960  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
    961  * @param amount The signed amount to add to field. If the amount causes the value
    962  * to exceed to maximum or minimum values for that field, other fields are modified
    963  * to preserve the magnitude of the change.
    964  * @param status A pointer to an UErrorCode to receive any errors
    965  * @see ucal_roll
    966  * @stable ICU 2.0
    967  */
    968 U_STABLE void U_EXPORT2
    969 ucal_add(UCalendar*           cal,
    970          UCalendarDateFields  field,
    971          int32_t              amount,
    972          UErrorCode*          status);
    973 
    974 /**
    975  * Add a specified signed amount to a particular field in a UCalendar.
    976  * This will not modify more significant fields in the calendar.
    977  * @param cal The UCalendar to which to add.
    978  * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
    979  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
    980  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
    981  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
    982  * @param amount The signed amount to add to field. If the amount causes the value
    983  * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
    984  * value.
    985  * @param status A pointer to an UErrorCode to receive any errors
    986  * @see ucal_add
    987  * @stable ICU 2.0
    988  */
    989 U_STABLE void U_EXPORT2
    990 ucal_roll(UCalendar*           cal,
    991           UCalendarDateFields  field,
    992           int32_t              amount,
    993           UErrorCode*          status);
    994 
    995 /**
    996  * Get the current value of a field from a UCalendar.
    997  * All fields are represented as 32-bit integers.
    998  * @param cal The UCalendar to query.
    999  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1000  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1001  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1002  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1003  * @param status A pointer to an UErrorCode to receive any errors
   1004  * @return The value of the desired field.
   1005  * @see ucal_set
   1006  * @see ucal_isSet
   1007  * @see ucal_clearField
   1008  * @see ucal_clear
   1009  * @stable ICU 2.0
   1010  */
   1011 U_STABLE int32_t U_EXPORT2
   1012 ucal_get(const UCalendar*     cal,
   1013          UCalendarDateFields  field,
   1014          UErrorCode*          status );
   1015 
   1016 /**
   1017  * Set the value of a field in a UCalendar.
   1018  * All fields are represented as 32-bit integers.
   1019  * @param cal The UCalendar to set.
   1020  * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1021  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1022  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1023  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1024  * @param value The desired value of field.
   1025  * @see ucal_get
   1026  * @see ucal_isSet
   1027  * @see ucal_clearField
   1028  * @see ucal_clear
   1029  * @stable ICU 2.0
   1030  */
   1031 U_STABLE void U_EXPORT2
   1032 ucal_set(UCalendar*           cal,
   1033          UCalendarDateFields  field,
   1034          int32_t              value);
   1035 
   1036 /**
   1037  * Determine if a field in a UCalendar is set.
   1038  * All fields are represented as 32-bit integers.
   1039  * @param cal The UCalendar to query.
   1040  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1041  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1042  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1043  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1044  * @return TRUE if field is set, FALSE otherwise.
   1045  * @see ucal_get
   1046  * @see ucal_set
   1047  * @see ucal_clearField
   1048  * @see ucal_clear
   1049  * @stable ICU 2.0
   1050  */
   1051 U_STABLE UBool U_EXPORT2
   1052 ucal_isSet(const UCalendar*     cal,
   1053            UCalendarDateFields  field);
   1054 
   1055 /**
   1056  * Clear a field in a UCalendar.
   1057  * All fields are represented as 32-bit integers.
   1058  * @param cal The UCalendar containing the field to clear.
   1059  * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1060  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1061  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1062  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1063  * @see ucal_get
   1064  * @see ucal_set
   1065  * @see ucal_isSet
   1066  * @see ucal_clear
   1067  * @stable ICU 2.0
   1068  */
   1069 U_STABLE void U_EXPORT2
   1070 ucal_clearField(UCalendar*           cal,
   1071                 UCalendarDateFields  field);
   1072 
   1073 /**
   1074  * Clear all fields in a UCalendar.
   1075  * All fields are represented as 32-bit integers.
   1076  * @param calendar The UCalendar to clear.
   1077  * @see ucal_get
   1078  * @see ucal_set
   1079  * @see ucal_isSet
   1080  * @see ucal_clearField
   1081  * @stable ICU 2.0
   1082  */
   1083 U_STABLE void U_EXPORT2
   1084 ucal_clear(UCalendar* calendar);
   1085 
   1086 /**
   1087  * Possible limit values for a UCalendar
   1088  * @stable ICU 2.0
   1089  */
   1090 enum UCalendarLimitType {
   1091   /** Minimum value */
   1092   UCAL_MINIMUM,
   1093   /** Maximum value */
   1094   UCAL_MAXIMUM,
   1095   /** Greatest minimum value */
   1096   UCAL_GREATEST_MINIMUM,
   1097   /** Leaest maximum value */
   1098   UCAL_LEAST_MAXIMUM,
   1099   /** Actual minimum value */
   1100   UCAL_ACTUAL_MINIMUM,
   1101   /** Actual maximum value */
   1102   UCAL_ACTUAL_MAXIMUM
   1103 };
   1104 
   1105 /** @stable ICU 2.0 */
   1106 typedef enum UCalendarLimitType UCalendarLimitType;
   1107 
   1108 /**
   1109  * Determine a limit for a field in a UCalendar.
   1110  * A limit is a maximum or minimum value for a field.
   1111  * @param cal The UCalendar to query.
   1112  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
   1113  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
   1114  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
   1115  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
   1116  * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM,
   1117  * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
   1118  * @param status A pointer to an UErrorCode to receive any errors.
   1119  * @return The requested value.
   1120  * @stable ICU 2.0
   1121  */
   1122 U_STABLE int32_t U_EXPORT2
   1123 ucal_getLimit(const UCalendar*     cal,
   1124               UCalendarDateFields  field,
   1125               UCalendarLimitType   type,
   1126               UErrorCode*          status);
   1127 
   1128 /** Get the locale for this calendar object. You can choose between valid and actual locale.
   1129  *  @param cal The calendar object
   1130  *  @param type type of the locale we're looking for (valid or actual)
   1131  *  @param status error code for the operation
   1132  *  @return the locale name
   1133  *  @stable ICU 2.8
   1134  */
   1135 U_STABLE const char * U_EXPORT2
   1136 ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
   1137 
   1138 /**
   1139  * Returns the timezone data version currently used by ICU.
   1140  * @param status error code for the operation
   1141  * @return the version string, such as "2007f"
   1142  * @stable ICU 3.8
   1143  */
   1144 U_STABLE const char * U_EXPORT2
   1145 ucal_getTZDataVersion(UErrorCode* status);
   1146 
   1147 /**
   1148  * Returns the canonical system timezone ID or the normalized
   1149  * custom time zone ID for the given time zone ID.
   1150  * @param id        The input timezone ID to be canonicalized.
   1151  * @param len       The length of id, or -1 if null-terminated.
   1152  * @param result    The buffer receives the canonical system timezone ID
   1153  *                  or the custom timezone ID in normalized format.
   1154  * @param resultCapacity    The capacity of the result buffer.
   1155  * @param isSystemID        Receives if the given ID is a known system
   1156      *                      timezone ID.
   1157  * @param status    Recevies the status.  When the given timezone ID
   1158  *                  is neither a known system time zone ID nor a
   1159  *                  valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
   1160  *                  is set.
   1161  * @return          The result string length, not including the terminating
   1162  *                  null.
   1163  * @stable ICU 4.0
   1164  */
   1165 U_STABLE int32_t U_EXPORT2
   1166 ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
   1167                             UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
   1168 /**
   1169  * Get the resource keyword value string designating the calendar type for the UCalendar.
   1170  * @param cal The UCalendar to query.
   1171  * @param status The error code for the operation.
   1172  * @return The resource keyword value string.
   1173  * @stable ICU 4.2
   1174  */
   1175 U_STABLE const char * U_EXPORT2
   1176 ucal_getType(const UCalendar *cal, UErrorCode* status);
   1177 
   1178 /**
   1179  * Given a key and a locale, returns an array of string values in a preferred
   1180  * order that would make a difference. These are all and only those values where
   1181  * the open (creation) of the service with the locale formed from the input locale
   1182  * plus input keyword and that value has different behavior than creation with the
   1183  * input locale alone.
   1184  * @param key           one of the keys supported by this service.  For now, only
   1185  *                      "calendar" is supported.
   1186  * @param locale        the locale
   1187  * @param commonlyUsed  if set to true it will return only commonly used values
   1188  *                      with the given locale in preferred order.  Otherwise,
   1189  *                      it will return all the available values for the locale.
   1190  * @param status error status
   1191  * @return a string enumeration over keyword values for the given key and the locale.
   1192  * @stable ICU 4.2
   1193  */
   1194 U_STABLE UEnumeration* U_EXPORT2
   1195 ucal_getKeywordValuesForLocale(const char* key,
   1196                                const char* locale,
   1197                                UBool commonlyUsed,
   1198                                UErrorCode* status);
   1199 
   1200 
   1201 /** Weekday types, as returned by ucal_getDayOfWeekType().
   1202  * @draft ICU 4.4
   1203  */
   1204 enum UCalendarWeekdayType {
   1205   /**
   1206    * Designates a full weekday (no part of the day is included in the weekend).
   1207    */
   1208   UCAL_WEEKDAY,
   1209   /**
   1210    * Designates a full weekend day (the entire day is included in the weekend).
   1211    */
   1212   UCAL_WEEKEND,
   1213   /**
   1214    * Designates a day that starts as a weekday and transitions to the weekend.
   1215    * Call ucal_getWeekendTransition() to get the time of transition.
   1216    */
   1217   UCAL_WEEKEND_ONSET,
   1218   /**
   1219    * Designates a day that starts as the weekend and transitions to a weekday.
   1220    * Call ucal_getWeekendTransition() to get the time of transition.
   1221    */
   1222   UCAL_WEEKEND_CEASE
   1223 };
   1224 
   1225 /** @draft ICU 4.4 */
   1226 typedef enum UCalendarWeekdayType UCalendarWeekdayType;
   1227 
   1228 /**
   1229  * Returns whether the given day of the week is a weekday, a
   1230  * weekend day, or a day that transitions from one to the other,
   1231  * in this calendar system. If a transition occurs at midnight,
   1232  * then the days before and after the transition will have the
   1233  * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time
   1234  * other than midnight, then the day of the transition will have
   1235  * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the
   1236  * method getWeekendTransition() will return the point of
   1237  * transition.
   1238  * @param cal The UCalendar to query.
   1239  * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY).
   1240  * @param status The error code for the operation.
   1241  * @return The UCalendarWeekdayType for the day of the week.
   1242  * @draft ICU 4.4
   1243  */
   1244 U_DRAFT UCalendarWeekdayType U_EXPORT2
   1245 ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status);
   1246 
   1247 /**
   1248  * Returns the time during the day at which the weekend begins or ends in
   1249  * this calendar system.  If ucal_getDayOfWeekType() rerturns UCAL_WEEKEND_ONSET
   1250  * for the specified dayOfWeek, return the time at which the weekend begins.
   1251  * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
   1252  * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns
   1253  * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
   1254  * (U_ILLEGAL_ARGUMENT_ERROR).
   1255  * @param cal The UCalendar to query.
   1256  * @param dayOfWeek The day of the week for which the weekend transition time is
   1257  * desired (UCAL_SUNDAY..UCAL_SATURDAY).
   1258  * @param status The error code for the operation.
   1259  * @return The milliseconds after midnight at which the weekend begins or ends.
   1260  * @draft ICU 4.4
   1261  */
   1262 U_DRAFT int32_t U_EXPORT2
   1263 ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
   1264 
   1265 /**
   1266  * Returns TRUE if the given UDate is in the weekend in
   1267  * this calendar system.
   1268  * @param cal The UCalendar to query.
   1269  * @param date The UDate in question.
   1270  * @param status The error code for the operation.
   1271  * @return TRUE if the given UDate is in the weekend in
   1272  * this calendar system, FALSE otherwise.
   1273  * @draft ICU 4.4
   1274  */
   1275 U_DRAFT UBool U_EXPORT2
   1276 ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status);
   1277 
   1278 
   1279 #endif /* #if !UCONFIG_NO_FORMATTING */
   1280 
   1281 #endif
   1282