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