icuSources/i18n/unicode/ucal.h

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