icuSources/i18n/unicode/ucal.h

   1 /*
   2  *******************************************************************************
   3  * Copyright (C) 1996-2008, 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
  15 #if !UCONFIG_NO_FORMATTING
  16
  17 /**
  18  * \file
  19  * \brief C API: Calendar
  20  *
  21  * <h2>Calendar C API</h2>
  22  *
  23  * UCalendar C API is used  for converting between a <code>UDate</code> object
  24  * and a set of integer fields such as <code>UCAL_YEAR</code>, <code>UCAL_MONTH</code>,
  25  * <code>UCAL_DAY</code>, <code>UCAL_HOUR</code>, and so on.
  26  * (A <code>UDate</code> object represents a specific instant in
  27  * time with millisecond precision. See UDate
  28  * for information about the <code>UDate</code> .)
  29  *
  30  * <p>
  31  * Types of <code>UCalendar</code> interpret a <code>UDate</code>
  32  * according to the rules of a specific calendar system. The U_STABLE
  33  * provides the enum UCalendarType with UCAL_TRADITIONAL and
  34  * UCAL_GREGORIAN.
  35  * <p>
  36  * Like other locale-sensitive C API, calendar API  provides a
  37  * function, <code>ucal_open()</code>, which returns a pointer to
  38  * <code>UCalendar</code> whose time fields have been initialized
  39  * with the current date and time. We need to specify the type of
  40  * calendar to be opened and the  timezoneId.
  41  * \htmlonly<blockquote>\endhtmlonly
  42  * <pre>
  43  * \code
  44  * UCalendar *caldef;
  45  * UChar *tzId;
  46  * UErrorCode status;
  47  * tzId=(UChar*)malloc(sizeof(UChar) * (strlen("PST") +1) );
  48  * u_uastrcpy(tzId, "PST");
  49  * caldef=ucal_open(tzID, u_strlen(tzID), NULL, UCAL_TRADITIONAL, &status);
  50  * \endcode
  51  * </pre>
  52  * \htmlonly</blockquote>\endhtmlonly
  53  *
  54  * <p>
  55  * A <code>UCalendar</code> object can produce all the time field values
  56  * needed to implement the date-time formatting for a particular language
  57  * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
  58  *
  59  * <p>
  60  * When computing a <code>UDate</code> from time fields, two special circumstances
  61  * may arise: there may be insufficient information to compute the
  62  * <code>UDate</code> (such as only year and month but no day in the month),
  63  * or there may be inconsistent information (such as "Tuesday, July 15, 1996"
  64  * -- July 15, 1996 is actually a Monday).
  65  *
  66  * <p>
  67  * <strong>Insufficient information.</strong> The calendar will use default
  68  * information to specify the missing fields. This may vary by calendar; for
  69  * the Gregorian calendar, the default for a field is the same as that of the
  70  * start of the epoch: i.e., UCAL_YEAR = 1970, UCAL_MONTH = JANUARY, UCAL_DATE = 1, etc.
  71  *
  72  * <p>
  73  * <strong>Inconsistent information.</strong> If fields conflict, the calendar
  74  * will give preference to fields set more recently. For example, when
  75  * determining the day, the calendar will look for one of the following
  76  * combinations of fields.  The most recent combination, as determined by the
  77  * most recently set single field, will be used.
  78  *
  79  * \htmlonly<blockquote>\endhtmlonly
  80  * <pre>
  81  * \code
  82  * UCAL_MONTH + UCAL_DAY_OF_MONTH
  83  * UCAL_MONTH + UCAL_WEEK_OF_MONTH + UCAL_DAY_OF_WEEK
  84  * UCAL_MONTH + UCAL_DAY_OF_WEEK_IN_MONTH + UCAL_DAY_OF_WEEK
  85  * UCAL_DAY_OF_YEAR
  86  * UCAL_DAY_OF_WEEK + UCAL_WEEK_OF_YEAR
  87  * \endcode
  88  * </pre>
  89  * \htmlonly</blockquote>\endhtmlonly
  90  *
  91  * For the time of day:
  92  *
  93  * \htmlonly<blockquote>\endhtmlonly
  94  * <pre>
  95  * \code
  96  * UCAL_HOUR_OF_DAY
  97  * UCAL_AM_PM + UCAL_HOUR
  98  * \endcode
  99  * </pre>
 100  * \htmlonly</blockquote>\endhtmlonly
 101  *
 102  * <p>
 103  * <strong>Note:</strong> for some non-Gregorian calendars, different
 104  * fields may be necessary for complete disambiguation. For example, a full
 105  * specification of the historial Arabic astronomical calendar requires year,
 106  * month, day-of-month <em>and</em> day-of-week in some cases.
 107  *
 108  * <p>
 109  * <strong>Note:</strong> There are certain possible ambiguities in
 110  * interpretation of certain singular times, which are resolved in the
 111  * following ways:
 112  * <ol>
 113  *     <li> 24:00:00 "belongs" to the following day. That is,
 114  *          23:59 on Dec 31, 1969 &lt; 24:00 on Jan 1, 1970 &lt; 24:01:00 on Jan 1, 1970
 115  *
 116  *     <li> Although historically not precise, midnight also belongs to "am",
 117  *          and noon belongs to "pm", so on the same day,
 118  *          12:00 am (midnight) &lt; 12:01 am, and 12:00 pm (noon) &lt; 12:01 pm
 119  * </ol>
 120  *
 121  * <p>
 122  * The date or time format strings are not part of the definition of a
 123  * calendar, as those must be modifiable or overridable by the user at
 124  * runtime. Use {@link DateFormat}
 125  * to format dates.
 126  *
 127  * <p>
 128  * <code>Calendar</code> provides an API for field "rolling", where fields
 129  * can be incremented or decremented, but wrap around. For example, rolling the
 130  * month up in the date <code>December 12, <b>1996</b></code> results in
 131  * <code>January 12, <b>1996</b></code>.
 132  *
 133  * <p>
 134  * <code>Calendar</code> also provides a date arithmetic function for
 135  * adding the specified (signed) amount of time to a particular time field.
 136  * For example, subtracting 5 days from the date <code>September 12, 1996</code>
 137  * results in <code>September 7, 1996</code>.
 138  *
 139  * @stable ICU 2.0
 140  */
 141
 142 /** A calendar.
 143  *  For usage in C programs.
 144  * @stable ICU 2.0
 145  */
 146 typedef void* UCalendar;
 147
 148 /** Possible types of UCalendars
 149  * @stable ICU 2.0
 150  */
 151 enum UCalendarType {
 152   /**
 153    * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar,
 154    * which may be the Gregorian calendar or some other calendar.
 155    * @stable ICU 2.0
 156    */
 157   UCAL_TRADITIONAL,
 158   /**
 159    * Unambiguously designates the Gregorian calendar for the locale.
 160    * @stable ICU 2.0
 161    */
 162   UCAL_GREGORIAN,
 163   /**
 164    * A better name for UCAL_TRADITIONAL.
 165    * @draft ICU 4.2
 166    */
 167   UCAL_DEFAULT = UCAL_TRADITIONAL
 168 };
 169
 170 /** @stable ICU 2.0 */
 171 typedef enum UCalendarType UCalendarType;
 172
 173 /** Possible fields in a UCalendar
 174  * @stable ICU 2.0
 175  */
 176 enum UCalendarDateFields {
 177   /**
 178    * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar.
 179    * This is a calendar-specific value.
 180    * @stable ICU 2.6
 181    */
 182   UCAL_ERA,
 183
 184   /**
 185    * Field number indicating the year. This is a calendar-specific value.
 186    * @stable ICU 2.6
 187    */
 188   UCAL_YEAR,
 189
 190   /**
 191    * Field number indicating the month. This is a calendar-specific value.
 192    * The first month of the year is
 193    * <code>JANUARY</code>; the last depends on the number of months in a year.
 194    * @see #UCAL_JANUARY
 195    * @see #UCAL_FEBRUARY
 196    * @see #UCAL_MARCH
 197    * @see #UCAL_APRIL
 198    * @see #UCAL_MAY
 199    * @see #UCAL_JUNE
 200    * @see #UCAL_JULY
 201    * @see #UCAL_AUGUST
 202    * @see #UCAL_SEPTEMBER
 203    * @see #UCAL_OCTOBER
 204    * @see #UCAL_NOVEMBER
 205    * @see #UCAL_DECEMBER
 206    * @see #UCAL_UNDECIMBER
 207    * @stable ICU 2.6
 208    */
 209   UCAL_MONTH,
 210
 211   /**
 212    * Field number indicating the
 213    * week number within the current year.  The first week of the year, as
 214    * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
 215    * attributes, has value 1.  Subclasses define
 216    * the value of <code>UCAL_WEEK_OF_YEAR</code> for days before the first week of
 217    * the year.
 218    * @see ucal_getAttribute
 219    * @see ucal_setAttribute
 220    * @stable ICU 2.6
 221    */
 222   UCAL_WEEK_OF_YEAR,
 223
 224  /**
 225    * Field number indicating the
 226    * week number within the current month.  The first week of the month, as
 227    * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
 228    * attributes, has value 1.  Subclasses define
 229    * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
 230    * the month.
 231    * @see ucal_getAttribute
 232    * @see ucal_setAttribute
 233    * @see #UCAL_FIRST_DAY_OF_WEEK
 234    * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
 235    * @stable ICU 2.6
 236    */
 237   UCAL_WEEK_OF_MONTH,
 238
 239  /**
 240    * Field number indicating the
 241    * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
 242    * The first day of the month has value 1.
 243    * @see #UCAL_DAY_OF_MONTH
 244    * @stable ICU 2.6
 245    */
 246   UCAL_DATE,
 247
 248  /**
 249    * Field number indicating the day
 250    * number within the current year.  The first day of the year has value 1.
 251    * @stable ICU 2.6
 252    */
 253   UCAL_DAY_OF_YEAR,
 254
 255  /**
 256    * Field number indicating the day
 257    * of the week.  This field takes values <code>SUNDAY</code>,
 258    * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
 259    * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
 260    * @see #UCAL_SUNDAY
 261    * @see #UCAL_MONDAY
 262    * @see #UCAL_TUESDAY
 263    * @see #UCAL_WEDNESDAY
 264    * @see #UCAL_THURSDAY
 265    * @see #UCAL_FRIDAY
 266    * @see #UCAL_SATURDAY
 267    * @stable ICU 2.6
 268    */
 269   UCAL_DAY_OF_WEEK,
 270
 271  /**
 272    * Field number indicating the
 273    * ordinal number of the day of the week within the current month. Together
 274    * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
 275    * within a month.  Unlike <code>WEEK_OF_MONTH</code> and
 276    * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
 277    * <code>getFirstDayOfWeek()</code> or
 278    * <code>getMinimalDaysInFirstWeek()</code>.  <code>DAY_OF_MONTH 1</code>
 279    * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
 280    * 1</code>; <code>8</code> through <code>15</code> correspond to
 281    * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
 282    * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
 283    * <code>DAY_OF_WEEK_IN_MONTH 1</code>.  Negative values count back from the
 284    * end of the month, so the last Sunday of a month is specified as
 285    * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>.  Because
 286    * negative values count backward they will usually be aligned differently
 287    * within the month than positive values.  For example, if a month has 31
 288    * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
 289    * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
 290    * @see #UCAL_DAY_OF_WEEK
 291    * @see #UCAL_WEEK_OF_MONTH
 292    * @stable ICU 2.6
 293    */
 294   UCAL_DAY_OF_WEEK_IN_MONTH,
 295
 296  /**
 297    * Field number indicating
 298    * whether the <code>HOUR</code> is before or after noon.
 299    * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
 300    * @see #UCAL_AM
 301    * @see #UCAL_PM
 302    * @see #UCAL_HOUR
 303    * @stable ICU 2.6
 304    */
 305   UCAL_AM_PM,
 306
 307  /**
 308    * Field number indicating the
 309    * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour
 310    * clock.
 311    * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
 312    * @see #UCAL_AM_PM
 313    * @see #UCAL_HOUR_OF_DAY
 314    * @stable ICU 2.6
 315    */
 316   UCAL_HOUR,
 317
 318  /**
 319    * Field number indicating the
 320    * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
 321    * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
 322    * @see #UCAL_HOUR
 323    * @stable ICU 2.6
 324    */
 325   UCAL_HOUR_OF_DAY,
 326
 327  /**
 328    * Field number indicating the
 329    * minute within the hour.
 330    * E.g., at 10:04:15.250 PM the <code>UCAL_MINUTE</code> is 4.
 331    * @stable ICU 2.6
 332    */
 333   UCAL_MINUTE,
 334
 335  /**
 336    * Field number indicating the
 337    * second within the minute.
 338    * E.g., at 10:04:15.250 PM the <code>UCAL_SECOND</code> is 15.
 339    * @stable ICU 2.6
 340    */
 341   UCAL_SECOND,
 342
 343  /**
 344    * Field number indicating the
 345    * millisecond within the second.
 346    * E.g., at 10:04:15.250 PM the <code>UCAL_MILLISECOND</code> is 250.
 347    * @stable ICU 2.6
 348    */
 349   UCAL_MILLISECOND,
 350
 351  /**
 352    * Field number indicating the
 353    * raw offset from GMT in milliseconds.
 354    * @stable ICU 2.6
 355    */
 356   UCAL_ZONE_OFFSET,
 357
 358  /**
 359    * Field number indicating the
 360    * daylight savings offset in milliseconds.
 361    * @stable ICU 2.6
 362    */
 363   UCAL_DST_OFFSET,
 364
 365  /**
 366    * Field number
 367    * indicating the extended year corresponding to the
 368    * <code>UCAL_WEEK_OF_YEAR</code> field.  This may be one greater or less
 369    * than the value of <code>UCAL_EXTENDED_YEAR</code>.
 370    * @stable ICU 2.6
 371    */
 372   UCAL_YEAR_WOY,
 373
 374  /**
 375    * Field number
 376    * indicating the localized day of week.  This will be a value from 1
 377    * to 7 inclusive, with 1 being the localized first day of the week.
 378    * @stable ICU 2.6
 379    */
 380   UCAL_DOW_LOCAL,
 381
 382   /**
 383    * Year of this calendar system, encompassing all supra-year fields. For example,
 384    * in Gregorian/Julian calendars, positive Extended Year values indicate years AD,
 385    *  1 BC = 0 extended, 2 BC = -1 extended, and so on.
 386    * @stable ICU 2.8
 387    */
 388   UCAL_EXTENDED_YEAR,
 389
 390  /**
 391    * Field number
 392    * indicating the modified Julian day number.  This is different from
 393    * the conventional Julian day number in two regards.  First, it
 394    * demarcates days at local zone midnight, rather than noon GMT.
 395    * Second, it is a local number; that is, it depends on the local time
 396    * zone.  It can be thought of as a single number that encompasses all
 397    * the date-related fields.
 398    * @stable ICU 2.8
 399    */
 400   UCAL_JULIAN_DAY,
 401
 402   /**
 403    * Ranges from 0 to 23:59:59.999 (regardless of DST).  This field behaves <em>exactly</em>
 404    * like a composite of all time-related fields, not including the zone fields.  As such,
 405    * it also reflects discontinuities of those fields on DST transition days.  On a day
 406    * of DST onset, it will jump forward.  On a day of DST cessation, it will jump
 407    * backward.  This reflects the fact that it must be combined with the DST_OFFSET field
 408    * to obtain a unique local time value.
 409    * @stable ICU 2.8
 410    */
 411   UCAL_MILLISECONDS_IN_DAY,
 412
 413   /**
 414    * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for
 415    * an example of this.
 416    */
 417   UCAL_IS_LEAP_MONTH,
 418
 419   /**
 420    * Field count
 421    * @stable ICU 2.6
 422    */
 423   UCAL_FIELD_COUNT,
 424
 425  /**
 426    * Field number indicating the
 427    * day of the month. This is a synonym for <code>UCAL_DATE</code>.
 428    * The first day of the month has value 1.
 429    * @see #UCAL_DATE
 430    * Synonym for UCAL_DATE
 431    * @stable ICU 2.8
 432    **/
 433   UCAL_DAY_OF_MONTH=UCAL_DATE
 434 };
 435
 436 /** @stable ICU 2.0 */
 437 typedef enum UCalendarDateFields UCalendarDateFields;
 438     /**
 439      * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
 440      * who create locale resources for the field of first-day-of-week should be aware of
 441      * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
 442      */
 443 /** Possible days of the week in a UCalendar
 444  * @stable ICU 2.0
 445  */
 446 enum UCalendarDaysOfWeek {
 447   /** Sunday */
 448   UCAL_SUNDAY = 1,
 449   /** Monday */
 450   UCAL_MONDAY,
 451   /** Tuesday */
 452   UCAL_TUESDAY,
 453   /** Wednesday */
 454   UCAL_WEDNESDAY,
 455   /** Thursday */
 456   UCAL_THURSDAY,
 457   /** Friday */
 458   UCAL_FRIDAY,
 459   /** Saturday */
 460   UCAL_SATURDAY
 461 };
 462
 463 /** @stable ICU 2.0 */
 464 typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
 465
 466 /** Possible months in a UCalendar. Note: Calendar month is 0-based.
 467  * @stable ICU 2.0
 468  */
 469 enum UCalendarMonths {
 470   /** January */
 471   UCAL_JANUARY,
 472   /** February */
 473   UCAL_FEBRUARY,
 474   /** March */
 475   UCAL_MARCH,
 476   /** April */
 477   UCAL_APRIL,
 478   /** May */
 479   UCAL_MAY,
 480   /** June */
 481   UCAL_JUNE,
 482   /** July */
 483   UCAL_JULY,
 484   /** August */
 485   UCAL_AUGUST,
 486   /** September */
 487   UCAL_SEPTEMBER,
 488   /** October */
 489   UCAL_OCTOBER,
 490   /** November */
 491   UCAL_NOVEMBER,
 492   /** December */
 493   UCAL_DECEMBER,
 494   /** Value of the <code>UCAL_MONTH</code> field indicating the
 495     * thirteenth month of the year. Although the Gregorian calendar
 496     * does not use this value, lunar calendars do.
 497     */
 498   UCAL_UNDECIMBER
 499 };
 500
 501 /** @stable ICU 2.0 */
 502 typedef enum UCalendarMonths UCalendarMonths;
 503
 504 /** Possible AM/PM values in a UCalendar
 505  * @stable ICU 2.0
 506  */
 507 enum UCalendarAMPMs {
 508     /** AM */
 509   UCAL_AM,
 510   /** PM */
 511   UCAL_PM
 512 };
 513
 514 /** @stable ICU 2.0 */
 515 typedef enum UCalendarAMPMs UCalendarAMPMs;
 516
 517 /**
 518  * Create an enumeration over all time zones.
 519  *
 520  * @param ec input/output error code
 521  *
 522  * @return an enumeration object that the caller must dispose of using
 523  * uenum_close(), or NULL upon failure. In case of failure *ec will
 524  * indicate the error.
 525  *
 526  * @stable ICU 2.6
 527  */
 528 U_STABLE UEnumeration* U_EXPORT2
 529 ucal_openTimeZones(UErrorCode* ec);
 530
 531 /**
 532  * Create an enumeration over all time zones associated with the given
 533  * country. Some zones are affiliated with no country (e.g., "UTC");
 534  * these may also be retrieved, as a group.
 535  *
 536  * @param country the ISO 3166 two-letter country code, or NULL to
 537  * retrieve zones not affiliated with any country
 538  *
 539  * @param ec input/output error code
 540  *
 541  * @return an enumeration object that the caller must dispose of using
 542  * uenum_close(), or NULL upon failure. In case of failure *ec will
 543  * indicate the error.
 544  *
 545  * @stable ICU 2.6
 546  */
 547 U_STABLE UEnumeration* U_EXPORT2
 548 ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
 549
 550 /**
 551  * Return the default time zone. The default is determined initially
 552  * by querying the host operating system. It may be changed with
 553  * ucal_setDefaultTimeZone() or with the C++ TimeZone API.
 554  *
 555  * @param result A buffer to receive the result, or NULL
 556  *
 557  * @param resultCapacity The capacity of the result buffer
 558  *
 559  * @param ec input/output error code
 560  *
 561  * @return The result string length, not including the terminating
 562  * null
 563  *
 564  * @stable ICU 2.6
 565  */
 566 U_STABLE int32_t U_EXPORT2
 567 ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
 568
 569 /**
 570  * Set the default time zone.
 571  *
 572  * @param zoneID null-terminated time zone ID
 573  *
 574  * @param ec input/output error code
 575  *
 576  * @stable ICU 2.6
 577  */
 578 U_STABLE void U_EXPORT2
 579 ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
 580
 581 /**
 582  * Return the amount of time in milliseconds that the clock is
 583  * advanced during daylight savings time for the given time zone, or
 584  * zero if the time zone does not observe daylight savings time.
 585  *
 586  * @param zoneID null-terminated time zone ID
 587  *
 588  * @param ec input/output error code
 589  *
 590  * @return the number of milliseconds the time is advanced with
 591  * respect to standard time when the daylight savings rules are in
 592  * effect. This is always a non-negative number, most commonly either
 593  * 3,600,000 (one hour) or zero.
 594  *
 595  * @stable ICU 2.6
 596  */
 597 U_STABLE int32_t U_EXPORT2
 598 ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
 599
 600 /**
 601  * Get the current date and time.
 602  * The value returned is represented as milliseconds from the epoch.
 603  * @return The current date and time.
 604  * @stable ICU 2.0
 605  */
 606 U_STABLE UDate U_EXPORT2
 607 ucal_getNow(void);
 608
 609 /**
 610  * Open a UCalendar.
 611  * A UCalendar may be used to convert a millisecond value to a year,
 612  * month, and day.
 613  * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
 614  * @param len The length of zoneID, or -1 if null-terminated.
 615  * @param locale The desired locale
 616  * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
 617  * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
 618  * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
 619  * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
 620  * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
 621  * @param status A pointer to an UErrorCode to receive any errors
 622  * @return A pointer to a UCalendar, or 0 if an error occurred.
 623  * @stable ICU 2.0
 624  */
 625 U_STABLE UCalendar* U_EXPORT2
 626 ucal_open(const UChar*   zoneID,
 627           int32_t        len,
 628           const char*    locale,
 629           UCalendarType  type,
 630           UErrorCode*    status);
 631
 632 /**
 633  * Close a UCalendar.
 634  * Once closed, a UCalendar may no longer be used.
 635  * @param cal The UCalendar to close.
 636  * @stable ICU 2.0
 637  */
 638 U_STABLE void U_EXPORT2
 639 ucal_close(UCalendar *cal);
 640
 641 /**
 642  * Open a copy of a UCalendar.
 643  * This function performs a deep copy.
 644  * @param cal The calendar to copy
 645  * @param status A pointer to an UErrorCode to receive any errors.
 646  * @return A pointer to a UCalendar identical to cal.
 647  * @draft ICU 4.0
 648  */
 649 U_DRAFT UCalendar* U_EXPORT2
 650 ucal_clone(const UCalendar* cal,
 651            UErrorCode*      status);
 652
 653 /**
 654  * Set the TimeZone used by a UCalendar.
 655  * A UCalendar uses a timezone for converting from Greenwich time to local time.
 656  * @param cal The UCalendar to set.
 657  * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
 658  * @param len The length of zoneID, or -1 if null-terminated.
 659  * @param status A pointer to an UErrorCode to receive any errors.
 660  * @stable ICU 2.0
 661  */
 662 U_STABLE void U_EXPORT2
 663 ucal_setTimeZone(UCalendar*    cal,
 664                  const UChar*  zoneID,
 665                  int32_t       len,
 666                  UErrorCode*   status);
 667
 668 /**
 669  * Possible formats for a UCalendar's display name
 670  * @stable ICU 2.0
 671  */
 672 enum UCalendarDisplayNameType {
 673   /** Standard display name */
 674   UCAL_STANDARD,
 675   /** Short standard display name */
 676   UCAL_SHORT_STANDARD,
 677   /** Daylight savings display name */
 678   UCAL_DST,
 679   /** Short daylight savings display name */
 680   UCAL_SHORT_DST
 681 };
 682
 683 /** @stable ICU 2.0 */
 684 typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
 685
 686 /**
 687  * Get the display name for a UCalendar's TimeZone.
 688  * A display name is suitable for presentation to a user.
 689  * @param cal          The UCalendar to query.
 690  * @param type         The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
 691  *                     UCAL_DST, UCAL_SHORT_DST
 692  * @param locale       The desired locale for the display name.
 693  * @param result       A pointer to a buffer to receive the formatted number.
 694  * @param resultLength The maximum size of result.
 695  * @param status       A pointer to an UErrorCode to receive any errors
 696  * @return             The total buffer size needed; if greater than resultLength, the output was truncated.
 697  * @stable ICU 2.0
 698  */
 699 U_STABLE int32_t U_EXPORT2
 700 ucal_getTimeZoneDisplayName(const UCalendar*          cal,
 701                             UCalendarDisplayNameType  type,
 702                             const char*               locale,
 703                             UChar*                    result,
 704                             int32_t                   resultLength,
 705                             UErrorCode*               status);
 706
 707 /**
 708  * Determine if a UCalendar is currently in daylight savings time.
 709  * Daylight savings time is not used in all parts of the world.
 710  * @param cal The UCalendar to query.
 711  * @param status A pointer to an UErrorCode to receive any errors
 712  * @return TRUE if cal is currently in daylight savings time, FALSE otherwise
 713  * @stable ICU 2.0
 714  */
 715 U_STABLE UBool U_EXPORT2
 716 ucal_inDaylightTime(const UCalendar*  cal,
 717                     UErrorCode*       status );
 718
 719 /**
 720  * Sets the GregorianCalendar change date. This is the point when the switch from
 721  * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
 722  * 15, 1582. Previous to this time and date will be Julian dates.
 723  *
 724  * This function works only for Gregorian calendars. If the UCalendar is not
 725  * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
 726  * error code is set.
 727  *
 728  * @param cal        The calendar object.
 729  * @param date       The given Gregorian cutover date.
 730  * @param pErrorCode Pointer to a standard ICU error code. Its input value must
 731  *                   pass the U_SUCCESS() test, or else the function returns
 732  *                   immediately. Check for U_FAILURE() on output or use with
 733  *                   function chaining. (See User Guide for details.)
 734  *
 735  * @see GregorianCalendar::setGregorianChange
 736  * @see ucal_getGregorianChange
 737  * @stable ICU 3.6
 738  */
 739 U_STABLE void U_EXPORT2
 740 ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
 741
 742 /**
 743  * Gets the Gregorian Calendar change date. This is the point when the switch from
 744  * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
 745  * 15, 1582. Previous to this time and date will be Julian dates.
 746  *
 747  * This function works only for Gregorian calendars. If the UCalendar is not
 748  * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
 749  * error code is set.
 750  *
 751  * @param cal        The calendar object.
 752  * @param pErrorCode Pointer to a standard ICU error code. Its input value must
 753  *                   pass the U_SUCCESS() test, or else the function returns
 754  *                   immediately. Check for U_FAILURE() on output or use with
 755  *                   function chaining. (See User Guide for details.)
 756  * @return   The Gregorian cutover time for this calendar.
 757  *
 758  * @see GregorianCalendar::getGregorianChange
 759  * @see ucal_setGregorianChange
 760  * @stable ICU 3.6
 761  */
 762 U_STABLE UDate U_EXPORT2
 763 ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
 764
 765 /**
 766  * Types of UCalendar attributes
 767  * @stable ICU 2.0
 768  */
 769 enum UCalendarAttribute {
 770     /** Lenient parsing */
 771   UCAL_LENIENT,
 772   /** First day of week */
 773   UCAL_FIRST_DAY_OF_WEEK,
 774   /** Minimum number of days in first week */
 775   UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
 776 };
 777
 778 /** @stable ICU 2.0 */
 779 typedef enum UCalendarAttribute UCalendarAttribute;
 780
 781 /**
 782  * Get a numeric attribute associated with a UCalendar.
 783  * Numeric attributes include the first day of the week, or the minimal numbers
 784  * of days in the first week of the month.
 785  * @param cal The UCalendar to query.
 786  * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
 787  * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
 788  * @return The value of attr.
 789  * @see ucal_setAttribute
 790  * @stable ICU 2.0
 791  */
 792 U_STABLE int32_t U_EXPORT2
 793 ucal_getAttribute(const UCalendar*    cal,
 794                   UCalendarAttribute  attr);
 795
 796 /**
 797  * Set a numeric attribute associated with a UCalendar.
 798  * Numeric attributes include the first day of the week, or the minimal numbers
 799  * of days in the first week of the month.
 800  * @param cal The UCalendar to set.
 801  * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
 802  * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
 803  * @param newValue The new value of attr.
 804  * @see ucal_getAttribute
 805  * @stable ICU 2.0
 806  */
 807 U_STABLE void U_EXPORT2
 808 ucal_setAttribute(UCalendar*          cal,
 809                   UCalendarAttribute  attr,
 810                   int32_t             newValue);
 811
 812 /**
 813  * Get a locale for which calendars are available.
 814  * A UCalendar in a locale returned by this function will contain the correct
 815  * day and month names for the locale.
 816  * @param index The index of the desired locale.
 817  * @return A locale for which calendars are available, or 0 if none.
 818  * @see ucal_countAvailable
 819  * @stable ICU 2.0
 820  */
 821 U_STABLE const char* U_EXPORT2
 822 ucal_getAvailable(int32_t index);
 823
 824 /**
 825  * Determine how many locales have calendars available.
 826  * This function is most useful as determining the loop ending condition for
 827  * calls to \ref ucal_getAvailable.
 828  * @return The number of locales for which calendars are available.
 829  * @see ucal_getAvailable
 830  * @stable ICU 2.0
 831  */
 832 U_STABLE int32_t U_EXPORT2
 833 ucal_countAvailable(void);
 834
 835 /**
 836  * Get a UCalendar's current time in millis.
 837  * The time is represented as milliseconds from the epoch.
 838  * @param cal The UCalendar to query.
 839  * @param status A pointer to an UErrorCode to receive any errors
 840  * @return The calendar's current time in millis.
 841  * @see ucal_setMillis
 842  * @see ucal_setDate
 843  * @see ucal_setDateTime
 844  * @stable ICU 2.0
 845  */
 846 U_STABLE UDate U_EXPORT2
 847 ucal_getMillis(const UCalendar*  cal,
 848                UErrorCode*       status);
 849
 850 /**
 851  * Set a UCalendar's current time in millis.
 852  * The time is represented as milliseconds from the epoch.
 853  * @param cal The UCalendar to set.
 854  * @param dateTime The desired date and time.
 855  * @param status A pointer to an UErrorCode to receive any errors
 856  * @see ucal_getMillis
 857  * @see ucal_setDate
 858  * @see ucal_setDateTime
 859  * @stable ICU 2.0
 860  */
 861 U_STABLE void U_EXPORT2
 862 ucal_setMillis(UCalendar*   cal,
 863                UDate        dateTime,
 864                UErrorCode*  status );
 865
 866 /**
 867  * Set a UCalendar's current date.
 868  * The date is represented as a series of 32-bit integers.
 869  * @param cal The UCalendar to set.
 870  * @param year The desired year.
 871  * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
 872  * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
 873  * @param date The desired day of the month.
 874  * @param status A pointer to an UErrorCode to receive any errors
 875  * @see ucal_getMillis
 876  * @see ucal_setMillis
 877  * @see ucal_setDateTime
 878  * @stable ICU 2.0
 879  */
 880 U_STABLE void U_EXPORT2
 881 ucal_setDate(UCalendar*   cal,
 882              int32_t      year,
 883              int32_t      month,
 884              int32_t      date,
 885              UErrorCode*  status);
 886
 887 /**
 888  * Set a UCalendar's current date.
 889  * The date is represented as a series of 32-bit integers.
 890  * @param cal The UCalendar to set.
 891  * @param year The desired year.
 892  * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
 893  * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
 894  * @param date The desired day of the month.
 895  * @param hour The desired hour of day.
 896  * @param minute The desired minute.
 897  * @param second The desirec second.
 898  * @param status A pointer to an UErrorCode to receive any errors
 899  * @see ucal_getMillis
 900  * @see ucal_setMillis
 901  * @see ucal_setDate
 902  * @stable ICU 2.0
 903  */
 904 U_STABLE void U_EXPORT2
 905 ucal_setDateTime(UCalendar*   cal,
 906                  int32_t      year,
 907                  int32_t      month,
 908                  int32_t      date,
 909                  int32_t      hour,
 910                  int32_t      minute,
 911                  int32_t      second,
 912                  UErrorCode*  status);
 913
 914 /**
 915  * Returns TRUE if two UCalendars are equivalent.  Equivalent
 916  * UCalendars will behave identically, but they may be set to
 917  * different times.
 918  * @param cal1 The first of the UCalendars to compare.
 919  * @param cal2 The second of the UCalendars to compare.
 920  * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise.
 921  * @stable ICU 2.0
 922  */
 923 U_STABLE UBool U_EXPORT2
 924 ucal_equivalentTo(const UCalendar*  cal1,
 925                   const UCalendar*  cal2);
 926
 927 /**
 928  * Add a specified signed amount to a particular field in a UCalendar.
 929  * This can modify more significant fields in the calendar.
 930  * @param cal The UCalendar to which to add.
 931  * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
 932  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
 933  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
 934  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
 935  * @param amount The signed amount to add to field. If the amount causes the value
 936  * to exceed to maximum or minimum values for that field, other fields are modified
 937  * to preserve the magnitude of the change.
 938  * @param status A pointer to an UErrorCode to receive any errors
 939  * @see ucal_roll
 940  * @stable ICU 2.0
 941  */
 942 U_STABLE void U_EXPORT2
 943 ucal_add(UCalendar*           cal,
 944          UCalendarDateFields  field,
 945          int32_t              amount,
 946          UErrorCode*          status);
 947
 948 /**
 949  * Add a specified signed amount to a particular field in a UCalendar.
 950  * This will not modify more significant fields in the calendar.
 951  * @param cal The UCalendar to which to add.
 952  * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
 953  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
 954  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
 955  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
 956  * @param amount The signed amount to add to field. If the amount causes the value
 957  * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
 958  * value.
 959  * @param status A pointer to an UErrorCode to receive any errors
 960  * @see ucal_add
 961  * @stable ICU 2.0
 962  */
 963 U_STABLE void U_EXPORT2
 964 ucal_roll(UCalendar*           cal,
 965           UCalendarDateFields  field,
 966           int32_t              amount,
 967           UErrorCode*          status);
 968
 969 /**
 970  * Get the current value of a field from a UCalendar.
 971  * All fields are represented as 32-bit integers.
 972  * @param cal The UCalendar to query.
 973  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
 974  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
 975  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
 976  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
 977  * @param status A pointer to an UErrorCode to receive any errors
 978  * @return The value of the desired field.
 979  * @see ucal_set
 980  * @see ucal_isSet
 981  * @see ucal_clearField
 982  * @see ucal_clear
 983  * @stable ICU 2.0
 984  */
 985 U_STABLE int32_t U_EXPORT2
 986 ucal_get(const UCalendar*     cal,
 987          UCalendarDateFields  field,
 988          UErrorCode*          status );
 989
 990 /**
 991  * Set the value of a field in a UCalendar.
 992  * All fields are represented as 32-bit integers.
 993  * @param cal The UCalendar to set.
 994  * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
 995  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
 996  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
 997  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
 998  * @param value The desired value of field.
 999  * @see ucal_get
1000  * @see ucal_isSet
1001  * @see ucal_clearField
1002  * @see ucal_clear
1003  * @stable ICU 2.0
1004  */
1005 U_STABLE void U_EXPORT2
1006 ucal_set(UCalendar*           cal,
1007          UCalendarDateFields  field,
1008          int32_t              value);
1009
1010 /**
1011  * Determine if a field in a UCalendar is set.
1012  * All fields are represented as 32-bit integers.
1013  * @param cal The UCalendar to query.
1014  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1015  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1016  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1017  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1018  * @return TRUE if field is set, FALSE otherwise.
1019  * @see ucal_get
1020  * @see ucal_set
1021  * @see ucal_clearField
1022  * @see ucal_clear
1023  * @stable ICU 2.0
1024  */
1025 U_STABLE UBool U_EXPORT2
1026 ucal_isSet(const UCalendar*     cal,
1027            UCalendarDateFields  field);
1028
1029 /**
1030  * Clear a field in a UCalendar.
1031  * All fields are represented as 32-bit integers.
1032  * @param cal The UCalendar containing the field to clear.
1033  * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1034  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1035  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1036  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1037  * @see ucal_get
1038  * @see ucal_set
1039  * @see ucal_isSet
1040  * @see ucal_clear
1041  * @stable ICU 2.0
1042  */
1043 U_STABLE void U_EXPORT2
1044 ucal_clearField(UCalendar*           cal,
1045                 UCalendarDateFields  field);
1046
1047 /**
1048  * Clear all fields in a UCalendar.
1049  * All fields are represented as 32-bit integers.
1050  * @param calendar The UCalendar to clear.
1051  * @see ucal_get
1052  * @see ucal_set
1053  * @see ucal_isSet
1054  * @see ucal_clearField
1055  * @stable ICU 2.0
1056  */
1057 U_STABLE void U_EXPORT2
1058 ucal_clear(UCalendar* calendar);
1059
1060 /**
1061  * Possible limit values for a UCalendar
1062  * @stable ICU 2.0
1063  */
1064 enum UCalendarLimitType {
1065   /** Minimum value */
1066   UCAL_MINIMUM,
1067   /** Maximum value */
1068   UCAL_MAXIMUM,
1069   /** Greatest minimum value */
1070   UCAL_GREATEST_MINIMUM,
1071   /** Leaest maximum value */
1072   UCAL_LEAST_MAXIMUM,
1073   /** Actual minimum value */
1074   UCAL_ACTUAL_MINIMUM,
1075   /** Actual maximum value */
1076   UCAL_ACTUAL_MAXIMUM
1077 };
1078
1079 /** @stable ICU 2.0 */
1080 typedef enum UCalendarLimitType UCalendarLimitType;
1081
1082 /**
1083  * Determine a limit for a field in a UCalendar.
1084  * A limit is a maximum or minimum value for a field.
1085  * @param cal The UCalendar to query.
1086  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1087  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1088  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1089  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1090  * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM,
1091  * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
1092  * @param status A pointer to an UErrorCode to receive any errors.
1093  * @return The requested value.
1094  * @stable ICU 2.0
1095  */
1096 U_STABLE int32_t U_EXPORT2
1097 ucal_getLimit(const UCalendar*     cal,
1098               UCalendarDateFields  field,
1099               UCalendarLimitType   type,
1100               UErrorCode*          status);
1101
1102 /** Get the locale for this calendar object. You can choose between valid and actual locale.
1103  *  @param cal The calendar object
1104  *  @param type type of the locale we're looking for (valid or actual)
1105  *  @param status error code for the operation
1106  *  @return the locale name
1107  *  @stable ICU 2.8
1108  */
1109 U_STABLE const char * U_EXPORT2
1110 ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
1111
1112 /**
1113  * Returns the timezone data version currently used by ICU.
1114  * @param status error code for the operation
1115  * @return the version string, such as "2007f"
1116  * @stable ICU 3.8
1117  */
1118 U_DRAFT const char * U_EXPORT2
1119 ucal_getTZDataVersion(UErrorCode* status);
1120
1121 /**
1122  * Returns the canonical system timezone ID or the normalized
1123  * custom time zone ID for the given time zone ID.
1124  * @param id        The input timezone ID to be canonicalized.
1125  * @param len       The length of id, or -1 if null-terminated.
1126  * @param result    The buffer receives the canonical system timezone ID
1127  *                  or the custom timezone ID in normalized format.
1128  * @param resultCapacity    The capacity of the result buffer.
1129  * @param isSystemID        Receives if the given ID is a known system
1130      *                      timezone ID.
1131  * @param status    Recevies the status.  When the given timezone ID
1132  *                  is neither a known system time zone ID nor a
1133  *                  valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
1134  *                  is set.
1135  * @return          The result string length, not including the terminating
1136  *                  null.
1137  * @draft ICU 4.0
1138  */
1139 U_DRAFT int32_t U_EXPORT2
1140 ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
1141                             UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
1142 /**
1143  * Get the resource keyword value string designating the calendar type for the UCalendar.
1144  * @param cal The UCalendar to query.
1145  * @param status The error code for the operation.
1146  * @return The resource keyword value string.
1147  * @draft ICU 4.2
1148  */
1149 U_DRAFT const char * U_EXPORT2
1150 ucal_getType(const UCalendar *cal, UErrorCode* status);
1151
1152 /**
1153  * The following is a temporary Apple-specific API to help InternationalPrefs
1154  * transition to the updated version of the above ICU API. It will be removed soon.
1155  */
1156 U_DRAFT const char * U_EXPORT2
1157 ucal_getTypeWithError(const UCalendar *cal, UErrorCode* status);
1158
1159 #endif /* #if !UCONFIG_NO_FORMATTING */
1160
1161 #endif