icuSources/i18n/unicode/ucal.h

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