icuSources/i18n/unicode/ucal.h

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