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