1 /* 2 ******************************************************************************* 3 * Copyright (C) 1996-2012, 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 /** 749 * Possible formats for a UCalendar's display name 750 * @stable ICU 2.0 751 */ 752 enum UCalendarDisplayNameType { 753 /** Standard display name */ 754 UCAL_STANDARD, 755 /** Short standard display name */ 756 UCAL_SHORT_STANDARD, 757 /** Daylight savings display name */ 758 UCAL_DST, 759 /** Short daylight savings display name */ 760 UCAL_SHORT_DST 761 }; 762 763 /** @stable ICU 2.0 */ 764 typedef enum UCalendarDisplayNameType UCalendarDisplayNameType; 765 766 /** 767 * Get the display name for a UCalendar's TimeZone. 768 * A display name is suitable for presentation to a user. 769 * @param cal The UCalendar to query. 770 * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD, 771 * UCAL_DST, UCAL_SHORT_DST 772 * @param locale The desired locale for the display name. 773 * @param result A pointer to a buffer to receive the formatted number. 774 * @param resultLength The maximum size of result. 775 * @param status A pointer to an UErrorCode to receive any errors 776 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 777 * @stable ICU 2.0 778 */ 779 U_STABLE int32_t U_EXPORT2 780 ucal_getTimeZoneDisplayName(const UCalendar* cal, 781 UCalendarDisplayNameType type, 782 const char* locale, 783 UChar* result, 784 int32_t resultLength, 785 UErrorCode* status); 786 787 /** 788 * Determine if a UCalendar is currently in daylight savings time. 789 * Daylight savings time is not used in all parts of the world. 790 * @param cal The UCalendar to query. 791 * @param status A pointer to an UErrorCode to receive any errors 792 * @return TRUE if cal is currently in daylight savings time, FALSE otherwise 793 * @stable ICU 2.0 794 */ 795 U_STABLE UBool U_EXPORT2 796 ucal_inDaylightTime(const UCalendar* cal, 797 UErrorCode* status ); 798 799 /** 800 * Sets the GregorianCalendar change date. This is the point when the switch from 801 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October 802 * 15, 1582. Previous to this time and date will be Julian dates. 803 * 804 * This function works only for Gregorian calendars. If the UCalendar is not 805 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR 806 * error code is set. 807 * 808 * @param cal The calendar object. 809 * @param date The given Gregorian cutover date. 810 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 811 * pass the U_SUCCESS() test, or else the function returns 812 * immediately. Check for U_FAILURE() on output or use with 813 * function chaining. (See User Guide for details.) 814 * 815 * @see GregorianCalendar::setGregorianChange 816 * @see ucal_getGregorianChange 817 * @stable ICU 3.6 818 */ 819 U_STABLE void U_EXPORT2 820 ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode); 821 822 /** 823 * Gets the Gregorian Calendar change date. This is the point when the switch from 824 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October 825 * 15, 1582. Previous to this time and date will be Julian dates. 826 * 827 * This function works only for Gregorian calendars. If the UCalendar is not 828 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR 829 * error code is set. 830 * 831 * @param cal The calendar object. 832 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 833 * pass the U_SUCCESS() test, or else the function returns 834 * immediately. Check for U_FAILURE() on output or use with 835 * function chaining. (See User Guide for details.) 836 * @return The Gregorian cutover time for this calendar. 837 * 838 * @see GregorianCalendar::getGregorianChange 839 * @see ucal_setGregorianChange 840 * @stable ICU 3.6 841 */ 842 U_STABLE UDate U_EXPORT2 843 ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode); 844 845 /** 846 * Types of UCalendar attributes 847 * @stable ICU 2.0 848 */ 849 enum UCalendarAttribute { 850 /** 851 * Lenient parsing 852 * @stable ICU 2.0 853 */ 854 UCAL_LENIENT, 855 /** 856 * First day of week 857 * @stable ICU 2.0 858 */ 859 UCAL_FIRST_DAY_OF_WEEK, 860 /** 861 * Minimum number of days in first week 862 * @stable ICU 2.0 863 */ 864 UCAL_MINIMAL_DAYS_IN_FIRST_WEEK 865 #ifndef U_HIDE_DRAFT_API 866 , 867 /** 868 * The behavior for handling wall time repeating multiple times 869 * at negative time zone offset transitions 870 * @draft ICU 49 871 */ 872 UCAL_REPEATED_WALL_TIME, 873 /** 874 * The behavior for handling skipped wall time at positive time 875 * zone offset transitions. 876 * @draft ICU 49 877 */ 878 UCAL_SKIPPED_WALL_TIME 879 #endif /* U_HIDE_DRAFT_API */ 880 }; 881 882 /** @stable ICU 2.0 */ 883 typedef enum UCalendarAttribute UCalendarAttribute; 884 885 /** 886 * Options for handling ambiguous wall time at time zone 887 * offset transitions. 888 * @draft ICU 49 889 */ 890 enum UCalendarWallTimeOption { 891 /** 892 * An ambiguous wall time to be interpreted as the latest. 893 * This option is valid for UCAL_REPEATED_WALL_TIME and 894 * UCAL_SKIPPED_WALL_TIME. 895 * @draft ICU 49 896 */ 897 UCAL_WALLTIME_LAST 898 #ifndef U_HIDE_DRAFT_API 899 , 900 /** 901 * An ambiguous wall time to be interpreted as the earliest. 902 * This option is valid for UCAL_REPEATED_WALL_TIME and 903 * UCAL_SKIPPED_WALL_TIME. 904 * @draft ICU 49 905 */ 906 UCAL_WALLTIME_FIRST, 907 /** 908 * An ambiguous wall time to be interpreted as the next valid 909 * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME. 910 * @draft ICU 49 911 */ 912 UCAL_WALLTIME_NEXT_VALID 913 #endif /* U_HIDE_DRAFT_API */ 914 }; 915 /** @draft ICU 49 */ 916 typedef enum UCalendarWallTimeOption UCalendarWallTimeOption; 917 918 /** 919 * Get a numeric attribute associated with a UCalendar. 920 * Numeric attributes include the first day of the week, or the minimal numbers 921 * of days in the first week of the month. 922 * @param cal The UCalendar to query. 923 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, 924 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME 925 * @return The value of attr. 926 * @see ucal_setAttribute 927 * @stable ICU 2.0 928 */ 929 U_STABLE int32_t U_EXPORT2 930 ucal_getAttribute(const UCalendar* cal, 931 UCalendarAttribute attr); 932 933 /** 934 * Set a numeric attribute associated with a UCalendar. 935 * Numeric attributes include the first day of the week, or the minimal numbers 936 * of days in the first week of the month. 937 * @param cal The UCalendar to set. 938 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, 939 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME 940 * @param newValue The new value of attr. 941 * @see ucal_getAttribute 942 * @stable ICU 2.0 943 */ 944 U_STABLE void U_EXPORT2 945 ucal_setAttribute(UCalendar* cal, 946 UCalendarAttribute attr, 947 int32_t newValue); 948 949 /** 950 * Get a locale for which calendars are available. 951 * A UCalendar in a locale returned by this function will contain the correct 952 * day and month names for the locale. 953 * @param localeIndex The index of the desired locale. 954 * @return A locale for which calendars are available, or 0 if none. 955 * @see ucal_countAvailable 956 * @stable ICU 2.0 957 */ 958 U_STABLE const char* U_EXPORT2 959 ucal_getAvailable(int32_t localeIndex); 960 961 /** 962 * Determine how many locales have calendars available. 963 * This function is most useful as determining the loop ending condition for 964 * calls to \ref ucal_getAvailable. 965 * @return The number of locales for which calendars are available. 966 * @see ucal_getAvailable 967 * @stable ICU 2.0 968 */ 969 U_STABLE int32_t U_EXPORT2 970 ucal_countAvailable(void); 971 972 /** 973 * Get a UCalendar's current time in millis. 974 * The time is represented as milliseconds from the epoch. 975 * @param cal The UCalendar to query. 976 * @param status A pointer to an UErrorCode to receive any errors 977 * @return The calendar's current time in millis. 978 * @see ucal_setMillis 979 * @see ucal_setDate 980 * @see ucal_setDateTime 981 * @stable ICU 2.0 982 */ 983 U_STABLE UDate U_EXPORT2 984 ucal_getMillis(const UCalendar* cal, 985 UErrorCode* status); 986 987 /** 988 * Set a UCalendar's current time in millis. 989 * The time is represented as milliseconds from the epoch. 990 * @param cal The UCalendar to set. 991 * @param dateTime The desired date and time. 992 * @param status A pointer to an UErrorCode to receive any errors 993 * @see ucal_getMillis 994 * @see ucal_setDate 995 * @see ucal_setDateTime 996 * @stable ICU 2.0 997 */ 998 U_STABLE void U_EXPORT2 999 ucal_setMillis(UCalendar* cal, 1000 UDate dateTime, 1001 UErrorCode* status ); 1002 1003 /** 1004 * Set a UCalendar's current date. 1005 * The date is represented as a series of 32-bit integers. 1006 * @param cal The UCalendar to set. 1007 * @param year The desired year. 1008 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, 1009 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER 1010 * @param date The desired day of the month. 1011 * @param status A pointer to an UErrorCode to receive any errors 1012 * @see ucal_getMillis 1013 * @see ucal_setMillis 1014 * @see ucal_setDateTime 1015 * @stable ICU 2.0 1016 */ 1017 U_STABLE void U_EXPORT2 1018 ucal_setDate(UCalendar* cal, 1019 int32_t year, 1020 int32_t month, 1021 int32_t date, 1022 UErrorCode* status); 1023 1024 /** 1025 * Set a UCalendar's current date. 1026 * The date is represented as a series of 32-bit integers. 1027 * @param cal The UCalendar to set. 1028 * @param year The desired year. 1029 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, 1030 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER 1031 * @param date The desired day of the month. 1032 * @param hour The desired hour of day. 1033 * @param minute The desired minute. 1034 * @param second The desirec second. 1035 * @param status A pointer to an UErrorCode to receive any errors 1036 * @see ucal_getMillis 1037 * @see ucal_setMillis 1038 * @see ucal_setDate 1039 * @stable ICU 2.0 1040 */ 1041 U_STABLE void U_EXPORT2 1042 ucal_setDateTime(UCalendar* cal, 1043 int32_t year, 1044 int32_t month, 1045 int32_t date, 1046 int32_t hour, 1047 int32_t minute, 1048 int32_t second, 1049 UErrorCode* status); 1050 1051 /** 1052 * Returns TRUE if two UCalendars are equivalent. Equivalent 1053 * UCalendars will behave identically, but they may be set to 1054 * different times. 1055 * @param cal1 The first of the UCalendars to compare. 1056 * @param cal2 The second of the UCalendars to compare. 1057 * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise. 1058 * @stable ICU 2.0 1059 */ 1060 U_STABLE UBool U_EXPORT2 1061 ucal_equivalentTo(const UCalendar* cal1, 1062 const UCalendar* cal2); 1063 1064 /** 1065 * Add a specified signed amount to a particular field in a UCalendar. 1066 * This can modify more significant fields in the calendar. 1067 * Adding a positive value always means moving forward in time, so for the Gregorian calendar, 1068 * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces 1069 * the numeric value of the field itself). 1070 * @param cal The UCalendar to which to add. 1071 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1072 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1073 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1074 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1075 * @param amount The signed amount to add to field. If the amount causes the value 1076 * to exceed to maximum or minimum values for that field, other fields are modified 1077 * to preserve the magnitude of the change. 1078 * @param status A pointer to an UErrorCode to receive any errors 1079 * @see ucal_roll 1080 * @stable ICU 2.0 1081 */ 1082 U_STABLE void U_EXPORT2 1083 ucal_add(UCalendar* cal, 1084 UCalendarDateFields field, 1085 int32_t amount, 1086 UErrorCode* status); 1087 1088 /** 1089 * Add a specified signed amount to a particular field in a UCalendar. 1090 * This will not modify more significant fields in the calendar. 1091 * Rolling by a positive value always means moving forward in time (unless the limit of the 1092 * field is reached, in which case it may pin or wrap), so for Gregorian calendar, 1093 * starting with 100 BC and rolling the year by +1 results in 99 BC. 1094 * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the 1095 * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around. 1096 * When eras only have a limit at one end, then attempting to roll the year past that limit will result in 1097 * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time 1098 * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for 1099 * era 0 (that is the only way to represent years before the calendar epoch). 1100 * @param cal The UCalendar to which to add. 1101 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1102 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1103 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1104 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1105 * @param amount The signed amount to add to field. If the amount causes the value 1106 * to exceed to maximum or minimum values for that field, the field is pinned to a permissible 1107 * value. 1108 * @param status A pointer to an UErrorCode to receive any errors 1109 * @see ucal_add 1110 * @stable ICU 2.0 1111 */ 1112 U_STABLE void U_EXPORT2 1113 ucal_roll(UCalendar* cal, 1114 UCalendarDateFields field, 1115 int32_t amount, 1116 UErrorCode* status); 1117 1118 /** 1119 * Get the current value of a field from a UCalendar. 1120 * All fields are represented as 32-bit integers. 1121 * @param cal The UCalendar to query. 1122 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1123 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1124 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1125 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1126 * @param status A pointer to an UErrorCode to receive any errors 1127 * @return The value of the desired field. 1128 * @see ucal_set 1129 * @see ucal_isSet 1130 * @see ucal_clearField 1131 * @see ucal_clear 1132 * @stable ICU 2.0 1133 */ 1134 U_STABLE int32_t U_EXPORT2 1135 ucal_get(const UCalendar* cal, 1136 UCalendarDateFields field, 1137 UErrorCode* status ); 1138 1139 /** 1140 * Set the value of a field in a UCalendar. 1141 * All fields are represented as 32-bit integers. 1142 * @param cal The UCalendar to set. 1143 * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1144 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1145 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1146 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1147 * @param value The desired value of field. 1148 * @see ucal_get 1149 * @see ucal_isSet 1150 * @see ucal_clearField 1151 * @see ucal_clear 1152 * @stable ICU 2.0 1153 */ 1154 U_STABLE void U_EXPORT2 1155 ucal_set(UCalendar* cal, 1156 UCalendarDateFields field, 1157 int32_t value); 1158 1159 /** 1160 * Determine if a field in a UCalendar is set. 1161 * All fields are represented as 32-bit integers. 1162 * @param cal The UCalendar to query. 1163 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1164 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1165 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1166 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1167 * @return TRUE if field is set, FALSE otherwise. 1168 * @see ucal_get 1169 * @see ucal_set 1170 * @see ucal_clearField 1171 * @see ucal_clear 1172 * @stable ICU 2.0 1173 */ 1174 U_STABLE UBool U_EXPORT2 1175 ucal_isSet(const UCalendar* cal, 1176 UCalendarDateFields field); 1177 1178 /** 1179 * Clear a field in a UCalendar. 1180 * All fields are represented as 32-bit integers. 1181 * @param cal The UCalendar containing the field to clear. 1182 * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1183 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1184 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1185 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1186 * @see ucal_get 1187 * @see ucal_set 1188 * @see ucal_isSet 1189 * @see ucal_clear 1190 * @stable ICU 2.0 1191 */ 1192 U_STABLE void U_EXPORT2 1193 ucal_clearField(UCalendar* cal, 1194 UCalendarDateFields field); 1195 1196 /** 1197 * Clear all fields in a UCalendar. 1198 * All fields are represented as 32-bit integers. 1199 * @param calendar The UCalendar to clear. 1200 * @see ucal_get 1201 * @see ucal_set 1202 * @see ucal_isSet 1203 * @see ucal_clearField 1204 * @stable ICU 2.0 1205 */ 1206 U_STABLE void U_EXPORT2 1207 ucal_clear(UCalendar* calendar); 1208 1209 /** 1210 * Possible limit values for a UCalendar 1211 * @stable ICU 2.0 1212 */ 1213 enum UCalendarLimitType { 1214 /** Minimum value */ 1215 UCAL_MINIMUM, 1216 /** Maximum value */ 1217 UCAL_MAXIMUM, 1218 /** Greatest minimum value */ 1219 UCAL_GREATEST_MINIMUM, 1220 /** Leaest maximum value */ 1221 UCAL_LEAST_MAXIMUM, 1222 /** Actual minimum value */ 1223 UCAL_ACTUAL_MINIMUM, 1224 /** Actual maximum value */ 1225 UCAL_ACTUAL_MAXIMUM 1226 }; 1227 1228 /** @stable ICU 2.0 */ 1229 typedef enum UCalendarLimitType UCalendarLimitType; 1230 1231 /** 1232 * Determine a limit for a field in a UCalendar. 1233 * A limit is a maximum or minimum value for a field. 1234 * @param cal The UCalendar to query. 1235 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1236 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1237 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1238 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1239 * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM, 1240 * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM 1241 * @param status A pointer to an UErrorCode to receive any errors. 1242 * @return The requested value. 1243 * @stable ICU 2.0 1244 */ 1245 U_STABLE int32_t U_EXPORT2 1246 ucal_getLimit(const UCalendar* cal, 1247 UCalendarDateFields field, 1248 UCalendarLimitType type, 1249 UErrorCode* status); 1250 1251 /** Get the locale for this calendar object. You can choose between valid and actual locale. 1252 * @param cal The calendar object 1253 * @param type type of the locale we're looking for (valid or actual) 1254 * @param status error code for the operation 1255 * @return the locale name 1256 * @stable ICU 2.8 1257 */ 1258 U_STABLE const char * U_EXPORT2 1259 ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status); 1260 1261 /** 1262 * Returns the timezone data version currently used by ICU. 1263 * @param status error code for the operation 1264 * @return the version string, such as "2007f" 1265 * @stable ICU 3.8 1266 */ 1267 U_STABLE const char * U_EXPORT2 1268 ucal_getTZDataVersion(UErrorCode* status); 1269 1270 /** 1271 * Returns the canonical system timezone ID or the normalized 1272 * custom time zone ID for the given time zone ID. 1273 * @param id The input timezone ID to be canonicalized. 1274 * @param len The length of id, or -1 if null-terminated. 1275 * @param result The buffer receives the canonical system timezone ID 1276 * or the custom timezone ID in normalized format. 1277 * @param resultCapacity The capacity of the result buffer. 1278 * @param isSystemID Receives if the given ID is a known system 1279 * timezone ID. 1280 * @param status Recevies the status. When the given timezone ID 1281 * is neither a known system time zone ID nor a 1282 * valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR 1283 * is set. 1284 * @return The result string length, not including the terminating 1285 * null. 1286 * @stable ICU 4.0 1287 */ 1288 U_STABLE int32_t U_EXPORT2 1289 ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len, 1290 UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status); 1291 /** 1292 * Get the resource keyword value string designating the calendar type for the UCalendar. 1293 * @param cal The UCalendar to query. 1294 * @param status The error code for the operation. 1295 * @return The resource keyword value string. 1296 * @stable ICU 4.2 1297 */ 1298 U_STABLE const char * U_EXPORT2 1299 ucal_getType(const UCalendar *cal, UErrorCode* status); 1300 1301 /** 1302 * Given a key and a locale, returns an array of string values in a preferred 1303 * order that would make a difference. These are all and only those values where 1304 * the open (creation) of the service with the locale formed from the input locale 1305 * plus input keyword and that value has different behavior than creation with the 1306 * input locale alone. 1307 * @param key one of the keys supported by this service. For now, only 1308 * "calendar" is supported. 1309 * @param locale the locale 1310 * @param commonlyUsed if set to true it will return only commonly used values 1311 * with the given locale in preferred order. Otherwise, 1312 * it will return all the available values for the locale. 1313 * @param status error status 1314 * @return a string enumeration over keyword values for the given key and the locale. 1315 * @stable ICU 4.2 1316 */ 1317 U_STABLE UEnumeration* U_EXPORT2 1318 ucal_getKeywordValuesForLocale(const char* key, 1319 const char* locale, 1320 UBool commonlyUsed, 1321 UErrorCode* status); 1322 1323 1324 /** Weekday types, as returned by ucal_getDayOfWeekType(). 1325 * @stable ICU 4.4 1326 */ 1327 enum UCalendarWeekdayType { 1328 /** 1329 * Designates a full weekday (no part of the day is included in the weekend). 1330 * @stable ICU 4.4 1331 */ 1332 UCAL_WEEKDAY, 1333 /** 1334 * Designates a full weekend day (the entire day is included in the weekend). 1335 * @stable ICU 4.4 1336 */ 1337 UCAL_WEEKEND, 1338 /** 1339 * Designates a day that starts as a weekday and transitions to the weekend. 1340 * Call ucal_getWeekendTransition() to get the time of transition. 1341 * @stable ICU 4.4 1342 */ 1343 UCAL_WEEKEND_ONSET, 1344 /** 1345 * Designates a day that starts as the weekend and transitions to a weekday. 1346 * Call ucal_getWeekendTransition() to get the time of transition. 1347 * @stable ICU 4.4 1348 */ 1349 UCAL_WEEKEND_CEASE 1350 }; 1351 1352 /** @stable ICU 4.4 */ 1353 typedef enum UCalendarWeekdayType UCalendarWeekdayType; 1354 1355 /** 1356 * Returns whether the given day of the week is a weekday, a 1357 * weekend day, or a day that transitions from one to the other, 1358 * in this calendar system. If a transition occurs at midnight, 1359 * then the days before and after the transition will have the 1360 * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time 1361 * other than midnight, then the day of the transition will have 1362 * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the 1363 * method getWeekendTransition() will return the point of 1364 * transition. 1365 * @param cal The UCalendar to query. 1366 * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY). 1367 * @param status The error code for the operation. 1368 * @return The UCalendarWeekdayType for the day of the week. 1369 * @stable ICU 4.4 1370 */ 1371 U_STABLE UCalendarWeekdayType U_EXPORT2 1372 ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status); 1373 1374 /** 1375 * Returns the time during the day at which the weekend begins or ends in 1376 * this calendar system. If ucal_getDayOfWeekType() rerturns UCAL_WEEKEND_ONSET 1377 * for the specified dayOfWeek, return the time at which the weekend begins. 1378 * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek, 1379 * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns 1380 * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition 1381 * (U_ILLEGAL_ARGUMENT_ERROR). 1382 * @param cal The UCalendar to query. 1383 * @param dayOfWeek The day of the week for which the weekend transition time is 1384 * desired (UCAL_SUNDAY..UCAL_SATURDAY). 1385 * @param status The error code for the operation. 1386 * @return The milliseconds after midnight at which the weekend begins or ends. 1387 * @stable ICU 4.4 1388 */ 1389 U_STABLE int32_t U_EXPORT2 1390 ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status); 1391 1392 /** 1393 * Returns TRUE if the given UDate is in the weekend in 1394 * this calendar system. 1395 * @param cal The UCalendar to query. 1396 * @param date The UDate in question. 1397 * @param status The error code for the operation. 1398 * @return TRUE if the given UDate is in the weekend in 1399 * this calendar system, FALSE otherwise. 1400 * @stable ICU 4.4 1401 */ 1402 U_STABLE UBool U_EXPORT2 1403 ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status); 1404 1405 /** 1406 * Return the difference between the target time and the time this calendar object is currently set to. 1407 * If the target time is after the current calendar setting, the the returned value will be positive. 1408 * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH 1409 * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the 1410 * current calendar setting. 1411 * 1412 * As a side effect of this call, this calendar is advanced toward target by the given amount. That is, 1413 * calling this function has the side effect of calling ucal_add on this calendar with the specified 1414 * field and an amount equal to the return value from this function. 1415 * 1416 * A typical way of using this function is to call it first with the largest field of interest, then 1417 * with progressively smaller fields. 1418 * 1419 * @param cal The UCalendar to compare and update. 1420 * @param target The target date to compare to the current calendar setting. 1421 * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1422 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1423 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1424 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1425 * @param status A pointer to an UErrorCode to receive any errors 1426 * @return The date difference for the specified field. 1427 * @stable ICU 4.8 1428 */ 1429 U_STABLE int32_t U_EXPORT2 1430 ucal_getFieldDifference(UCalendar* cal, 1431 UDate target, 1432 UCalendarDateFields field, 1433 UErrorCode* status); 1434 1435 #ifndef U_HIDE_DRAFT_API 1436 /** 1437 * Time zone transition types for ucal_getTimeZoneTransitionDate 1438 * @draft ICU 50 1439 */ 1440 enum UTimeZoneTransitionType { 1441 /** 1442 * Get the next transition after the current date, 1443 * i.e. excludes the current date 1444 * @draft ICU 50 1445 */ 1446 UCAL_TZ_TRANSITION_NEXT, 1447 /** 1448 * Get the next transition on or after the current date, 1449 * i.e. may include the current date 1450 * @draft ICU 50 1451 */ 1452 UCAL_TZ_TRANSITION_NEXT_INCLUSIVE, 1453 /** 1454 * Get the previous transition before the current date, 1455 * i.e. excludes the current date 1456 * @draft ICU 50 1457 */ 1458 UCAL_TZ_TRANSITION_PREVIOUS, 1459 /** 1460 * Get the previous transition on or before the current date, 1461 * i.e. may include the current date 1462 * @draft ICU 50 1463 */ 1464 UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE 1465 }; 1466 1467 /** @draft ICU 50 */ 1468 typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; 1469 1470 /** 1471 * Get the UDate for the next/previous time zone transition relative to 1472 * the calendar's current date, in the time zone to which the calendar 1473 * is currently set. If there is no known time zone transition of the 1474 * requested type relative to the calendar's date, the function returns 1475 * FALSE. 1476 * @param cal The UCalendar to query. 1477 * @param type The type of transition desired. 1478 * @param transition A pointer to a UDate to be set to the transition time. 1479 * If the function returns FALSE, the value set is unspecified. 1480 * @param status A pointer to a UErrorCode to receive any errors. 1481 * @return TRUE if a valid transition time is set in *transition, FALSE 1482 * otherwise. 1483 * @draft ICU 50 1484 */ 1485 U_DRAFT UBool U_EXPORT2 1486 ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type, 1487 UDate* transition, UErrorCode* status); 1488 1489 #endif /* U_HIDE_DRAFT_API */ 1490 1491 #endif /* #if !UCONFIG_NO_FORMATTING */ 1492 1493 #endif 1494
