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