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