Where Online Learning is simpler!
The C and C++ Include Header Files
/usr/include/unicode/ucal.h
$ cat -n /usr/include/unicode/ucal.h 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 #ifndef U_HIDE_DRAFT_API 446 /** 447 * Field number indicating the month. This is a calendar-specific value. 448 * Differ from UCAL_MONTH, this value is continuous and unique within a 449 * year and range from 0 to 11 or 0 to 12 depending on how many months in a 450 * year, the calendar system has leap month or not, and in leap year or not. 451 * It is the ordinal position of that month in the corresponding year of 452 * the calendar. For Chinese, Dangi, and Hebrew calendar, the range is 453 * 0 to 11 in non-leap years and 0 to 12 in leap years. For Coptic and Ethiopian 454 * calendar, the range is always 0 to 12. For other calendars supported by 455 * ICU now, the range is 0 to 11. When the number of months in a year of the 456 * identified calendar is variable, a different UCAL_ORDINAL_MONTH value can 457 * be used for dates that are part of the same named month in different years. 458 * For example, in the Hebrew calendar, "1 Nisan 5781" is associated with 459 * UCAL_ORDINAL_MONTH value 6 while "1 Nisan 5782" is associated with 460 * UCAL_ORDINAL_MONTH value 7 because 5782 is a leap year and Nisan follows 461 * the insertion of Adar I. In Chinese calendar, "Year 4664 Month 6 Day 2" 462 * is associated with UCAL_ORDINAL_MONTH value 5 while "Year 4665 Month 6 Day 2" 463 * is associated with UCAL_ORDINAL_MONTH value 6 because 4665 is a leap year 464 * and there is an extra "Leap Month 5" which associated with UCAL_ORDINAL_MONTH 465 * value 5 before "Month 6" of year 4664. 466 * 467 * @draft ICU 73 468 */ 469 UCAL_ORDINAL_MONTH, 470 #endif // U_HIDE_DRAFT_API 471 472 /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, 473 * it is needed for layout of Calendar, DateFormat, and other objects */ 474 #ifndef U_FORCE_HIDE_DEPRECATED_API 475 /** 476 * One more than the highest normal UCalendarDateFields value. 477 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 478 */ 479 #ifdef U_HIDE_DRAFT_API 480 // Must include all fields that will be in structs 481 UCAL_FIELD_COUNT = UCAL_IS_LEAP_MONTH + 2, 482 #else // U_HIDE_DRAFT_API (for UCAL_ORDINAL_MONTH) 483 UCAL_FIELD_COUNT = UCAL_ORDINAL_MONTH + 1, 484 #endif // U_HIDE_DRAFT_API (for UCAL_ORDINAL_MONTH) 485 486 #endif // U_FORCE_HIDE_DEPRECATED_API 487 488 /** 489 * Field number indicating the 490 * day of the month. This is a synonym for <code>UCAL_DATE</code>. 491 * The first day of the month has value 1. 492 * @see #UCAL_DATE 493 * Synonym for UCAL_DATE 494 * @stable ICU 2.8 495 **/ 496 UCAL_DAY_OF_MONTH=UCAL_DATE 497 }; 498 499 /** @stable ICU 2.0 */ 500 typedef enum UCalendarDateFields UCalendarDateFields; 501 /** 502 * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients 503 * who create locale resources for the field of first-day-of-week should be aware of 504 * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY. 505 */ 506 /** Possible days of the week in a UCalendar 507 * @stable ICU 2.0 508 */ 509 enum UCalendarDaysOfWeek { 510 /** Sunday */ 511 UCAL_SUNDAY = 1, 512 /** Monday */ 513 UCAL_MONDAY, 514 /** Tuesday */ 515 UCAL_TUESDAY, 516 /** Wednesday */ 517 UCAL_WEDNESDAY, 518 /** Thursday */ 519 UCAL_THURSDAY, 520 /** Friday */ 521 UCAL_FRIDAY, 522 /** Saturday */ 523 UCAL_SATURDAY 524 }; 525 526 /** @stable ICU 2.0 */ 527 typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek; 528 529 /** Possible months in a UCalendar. Note: Calendar month is 0-based. 530 * @stable ICU 2.0 531 */ 532 enum UCalendarMonths { 533 /** January */ 534 UCAL_JANUARY, 535 /** February */ 536 UCAL_FEBRUARY, 537 /** March */ 538 UCAL_MARCH, 539 /** April */ 540 UCAL_APRIL, 541 /** May */ 542 UCAL_MAY, 543 /** June */ 544 UCAL_JUNE, 545 /** July */ 546 UCAL_JULY, 547 /** August */ 548 UCAL_AUGUST, 549 /** September */ 550 UCAL_SEPTEMBER, 551 /** October */ 552 UCAL_OCTOBER, 553 /** November */ 554 UCAL_NOVEMBER, 555 /** December */ 556 UCAL_DECEMBER, 557 /** Value of the <code>UCAL_MONTH</code> field indicating the 558 * thirteenth month of the year. Although the Gregorian calendar 559 * does not use this value, lunar calendars do. 560 */ 561 UCAL_UNDECIMBER 562 }; 563 564 /** @stable ICU 2.0 */ 565 typedef enum UCalendarMonths UCalendarMonths; 566 567 /** Possible AM/PM values in a UCalendar 568 * @stable ICU 2.0 569 */ 570 enum UCalendarAMPMs { 571 /** AM */ 572 UCAL_AM, 573 /** PM */ 574 UCAL_PM 575 }; 576 577 /** @stable ICU 2.0 */ 578 typedef enum UCalendarAMPMs UCalendarAMPMs; 579 580 /** 581 * System time zone type constants used by filtering zones 582 * in ucal_openTimeZoneIDEnumeration. 583 * @see ucal_openTimeZoneIDEnumeration 584 * @stable ICU 4.8 585 */ 586 enum USystemTimeZoneType { 587 /** 588 * Any system zones. 589 * @stable ICU 4.8 590 */ 591 UCAL_ZONE_TYPE_ANY, 592 /** 593 * Canonical system zones. 594 * @stable ICU 4.8 595 */ 596 UCAL_ZONE_TYPE_CANONICAL, 597 /** 598 * Canonical system zones associated with actual locations. 599 * @stable ICU 4.8 600 */ 601 UCAL_ZONE_TYPE_CANONICAL_LOCATION 602 }; 603 604 /** @stable ICU 4.8 */ 605 typedef enum USystemTimeZoneType USystemTimeZoneType; 606 607 /** 608 * Create an enumeration over system time zone IDs with the given 609 * filter conditions. 610 * @param zoneType The system time zone type. 611 * @param region The ISO 3166 two-letter country code or UN M.49 612 * three-digit area code. When NULL, no filtering 613 * done by region. 614 * @param rawOffset An offset from GMT in milliseconds, ignoring the 615 * effect of daylight savings time, if any. When NULL, 616 * no filtering done by zone offset. 617 * @param ec A pointer to an UErrorCode to receive any errors 618 * @return an enumeration object that the caller must dispose of 619 * using enum_close(), or NULL upon failure. In case of failure, 620 * *ec will indicate the error. 621 * @stable ICU 4.8 622 */ 623 U_CAPI UEnumeration* U_EXPORT2 624 ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region, 625 const int32_t* rawOffset, UErrorCode* ec); 626 627 /** 628 * Create an enumeration over all time zones. 629 * 630 * @param ec input/output error code 631 * 632 * @return an enumeration object that the caller must dispose of using 633 * uenum_close(), or NULL upon failure. In case of failure *ec will 634 * indicate the error. 635 * 636 * @stable ICU 2.6 637 */ 638 U_CAPI UEnumeration* U_EXPORT2 639 ucal_openTimeZones(UErrorCode* ec); 640 641 /** 642 * Create an enumeration over all time zones associated with the given 643 * country. Some zones are affiliated with no country (e.g., "UTC"); 644 * these may also be retrieved, as a group. 645 * 646 * @param country the ISO 3166 two-letter country code, or NULL to 647 * retrieve zones not affiliated with any country 648 * 649 * @param ec input/output error code 650 * 651 * @return an enumeration object that the caller must dispose of using 652 * uenum_close(), or NULL upon failure. In case of failure *ec will 653 * indicate the error. 654 * 655 * @stable ICU 2.6 656 */ 657 U_CAPI UEnumeration* U_EXPORT2 658 ucal_openCountryTimeZones(const char* country, UErrorCode* ec); 659 660 /** 661 * Return the default time zone. The default is determined initially 662 * by querying the host operating system. If the host system detection 663 * routines fail, or if they specify a TimeZone or TimeZone offset 664 * which is not recognized, then the special TimeZone "Etc/Unknown" 665 * is returned. 666 * 667 * The default may be changed with `ucal_setDefaultTimeZone()` or with 668 * the C++ TimeZone API, `TimeZone::adoptDefault(TimeZone*)`. 669 * 670 * @param result A buffer to receive the result, or NULL 671 * 672 * @param resultCapacity The capacity of the result buffer 673 * 674 * @param ec input/output error code 675 * 676 * @return The result string length, not including the terminating 677 * null 678 * 679 * @see #UCAL_UNKNOWN_ZONE_ID 680 * 681 * @stable ICU 2.6 682 */ 683 U_CAPI int32_t U_EXPORT2 684 ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec); 685 686 /** 687 * Set the default time zone. 688 * 689 * @param zoneID null-terminated time zone ID 690 * 691 * @param ec input/output error code 692 * 693 * @stable ICU 2.6 694 */ 695 U_CAPI void U_EXPORT2 696 ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec); 697 698 /** 699 * Return the current host time zone. The host time zone is detected from 700 * the current host system configuration by querying the host operating 701 * system. If the host system detection routines fail, or if they specify 702 * a TimeZone or TimeZone offset which is not recognized, then the special 703 * TimeZone "Etc/Unknown" is returned. 704 * 705 * Note that host time zone and the ICU default time zone can be different. 706 * 707 * The ICU default time zone does not change once initialized unless modified 708 * by calling `ucal_setDefaultTimeZone()` or with the C++ TimeZone API, 709 * `TimeZone::adoptDefault(TimeZone*)`. 710 * 711 * If the host operating system configuration has changed since ICU has 712 * initialized then the returned value can be different than the ICU default 713 * time zone, even if the default has not changed. 714 * 715 * <p>This function is not thread safe.</p> 716 * 717 * @param result A buffer to receive the result, or NULL 718 * @param resultCapacity The capacity of the result buffer 719 * @param ec input/output error code 720 * @return The result string length, not including the terminating 721 * null 722 * 723 * @see #UCAL_UNKNOWN_ZONE_ID 724 * 725 * @stable ICU 65 726 */ 727 U_CAPI int32_t U_EXPORT2 728 ucal_getHostTimeZone(UChar *result, int32_t resultCapacity, UErrorCode *ec); 729 730 /** 731 * Return the amount of time in milliseconds that the clock is 732 * advanced during daylight savings time for the given time zone, or 733 * zero if the time zone does not observe daylight savings time. 734 * 735 * @param zoneID null-terminated time zone ID 736 * 737 * @param ec input/output error code 738 * 739 * @return the number of milliseconds the time is advanced with 740 * respect to standard time when the daylight savings rules are in 741 * effect. This is always a non-negative number, most commonly either 742 * 3,600,000 (one hour) or zero. 743 * 744 * @stable ICU 2.6 745 */ 746 U_CAPI int32_t U_EXPORT2 747 ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec); 748 749 /** 750 * Get the current date and time. 751 * The value returned is represented as milliseconds from the epoch. 752 * @return The current date and time. 753 * @stable ICU 2.0 754 */ 755 U_CAPI UDate U_EXPORT2 756 ucal_getNow(void); 757 758 /** 759 * Open a UCalendar. 760 * A UCalendar may be used to convert a millisecond value to a year, 761 * month, and day. 762 * <p> 763 * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown", 764 * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID 765 * <code>UCAL_UNKNOWN_ZONE_ID</code> ("Etc/Unknown") without any errors/warnings. If you want 766 * to check if a TimeZone ID is valid prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>. 767 * 768 * @param zoneID The desired TimeZone ID. If 0, use the default time zone. 769 * @param len The length of zoneID, or -1 if null-terminated. 770 * @param locale The desired locale 771 * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian 772 * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the 773 * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the 774 * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale 775 * and then pass the locale to ucal_open with UCAL_DEFAULT as the type. 776 * @param status A pointer to an UErrorCode to receive any errors 777 * @return A pointer to a UCalendar, or 0 if an error occurred. 778 * @see #UCAL_UNKNOWN_ZONE_ID 779 * @stable ICU 2.0 780 */ 781 U_CAPI UCalendar* U_EXPORT2 782 ucal_open(const UChar* zoneID, 783 int32_t len, 784 const char* locale, 785 UCalendarType type, 786 UErrorCode* status); 787 788 /** 789 * Close a UCalendar. 790 * Once closed, a UCalendar may no longer be used. 791 * @param cal The UCalendar to close. 792 * @stable ICU 2.0 793 */ 794 U_CAPI void U_EXPORT2 795 ucal_close(UCalendar *cal); 796 797 #if U_SHOW_CPLUSPLUS_API 798 799 U_NAMESPACE_BEGIN 800 801 /** 802 * \class LocalUCalendarPointer 803 * "Smart pointer" class, closes a UCalendar via ucal_close(). 804 * For most methods see the LocalPointerBase base class. 805 * 806 * @see LocalPointerBase 807 * @see LocalPointer 808 * @stable ICU 4.4 809 */ 810 U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close); 811 812 U_NAMESPACE_END 813 814 #endif 815 816 /** 817 * Open a copy of a UCalendar. 818 * This function performs a deep copy. 819 * @param cal The calendar to copy 820 * @param status A pointer to an UErrorCode to receive any errors. 821 * @return A pointer to a UCalendar identical to cal. 822 * @stable ICU 4.0 823 */ 824 U_CAPI UCalendar* U_EXPORT2 825 ucal_clone(const UCalendar* cal, 826 UErrorCode* status); 827 828 /** 829 * Set the TimeZone used by a UCalendar. 830 * A UCalendar uses a timezone for converting from Greenwich time to local time. 831 * @param cal The UCalendar to set. 832 * @param zoneID The desired TimeZone ID. If 0, use the default time zone. 833 * @param len The length of zoneID, or -1 if null-terminated. 834 * @param status A pointer to an UErrorCode to receive any errors. 835 * @stable ICU 2.0 836 */ 837 U_CAPI void U_EXPORT2 838 ucal_setTimeZone(UCalendar* cal, 839 const UChar* zoneID, 840 int32_t len, 841 UErrorCode* status); 842 843 /** 844 * Get the ID of the UCalendar's time zone. 845 * 846 * @param cal The UCalendar to query. 847 * @param result Receives the UCalendar's time zone ID. 848 * @param resultLength The maximum size of result. 849 * @param status Receives the status. 850 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 851 * @stable ICU 51 852 */ 853 U_CAPI int32_t U_EXPORT2 854 ucal_getTimeZoneID(const UCalendar *cal, 855 UChar *result, 856 int32_t resultLength, 857 UErrorCode *status); 858 859 /** 860 * Possible formats for a UCalendar's display name 861 * @stable ICU 2.0 862 */ 863 enum UCalendarDisplayNameType { 864 /** Standard display name */ 865 UCAL_STANDARD, 866 /** Short standard display name */ 867 UCAL_SHORT_STANDARD, 868 /** Daylight savings display name */ 869 UCAL_DST, 870 /** Short daylight savings display name */ 871 UCAL_SHORT_DST 872 }; 873 874 /** @stable ICU 2.0 */ 875 typedef enum UCalendarDisplayNameType UCalendarDisplayNameType; 876 877 /** 878 * Get the display name for a UCalendar's TimeZone. 879 * A display name is suitable for presentation to a user. 880 * @param cal The UCalendar to query. 881 * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD, 882 * UCAL_DST, UCAL_SHORT_DST 883 * @param locale The desired locale for the display name. 884 * @param result A pointer to a buffer to receive the formatted number. 885 * @param resultLength The maximum size of result. 886 * @param status A pointer to an UErrorCode to receive any errors 887 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 888 * @stable ICU 2.0 889 */ 890 U_CAPI int32_t U_EXPORT2 891 ucal_getTimeZoneDisplayName(const UCalendar* cal, 892 UCalendarDisplayNameType type, 893 const char* locale, 894 UChar* result, 895 int32_t resultLength, 896 UErrorCode* status); 897 898 /** 899 * Determine if a UCalendar is currently in daylight savings time. 900 * Daylight savings time is not used in all parts of the world. 901 * @param cal The UCalendar to query. 902 * @param status A pointer to an UErrorCode to receive any errors 903 * @return true if cal is currently in daylight savings time, false otherwise 904 * @stable ICU 2.0 905 */ 906 U_CAPI UBool U_EXPORT2 907 ucal_inDaylightTime(const UCalendar* cal, 908 UErrorCode* status ); 909 910 /** 911 * Sets the GregorianCalendar change date. This is the point when the switch from 912 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October 913 * 15, 1582. Previous to this time and date will be Julian dates. 914 * 915 * This function works only for Gregorian calendars. If the UCalendar is not 916 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR 917 * error code is set. 918 * 919 * @param cal The calendar object. 920 * @param date The given Gregorian cutover date. 921 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 922 * pass the U_SUCCESS() test, or else the function returns 923 * immediately. Check for U_FAILURE() on output or use with 924 * function chaining. (See User Guide for details.) 925 * 926 * @see GregorianCalendar::setGregorianChange 927 * @see ucal_getGregorianChange 928 * @stable ICU 3.6 929 */ 930 U_CAPI void U_EXPORT2 931 ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode); 932 933 /** 934 * Gets the Gregorian Calendar change date. This is the point when the switch from 935 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October 936 * 15, 1582. Previous to this time and date will be Julian dates. 937 * 938 * This function works only for Gregorian calendars. If the UCalendar is not 939 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR 940 * error code is set. 941 * 942 * @param cal The calendar object. 943 * @param pErrorCode Pointer to a standard ICU error code. Its input value must 944 * pass the U_SUCCESS() test, or else the function returns 945 * immediately. Check for U_FAILURE() on output or use with 946 * function chaining. (See User Guide for details.) 947 * @return The Gregorian cutover time for this calendar. 948 * 949 * @see GregorianCalendar::getGregorianChange 950 * @see ucal_setGregorianChange 951 * @stable ICU 3.6 952 */ 953 U_CAPI UDate U_EXPORT2 954 ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode); 955 956 /** 957 * Types of UCalendar attributes 958 * @stable ICU 2.0 959 */ 960 enum UCalendarAttribute { 961 /** 962 * Lenient parsing 963 * @stable ICU 2.0 964 */ 965 UCAL_LENIENT, 966 /** 967 * First day of week 968 * @stable ICU 2.0 969 */ 970 UCAL_FIRST_DAY_OF_WEEK, 971 /** 972 * Minimum number of days in first week 973 * @stable ICU 2.0 974 */ 975 UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, 976 /** 977 * The behavior for handling wall time repeating multiple times 978 * at negative time zone offset transitions 979 * @stable ICU 49 980 */ 981 UCAL_REPEATED_WALL_TIME, 982 /** 983 * The behavior for handling skipped wall time at positive time 984 * zone offset transitions. 985 * @stable ICU 49 986 */ 987 UCAL_SKIPPED_WALL_TIME 988 }; 989 990 /** @stable ICU 2.0 */ 991 typedef enum UCalendarAttribute UCalendarAttribute; 992 993 /** 994 * Options for handling ambiguous wall time at time zone 995 * offset transitions. 996 * @stable ICU 49 997 */ 998 enum UCalendarWallTimeOption { 999 /** 1000 * An ambiguous wall time to be interpreted as the latest. 1001 * This option is valid for UCAL_REPEATED_WALL_TIME and 1002 * UCAL_SKIPPED_WALL_TIME. 1003 * @stable ICU 49 1004 */ 1005 UCAL_WALLTIME_LAST, 1006 /** 1007 * An ambiguous wall time to be interpreted as the earliest. 1008 * This option is valid for UCAL_REPEATED_WALL_TIME and 1009 * UCAL_SKIPPED_WALL_TIME. 1010 * @stable ICU 49 1011 */ 1012 UCAL_WALLTIME_FIRST, 1013 /** 1014 * An ambiguous wall time to be interpreted as the next valid 1015 * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME. 1016 * @stable ICU 49 1017 */ 1018 UCAL_WALLTIME_NEXT_VALID 1019 }; 1020 /** @stable ICU 49 */ 1021 typedef enum UCalendarWallTimeOption UCalendarWallTimeOption; 1022 1023 /** 1024 * Get a numeric attribute associated with a UCalendar. 1025 * Numeric attributes include the first day of the week, or the minimal numbers 1026 * of days in the first week of the month. 1027 * @param cal The UCalendar to query. 1028 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, 1029 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME 1030 * @return The value of attr. 1031 * @see ucal_setAttribute 1032 * @stable ICU 2.0 1033 */ 1034 U_CAPI int32_t U_EXPORT2 1035 ucal_getAttribute(const UCalendar* cal, 1036 UCalendarAttribute attr); 1037 1038 /** 1039 * Set a numeric attribute associated with a UCalendar. 1040 * Numeric attributes include the first day of the week, or the minimal numbers 1041 * of days in the first week of the month. 1042 * @param cal The UCalendar to set. 1043 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, 1044 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME 1045 * @param newValue The new value of attr. 1046 * @see ucal_getAttribute 1047 * @stable ICU 2.0 1048 */ 1049 U_CAPI void U_EXPORT2 1050 ucal_setAttribute(UCalendar* cal, 1051 UCalendarAttribute attr, 1052 int32_t newValue); 1053 1054 /** 1055 * Get a locale for which calendars are available. 1056 * A UCalendar in a locale returned by this function will contain the correct 1057 * day and month names for the locale. 1058 * @param localeIndex The index of the desired locale. 1059 * @return A locale for which calendars are available, or 0 if none. 1060 * @see ucal_countAvailable 1061 * @stable ICU 2.0 1062 */ 1063 U_CAPI const char* U_EXPORT2 1064 ucal_getAvailable(int32_t localeIndex); 1065 1066 /** 1067 * Determine how many locales have calendars available. 1068 * This function is most useful as determining the loop ending condition for 1069 * calls to \ref ucal_getAvailable. 1070 * @return The number of locales for which calendars are available. 1071 * @see ucal_getAvailable 1072 * @stable ICU 2.0 1073 */ 1074 U_CAPI int32_t U_EXPORT2 1075 ucal_countAvailable(void); 1076 1077 /** 1078 * Get a UCalendar's current time in millis. 1079 * The time is represented as milliseconds from the epoch. 1080 * @param cal The UCalendar to query. 1081 * @param status A pointer to an UErrorCode to receive any errors 1082 * @return The calendar's current time in millis. 1083 * @see ucal_setMillis 1084 * @see ucal_setDate 1085 * @see ucal_setDateTime 1086 * @stable ICU 2.0 1087 */ 1088 U_CAPI UDate U_EXPORT2 1089 ucal_getMillis(const UCalendar* cal, 1090 UErrorCode* status); 1091 1092 /** 1093 * Set a UCalendar's current time in millis. 1094 * The time is represented as milliseconds from the epoch. 1095 * @param cal The UCalendar to set. 1096 * @param dateTime The desired date and time. 1097 * @param status A pointer to an UErrorCode to receive any errors 1098 * @see ucal_getMillis 1099 * @see ucal_setDate 1100 * @see ucal_setDateTime 1101 * @stable ICU 2.0 1102 */ 1103 U_CAPI void U_EXPORT2 1104 ucal_setMillis(UCalendar* cal, 1105 UDate dateTime, 1106 UErrorCode* status ); 1107 1108 /** 1109 * Set a UCalendar's current date. 1110 * The date is represented as a series of 32-bit integers. 1111 * @param cal The UCalendar to set. 1112 * @param year The desired year. 1113 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, 1114 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER 1115 * @param date The desired day of the month. 1116 * @param status A pointer to an UErrorCode to receive any errors 1117 * @see ucal_getMillis 1118 * @see ucal_setMillis 1119 * @see ucal_setDateTime 1120 * @stable ICU 2.0 1121 */ 1122 U_CAPI void U_EXPORT2 1123 ucal_setDate(UCalendar* cal, 1124 int32_t year, 1125 int32_t month, 1126 int32_t date, 1127 UErrorCode* status); 1128 1129 /** 1130 * Set a UCalendar's current date. 1131 * The date is represented as a series of 32-bit integers. 1132 * @param cal The UCalendar to set. 1133 * @param year The desired year. 1134 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, 1135 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER 1136 * @param date The desired day of the month. 1137 * @param hour The desired hour of day. 1138 * @param minute The desired minute. 1139 * @param second The desirec second. 1140 * @param status A pointer to an UErrorCode to receive any errors 1141 * @see ucal_getMillis 1142 * @see ucal_setMillis 1143 * @see ucal_setDate 1144 * @stable ICU 2.0 1145 */ 1146 U_CAPI void U_EXPORT2 1147 ucal_setDateTime(UCalendar* cal, 1148 int32_t year, 1149 int32_t month, 1150 int32_t date, 1151 int32_t hour, 1152 int32_t minute, 1153 int32_t second, 1154 UErrorCode* status); 1155 1156 /** 1157 * Returns true if two UCalendars are equivalent. Equivalent 1158 * UCalendars will behave identically, but they may be set to 1159 * different times. 1160 * @param cal1 The first of the UCalendars to compare. 1161 * @param cal2 The second of the UCalendars to compare. 1162 * @return true if cal1 and cal2 are equivalent, false otherwise. 1163 * @stable ICU 2.0 1164 */ 1165 U_CAPI UBool U_EXPORT2 1166 ucal_equivalentTo(const UCalendar* cal1, 1167 const UCalendar* cal2); 1168 1169 /** 1170 * Add a specified signed amount to a particular field in a UCalendar. 1171 * This can modify more significant fields in the calendar. 1172 * Adding a positive value always means moving forward in time, so for the Gregorian calendar, 1173 * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces 1174 * the numeric value of the field itself). 1175 * @param cal The UCalendar to which to add. 1176 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1177 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1178 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1179 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1180 * @param amount The signed amount to add to field. If the amount causes the value 1181 * to exceed to maximum or minimum values for that field, other fields are modified 1182 * to preserve the magnitude of the change. 1183 * @param status A pointer to an UErrorCode to receive any errors 1184 * @see ucal_roll 1185 * @stable ICU 2.0 1186 */ 1187 U_CAPI void U_EXPORT2 1188 ucal_add(UCalendar* cal, 1189 UCalendarDateFields field, 1190 int32_t amount, 1191 UErrorCode* status); 1192 1193 /** 1194 * Add a specified signed amount to a particular field in a UCalendar. 1195 * This will not modify more significant fields in the calendar. 1196 * Rolling by a positive value always means moving forward in time (unless the limit of the 1197 * field is reached, in which case it may pin or wrap), so for Gregorian calendar, 1198 * starting with 100 BC and rolling the year by +1 results in 99 BC. 1199 * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the 1200 * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around. 1201 * When eras only have a limit at one end, then attempting to roll the year past that limit will result in 1202 * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time 1203 * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for 1204 * era 0 (that is the only way to represent years before the calendar epoch). 1205 * @param cal The UCalendar to which to add. 1206 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1207 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1208 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1209 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1210 * @param amount The signed amount to add to field. If the amount causes the value 1211 * to exceed to maximum or minimum values for that field, the field is pinned to a permissible 1212 * value. 1213 * @param status A pointer to an UErrorCode to receive any errors 1214 * @see ucal_add 1215 * @stable ICU 2.0 1216 */ 1217 U_CAPI void U_EXPORT2 1218 ucal_roll(UCalendar* cal, 1219 UCalendarDateFields field, 1220 int32_t amount, 1221 UErrorCode* status); 1222 1223 /** 1224 * Get the current value of a field from a UCalendar. 1225 * All fields are represented as 32-bit integers. 1226 * @param cal The UCalendar to query. 1227 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1228 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1229 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1230 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1231 * @param status A pointer to an UErrorCode to receive any errors 1232 * @return The value of the desired field. 1233 * @see ucal_set 1234 * @see ucal_isSet 1235 * @see ucal_clearField 1236 * @see ucal_clear 1237 * @stable ICU 2.0 1238 */ 1239 U_CAPI int32_t U_EXPORT2 1240 ucal_get(const UCalendar* cal, 1241 UCalendarDateFields field, 1242 UErrorCode* status ); 1243 1244 /** 1245 * Set the value of a field in a UCalendar. 1246 * All fields are represented as 32-bit integers. 1247 * @param cal The UCalendar to set. 1248 * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1249 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1250 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1251 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1252 * @param value The desired value of field. 1253 * @see ucal_get 1254 * @see ucal_isSet 1255 * @see ucal_clearField 1256 * @see ucal_clear 1257 * @stable ICU 2.0 1258 */ 1259 U_CAPI void U_EXPORT2 1260 ucal_set(UCalendar* cal, 1261 UCalendarDateFields field, 1262 int32_t value); 1263 1264 /** 1265 * Determine if a field in a UCalendar is set. 1266 * All fields are represented as 32-bit integers. 1267 * @param cal The UCalendar to query. 1268 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1269 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1270 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1271 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1272 * @return true if field is set, false otherwise. 1273 * @see ucal_get 1274 * @see ucal_set 1275 * @see ucal_clearField 1276 * @see ucal_clear 1277 * @stable ICU 2.0 1278 */ 1279 U_CAPI UBool U_EXPORT2 1280 ucal_isSet(const UCalendar* cal, 1281 UCalendarDateFields field); 1282 1283 /** 1284 * Clear a field in a UCalendar. 1285 * All fields are represented as 32-bit integers. 1286 * @param cal The UCalendar containing the field to clear. 1287 * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1288 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1289 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1290 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1291 * @see ucal_get 1292 * @see ucal_set 1293 * @see ucal_isSet 1294 * @see ucal_clear 1295 * @stable ICU 2.0 1296 */ 1297 U_CAPI void U_EXPORT2 1298 ucal_clearField(UCalendar* cal, 1299 UCalendarDateFields field); 1300 1301 /** 1302 * Clear all fields in a UCalendar. 1303 * All fields are represented as 32-bit integers. 1304 * @param calendar The UCalendar to clear. 1305 * @see ucal_get 1306 * @see ucal_set 1307 * @see ucal_isSet 1308 * @see ucal_clearField 1309 * @stable ICU 2.0 1310 */ 1311 U_CAPI void U_EXPORT2 1312 ucal_clear(UCalendar* calendar); 1313 1314 /** 1315 * Possible limit values for a UCalendar 1316 * @stable ICU 2.0 1317 */ 1318 enum UCalendarLimitType { 1319 /** Minimum value */ 1320 UCAL_MINIMUM, 1321 /** Maximum value */ 1322 UCAL_MAXIMUM, 1323 /** Greatest minimum value */ 1324 UCAL_GREATEST_MINIMUM, 1325 /** Least maximum value */ 1326 UCAL_LEAST_MAXIMUM, 1327 /** Actual minimum value */ 1328 UCAL_ACTUAL_MINIMUM, 1329 /** Actual maximum value */ 1330 UCAL_ACTUAL_MAXIMUM 1331 }; 1332 1333 /** @stable ICU 2.0 */ 1334 typedef enum UCalendarLimitType UCalendarLimitType; 1335 1336 /** 1337 * Determine a limit for a field in a UCalendar. 1338 * A limit is a maximum or minimum value for a field. 1339 * @param cal The UCalendar to query. 1340 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1341 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1342 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1343 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1344 * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM, 1345 * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM 1346 * @param status A pointer to an UErrorCode to receive any errors. 1347 * @return The requested value. 1348 * @stable ICU 2.0 1349 */ 1350 U_CAPI int32_t U_EXPORT2 1351 ucal_getLimit(const UCalendar* cal, 1352 UCalendarDateFields field, 1353 UCalendarLimitType type, 1354 UErrorCode* status); 1355 1356 /** Get the locale for this calendar object. You can choose between valid and actual locale. 1357 * @param cal The calendar object 1358 * @param type type of the locale we're looking for (valid or actual) 1359 * @param status error code for the operation 1360 * @return the locale name 1361 * @stable ICU 2.8 1362 */ 1363 U_CAPI const char * U_EXPORT2 1364 ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status); 1365 1366 /** 1367 * Returns the timezone data version currently used by ICU. 1368 * @param status error code for the operation 1369 * @return the version string, such as "2007f" 1370 * @stable ICU 3.8 1371 */ 1372 U_CAPI const char * U_EXPORT2 1373 ucal_getTZDataVersion(UErrorCode* status); 1374 1375 /** 1376 * Returns the canonical system timezone ID or the normalized 1377 * custom time zone ID for the given time zone ID. 1378 * @param id The input timezone ID to be canonicalized. 1379 * @param len The length of id, or -1 if null-terminated. 1380 * @param result The buffer receives the canonical system timezone ID 1381 * or the custom timezone ID in normalized format. 1382 * @param resultCapacity The capacity of the result buffer. 1383 * @param isSystemID Receives if the given ID is a known system 1384 * timezone ID. 1385 * @param status Receives the status. When the given timezone ID 1386 * is neither a known system time zone ID nor a 1387 * valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR 1388 * is set. 1389 * @return The result string length, not including the terminating 1390 * null. 1391 * @stable ICU 4.0 1392 */ 1393 U_CAPI int32_t U_EXPORT2 1394 ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len, 1395 UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status); 1396 1397 #ifndef U_HIDE_DRAFT_API 1398 /** 1399 * Returns the preferred time zone ID in the IANA time zone database for the given time zone ID. 1400 * There are two types of preferred IDs. The first type is the one defined in zone.tab file, 1401 * such as "America/Los_Angeles". The second types is the one defined for zones not associated 1402 * with a specific region, but not defined with "Link" syntax such as "Etc/GMT+10". 1403 * 1404 * <p>Note: For most of valid time zone IDs, this method returns an ID same as ucal_getCanonicalTimeZoneID(). 1405 * ucal_getCanonicalTimeZoneID() is based on canonical time zone IDs defined in Unicode CLDR. 1406 * These canonical time zone IDs in CLDR were based on very old version of the time zone database. 1407 * In the IANA time zone database, some IDs were updated since then. This API returns a newer 1408 * time zone ID. For example, CLDR defines "Asia/Calcutta" as the canonical time zone ID. This 1409 * method returns "Asia/Kolkata" instead. 1410 * <p> "Etc/Unknown" is a special time zone ID defined by CLDR. There are no corresponding zones 1411 * in the IANA time zone database. Therefore, this API returns U_ILLEGAL_ARGUMENT_ERROR when the 1412 * input ID is "Etc/Unknown". 1413 * 1414 * @param id The input time zone ID. 1415 * @param len The length of the input time zone ID. 1416 * @param result The buffer receives the preferred time zone ID in the IANA time zone database. 1417 * @param resultCapacity The capacity of the result buffer. 1418 * @param status Receives the status. When the given time zone ID is not a known system time zone 1419 * ID, U_ILLEGAL_ARGUMENT_ERROR is set. 1420 * @return The result string length, not including the terminating null. 1421 * @draft ICU 74 1422 */ 1423 U_CAPI int32_t U_EXPORT2 1424 ucal_getIanaTimeZoneID(const UChar* id, int32_t len, 1425 UChar* result, int32_t resultCapacity, UErrorCode* status); 1426 #endif // U_HIDE_DRAFT_API 1427 1428 /** 1429 * Get the resource keyword value string designating the calendar type for the UCalendar. 1430 * @param cal The UCalendar to query. 1431 * @param status The error code for the operation. 1432 * @return The resource keyword value string. 1433 * @stable ICU 4.2 1434 */ 1435 U_CAPI const char * U_EXPORT2 1436 ucal_getType(const UCalendar *cal, UErrorCode* status); 1437 1438 /** 1439 * Given a key and a locale, returns an array of string values in a preferred 1440 * order that would make a difference. These are all and only those values where 1441 * the open (creation) of the service with the locale formed from the input locale 1442 * plus input keyword and that value has different behavior than creation with the 1443 * input locale alone. 1444 * @param key one of the keys supported by this service. For now, only 1445 * "calendar" is supported. 1446 * @param locale the locale 1447 * @param commonlyUsed if set to true it will return only commonly used values 1448 * with the given locale in preferred order. Otherwise, 1449 * it will return all the available values for the locale. 1450 * @param status error status 1451 * @return a string enumeration over keyword values for the given key and the locale. 1452 * @stable ICU 4.2 1453 */ 1454 U_CAPI UEnumeration* U_EXPORT2 1455 ucal_getKeywordValuesForLocale(const char* key, 1456 const char* locale, 1457 UBool commonlyUsed, 1458 UErrorCode* status); 1459 1460 1461 /** Weekday types, as returned by ucal_getDayOfWeekType(). 1462 * @stable ICU 4.4 1463 */ 1464 enum UCalendarWeekdayType { 1465 /** 1466 * Designates a full weekday (no part of the day is included in the weekend). 1467 * @stable ICU 4.4 1468 */ 1469 UCAL_WEEKDAY, 1470 /** 1471 * Designates a full weekend day (the entire day is included in the weekend). 1472 * @stable ICU 4.4 1473 */ 1474 UCAL_WEEKEND, 1475 /** 1476 * Designates a day that starts as a weekday and transitions to the weekend. 1477 * Call ucal_getWeekendTransition() to get the time of transition. 1478 * @stable ICU 4.4 1479 */ 1480 UCAL_WEEKEND_ONSET, 1481 /** 1482 * Designates a day that starts as the weekend and transitions to a weekday. 1483 * Call ucal_getWeekendTransition() to get the time of transition. 1484 * @stable ICU 4.4 1485 */ 1486 UCAL_WEEKEND_CEASE 1487 }; 1488 1489 /** @stable ICU 4.4 */ 1490 typedef enum UCalendarWeekdayType UCalendarWeekdayType; 1491 1492 /** 1493 * Returns whether the given day of the week is a weekday, a weekend day, 1494 * or a day that transitions from one to the other, for the locale and 1495 * calendar system associated with this UCalendar (the locale's region is 1496 * often the most determinant factor). If a transition occurs at midnight, 1497 * then the days before and after the transition will have the 1498 * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time 1499 * other than midnight, then the day of the transition will have 1500 * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the 1501 * function ucal_getWeekendTransition() will return the point of 1502 * transition. 1503 * @param cal The UCalendar to query. 1504 * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY). 1505 * @param status The error code for the operation. 1506 * @return The UCalendarWeekdayType for the day of the week. 1507 * @stable ICU 4.4 1508 */ 1509 U_CAPI UCalendarWeekdayType U_EXPORT2 1510 ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status); 1511 1512 /** 1513 * Returns the time during the day at which the weekend begins or ends in 1514 * this calendar system. If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET 1515 * for the specified dayOfWeek, return the time at which the weekend begins. 1516 * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek, 1517 * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns 1518 * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition 1519 * (U_ILLEGAL_ARGUMENT_ERROR). 1520 * @param cal The UCalendar to query. 1521 * @param dayOfWeek The day of the week for which the weekend transition time is 1522 * desired (UCAL_SUNDAY..UCAL_SATURDAY). 1523 * @param status The error code for the operation. 1524 * @return The milliseconds after midnight at which the weekend begins or ends. 1525 * @stable ICU 4.4 1526 */ 1527 U_CAPI int32_t U_EXPORT2 1528 ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status); 1529 1530 /** 1531 * Returns true if the given UDate is in the weekend in 1532 * this calendar system. 1533 * @param cal The UCalendar to query. 1534 * @param date The UDate in question. 1535 * @param status The error code for the operation. 1536 * @return true if the given UDate is in the weekend in 1537 * this calendar system, false otherwise. 1538 * @stable ICU 4.4 1539 */ 1540 U_CAPI UBool U_EXPORT2 1541 ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status); 1542 1543 /** 1544 * Return the difference between the target time and the time this calendar object is currently set to. 1545 * If the target time is after the current calendar setting, the the returned value will be positive. 1546 * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH 1547 * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the 1548 * current calendar setting. 1549 * 1550 * As a side effect of this call, this calendar is advanced toward target by the given amount. That is, 1551 * calling this function has the side effect of calling ucal_add on this calendar with the specified 1552 * field and an amount equal to the return value from this function. 1553 * 1554 * A typical way of using this function is to call it first with the largest field of interest, then 1555 * with progressively smaller fields. 1556 * 1557 * @param cal The UCalendar to compare and update. 1558 * @param target The target date to compare to the current calendar setting. 1559 * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, 1560 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, 1561 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, 1562 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. 1563 * @param status A pointer to an UErrorCode to receive any errors 1564 * @return The date difference for the specified field. 1565 * @stable ICU 4.8 1566 */ 1567 U_CAPI int32_t U_EXPORT2 1568 ucal_getFieldDifference(UCalendar* cal, 1569 UDate target, 1570 UCalendarDateFields field, 1571 UErrorCode* status); 1572 1573 /** 1574 * Time zone transition types for ucal_getTimeZoneTransitionDate 1575 * @stable ICU 50 1576 */ 1577 enum UTimeZoneTransitionType { 1578 /** 1579 * Get the next transition after the current date, 1580 * i.e. excludes the current date 1581 * @stable ICU 50 1582 */ 1583 UCAL_TZ_TRANSITION_NEXT, 1584 /** 1585 * Get the next transition on or after the current date, 1586 * i.e. may include the current date 1587 * @stable ICU 50 1588 */ 1589 UCAL_TZ_TRANSITION_NEXT_INCLUSIVE, 1590 /** 1591 * Get the previous transition before the current date, 1592 * i.e. excludes the current date 1593 * @stable ICU 50 1594 */ 1595 UCAL_TZ_TRANSITION_PREVIOUS, 1596 /** 1597 * Get the previous transition on or before the current date, 1598 * i.e. may include the current date 1599 * @stable ICU 50 1600 */ 1601 UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE 1602 }; 1603 1604 typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */ 1605 1606 /** 1607 * Get the UDate for the next/previous time zone transition relative to 1608 * the calendar's current date, in the time zone to which the calendar 1609 * is currently set. If there is no known time zone transition of the 1610 * requested type relative to the calendar's date, the function returns 1611 * false. 1612 * @param cal The UCalendar to query. 1613 * @param type The type of transition desired. 1614 * @param transition A pointer to a UDate to be set to the transition time. 1615 * If the function returns false, the value set is unspecified. 1616 * @param status A pointer to a UErrorCode to receive any errors. 1617 * @return true if a valid transition time is set in *transition, false 1618 * otherwise. 1619 * @stable ICU 50 1620 */ 1621 U_CAPI UBool U_EXPORT2 1622 ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type, 1623 UDate* transition, UErrorCode* status); 1624 1625 /** 1626 * Converts a system time zone ID to an equivalent Windows time zone ID. For example, 1627 * Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles". 1628 * 1629 * <p>There are system time zones that cannot be mapped to Windows zones. When the input 1630 * system time zone ID is unknown or unmappable to a Windows time zone, then this 1631 * function returns 0 as the result length, but the operation itself remains successful 1632 * (no error status set on return). 1633 * 1634 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html"> 1635 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes, 1636 * please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data"> 1637 * Updating the Time Zone Data</a>. 1638 * 1639 * @param id A system time zone ID. 1640 * @param len The length of <code>id</code>, or -1 if null-terminated. 1641 * @param winid A buffer to receive a Windows time zone ID. 1642 * @param winidCapacity The capacity of the result buffer <code>winid</code>. 1643 * @param status Receives the status. 1644 * @return The result string length, not including the terminating null. 1645 * @see ucal_getTimeZoneIDForWindowsID 1646 * 1647 * @stable ICU 52 1648 */ 1649 U_CAPI int32_t U_EXPORT2 1650 ucal_getWindowsTimeZoneID(const UChar* id, int32_t len, 1651 UChar* winid, int32_t winidCapacity, UErrorCode* status); 1652 1653 /** 1654 * Converts a Windows time zone ID to an equivalent system time zone ID 1655 * for a region. For example, system time zone ID "America/Los_Angeles" is returned 1656 * for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>), 1657 * "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and 1658 * region "CA". 1659 * 1660 * <p>Not all Windows time zones can be mapped to system time zones. When the input 1661 * Windows time zone ID is unknown or unmappable to a system time zone, then this 1662 * function returns 0 as the result length, but the operation itself remains successful 1663 * (no error status set on return). 1664 * 1665 * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html"> 1666 * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes, 1667 * please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data"> 1668 * Updating the Time Zone Data</a>. 1669 * 1670 * @param winid A Windows time zone ID. 1671 * @param len The length of <code>winid</code>, or -1 if null-terminated. 1672 * @param region A null-terminated region code, or <code>NULL</code> if no regional preference. 1673 * @param id A buffer to receive a system time zone ID. 1674 * @param idCapacity The capacity of the result buffer <code>id</code>. 1675 * @param status Receives the status. 1676 * @return The result string length, not including the terminating null. 1677 * @see ucal_getWindowsTimeZoneID 1678 * 1679 * @stable ICU 52 1680 */ 1681 U_CAPI int32_t U_EXPORT2 1682 ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region, 1683 UChar* id, int32_t idCapacity, UErrorCode* status); 1684 1685 /** 1686 * Options used by ucal_getTimeZoneOffsetFromLocal and BasicTimeZone::getOffsetFromLocal() 1687 * to specify how to interpret an input time when it does not exist, or when it is ambiguous, 1688 * around a time zone transition. 1689 * @stable ICU 69 1690 */ 1691 enum UTimeZoneLocalOption { 1692 /** 1693 * An input time is always interpreted as local time before 1694 * a time zone transition. 1695 * @stable ICU 69 1696 */ 1697 UCAL_TZ_LOCAL_FORMER = 0x04, 1698 /** 1699 * An input time is always interpreted as local time after 1700 * a time zone transition. 1701 * @stable ICU 69 1702 */ 1703 UCAL_TZ_LOCAL_LATTER = 0x0C, 1704 /** 1705 * An input time is interpreted as standard time when local 1706 * time is switched to/from daylight saving time. When both 1707 * sides of a time zone transition are standard time, 1708 * or daylight saving time, the local time before the 1709 * transition is used. 1710 * @stable ICU 69 1711 */ 1712 UCAL_TZ_LOCAL_STANDARD_FORMER = UCAL_TZ_LOCAL_FORMER | 0x01, 1713 /** 1714 * An input time is interpreted as standard time when local 1715 * time is switched to/from daylight saving time. When both 1716 * sides of a time zone transition are standard time, 1717 * or daylight saving time, the local time after the 1718 * transition is used. 1719 * @stable ICU 69 1720 */ 1721 UCAL_TZ_LOCAL_STANDARD_LATTER = UCAL_TZ_LOCAL_LATTER | 0x01, 1722 /** 1723 * An input time is interpreted as daylight saving time when 1724 * local time is switched to/from standard time. When both 1725 * sides of a time zone transition are standard time, 1726 * or daylight saving time, the local time before the 1727 * transition is used. 1728 * @stable ICU 69 1729 */ 1730 UCAL_TZ_LOCAL_DAYLIGHT_FORMER = UCAL_TZ_LOCAL_FORMER | 0x03, 1731 /** 1732 * An input time is interpreted as daylight saving time when 1733 * local time is switched to/from standard time. When both 1734 * sides of a time zone transition are standard time, 1735 * or daylight saving time, the local time after the 1736 * transition is used. 1737 * @stable ICU 69 1738 */ 1739 UCAL_TZ_LOCAL_DAYLIGHT_LATTER = UCAL_TZ_LOCAL_LATTER | 0x03, 1740 }; 1741 typedef enum UTimeZoneLocalOption UTimeZoneLocalOption; /**< @stable ICU 69 */ 1742 1743 /** 1744 * Returns the time zone raw and GMT offset for the given moment 1745 * in time. Upon return, local-millis = GMT-millis + rawOffset + 1746 * dstOffset. All computations are performed in the proleptic 1747 * Gregorian calendar. 1748 * 1749 * @param cal The UCalendar which specify the local date and time value to query. 1750 * @param nonExistingTimeOpt The option to indicate how to interpret the date and 1751 * time in the calendar represent a local time that skipped at a positive time 1752 * zone transitions (e.g. when the daylight saving time starts or the time zone 1753 * offset is increased due to a time zone rule change). 1754 * @param duplicatedTimeOpt The option to indicate how to interpret the date and 1755 * time in the calendar represent a local time that repeating multiple times at a 1756 * negative time zone transition (e.g. when the daylight saving time ends or the 1757 * time zone offset is decreased due to a time zone rule change) 1758 * @param rawOffset output parameter to receive the raw offset, that 1759 * is, the offset not including DST adjustments. 1760 * If the status is set to one of the error code, the value set is unspecified. 1761 * @param dstOffset output parameter to receive the DST offset, 1762 * that is, the offset to be added to `rawOffset' to obtain the 1763 * total offset between local and GMT time. If DST is not in 1764 * effect, this value is zero; otherwise it is a positive value, 1765 * typically one hour. 1766 * If the status is set to one of the error code, the value set is unspecified. 1767 * @param status A pointer to a UErrorCode to receive any errors. 1768 * @stable ICU 69 1769 */ 1770 U_CAPI void U_EXPORT2 1771 ucal_getTimeZoneOffsetFromLocal( 1772 const UCalendar* cal, 1773 UTimeZoneLocalOption nonExistingTimeOpt, 1774 UTimeZoneLocalOption duplicatedTimeOpt, 1775 int32_t* rawOffset, int32_t* dstOffset, UErrorCode* status); 1776 1777 #endif /* #if !UCONFIG_NO_FORMATTING */ 1778 1779 #endif
Contact us
|
About us
|
Term of use
|
Copyright © 2000-2025 MyWebUniversity.com ™
