icuSources/i18n/unicode/ucal.h

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