icuSources/i18n/unicode/ucal.h

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