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