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