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