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