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