Where Online Learning is simpler!
The C and C++ Include Header Files
/usr/include/unicode/calendar.h
$ cat -n /usr/include/unicode/calendar.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) 1997-2014, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ******************************************************************************** 8 * 9 * File CALENDAR.H 10 * 11 * Modification History: 12 * 13 * Date Name Description 14 * 04/22/97 aliu Expanded and corrected comments and other header 15 * contents. 16 * 05/01/97 aliu Made equals(), before(), after() arguments const. 17 * 05/20/97 aliu Replaced fAreFieldsSet with fAreFieldsInSync and 18 * fAreAllFieldsSet. 19 * 07/27/98 stephen Sync up with JDK 1.2 20 * 11/15/99 weiv added YEAR_WOY and DOW_LOCAL 21 * to EDateFields 22 * 8/19/2002 srl Removed Javaisms 23 * 11/07/2003 srl Update, clean up documentation. 24 ******************************************************************************** 25 */ 26 27 #ifndef CALENDAR_H 28 #define CALENDAR_H 29 30 #include "unicode/utypes.h" 31 32 #if U_SHOW_CPLUSPLUS_API 33 34 /** 35 * \file 36 * \brief C++ API: Calendar object 37 */ 38 #if !UCONFIG_NO_FORMATTING 39 40 #include "unicode/uobject.h" 41 #include "unicode/locid.h" 42 #include "unicode/timezone.h" 43 #include "unicode/ucal.h" 44 #include "unicode/umisc.h" 45 46 U_NAMESPACE_BEGIN 47 48 class ICUServiceFactory; 49 50 // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API, 51 // it is a return type for a virtual method (@internal) 52 /** 53 * @internal 54 */ 55 typedef int32_t UFieldResolutionTable[12][8]; 56 57 class BasicTimeZone; 58 /** 59 * `Calendar` is an abstract base class for converting between 60 * a `UDate` object and a set of integer fields such as 61 * `YEAR`, `MONTH`, `DAY`, `HOUR`, and so on. 62 * (A `UDate` object represents a specific instant in 63 * time with millisecond precision. See UDate 64 * for information about the `UDate` class.) 65 * 66 * Subclasses of `Calendar` interpret a `UDate` 67 * according to the rules of a specific calendar system. 68 * The most commonly used subclass of `Calendar` is 69 * `GregorianCalendar`. Other subclasses could represent 70 * the various types of lunar calendars in use in many parts of the world. 71 * 72 * **NOTE**: (ICU 2.6) The subclass interface should be considered unstable - 73 * it WILL change. 74 * 75 * Like other locale-sensitive classes, `Calendar` provides a 76 * static method, `createInstance`, for getting a generally useful 77 * object of this type. `Calendar`'s `createInstance` method 78 * returns the appropriate `Calendar` subclass whose 79 * time fields have been initialized with the current date and time: 80 * 81 * Calendar *rightNow = Calendar::createInstance(errCode); 82 * 83 * A `Calendar` object can produce all the time field values 84 * needed to implement the date-time formatting for a particular language 85 * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional). 86 * 87 * When computing a `UDate` from time fields, some special circumstances 88 * may arise: there may be insufficient information to compute the 89 * `UDate` (such as only year and month but no day in the month), 90 * there may be inconsistent information (such as "Tuesday, July 15, 1996" 91 * -- July 15, 1996 is actually a Monday), or the input time might be ambiguous 92 * because of time zone transition. 93 * 94 * **Insufficient information.** The calendar will use default 95 * information to specify the missing fields. This may vary by calendar; for 96 * the Gregorian calendar, the default for a field is the same as that of the 97 * start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. 98 * 99 * **Inconsistent information.** If fields conflict, the calendar 100 * will give preference to fields set more recently. For example, when 101 * determining the day, the calendar will look for one of the following 102 * combinations of fields. The most recent combination, as determined by the 103 * most recently set single field, will be used. 104 * 105 * MONTH + DAY_OF_MONTH 106 * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK 107 * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK 108 * DAY_OF_YEAR 109 * DAY_OF_WEEK + WEEK_OF_YEAR 110 * 111 * For the time of day: 112 * 113 * HOUR_OF_DAY 114 * AM_PM + HOUR 115 * 116 * **Ambiguous Wall Clock Time.** When time offset from UTC has 117 * changed, it produces an ambiguous time slot around the transition. For example, 118 * many US locations observe daylight saving time. On the date switching to daylight 119 * saving time in US, wall clock time jumps from 12:59 AM (standard) to 2:00 AM 120 * (daylight). Therefore, wall clock time from 1:00 AM to 1:59 AM do not exist on 121 * the date. When the input wall time fall into this missing time slot, the ICU 122 * Calendar resolves the time using the UTC offset before the transition by default. 123 * In this example, 1:30 AM is interpreted as 1:30 AM standard time (non-exist), 124 * so the final result will be 2:30 AM daylight time. 125 * 126 * On the date switching back to standard time, wall clock time is moved back one 127 * hour at 2:00 AM. So wall clock time from 1:00 AM to 1:59 AM occur twice. In this 128 * case, the ICU Calendar resolves the time using the UTC offset after the transition 129 * by default. For example, 1:30 AM on the date is resolved as 1:30 AM standard time. 130 * 131 * Ambiguous wall clock time resolution behaviors can be customized by Calendar APIs 132 * {@link #setRepeatedWallTimeOption} and {@link #setSkippedWallTimeOption}. 133 * These methods are available in ICU 49 or later versions. 134 * 135 * **Note:** for some non-Gregorian calendars, different 136 * fields may be necessary for complete disambiguation. For example, a full 137 * specification of the historical Arabic astronomical calendar requires year, 138 * month, day-of-month *and* day-of-week in some cases. 139 * 140 * **Note:** There are certain possible ambiguities in 141 * interpretation of certain singular times, which are resolved in the 142 * following ways: 143 * 144 * 1. 24:00:00 "belongs" to the following day. That is, 145 * 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970 146 * 2. Although historically not precise, midnight also belongs to "am", 147 * and noon belongs to "pm", so on the same day, 148 * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm 149 * 150 * The date or time format strings are not part of the definition of a 151 * calendar, as those must be modifiable or overridable by the user at 152 * runtime. Use `DateFormat` to format dates. 153 * 154 * `Calendar` provides an API for field "rolling", where fields 155 * can be incremented or decremented, but wrap around. For example, rolling the 156 * month up in the date December 12, **1996** results in 157 * January 12, **1996**. 158 * 159 * `Calendar` also provides a date arithmetic function for 160 * adding the specified (signed) amount of time to a particular time field. 161 * For example, subtracting 5 days from the date `September 12, 1996` 162 * results in `September 7, 1996`. 163 * 164 * ***Supported range*** 165 * 166 * The allowable range of `Calendar` has been narrowed. `GregorianCalendar` used 167 * to attempt to support the range of dates with millisecond values from 168 * `Long.MIN_VALUE` to `Long.MAX_VALUE`. The new `Calendar` protocol specifies the 169 * maximum range of supportable dates as those having Julian day numbers 170 * of `-0x7F000000` to `+0x7F000000`. This corresponds to years from ~5,800,000 BCE 171 * to ~5,800,000 CE. Programmers should use the protected constants in `Calendar` to 172 * specify an extremely early or extremely late date. 173 * 174 * <p> 175 * The Japanese calendar uses a combination of era name and year number. 176 * When an emperor of Japan abdicates and a new emperor ascends the throne, 177 * a new era is declared and year number is reset to 1. Even if the date of 178 * abdication is scheduled ahead of time, the new era name might not be 179 * announced until just before the date. In such case, ICU4C may include 180 * a start date of future era without actual era name, but not enabled 181 * by default. ICU4C users who want to test the behavior of the future era 182 * can enable the tentative era by: 183 * <ul> 184 * <li>Environment variable <code>ICU_ENABLE_TENTATIVE_ERA=true</code>.</li> 185 * </ul> 186 * 187 * @stable ICU 2.0 188 */ 189 class U_I18N_API Calendar : public UObject { 190 public: 191 #ifndef U_FORCE_HIDE_DEPRECATED_API 192 /** 193 * Field IDs for date and time. Used to specify date/time fields. ERA is calendar 194 * specific. Example ranges given are for illustration only; see specific Calendar 195 * subclasses for actual ranges. 196 * @deprecated ICU 2.6. Use C enum UCalendarDateFields defined in ucal.h 197 */ 198 enum EDateFields { 199 #ifndef U_HIDE_DEPRECATED_API 200 /* 201 * ERA may be defined on other platforms. To avoid any potential problems undefined it here. 202 */ 203 #ifdef ERA 204 #undef ERA 205 #endif 206 ERA, // Example: 0..1 207 YEAR, // Example: 1..big number 208 MONTH, // Example: 0..11 209 WEEK_OF_YEAR, // Example: 1..53 210 WEEK_OF_MONTH, // Example: 1..4 211 DATE, // Example: 1..31 212 DAY_OF_YEAR, // Example: 1..365 213 DAY_OF_WEEK, // Example: 1..7 214 DAY_OF_WEEK_IN_MONTH, // Example: 1..4, may be specified as -1 215 AM_PM, // Example: 0..1 216 HOUR, // Example: 0..11 217 HOUR_OF_DAY, // Example: 0..23 218 MINUTE, // Example: 0..59 219 SECOND, // Example: 0..59 220 MILLISECOND, // Example: 0..999 221 ZONE_OFFSET, // Example: -12*U_MILLIS_PER_HOUR..12*U_MILLIS_PER_HOUR 222 DST_OFFSET, // Example: 0 or U_MILLIS_PER_HOUR 223 YEAR_WOY, // 'Y' Example: 1..big number - Year of Week of Year 224 DOW_LOCAL, // 'e' Example: 1..7 - Day of Week / Localized 225 226 EXTENDED_YEAR, 227 JULIAN_DAY, 228 MILLISECONDS_IN_DAY, 229 IS_LEAP_MONTH, 230 231 FIELD_COUNT = UCAL_FIELD_COUNT // See ucal.h for other fields. 232 #endif /* U_HIDE_DEPRECATED_API */ 233 }; 234 #endif // U_FORCE_HIDE_DEPRECATED_API 235 236 #ifndef U_HIDE_DEPRECATED_API 237 /** 238 * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients 239 * who create locale resources for the field of first-day-of-week should be aware of 240 * this. For instance, in US locale, first-day-of-week is set to 1, i.e., SUNDAY. 241 * @deprecated ICU 2.6. Use C enum UCalendarDaysOfWeek defined in ucal.h 242 */ 243 enum EDaysOfWeek { 244 SUNDAY = 1, 245 MONDAY, 246 TUESDAY, 247 WEDNESDAY, 248 THURSDAY, 249 FRIDAY, 250 SATURDAY 251 }; 252 253 /** 254 * Useful constants for month. Note: Calendar month is 0-based. 255 * @deprecated ICU 2.6. Use C enum UCalendarMonths defined in ucal.h 256 */ 257 enum EMonths { 258 JANUARY, 259 FEBRUARY, 260 MARCH, 261 APRIL, 262 MAY, 263 JUNE, 264 JULY, 265 AUGUST, 266 SEPTEMBER, 267 OCTOBER, 268 NOVEMBER, 269 DECEMBER, 270 UNDECIMBER 271 }; 272 273 /** 274 * Useful constants for hour in 12-hour clock. Used in GregorianCalendar. 275 * @deprecated ICU 2.6. Use C enum UCalendarAMPMs defined in ucal.h 276 */ 277 enum EAmpm { 278 AM, 279 PM 280 }; 281 #endif /* U_HIDE_DEPRECATED_API */ 282 283 /** 284 * destructor 285 * @stable ICU 2.0 286 */ 287 virtual ~Calendar(); 288 289 /** 290 * Create and return a polymorphic copy of this calendar. 291 * 292 * @return a polymorphic copy of this calendar. 293 * @stable ICU 2.0 294 */ 295 virtual Calendar* clone() const = 0; 296 297 /** 298 * Creates a Calendar using the default timezone and locale. Clients are responsible 299 * for deleting the object returned. 300 * 301 * @param success Indicates the success/failure of Calendar creation. Filled in 302 * with U_ZERO_ERROR if created successfully, set to a failure result 303 * otherwise. U_MISSING_RESOURCE_ERROR will be returned if the resource data 304 * requests a calendar type which has not been installed. 305 * @return A Calendar if created successfully. nullptr otherwise. 306 * @stable ICU 2.0 307 */ 308 static Calendar* U_EXPORT2 createInstance(UErrorCode& success); 309 310 /** 311 * Creates a Calendar using the given timezone and the default locale. 312 * The Calendar takes ownership of zoneToAdopt; the 313 * client must not delete it. 314 * 315 * @param zoneToAdopt The given timezone to be adopted. 316 * @param success Indicates the success/failure of Calendar creation. Filled in 317 * with U_ZERO_ERROR if created successfully, set to a failure result 318 * otherwise. 319 * @return A Calendar if created successfully. nullptr otherwise. 320 * @stable ICU 2.0 321 */ 322 static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, UErrorCode& success); 323 324 /** 325 * Creates a Calendar using the given timezone and the default locale. The TimeZone 326 * is _not_ adopted; the client is still responsible for deleting it. 327 * 328 * @param zone The timezone. 329 * @param success Indicates the success/failure of Calendar creation. Filled in 330 * with U_ZERO_ERROR if created successfully, set to a failure result 331 * otherwise. 332 * @return A Calendar if created successfully. nullptr otherwise. 333 * @stable ICU 2.0 334 */ 335 static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, UErrorCode& success); 336 337 /** 338 * Creates a Calendar using the default timezone and the given locale. 339 * 340 * @param aLocale The given locale. 341 * @param success Indicates the success/failure of Calendar creation. Filled in 342 * with U_ZERO_ERROR if created successfully, set to a failure result 343 * otherwise. 344 * @return A Calendar if created successfully. nullptr otherwise. 345 * @stable ICU 2.0 346 */ 347 static Calendar* U_EXPORT2 createInstance(const Locale& aLocale, UErrorCode& success); 348 349 /** 350 * Creates a Calendar using the given timezone and given locale. 351 * The Calendar takes ownership of zoneToAdopt; the 352 * client must not delete it. 353 * 354 * @param zoneToAdopt The given timezone to be adopted. 355 * @param aLocale The given locale. 356 * @param success Indicates the success/failure of Calendar creation. Filled in 357 * with U_ZERO_ERROR if created successfully, set to a failure result 358 * otherwise. 359 * @return A Calendar if created successfully. nullptr otherwise. 360 * @stable ICU 2.0 361 */ 362 static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, const Locale& aLocale, UErrorCode& success); 363 364 /** 365 * Gets a Calendar using the given timezone and given locale. The TimeZone 366 * is _not_ adopted; the client is still responsible for deleting it. 367 * 368 * @param zone The given timezone. 369 * @param aLocale The given locale. 370 * @param success Indicates the success/failure of Calendar creation. Filled in 371 * with U_ZERO_ERROR if created successfully, set to a failure result 372 * otherwise. 373 * @return A Calendar if created successfully. nullptr otherwise. 374 * @stable ICU 2.0 375 */ 376 static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, const Locale& aLocale, UErrorCode& success); 377 378 /** 379 * Returns a list of the locales for which Calendars are installed. 380 * 381 * @param count Number of locales returned. 382 * @return An array of Locale objects representing the set of locales for which 383 * Calendars are installed. The system retains ownership of this list; 384 * the caller must NOT delete it. Does not include user-registered Calendars. 385 * @stable ICU 2.0 386 */ 387 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); 388 389 390 /** 391 * Given a key and a locale, returns an array of string values in a preferred 392 * order that would make a difference. These are all and only those values where 393 * the open (creation) of the service with the locale formed from the input locale 394 * plus input keyword and that value has different behavior than creation with the 395 * input locale alone. 396 * @param key one of the keys supported by this service. For now, only 397 * "calendar" is supported. 398 * @param locale the locale 399 * @param commonlyUsed if set to true it will return only commonly used values 400 * with the given locale in preferred order. Otherwise, 401 * it will return all the available values for the locale. 402 * @param status ICU Error Code 403 * @return a string enumeration over keyword values for the given key and the locale. 404 * @stable ICU 4.2 405 */ 406 static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* key, 407 const Locale& locale, UBool commonlyUsed, UErrorCode& status); 408 409 /** 410 * Returns the current UTC (GMT) time measured in milliseconds since 0:00:00 on 1/1/70 411 * (derived from the system time). 412 * 413 * @return The current UTC time in milliseconds. 414 * @stable ICU 2.0 415 */ 416 static UDate U_EXPORT2 getNow(void); 417 418 /** 419 * Gets this Calendar's time as milliseconds. May involve recalculation of time due 420 * to previous calls to set time field values. The time specified is non-local UTC 421 * (GMT) time. Although this method is const, this object may actually be changed 422 * (semantically const). 423 * 424 * @param status Output param set to success/failure code on exit. If any value 425 * previously set in the time field is invalid or restricted by 426 * leniency, this will be set to an error status. 427 * @return The current time in UTC (GMT) time, or zero if the operation 428 * failed. 429 * @stable ICU 2.0 430 */ 431 inline UDate getTime(UErrorCode& status) const { return getTimeInMillis(status); } 432 433 /** 434 * Sets this Calendar's current time with the given UDate. The time specified should 435 * be in non-local UTC (GMT) time. 436 * 437 * @param date The given UDate in UTC (GMT) time. 438 * @param status Output param set to success/failure code on exit. If any value 439 * set in the time field is invalid or restricted by 440 * leniency, this will be set to an error status. 441 * @stable ICU 2.0 442 */ 443 inline void setTime(UDate date, UErrorCode& status) { setTimeInMillis(date, status); } 444 445 /** 446 * Compares the equality of two Calendar objects. Objects of different subclasses 447 * are considered unequal. This comparison is very exacting; two Calendar objects 448 * must be in exactly the same state to be considered equal. To compare based on the 449 * represented time, use equals() instead. 450 * 451 * @param that The Calendar object to be compared with. 452 * @return true if the given Calendar is the same as this Calendar; false 453 * otherwise. 454 * @stable ICU 2.0 455 */ 456 virtual bool operator==(const Calendar& that) const; 457 458 /** 459 * Compares the inequality of two Calendar objects. 460 * 461 * @param that The Calendar object to be compared with. 462 * @return true if the given Calendar is not the same as this Calendar; false 463 * otherwise. 464 * @stable ICU 2.0 465 */ 466 bool operator!=(const Calendar& that) const {return !operator==(that);} 467 468 /** 469 * Returns true if the given Calendar object is equivalent to this 470 * one. An equivalent Calendar will behave exactly as this one 471 * does, but it may be set to a different time. By contrast, for 472 * the operator==() method to return true, the other Calendar must 473 * be set to the same time. 474 * 475 * @param other the Calendar to be compared with this Calendar 476 * @stable ICU 2.4 477 */ 478 virtual UBool isEquivalentTo(const Calendar& other) const; 479 480 /** 481 * Compares the Calendar time, whereas Calendar::operator== compares the equality of 482 * Calendar objects. 483 * 484 * @param when The Calendar to be compared with this Calendar. Although this is a 485 * const parameter, the object may be modified physically 486 * (semantically const). 487 * @param status Output param set to success/failure code on exit. If any value 488 * previously set in the time field is invalid or restricted by 489 * leniency, this will be set to an error status. 490 * @return True if the current time of this Calendar is equal to the time of 491 * Calendar when; false otherwise. 492 * @stable ICU 2.0 493 */ 494 UBool equals(const Calendar& when, UErrorCode& status) const; 495 496 /** 497 * Returns true if this Calendar's current time is before "when"'s current time. 498 * 499 * @param when The Calendar to be compared with this Calendar. Although this is a 500 * const parameter, the object may be modified physically 501 * (semantically const). 502 * @param status Output param set to success/failure code on exit. If any value 503 * previously set in the time field is invalid or restricted by 504 * leniency, this will be set to an error status. 505 * @return True if the current time of this Calendar is before the time of 506 * Calendar when; false otherwise. 507 * @stable ICU 2.0 508 */ 509 UBool before(const Calendar& when, UErrorCode& status) const; 510 511 /** 512 * Returns true if this Calendar's current time is after "when"'s current time. 513 * 514 * @param when The Calendar to be compared with this Calendar. Although this is a 515 * const parameter, the object may be modified physically 516 * (semantically const). 517 * @param status Output param set to success/failure code on exit. If any value 518 * previously set in the time field is invalid or restricted by 519 * leniency, this will be set to an error status. 520 * @return True if the current time of this Calendar is after the time of 521 * Calendar when; false otherwise. 522 * @stable ICU 2.0 523 */ 524 UBool after(const Calendar& when, UErrorCode& status) const; 525 526 #ifndef U_FORCE_HIDE_DEPRECATED_API 527 /** 528 * UDate Arithmetic function. Adds the specified (signed) amount of time to the given 529 * time field, based on the calendar's rules. For example, to subtract 5 days from 530 * the current time of the calendar, call add(Calendar::DATE, -5). When adding on 531 * the month or Calendar::MONTH field, other fields like date might conflict and 532 * need to be changed. For instance, adding 1 month on the date 01/31/96 will result 533 * in 02/29/96. 534 * Adding a positive value always means moving forward in time, so for the Gregorian calendar, 535 * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces 536 * the numeric value of the field itself). 537 * 538 * @param field Specifies which date field to modify. 539 * @param amount The amount of time to be added to the field, in the natural unit 540 * for that field (e.g., days for the day fields, hours for the hour 541 * field.) 542 * @param status Output param set to success/failure code on exit. If any value 543 * previously set in the time field is invalid or restricted by 544 * leniency, this will be set to an error status. 545 * @deprecated ICU 2.6. use add(UCalendarDateFields field, int32_t amount, UErrorCode& status) instead. 546 */ 547 virtual void add(EDateFields field, int32_t amount, UErrorCode& status); 548 #endif // U_FORCE_HIDE_DEPRECATED_API 549 550 /** 551 * UDate Arithmetic function. Adds the specified (signed) amount of time to the given 552 * time field, based on the calendar's rules. For example, to subtract 5 days from 553 * the current time of the calendar, call add(Calendar::DATE, -5). When adding on 554 * the month or Calendar::MONTH field, other fields like date might conflict and 555 * need to be changed. For instance, adding 1 month on the date 01/31/96 will result 556 * in 02/29/96. 557 * Adding a positive value always means moving forward in time, so for the Gregorian calendar, 558 * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces 559 * the numeric value of the field itself). 560 * 561 * @param field Specifies which date field to modify. 562 * @param amount The amount of time to be added to the field, in the natural unit 563 * for that field (e.g., days for the day fields, hours for the hour 564 * field.) 565 * @param status Output param set to success/failure code on exit. If any value 566 * previously set in the time field is invalid or restricted by 567 * leniency, this will be set to an error status. 568 * @stable ICU 2.6. 569 */ 570 virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& status); 571 572 #ifndef U_HIDE_DEPRECATED_API 573 /** 574 * Time Field Rolling function. Rolls (up/down) a single unit of time on the given 575 * time field. For example, to roll the current date up by one day, call 576 * roll(Calendar::DATE, true). When rolling on the year or Calendar::YEAR field, it 577 * will roll the year value in the range between getMinimum(Calendar::YEAR) and the 578 * value returned by getMaximum(Calendar::YEAR). When rolling on the month or 579 * Calendar::MONTH field, other fields like date might conflict and, need to be 580 * changed. For instance, rolling the month up on the date 01/31/96 will result in 581 * 02/29/96. Rolling up always means rolling forward in time (unless the limit of the 582 * field is reached, in which case it may pin or wrap), so for Gregorian calendar, 583 * starting with 100 BC and rolling the year up results in 99 BC. 584 * When eras have a definite beginning and end (as in the Chinese calendar, or as in 585 * most eras in the Japanese calendar) then rolling the year past either limit of the 586 * era will cause the year to wrap around. When eras only have a limit at one end, 587 * then attempting to roll the year past that limit will result in pinning the year 588 * at that limit. Note that for most calendars in which era 0 years move forward in 589 * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to 590 * result in negative years for era 0 (that is the only way to represent years before 591 * the calendar epoch). 592 * When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the 593 * hour value in the range between 0 and 23, which is zero-based. 594 * <P> 595 * NOTE: Do not use this method -- use roll(EDateFields, int, UErrorCode&) instead. 596 * 597 * @param field The time field. 598 * @param up Indicates if the value of the specified time field is to be rolled 599 * up or rolled down. Use true if rolling up, false otherwise. 600 * @param status Output param set to success/failure code on exit. If any value 601 * previously set in the time field is invalid or restricted by 602 * leniency, this will be set to an error status. 603 * @deprecated ICU 2.6. Use roll(UCalendarDateFields field, UBool up, UErrorCode& status) instead. 604 */ 605 inline void roll(EDateFields field, UBool up, UErrorCode& status); 606 #endif /* U_HIDE_DEPRECATED_API */ 607 608 /** 609 * Time Field Rolling function. Rolls (up/down) a single unit of time on the given 610 * time field. For example, to roll the current date up by one day, call 611 * roll(Calendar::DATE, true). When rolling on the year or Calendar::YEAR field, it 612 * will roll the year value in the range between getMinimum(Calendar::YEAR) and the 613 * value returned by getMaximum(Calendar::YEAR). When rolling on the month or 614 * Calendar::MONTH field, other fields like date might conflict and, need to be 615 * changed. For instance, rolling the month up on the date 01/31/96 will result in 616 * 02/29/96. Rolling up always means rolling forward in time (unless the limit of the 617 * field is reached, in which case it may pin or wrap), so for Gregorian calendar, 618 * starting with 100 BC and rolling the year up results in 99 BC. 619 * When eras have a definite beginning and end (as in the Chinese calendar, or as in 620 * most eras in the Japanese calendar) then rolling the year past either limit of the 621 * era will cause the year to wrap around. When eras only have a limit at one end, 622 * then attempting to roll the year past that limit will result in pinning the year 623 * at that limit. Note that for most calendars in which era 0 years move forward in 624 * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to 625 * result in negative years for era 0 (that is the only way to represent years before 626 * the calendar epoch). 627 * When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the 628 * hour value in the range between 0 and 23, which is zero-based. 629 * <P> 630 * NOTE: Do not use this method -- use roll(UCalendarDateFields, int, UErrorCode&) instead. 631 * 632 * @param field The time field. 633 * @param up Indicates if the value of the specified time field is to be rolled 634 * up or rolled down. Use true if rolling up, false otherwise. 635 * @param status Output param set to success/failure code on exit. If any value 636 * previously set in the time field is invalid or restricted by 637 * leniency, this will be set to an error status. 638 * @stable ICU 2.6. 639 */ 640 inline void roll(UCalendarDateFields field, UBool up, UErrorCode& status); 641 642 #ifndef U_FORCE_HIDE_DEPRECATED_API 643 /** 644 * Time Field Rolling function. Rolls by the given amount on the given 645 * time field. For example, to roll the current date up by one day, call 646 * roll(Calendar::DATE, +1, status). When rolling on the month or 647 * Calendar::MONTH field, other fields like date might conflict and, need to be 648 * changed. For instance, rolling the month up on the date 01/31/96 will result in 649 * 02/29/96. Rolling by a positive value always means rolling forward in time (unless 650 * the limit of the field is reached, in which case it may pin or wrap), so for 651 * Gregorian calendar, starting with 100 BC and rolling the year by + 1 results in 99 BC. 652 * When eras have a definite beginning and end (as in the Chinese calendar, or as in 653 * most eras in the Japanese calendar) then rolling the year past either limit of the 654 * era will cause the year to wrap around. When eras only have a limit at one end, 655 * then attempting to roll the year past that limit will result in pinning the year 656 * at that limit. Note that for most calendars in which era 0 years move forward in 657 * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to 658 * result in negative years for era 0 (that is the only way to represent years before 659 * the calendar epoch). 660 * When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the 661 * hour value in the range between 0 and 23, which is zero-based. 662 * <P> 663 * The only difference between roll() and add() is that roll() does not change 664 * the value of more significant fields when it reaches the minimum or maximum 665 * of its range, whereas add() does. 666 * 667 * @param field The time field. 668 * @param amount Indicates amount to roll. 669 * @param status Output param set to success/failure code on exit. If any value 670 * previously set in the time field is invalid, this will be set to 671 * an error status. 672 * @deprecated ICU 2.6. Use roll(UCalendarDateFields field, int32_t amount, UErrorCode& status) instead. 673 */ 674 virtual void roll(EDateFields field, int32_t amount, UErrorCode& status); 675 #endif // U_FORCE_HIDE_DEPRECATED_API 676 677 /** 678 * Time Field Rolling function. Rolls by the given amount on the given 679 * time field. For example, to roll the current date up by one day, call 680 * roll(Calendar::DATE, +1, status). When rolling on the month or 681 * Calendar::MONTH field, other fields like date might conflict and, need to be 682 * changed. For instance, rolling the month up on the date 01/31/96 will result in 683 * 02/29/96. Rolling by a positive value always means rolling forward in time (unless 684 * the limit of the field is reached, in which case it may pin or wrap), so for 685 * Gregorian calendar, starting with 100 BC and rolling the year by + 1 results in 99 BC. 686 * When eras have a definite beginning and end (as in the Chinese calendar, or as in 687 * most eras in the Japanese calendar) then rolling the year past either limit of the 688 * era will cause the year to wrap around. When eras only have a limit at one end, 689 * then attempting to roll the year past that limit will result in pinning the year 690 * at that limit. Note that for most calendars in which era 0 years move forward in 691 * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to 692 * result in negative years for era 0 (that is the only way to represent years before 693 * the calendar epoch). 694 * When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the 695 * hour value in the range between 0 and 23, which is zero-based. 696 * <P> 697 * The only difference between roll() and add() is that roll() does not change 698 * the value of more significant fields when it reaches the minimum or maximum 699 * of its range, whereas add() does. 700 * 701 * @param field The time field. 702 * @param amount Indicates amount to roll. 703 * @param status Output param set to success/failure code on exit. If any value 704 * previously set in the time field is invalid, this will be set to 705 * an error status. 706 * @stable ICU 2.6. 707 */ 708 virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode& status); 709 710 #ifndef U_FORCE_HIDE_DEPRECATED_API 711 /** 712 * Return the difference between the given time and the time this 713 * calendar object is set to. If this calendar is set 714 * <em>before</em> the given time, the returned value will be 715 * positive. If this calendar is set <em>after</em> the given 716 * time, the returned value will be negative. The 717 * <code>field</code> parameter specifies the units of the return 718 * value. For example, if <code>fieldDifference(when, 719 * Calendar::MONTH)</code> returns 3, then this calendar is set to 720 * 3 months before <code>when</code>, and possibly some addition 721 * time less than one month. 722 * 723 * <p>As a side effect of this call, this calendar is advanced 724 * toward <code>when</code> by the given amount. That is, calling 725 * this method has the side effect of calling <code>add(field, 726 * n)</code>, where <code>n</code> is the return value. 727 * 728 * <p>Usage: To use this method, call it first with the largest 729 * field of interest, then with progressively smaller fields. For 730 * example: 731 * 732 * <pre> 733 * int y = cal->fieldDifference(when, Calendar::YEAR, err); 734 * int m = cal->fieldDifference(when, Calendar::MONTH, err); 735 * int d = cal->fieldDifference(when, Calendar::DATE, err);</pre> 736 * 737 * computes the difference between <code>cal</code> and 738 * <code>when</code> in years, months, and days. 739 * 740 * <p>Note: <code>fieldDifference()</code> is 741 * <em>asymmetrical</em>. That is, in the following code: 742 * 743 * <pre> 744 * cal->setTime(date1, err); 745 * int m1 = cal->fieldDifference(date2, Calendar::MONTH, err); 746 * int d1 = cal->fieldDifference(date2, Calendar::DATE, err); 747 * cal->setTime(date2, err); 748 * int m2 = cal->fieldDifference(date1, Calendar::MONTH, err); 749 * int d2 = cal->fieldDifference(date1, Calendar::DATE, err);</pre> 750 * 751 * one might expect that <code>m1 == -m2 && d1 == -d2</code>. 752 * However, this is not generally the case, because of 753 * irregularities in the underlying calendar system (e.g., the 754 * Gregorian calendar has a varying number of days per month). 755 * 756 * @param when the date to compare this calendar's time to 757 * @param field the field in which to compute the result 758 * @param status Output param set to success/failure code on exit. If any value 759 * previously set in the time field is invalid, this will be set to 760 * an error status. 761 * @return the difference, either positive or negative, between 762 * this calendar's time and <code>when</code>, in terms of 763 * <code>field</code>. 764 * @deprecated ICU 2.6. Use fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status). 765 */ 766 virtual int32_t fieldDifference(UDate when, EDateFields field, UErrorCode& status); 767 #endif // U_FORCE_HIDE_DEPRECATED_API 768 769 /** 770 * Return the difference between the given time and the time this 771 * calendar object is set to. If this calendar is set 772 * <em>before</em> the given time, the returned value will be 773 * positive. If this calendar is set <em>after</em> the given 774 * time, the returned value will be negative. The 775 * <code>field</code> parameter specifies the units of the return 776 * value. For example, if <code>fieldDifference(when, 777 * Calendar::MONTH)</code> returns 3, then this calendar is set to 778 * 3 months before <code>when</code>, and possibly some addition 779 * time less than one month. 780 * 781 * <p>As a side effect of this call, this calendar is advanced 782 * toward <code>when</code> by the given amount. That is, calling 783 * this method has the side effect of calling <code>add(field, 784 * n)</code>, where <code>n</code> is the return value. 785 * 786 * <p>Usage: To use this method, call it first with the largest 787 * field of interest, then with progressively smaller fields. For 788 * example: 789 * 790 * <pre> 791 * int y = cal->fieldDifference(when, Calendar::YEAR, err); 792 * int m = cal->fieldDifference(when, Calendar::MONTH, err); 793 * int d = cal->fieldDifference(when, Calendar::DATE, err);</pre> 794 * 795 * computes the difference between <code>cal</code> and 796 * <code>when</code> in years, months, and days. 797 * 798 * <p>Note: <code>fieldDifference()</code> is 799 * <em>asymmetrical</em>. That is, in the following code: 800 * 801 * <pre> 802 * cal->setTime(date1, err); 803 * int m1 = cal->fieldDifference(date2, Calendar::MONTH, err); 804 * int d1 = cal->fieldDifference(date2, Calendar::DATE, err); 805 * cal->setTime(date2, err); 806 * int m2 = cal->fieldDifference(date1, Calendar::MONTH, err); 807 * int d2 = cal->fieldDifference(date1, Calendar::DATE, err);</pre> 808 * 809 * one might expect that <code>m1 == -m2 && d1 == -d2</code>. 810 * However, this is not generally the case, because of 811 * irregularities in the underlying calendar system (e.g., the 812 * Gregorian calendar has a varying number of days per month). 813 * 814 * @param when the date to compare this calendar's time to 815 * @param field the field in which to compute the result 816 * @param status Output param set to success/failure code on exit. If any value 817 * previously set in the time field is invalid, this will be set to 818 * an error status. 819 * @return the difference, either positive or negative, between 820 * this calendar's time and <code>when</code>, in terms of 821 * <code>field</code>. 822 * @stable ICU 2.6. 823 */ 824 virtual int32_t fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status); 825 826 /** 827 * Sets the calendar's time zone to be the one passed in. The Calendar takes ownership 828 * of the TimeZone; the caller is no longer responsible for deleting it. If the 829 * given time zone is nullptr, this function has no effect. 830 * 831 * @param value The given time zone. 832 * @stable ICU 2.0 833 */ 834 void adoptTimeZone(TimeZone* value); 835 836 /** 837 * Sets the calendar's time zone to be the same as the one passed in. The TimeZone 838 * passed in is _not_ adopted; the client is still responsible for deleting it. 839 * 840 * @param zone The given time zone. 841 * @stable ICU 2.0 842 */ 843 void setTimeZone(const TimeZone& zone); 844 845 /** 846 * Returns a reference to the time zone owned by this calendar. The returned reference 847 * is only valid until clients make another call to adoptTimeZone or setTimeZone, 848 * or this Calendar is destroyed. 849 * 850 * @return The time zone object associated with this calendar. 851 * @stable ICU 2.0 852 */ 853 const TimeZone& getTimeZone(void) const; 854 855 /** 856 * Returns the time zone owned by this calendar. The caller owns the returned object 857 * and must delete it when done. After this call, the new time zone associated 858 * with this Calendar is the default TimeZone as returned by TimeZone::createDefault(). 859 * 860 * @return The time zone object which was associated with this calendar. 861 * @stable ICU 2.0 862 */ 863 TimeZone* orphanTimeZone(void); 864 865 /** 866 * Queries if the current date for this Calendar is in Daylight Savings Time. 867 * 868 * @param status Fill-in parameter which receives the status of this operation. 869 * @return True if the current date for this Calendar is in Daylight Savings Time, 870 * false, otherwise. 871 * @stable ICU 2.0 872 */ 873 virtual UBool inDaylightTime(UErrorCode& status) const; 874 875 /** 876 * Specifies whether or not date/time interpretation is to be lenient. With lenient 877 * interpretation, a date such as "February 942, 1996" will be treated as being 878 * equivalent to the 941st day after February 1, 1996. With strict interpretation, 879 * such dates will cause an error when computing time from the time field values 880 * representing the dates. 881 * 882 * @param lenient True specifies date/time interpretation to be lenient. 883 * 884 * @see DateFormat#setLenient 885 * @stable ICU 2.0 886 */ 887 void setLenient(UBool lenient); 888 889 /** 890 * Tells whether date/time interpretation is to be lenient. 891 * 892 * @return True tells that date/time interpretation is to be lenient. 893 * @stable ICU 2.0 894 */ 895 UBool isLenient(void) const; 896 897 /** 898 * Sets the behavior for handling wall time repeating multiple times 899 * at negative time zone offset transitions. For example, 1:30 AM on 900 * November 6, 2011 in US Eastern time (America/New_York) occurs twice; 901 * 1:30 AM EDT, then 1:30 AM EST one hour later. When <code>UCAL_WALLTIME_FIRST</code> 902 * is used, the wall time 1:30AM in this example will be interpreted as 1:30 AM EDT 903 * (first occurrence). When <code>UCAL_WALLTIME_LAST</code> is used, it will be 904 * interpreted as 1:30 AM EST (last occurrence). The default value is 905 * <code>UCAL_WALLTIME_LAST</code>. 906 * <p> 907 * <b>Note:</b>When <code>UCAL_WALLTIME_NEXT_VALID</code> is not a valid 908 * option for this. When the argument is neither <code>UCAL_WALLTIME_FIRST</code> 909 * nor <code>UCAL_WALLTIME_LAST</code>, this method has no effect and will keep 910 * the current setting. 911 * 912 * @param option the behavior for handling repeating wall time, either 913 * <code>UCAL_WALLTIME_FIRST</code> or <code>UCAL_WALLTIME_LAST</code>. 914 * @see #getRepeatedWallTimeOption 915 * @stable ICU 49 916 */ 917 void setRepeatedWallTimeOption(UCalendarWallTimeOption option); 918 919 /** 920 * Gets the behavior for handling wall time repeating multiple times 921 * at negative time zone offset transitions. 922 * 923 * @return the behavior for handling repeating wall time, either 924 * <code>UCAL_WALLTIME_FIRST</code> or <code>UCAL_WALLTIME_LAST</code>. 925 * @see #setRepeatedWallTimeOption 926 * @stable ICU 49 927 */ 928 UCalendarWallTimeOption getRepeatedWallTimeOption(void) const; 929 930 /** 931 * Sets the behavior for handling skipped wall time at positive time zone offset 932 * transitions. For example, 2:30 AM on March 13, 2011 in US Eastern time (America/New_York) 933 * does not exist because the wall time jump from 1:59 AM EST to 3:00 AM EDT. When 934 * <code>UCAL_WALLTIME_FIRST</code> is used, 2:30 AM is interpreted as 30 minutes before 3:00 AM 935 * EDT, therefore, it will be resolved as 1:30 AM EST. When <code>UCAL_WALLTIME_LAST</code> 936 * is used, 2:30 AM is interpreted as 31 minutes after 1:59 AM EST, therefore, it will be 937 * resolved as 3:30 AM EDT. When <code>UCAL_WALLTIME_NEXT_VALID</code> is used, 2:30 AM will 938 * be resolved as next valid wall time, that is 3:00 AM EDT. The default value is 939 * <code>UCAL_WALLTIME_LAST</code>. 940 * <p> 941 * <b>Note:</b>This option is effective only when this calendar is lenient. 942 * When the calendar is strict, such non-existing wall time will cause an error. 943 * 944 * @param option the behavior for handling skipped wall time at positive time zone 945 * offset transitions, one of <code>UCAL_WALLTIME_FIRST</code>, <code>UCAL_WALLTIME_LAST</code> and 946 * <code>UCAL_WALLTIME_NEXT_VALID</code>. 947 * @see #getSkippedWallTimeOption 948 * 949 * @stable ICU 49 950 */ 951 void setSkippedWallTimeOption(UCalendarWallTimeOption option); 952 953 /** 954 * Gets the behavior for handling skipped wall time at positive time zone offset 955 * transitions. 956 * 957 * @return the behavior for handling skipped wall time, one of 958 * <code>UCAL_WALLTIME_FIRST</code>, <code>UCAL_WALLTIME_LAST</code> 959 * and <code>UCAL_WALLTIME_NEXT_VALID</code>. 960 * @see #setSkippedWallTimeOption 961 * @stable ICU 49 962 */ 963 UCalendarWallTimeOption getSkippedWallTimeOption(void) const; 964 965 /** 966 * Sets what the first day of the week is; e.g., Sunday in US, Monday in France. 967 * 968 * @param value The given first day of the week. 969 * @stable ICU 2.6. 970 */ 971 void setFirstDayOfWeek(UCalendarDaysOfWeek value); 972 973 #ifndef U_HIDE_DEPRECATED_API 974 /** 975 * Gets what the first day of the week is; e.g., Sunday in US, Monday in France. 976 * 977 * @return The first day of the week. 978 * @deprecated ICU 2.6 use the overload with error code 979 */ 980 EDaysOfWeek getFirstDayOfWeek(void) const; 981 #endif /* U_HIDE_DEPRECATED_API */ 982 983 /** 984 * Gets what the first day of the week is; e.g., Sunday in US, Monday in France. 985 * 986 * @param status error code 987 * @return The first day of the week. 988 * @stable ICU 2.6 989 */ 990 UCalendarDaysOfWeek getFirstDayOfWeek(UErrorCode &status) const; 991 992 /** 993 * Sets what the minimal days required in the first week of the year are; For 994 * example, if the first week is defined as one that contains the first day of the 995 * first month of a year, call the method with value 1. If it must be a full week, 996 * use value 7. 997 * 998 * @param value The given minimal days required in the first week of the year. 999 * @stable ICU 2.0 1000 */ 1001 void setMinimalDaysInFirstWeek(uint8_t value); 1002 1003 /** 1004 * Gets what the minimal days required in the first week of the year are; e.g., if 1005 * the first week is defined as one that contains the first day of the first month 1006 * of a year, getMinimalDaysInFirstWeek returns 1. If the minimal days required must 1007 * be a full week, getMinimalDaysInFirstWeek returns 7. 1008 * 1009 * @return The minimal days required in the first week of the year. 1010 * @stable ICU 2.0 1011 */ 1012 uint8_t getMinimalDaysInFirstWeek(void) const; 1013 1014 #ifndef U_FORCE_HIDE_DEPRECATED_API 1015 /** 1016 * Gets the minimum value for the given time field. e.g., for Gregorian 1017 * DAY_OF_MONTH, 1. 1018 * 1019 * @param field The given time field. 1020 * @return The minimum value for the given time field. 1021 * @deprecated ICU 2.6. Use getMinimum(UCalendarDateFields field) instead. 1022 */ 1023 virtual int32_t getMinimum(EDateFields field) const; 1024 #endif // U_FORCE_HIDE_DEPRECATED_API 1025 1026 /** 1027 * Gets the minimum value for the given time field. e.g., for Gregorian 1028 * DAY_OF_MONTH, 1. 1029 * 1030 * @param field The given time field. 1031 * @return The minimum value for the given time field. 1032 * @stable ICU 2.6. 1033 */ 1034 virtual int32_t getMinimum(UCalendarDateFields field) const; 1035 1036 #ifndef U_FORCE_HIDE_DEPRECATED_API 1037 /** 1038 * Gets the maximum value for the given time field. e.g. for Gregorian DAY_OF_MONTH, 1039 * 31. 1040 * 1041 * @param field The given time field. 1042 * @return The maximum value for the given time field. 1043 * @deprecated ICU 2.6. Use getMaximum(UCalendarDateFields field) instead. 1044 */ 1045 virtual int32_t getMaximum(EDateFields field) const; 1046 #endif // U_FORCE_HIDE_DEPRECATED_API 1047 1048 /** 1049 * Gets the maximum value for the given time field. e.g. for Gregorian DAY_OF_MONTH, 1050 * 31. 1051 * 1052 * @param field The given time field. 1053 * @return The maximum value for the given time field. 1054 * @stable ICU 2.6. 1055 */ 1056 virtual int32_t getMaximum(UCalendarDateFields field) const; 1057 1058 #ifndef U_FORCE_HIDE_DEPRECATED_API 1059 /** 1060 * Gets the highest minimum value for the given field if varies. Otherwise same as 1061 * getMinimum(). For Gregorian, no difference. 1062 * 1063 * @param field The given time field. 1064 * @return The highest minimum value for the given time field. 1065 * @deprecated ICU 2.6. Use getGreatestMinimum(UCalendarDateFields field) instead. 1066 */ 1067 virtual int32_t getGreatestMinimum(EDateFields field) const; 1068 #endif // U_FORCE_HIDE_DEPRECATED_API 1069 1070 /** 1071 * Gets the highest minimum value for the given field if varies. Otherwise same as 1072 * getMinimum(). For Gregorian, no difference. 1073 * 1074 * @param field The given time field. 1075 * @return The highest minimum value for the given time field. 1076 * @stable ICU 2.6. 1077 */ 1078 virtual int32_t getGreatestMinimum(UCalendarDateFields field) const; 1079 1080 #ifndef U_FORCE_HIDE_DEPRECATED_API 1081 /** 1082 * Gets the lowest maximum value for the given field if varies. Otherwise same as 1083 * getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28. 1084 * 1085 * @param field The given time field. 1086 * @return The lowest maximum value for the given time field. 1087 * @deprecated ICU 2.6. Use getLeastMaximum(UCalendarDateFields field) instead. 1088 */ 1089 virtual int32_t getLeastMaximum(EDateFields field) const; 1090 #endif // U_FORCE_HIDE_DEPRECATED_API 1091 1092 /** 1093 * Gets the lowest maximum value for the given field if varies. Otherwise same as 1094 * getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28. 1095 * 1096 * @param field The given time field. 1097 * @return The lowest maximum value for the given time field. 1098 * @stable ICU 2.6. 1099 */ 1100 virtual int32_t getLeastMaximum(UCalendarDateFields field) const; 1101 1102 #ifndef U_HIDE_DEPRECATED_API 1103 /** 1104 * Return the minimum value that this field could have, given the current date. 1105 * For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum(). 1106 * 1107 * The version of this function on Calendar uses an iterative algorithm to determine the 1108 * actual minimum value for the field. There is almost always a more efficient way to 1109 * accomplish this (in most cases, you can simply return getMinimum()). GregorianCalendar 1110 * overrides this function with a more efficient implementation. 1111 * 1112 * @param field the field to determine the minimum of 1113 * @param status Fill-in parameter which receives the status of this operation. 1114 * @return the minimum of the given field for the current date of this Calendar 1115 * @deprecated ICU 2.6. Use getActualMinimum(UCalendarDateFields field, UErrorCode& status) instead. 1116 */ 1117 int32_t getActualMinimum(EDateFields field, UErrorCode& status) const; 1118 #endif /* U_HIDE_DEPRECATED_API */ 1119 1120 /** 1121 * Return the minimum value that this field could have, given the current date. 1122 * For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum(). 1123 * 1124 * The version of this function on Calendar uses an iterative algorithm to determine the 1125 * actual minimum value for the field. There is almost always a more efficient way to 1126 * accomplish this (in most cases, you can simply return getMinimum()). GregorianCalendar 1127 * overrides this function with a more efficient implementation. 1128 * 1129 * @param field the field to determine the minimum of 1130 * @param status Fill-in parameter which receives the status of this operation. 1131 * @return the minimum of the given field for the current date of this Calendar 1132 * @stable ICU 2.6. 1133 */ 1134 virtual int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& status) const; 1135 1136 /** 1137 * Return the maximum value that this field could have, given the current date. 1138 * For example, with the date "Feb 3, 1997" and the DAY_OF_MONTH field, the actual 1139 * maximum would be 28; for "Feb 3, 1996" it s 29. Similarly for a Hebrew calendar, 1140 * for some years the actual maximum for MONTH is 12, and for others 13. 1141 * 1142 * The version of this function on Calendar uses an iterative algorithm to determine the 1143 * actual maximum value for the field. There is almost always a more efficient way to 1144 * accomplish this (in most cases, you can simply return getMaximum()). GregorianCalendar 1145 * overrides this function with a more efficient implementation. 1146 * 1147 * @param field the field to determine the maximum of 1148 * @param status Fill-in parameter which receives the status of this operation. 1149 * @return the maximum of the given field for the current date of this Calendar 1150 * @stable ICU 2.6. 1151 */ 1152 virtual int32_t getActualMaximum(UCalendarDateFields field, UErrorCode& status) const; 1153 1154 /** 1155 * Gets the value for a given time field. Recalculate the current time field values 1156 * if the time value has been changed by a call to setTime(). Return zero for unset 1157 * fields if any fields have been explicitly set by a call to set(). To force a 1158 * recomputation of all fields regardless of the previous state, call complete(). 1159 * This method is semantically const, but may alter the object in memory. 1160 * 1161 * @param field The given time field. 1162 * @param status Fill-in parameter which receives the status of the operation. 1163 * @return The value for the given time field, or zero if the field is unset, 1164 * and set() has been called for any other field. 1165 * @stable ICU 2.6. 1166 */ 1167 int32_t get(UCalendarDateFields field, UErrorCode& status) const; 1168 1169 /** 1170 * Determines if the given time field has a value set. This can affect in the 1171 * resolving of time in Calendar. Unset fields have a value of zero, by definition. 1172 * 1173 * @param field The given time field. 1174 * @return True if the given time field has a value set; false otherwise. 1175 * @stable ICU 2.6. 1176 */ 1177 UBool isSet(UCalendarDateFields field) const; 1178 1179 /** 1180 * Sets the given time field with the given value. 1181 * 1182 * @param field The given time field. 1183 * @param value The value to be set for the given time field. 1184 * @stable ICU 2.6. 1185 */ 1186 void set(UCalendarDateFields field, int32_t value); 1187 1188 /** 1189 * Sets the values for the fields YEAR, MONTH, and DATE. Other field values are 1190 * retained; call clear() first if this is not desired. 1191 * 1192 * @param year The value used to set the YEAR time field. 1193 * @param month The value used to set the MONTH time field. Month value is 0-based. 1194 * e.g., 0 for January. 1195 * @param date The value used to set the DATE time field. 1196 * @stable ICU 2.0 1197 */ 1198 void set(int32_t year, int32_t month, int32_t date); 1199 1200 /** 1201 * Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, and MINUTE. Other 1202 * field values are retained; call clear() first if this is not desired. 1203 * 1204 * @param year The value used to set the YEAR time field. 1205 * @param month The value used to set the MONTH time field. Month value is 1206 * 0-based. E.g., 0 for January. 1207 * @param date The value used to set the DATE time field. 1208 * @param hour The value used to set the HOUR_OF_DAY time field. 1209 * @param minute The value used to set the MINUTE time field. 1210 * @stable ICU 2.0 1211 */ 1212 void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute); 1213 1214 /** 1215 * Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, MINUTE, and SECOND. 1216 * Other field values are retained; call clear() first if this is not desired. 1217 * 1218 * @param year The value used to set the YEAR time field. 1219 * @param month The value used to set the MONTH time field. Month value is 1220 * 0-based. E.g., 0 for January. 1221 * @param date The value used to set the DATE time field. 1222 * @param hour The value used to set the HOUR_OF_DAY time field. 1223 * @param minute The value used to set the MINUTE time field. 1224 * @param second The value used to set the SECOND time field. 1225 * @stable ICU 2.0 1226 */ 1227 void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute, int32_t second); 1228 1229 /** 1230 * Clears the values of all the time fields, making them both unset and assigning 1231 * them a value of zero. The field values will be determined during the next 1232 * resolving of time into time fields. 1233 * @stable ICU 2.0 1234 */ 1235 void clear(void); 1236 1237 /** 1238 * Clears the value in the given time field, both making it unset and assigning it a 1239 * value of zero. This field value will be determined during the next resolving of 1240 * time into time fields. Clearing UCAL_ORDINAL_MONTH or UCAL_MONTH will 1241 * clear both fields. 1242 * 1243 * @param field The time field to be cleared. 1244 * @stable ICU 2.6. 1245 */ 1246 void clear(UCalendarDateFields field); 1247 1248 /** 1249 * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. This method is to 1250 * implement a simple version of RTTI, since not all C++ compilers support genuine 1251 * RTTI. Polymorphic operator==() and clone() methods call this method. 1252 * <P> 1253 * Concrete subclasses of Calendar must implement getDynamicClassID() and also a 1254 * static method and data member: 1255 * 1256 * static UClassID getStaticClassID() { return (UClassID)&fgClassID; } 1257 * static char fgClassID; 1258 * 1259 * @return The class ID for this object. All objects of a given class have the 1260 * same class ID. Objects of other classes have different class IDs. 1261 * @stable ICU 2.0 1262 */ 1263 virtual UClassID getDynamicClassID(void) const override = 0; 1264 1265 /** 1266 * Returns the calendar type name string for this Calendar object. 1267 * The returned string is the legacy ICU calendar attribute value, 1268 * for example, "gregorian" or "japanese". 1269 * 1270 * See type="old type name" for the calendar attribute of locale IDs 1271 * at http://www.unicode.org/reports/tr35/#Key_Type_Definitions 1272 * 1273 * Sample code for getting the LDML/BCP 47 calendar key value: 1274 * \code 1275 * const char *calType = cal->getType(); 1276 * if (0 == strcmp(calType, "unknown")) { 1277 * // deal with unknown calendar type 1278 * } else { 1279 * string localeID("root@calendar="); 1280 * localeID.append(calType); 1281 * char langTag[100]; 1282 * UErrorCode errorCode = U_ZERO_ERROR; 1283 * int32_t length = uloc_toLanguageTag(localeID.c_str(), langTag, (int32_t)sizeof(langTag), true, &errorCode); 1284 * if (U_FAILURE(errorCode)) { 1285 * // deal with errors & overflow 1286 * } 1287 * string lang(langTag, length); 1288 * size_t caPos = lang.find("-ca-"); 1289 * lang.erase(0, caPos + 4); 1290 * // lang now contains the LDML calendar type 1291 * } 1292 * \endcode 1293 * 1294 * @return legacy calendar type name string 1295 * @stable ICU 49 1296 */ 1297 virtual const char * getType() const = 0; 1298 1299 /** 1300 * Returns whether the given day of the week is a weekday, a weekend day, 1301 * or a day that transitions from one to the other, for the locale and 1302 * calendar system associated with this Calendar (the locale's region is 1303 * often the most determinant factor). If a transition occurs at midnight, 1304 * then the days before and after the transition will have the 1305 * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time 1306 * other than midnight, then the day of the transition will have 1307 * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the 1308 * method getWeekendTransition() will return the point of 1309 * transition. 1310 * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY). 1311 * @param status The error code for the operation. 1312 * @return The UCalendarWeekdayType for the day of the week. 1313 * @stable ICU 4.4 1314 */ 1315 virtual UCalendarWeekdayType getDayOfWeekType(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const; 1316 1317 /** 1318 * Returns the time during the day at which the weekend begins or ends in 1319 * this calendar system. If getDayOfWeekType() returns UCAL_WEEKEND_ONSET 1320 * for the specified dayOfWeek, return the time at which the weekend begins. 1321 * If getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek, 1322 * return the time at which the weekend ends. If getDayOfWeekType() returns 1323 * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition 1324 * (U_ILLEGAL_ARGUMENT_ERROR). 1325 * @param dayOfWeek The day of the week for which the weekend transition time is 1326 * desired (UCAL_SUNDAY..UCAL_SATURDAY). 1327 * @param status The error code for the operation. 1328 * @return The milliseconds after midnight at which the weekend begins or ends. 1329 * @stable ICU 4.4 1330 */ 1331 virtual int32_t getWeekendTransition(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const; 1332 1333 /** 1334 * Returns true if the given UDate is in the weekend in 1335 * this calendar system. 1336 * @param date The UDate in question. 1337 * @param status The error code for the operation. 1338 * @return true if the given UDate is in the weekend in 1339 * this calendar system, false otherwise. 1340 * @stable ICU 4.4 1341 */ 1342 virtual UBool isWeekend(UDate date, UErrorCode &status) const; 1343 1344 /** 1345 * Returns true if this Calendar's current date-time is in the weekend in 1346 * this calendar system. 1347 * @return true if this Calendar's current date-time is in the weekend in 1348 * this calendar system, false otherwise. 1349 * @stable ICU 4.4 1350 */ 1351 virtual UBool isWeekend(void) const; 1352 1353 #ifndef U_FORCE_HIDE_DRAFT_API 1354 /** 1355 * Returns true if the date is in a leap year. Recalculate the current time 1356 * field values if the time value has been changed by a call to * setTime(). 1357 * This method is semantically const, but may alter the object in memory. 1358 * A "leap year" is a year that contains more days than other years (for 1359 * solar or lunar calendars) or more months than other years (for lunisolar 1360 * calendars like Hebrew or Chinese), as defined in the ECMAScript Temporal 1361 * proposal. 1362 * 1363 * @param status ICU Error Code 1364 * @return True if the date in the fields is in a Temporal proposal 1365 * defined leap year. False otherwise. 1366 * @draft ICU 73 1367 */ 1368 virtual bool inTemporalLeapYear(UErrorCode& status) const; 1369 1370 /** 1371 * Gets The Temporal monthCode value corresponding to the month for the date. 1372 * The value is a string identifier that starts with the literal grapheme 1373 * "M" followed by two graphemes representing the zero-padded month number 1374 * of the current month in a normal (non-leap) year and suffixed by an 1375 * optional literal grapheme "L" if this is a leap month in a lunisolar 1376 * calendar. The 25 possible values are "M01" .. "M13" and "M01L" .. "M12L". 1377 * For the Hebrew calendar, the values are "M01" .. "M12" for non-leap year, and 1378 * "M01" .. "M05", "M05L", "M06" .. "M12" for leap year. 1379 * For the Chinese calendar, the values are "M01" .. "M12" for non-leap year and 1380 * in leap year with another monthCode in "M01L" .. "M12L". 1381 * For Coptic and Ethiopian calendar, the Temporal monthCode values for any 1382 * years are "M01" to "M13". 1383 * 1384 * @param status ICU Error Code 1385 * @return One of 25 possible strings in {"M01".."M13", "M01L".."M12L"}. 1386 * @draft ICU 73 1387 */ 1388 virtual const char* getTemporalMonthCode(UErrorCode& status) const; 1389 1390 /** 1391 * Sets The Temporal monthCode which is a string identifier that starts 1392 * with the literal grapheme "M" followed by two graphemes representing 1393 * the zero-padded month number of the current month in a normal 1394 * (non-leap) year and suffixed by an optional literal grapheme "L" if this 1395 * is a leap month in a lunisolar calendar. The 25 possible values are 1396 * "M01" .. "M13" and "M01L" .. "M12L". For Hebrew calendar, the values are 1397 * "M01" .. "M12" for non-leap years, and "M01" .. "M05", "M05L", "M06" 1398 * .. "M12" for leap year. 1399 * For the Chinese calendar, the values are "M01" .. "M12" for non-leap year and 1400 * in leap year with another monthCode in "M01L" .. "M12L". 1401 * For Coptic and Ethiopian calendar, the Temporal monthCode values for any 1402 * years are "M01" to "M13". 1403 * 1404 * @param temporalMonth The value to be set for temporal monthCode. 1405 * @param status ICU Error Code 1406 * 1407 * @draft ICU 73 1408 */ 1409 virtual void setTemporalMonthCode(const char* temporalMonth, UErrorCode& status); 1410 1411 #endif // U_FORCE_HIDE_DRAFT_API 1412 1413 protected: 1414 1415 /** 1416 * Constructs a Calendar with the default time zone as returned by 1417 * TimeZone::createInstance(), and the default locale. 1418 * 1419 * @param success Indicates the status of Calendar object construction. Returns 1420 * U_ZERO_ERROR if constructed successfully. 1421 * @stable ICU 2.0 1422 */ 1423 Calendar(UErrorCode& success); 1424 1425 /** 1426 * Copy constructor 1427 * 1428 * @param source Calendar object to be copied from 1429 * @stable ICU 2.0 1430 */ 1431 Calendar(const Calendar& source); 1432 1433 /** 1434 * Default assignment operator 1435 * 1436 * @param right Calendar object to be copied 1437 * @stable ICU 2.0 1438 */ 1439 Calendar& operator=(const Calendar& right); 1440 1441 /** 1442 * Constructs a Calendar with the given time zone and locale. Clients are no longer 1443 * responsible for deleting the given time zone object after it's adopted. 1444 * 1445 * @param zone The given time zone. 1446 * @param aLocale The given locale. 1447 * @param success Indicates the status of Calendar object construction. Returns 1448 * U_ZERO_ERROR if constructed successfully. 1449 * @stable ICU 2.0 1450 */ 1451 Calendar(TimeZone* zone, const Locale& aLocale, UErrorCode& success); 1452 1453 /** 1454 * Constructs a Calendar with the given time zone and locale. 1455 * 1456 * @param zone The given time zone. 1457 * @param aLocale The given locale. 1458 * @param success Indicates the status of Calendar object construction. Returns 1459 * U_ZERO_ERROR if constructed successfully. 1460 * @stable ICU 2.0 1461 */ 1462 Calendar(const TimeZone& zone, const Locale& aLocale, UErrorCode& success); 1463 1464 /** 1465 * Converts Calendar's time field values to GMT as milliseconds. 1466 * 1467 * @param status Output param set to success/failure code on exit. If any value 1468 * previously set in the time field is invalid or restricted by 1469 * leniency, this will be set to an error status. 1470 * @stable ICU 2.0 1471 */ 1472 virtual void computeTime(UErrorCode& status); 1473 1474 /** 1475 * Converts GMT as milliseconds to time field values. This allows you to sync up the 1476 * time field values with a new time that is set for the calendar. This method 1477 * does NOT recompute the time first; to recompute the time, then the fields, use 1478 * the method complete(). 1479 * 1480 * @param status Output param set to success/failure code on exit. If any value 1481 * previously set in the time field is invalid or restricted by 1482 * leniency, this will be set to an error status. 1483 * @stable ICU 2.0 1484 */ 1485 virtual void computeFields(UErrorCode& status); 1486 1487 /** 1488 * Gets this Calendar's current time as a long. 1489 * 1490 * @param status Output param set to success/failure code on exit. If any value 1491 * previously set in the time field is invalid or restricted by 1492 * leniency, this will be set to an error status. 1493 * @return the current time as UTC milliseconds from the epoch. 1494 * @stable ICU 2.0 1495 */ 1496 double getTimeInMillis(UErrorCode& status) const; 1497 1498 /** 1499 * Sets this Calendar's current time from the given long value. 1500 * @param millis the new time in UTC milliseconds from the epoch. 1501 * @param status Output param set to success/failure code on exit. If any value 1502 * previously set in the time field is invalid or restricted by 1503 * leniency, this will be set to an error status. 1504 * @stable ICU 2.0 1505 */ 1506 void setTimeInMillis( double millis, UErrorCode& status ); 1507 1508 /** 1509 * Recomputes the current time from currently set fields, and then fills in any 1510 * unset fields in the time field list. 1511 * 1512 * @param status Output param set to success/failure code on exit. If any value 1513 * previously set in the time field is invalid or restricted by 1514 * leniency, this will be set to an error status. 1515 * @stable ICU 2.0 1516 */ 1517 void complete(UErrorCode& status); 1518 1519 #ifndef U_HIDE_DEPRECATED_API 1520 /** 1521 * Gets the value for a given time field. Subclasses can use this function to get 1522 * field values without forcing recomputation of time. 1523 * 1524 * @param field The given time field. 1525 * @return The value for the given time field. 1526 * @deprecated ICU 2.6. Use internalGet(UCalendarDateFields field) instead. 1527 */ 1528 inline int32_t internalGet(EDateFields field) const {return fFields[field];} 1529 #endif /* U_HIDE_DEPRECATED_API */ 1530 1531 #ifndef U_HIDE_INTERNAL_API 1532 /** 1533 * Gets the value for a given time field. Subclasses can use this function to get 1534 * field values without forcing recomputation of time. If the field's stamp is UNSET, 1535 * the defaultValue is used. 1536 * 1537 * @param field The given time field. 1538 * @param defaultValue a default value used if the field is unset. 1539 * @return The value for the given time field. 1540 * @internal 1541 */ 1542 inline int32_t internalGet(UCalendarDateFields field, int32_t defaultValue) const {return fStamp[field]>kUnset ? fFields[field] : defaultValue;} 1543 1544 /** 1545 * Gets the value for a given time field. Subclasses can use this function to get 1546 * field values without forcing recomputation of time. 1547 * 1548 * @param field The given time field. 1549 * @return The value for the given time field. 1550 * @internal 1551 */ 1552 inline int32_t internalGet(UCalendarDateFields field) const {return fFields[field];} 1553 #endif /* U_HIDE_INTERNAL_API */ 1554 1555 /** 1556 * Use this function instead of internalGet(UCAL_MONTH). The implementation 1557 * check the timestamp of UCAL_MONTH and UCAL_ORDINAL_MONTH and use the 1558 * one set later. The subclass should override it to conver the value of UCAL_ORDINAL_MONTH 1559 * to UCAL_MONTH correctly if UCAL_ORDINAL_MONTH has higher priority. 1560 * 1561 * @return The value for the UCAL_MONTH. 1562 * @internal 1563 */ 1564 virtual int32_t internalGetMonth() const; 1565 1566 /** 1567 * Use this function instead of internalGet(UCAL_MONTH, defaultValue). The implementation 1568 * check the timestamp of UCAL_MONTH and UCAL_ORDINAL_MONTH and use the 1569 * one set later. The subclass should override it to conver the value of UCAL_ORDINAL_MONTH 1570 * to UCAL_MONTH correctly if UCAL_ORDINAL_MONTH has higher priority. 1571 * 1572 * @param defaultValue a default value used if the UCAL_MONTH and 1573 * UCAL_ORDINAL are both unset. 1574 * @return The value for the UCAL_MONTH. 1575 * @internal 1576 */ 1577 virtual int32_t internalGetMonth(int32_t defaultValue) const; 1578 1579 #ifndef U_HIDE_DEPRECATED_API 1580 /** 1581 * Sets the value for a given time field. This is a fast internal method for 1582 * subclasses. It does not affect the areFieldsInSync, isTimeSet, or areAllFieldsSet 1583 * flags. 1584 * 1585 * @param field The given time field. 1586 * @param value The value for the given time field. 1587 * @deprecated ICU 2.6. Use internalSet(UCalendarDateFields field, int32_t value) instead. 1588 */ 1589 void internalSet(EDateFields field, int32_t value); 1590 #endif /* U_HIDE_DEPRECATED_API */ 1591 1592 /** 1593 * Sets the value for a given time field. This is a fast internal method for 1594 * subclasses. It does not affect the areFieldsInSync, isTimeSet, or areAllFieldsSet 1595 * flags. 1596 * 1597 * @param field The given time field. 1598 * @param value The value for the given time field. 1599 * @stable ICU 2.6. 1600 */ 1601 inline void internalSet(UCalendarDateFields field, int32_t value); 1602 1603 /** 1604 * Prepare this calendar for computing the actual minimum or maximum. 1605 * This method modifies this calendar's fields; it is called on a 1606 * temporary calendar. 1607 * @internal 1608 */ 1609 virtual void prepareGetActual(UCalendarDateFields field, UBool isMinimum, UErrorCode &status); 1610 1611 /** 1612 * Limit enums. Not in sync with UCalendarLimitType (refers to internal fields). 1613 * @internal 1614 */ 1615 enum ELimitType { 1616 #ifndef U_HIDE_INTERNAL_API 1617 UCAL_LIMIT_MINIMUM = 0, 1618 UCAL_LIMIT_GREATEST_MINIMUM, 1619 UCAL_LIMIT_LEAST_MAXIMUM, 1620 UCAL_LIMIT_MAXIMUM, 1621 UCAL_LIMIT_COUNT 1622 #endif /* U_HIDE_INTERNAL_API */ 1623 }; 1624 1625 /** 1626 * Subclass API for defining limits of different types. 1627 * Subclasses must implement this method to return limits for the 1628 * following fields: 1629 * 1630 * <pre>UCAL_ERA 1631 * UCAL_YEAR 1632 * UCAL_MONTH 1633 * UCAL_WEEK_OF_YEAR 1634 * UCAL_WEEK_OF_MONTH 1635 * UCAL_DATE (DAY_OF_MONTH on Java) 1636 * UCAL_DAY_OF_YEAR 1637 * UCAL_DAY_OF_WEEK_IN_MONTH 1638 * UCAL_YEAR_WOY 1639 * UCAL_EXTENDED_YEAR</pre> 1640 * 1641 * @param field one of the above field numbers 1642 * @param limitType one of <code>MINIMUM</code>, <code>GREATEST_MINIMUM</code>, 1643 * <code>LEAST_MAXIMUM</code>, or <code>MAXIMUM</code> 1644 * @internal 1645 */ 1646 virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const = 0; 1647 1648 /** 1649 * Return a limit for a field. 1650 * @param field the field, from <code>0..UCAL_MAX_FIELD</code> 1651 * @param limitType the type specifier for the limit 1652 * @see #ELimitType 1653 * @internal 1654 */ 1655 virtual int32_t getLimit(UCalendarDateFields field, ELimitType limitType) const; 1656 1657 /** 1658 * Return the Julian day number of day before the first day of the 1659 * given month in the given extended year. Subclasses should override 1660 * this method to implement their calendar system. 1661 * @param eyear the extended year 1662 * @param month the zero-based month, or 0 if useMonth is false 1663 * @param useMonth if false, compute the day before the first day of 1664 * the given year, otherwise, compute the day before the first day of 1665 * the given month 1666 * @return the Julian day number of the day before the first 1667 * day of the given month and year 1668 * @internal 1669 */ 1670 virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month, 1671 UBool useMonth) const = 0; 1672 1673 /** 1674 * Return the number of days in the given month of the given extended 1675 * year of this calendar system. Subclasses should override this 1676 * method if they can provide a more correct or more efficient 1677 * implementation than the default implementation in Calendar. 1678 * @internal 1679 */ 1680 virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const ; 1681 1682 /** 1683 * Return the number of days in the given extended year of this 1684 * calendar system. Subclasses should override this method if they can 1685 * provide a more correct or more efficient implementation than the 1686 * default implementation in Calendar. 1687 * @stable ICU 2.0 1688 */ 1689 virtual int32_t handleGetYearLength(int32_t eyear) const; 1690 1691 1692 /** 1693 * Return the extended year defined by the current fields. This will 1694 * use the UCAL_EXTENDED_YEAR field or the UCAL_YEAR and supra-year fields (such 1695 * as UCAL_ERA) specific to the calendar system, depending on which set of 1696 * fields is newer. 1697 * @return the extended year 1698 * @internal 1699 */ 1700 virtual int32_t handleGetExtendedYear() = 0; 1701 1702 /** 1703 * Subclasses may override this. This method calls 1704 * handleGetMonthLength() to obtain the calendar-specific month 1705 * length. 1706 * @param bestField which field to use to calculate the date 1707 * @return julian day specified by calendar fields. 1708 * @internal 1709 */ 1710 virtual int32_t handleComputeJulianDay(UCalendarDateFields bestField); 1711 1712 /** 1713 * Subclasses must override this to convert from week fields 1714 * (YEAR_WOY and WEEK_OF_YEAR) to an extended year in the case 1715 * where YEAR, EXTENDED_YEAR are not set. 1716 * The Calendar implementation assumes yearWoy is in extended gregorian form 1717 * @return the extended year, UCAL_EXTENDED_YEAR 1718 * @internal 1719 */ 1720 virtual int32_t handleGetExtendedYearFromWeekFields(int32_t yearWoy, int32_t woy); 1721 1722 /** 1723 * Validate a single field of this calendar. Subclasses should 1724 * override this method to validate any calendar-specific fields. 1725 * Generic fields can be handled by `Calendar::validateField()`. 1726 * @internal 1727 */ 1728 virtual void validateField(UCalendarDateFields field, UErrorCode &status); 1729 1730 #ifndef U_HIDE_INTERNAL_API 1731 /** 1732 * Compute the Julian day from fields. Will determine whether to use 1733 * the JULIAN_DAY field directly, or other fields. 1734 * @return the julian day 1735 * @internal 1736 */ 1737 int32_t computeJulianDay(); 1738 1739 /** 1740 * Compute the milliseconds in the day from the fields. This is a 1741 * value from 0 to 23:59:59.999 inclusive, unless fields are out of 1742 * range, in which case it can be an arbitrary value. This value 1743 * reflects local zone wall time. 1744 * @internal 1745 */ 1746 double computeMillisInDay(); 1747 1748 /** 1749 * This method can assume EXTENDED_YEAR has been set. 1750 * @param millis milliseconds of the date fields 1751 * @param millisInDay milliseconds of the time fields; may be out 1752 * or range. 1753 * @param ec Output param set to failure code on function return 1754 * when this function fails. 1755 * @internal 1756 */ 1757 int32_t computeZoneOffset(double millis, double millisInDay, UErrorCode &ec); 1758 1759 1760 /** 1761 * Determine the best stamp in a range. 1762 * @param start first enum to look at 1763 * @param end last enum to look at 1764 * @param bestSoFar stamp prior to function call 1765 * @return the stamp value of the best stamp 1766 * @internal 1767 */ 1768 int32_t newestStamp(UCalendarDateFields start, UCalendarDateFields end, int32_t bestSoFar) const; 1769 1770 /** 1771 * Marker for end of resolve set (row or group). Value for field resolution tables. 1772 * 1773 * @see #resolveFields 1774 * @internal 1775 */ 1776 static constexpr int32_t kResolveSTOP = -1; 1777 /** 1778 * Value to be bitwised "ORed" against resolve table field values for remapping. 1779 * Example: (UCAL_DATE | kResolveRemap) in 1st column will cause 'UCAL_DATE' to be returned, 1780 * but will not examine the value of UCAL_DATE. 1781 * Value for field resolution tables. 1782 * 1783 * @see #resolveFields 1784 * @internal 1785 */ 1786 static constexpr int32_t kResolveRemap = 32; 1787 1788 /** 1789 * Precedence table for Dates 1790 * @see #resolveFields 1791 * @internal 1792 */ 1793 static const UFieldResolutionTable kDatePrecedence[]; 1794 1795 /** 1796 * Precedence table for Year 1797 * @see #resolveFields 1798 * @internal 1799 */ 1800 static const UFieldResolutionTable kYearPrecedence[]; 1801 1802 /** 1803 * Precedence table for Day of Week 1804 * @see #resolveFields 1805 * @internal 1806 */ 1807 static const UFieldResolutionTable kDOWPrecedence[]; 1808 1809 /** 1810 * Precedence table for Months 1811 * @see #resolveFields 1812 * @internal 1813 */ 1814 static const UFieldResolutionTable kMonthPrecedence[]; 1815 1816 /** 1817 * Given a precedence table, return the newest field combination in 1818 * the table, or UCAL_FIELD_COUNT if none is found. 1819 * 1820 * <p>The precedence table is a 3-dimensional array of integers. It 1821 * may be thought of as an array of groups. Each group is an array of 1822 * lines. Each line is an array of field numbers. Within a line, if 1823 * all fields are set, then the time stamp of the line is taken to be 1824 * the stamp of the most recently set field. If any field of a line is 1825 * unset, then the line fails to match. Within a group, the line with 1826 * the newest time stamp is selected. The first field of the line is 1827 * returned to indicate which line matched. 1828 * 1829 * <p>In some cases, it may be desirable to map a line to field that 1830 * whose stamp is NOT examined. For example, if the best field is 1831 * DAY_OF_WEEK then the DAY_OF_WEEK_IN_MONTH algorithm may be used. In 1832 * order to do this, insert the value <code>kResolveRemap | F</code> at 1833 * the start of the line, where <code>F</code> is the desired return 1834 * field value. This field will NOT be examined; it only determines 1835 * the return value if the other fields in the line are the newest. 1836 * 1837 * <p>If all lines of a group contain at least one unset field, then no 1838 * line will match, and the group as a whole will fail to match. In 1839 * that case, the next group will be processed. If all groups fail to 1840 * match, then UCAL_FIELD_COUNT is returned. 1841 * @internal 1842 */ 1843 UCalendarDateFields resolveFields(const UFieldResolutionTable *precedenceTable) const; 1844 #endif /* U_HIDE_INTERNAL_API */ 1845 1846 1847 /** 1848 * @internal 1849 */ 1850 virtual const UFieldResolutionTable* getFieldResolutionTable() const; 1851 1852 #ifndef U_HIDE_INTERNAL_API 1853 /** 1854 * Return the field that is newer, either defaultField, or 1855 * alternateField. If neither is newer or neither is set, return defaultField. 1856 * @internal 1857 */ 1858 UCalendarDateFields newerField(UCalendarDateFields defaultField, UCalendarDateFields alternateField) const; 1859 #endif /* U_HIDE_INTERNAL_API */ 1860 1861 1862 private: 1863 /** 1864 * Helper function for calculating limits by trial and error 1865 * @param field The field being investigated 1866 * @param startValue starting (least max) value of field 1867 * @param endValue ending (greatest max) value of field 1868 * @param status return type 1869 * @internal (private) 1870 */ 1871 int32_t getActualHelper(UCalendarDateFields field, int32_t startValue, int32_t endValue, UErrorCode &status) const; 1872 1873 1874 protected: 1875 /** 1876 * The flag which indicates if the current time is set in the calendar. 1877 * @stable ICU 2.0 1878 */ 1879 UBool fIsTimeSet; 1880 1881 /** 1882 * True if the fields are in sync with the currently set time of this Calendar. 1883 * If false, then the next attempt to get the value of a field will 1884 * force a recomputation of all fields from the current value of the time 1885 * field. 1886 * <P> 1887 * This should really be named areFieldsInSync, but the old name is retained 1888 * for backward compatibility. 1889 * @stable ICU 2.0 1890 */ 1891 UBool fAreFieldsSet; 1892 1893 /** 1894 * True if all of the fields have been set. This is initially false, and set to 1895 * true by computeFields(). 1896 * @stable ICU 2.0 1897 */ 1898 UBool fAreAllFieldsSet; 1899 1900 /** 1901 * True if all fields have been virtually set, but have not yet been 1902 * computed. This occurs only in setTimeInMillis(). A calendar set 1903 * to this state will compute all fields from the time if it becomes 1904 * necessary, but otherwise will delay such computation. 1905 * @stable ICU 3.0 1906 */ 1907 UBool fAreFieldsVirtuallySet; 1908 1909 /** 1910 * Get the current time without recomputing. 1911 * 1912 * @return the current time without recomputing. 1913 * @stable ICU 2.0 1914 */ 1915 UDate internalGetTime(void) const { return fTime; } 1916 1917 /** 1918 * Set the current time without affecting flags or fields. 1919 * 1920 * @param time The time to be set 1921 * @return the current time without recomputing. 1922 * @stable ICU 2.0 1923 */ 1924 void internalSetTime(UDate time) { fTime = time; } 1925 1926 /** 1927 * The time fields containing values into which the millis is computed. 1928 * @stable ICU 2.0 1929 */ 1930 int32_t fFields[UCAL_FIELD_COUNT]; 1931 1932 #ifndef U_FORCE_HIDE_DEPRECATED_API 1933 /** 1934 * The flags which tell if a specified time field for the calendar is set. 1935 * @deprecated ICU 2.8 use (fStamp[n]!=kUnset) 1936 */ 1937 UBool fIsSet[UCAL_FIELD_COUNT]; 1938 #endif // U_FORCE_HIDE_DEPRECATED_API 1939 1940 /** Special values of stamp[] 1941 * @stable ICU 2.0 1942 */ 1943 enum { 1944 kUnset = 0, 1945 kInternallySet, 1946 kMinimumUserStamp 1947 }; 1948 1949 /** 1950 * Pseudo-time-stamps which specify when each field was set. There 1951 * are two special values, UNSET and INTERNALLY_SET. Values from 1952 * MINIMUM_USER_SET to Integer.MAX_VALUE are legal user set values. 1953 * @stable ICU 2.0 1954 */ 1955 int32_t fStamp[UCAL_FIELD_COUNT]; 1956 1957 /** 1958 * Subclasses may override this method to compute several fields 1959 * specific to each calendar system. These are: 1960 * 1961 * <ul><li>ERA 1962 * <li>YEAR 1963 * <li>MONTH 1964 * <li>DAY_OF_MONTH 1965 * <li>DAY_OF_YEAR 1966 * <li>EXTENDED_YEAR</ul> 1967 * 1968 * Subclasses can refer to the DAY_OF_WEEK and DOW_LOCAL fields, which 1969 * will be set when this method is called. Subclasses can also call 1970 * the getGregorianXxx() methods to obtain Gregorian calendar 1971 * equivalents for the given Julian day. 1972 * 1973 * <p>In addition, subclasses should compute any subclass-specific 1974 * fields, that is, fields from BASE_FIELD_COUNT to 1975 * getFieldCount() - 1. 1976 * 1977 * <p>The default implementation in <code>Calendar</code> implements 1978 * a pure proleptic Gregorian calendar. 1979 * @internal 1980 */ 1981 virtual void handleComputeFields(int32_t julianDay, UErrorCode &status); 1982 1983 #ifndef U_HIDE_INTERNAL_API 1984 /** 1985 * Return the extended year on the Gregorian calendar as computed by 1986 * <code>computeGregorianFields()</code>. 1987 * @internal 1988 */ 1989 int32_t getGregorianYear() const { 1990 return fGregorianYear; 1991 } 1992 1993 /** 1994 * Return the month (0-based) on the Gregorian calendar as computed by 1995 * <code>computeGregorianFields()</code>. 1996 * @internal 1997 */ 1998 int32_t getGregorianMonth() const { 1999 return fGregorianMonth; 2000 } 2001 2002 /** 2003 * Return the day of year (1-based) on the Gregorian calendar as 2004 * computed by <code>computeGregorianFields()</code>. 2005 * @internal 2006 */ 2007 int32_t getGregorianDayOfYear() const { 2008 return fGregorianDayOfYear; 2009 } 2010 2011 /** 2012 * Return the day of month (1-based) on the Gregorian calendar as 2013 * computed by <code>computeGregorianFields()</code>. 2014 * @internal 2015 */ 2016 int32_t getGregorianDayOfMonth() const { 2017 return fGregorianDayOfMonth; 2018 } 2019 #endif /* U_HIDE_INTERNAL_API */ 2020 2021 /** 2022 * Called by computeJulianDay. Returns the default month (0-based) for the year, 2023 * taking year and era into account. Defaults to 0 for Gregorian, which doesn't care. 2024 * @param eyear The extended year 2025 * @internal 2026 */ 2027 virtual int32_t getDefaultMonthInYear(int32_t eyear) ; 2028 2029 2030 /** 2031 * Called by computeJulianDay. Returns the default day (1-based) for the month, 2032 * taking currently-set year and era into account. Defaults to 1 for Gregorian. 2033 * @param eyear the extended year 2034 * @param month the month in the year 2035 * @internal 2036 */ 2037 virtual int32_t getDefaultDayInMonth(int32_t eyear, int32_t month); 2038 2039 //------------------------------------------------------------------------- 2040 // Protected utility methods for use by subclasses. These are very handy 2041 // for implementing add, roll, and computeFields. 2042 //------------------------------------------------------------------------- 2043 2044 /** 2045 * Adjust the specified field so that it is within 2046 * the allowable range for the date to which this calendar is set. 2047 * For example, in a Gregorian calendar pinning the {@link #UCalendarDateFields DAY_OF_MONTH} 2048 * field for a calendar set to April 31 would cause it to be set 2049 * to April 30. 2050 * <p> 2051 * <b>Subclassing:</b> 2052 * <br> 2053 * This utility method is intended for use by subclasses that need to implement 2054 * their own overrides of {@link #roll roll} and {@link #add add}. 2055 * <p> 2056 * <b>Note:</b> 2057 * <code>pinField</code> is implemented in terms of 2058 * {@link #getActualMinimum getActualMinimum} 2059 * and {@link #getActualMaximum getActualMaximum}. If either of those methods uses 2060 * a slow, iterative algorithm for a particular field, it would be 2061 * unwise to attempt to call <code>pinField</code> for that field. If you 2062 * really do need to do so, you should override this method to do 2063 * something more efficient for that field. 2064 * <p> 2065 * @param field The calendar field whose value should be pinned. 2066 * @param status Output param set to failure code on function return 2067 * when this function fails. 2068 * 2069 * @see #getActualMinimum 2070 * @see #getActualMaximum 2071 * @stable ICU 2.0 2072 */ 2073 virtual void pinField(UCalendarDateFields field, UErrorCode& status); 2074 2075 /** 2076 * Return the week number of a day, within a period. This may be the week number in 2077 * a year or the week number in a month. Usually this will be a value >= 1, but if 2078 * some initial days of the period are excluded from week 1, because 2079 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} is > 1, then 2080 * the week number will be zero for those 2081 * initial days. This method requires the day number and day of week for some 2082 * known date in the period in order to determine the day of week 2083 * on the desired day. 2084 * <p> 2085 * <b>Subclassing:</b> 2086 * <br> 2087 * This method is intended for use by subclasses in implementing their 2088 * {@link #computeTime computeTime} and/or {@link #computeFields computeFields} methods. 2089 * It is often useful in {@link #getActualMinimum getActualMinimum} and 2090 * {@link #getActualMaximum getActualMaximum} as well. 2091 * <p> 2092 * This variant is handy for computing the week number of some other 2093 * day of a period (often the first or last day of the period) when its day 2094 * of the week is not known but the day number and day of week for some other 2095 * day in the period (e.g. the current date) <em>is</em> known. 2096 * <p> 2097 * @param desiredDay The {@link #UCalendarDateFields DAY_OF_YEAR} or 2098 * {@link #UCalendarDateFields DAY_OF_MONTH} whose week number is desired. 2099 * Should be 1 for the first day of the period. 2100 * 2101 * @param dayOfPeriod The {@link #UCalendarDateFields DAY_OF_YEAR} 2102 * or {@link #UCalendarDateFields DAY_OF_MONTH} for a day in the period whose 2103 * {@link #UCalendarDateFields DAY_OF_WEEK} is specified by the 2104 * <code>knownDayOfWeek</code> parameter. 2105 * Should be 1 for first day of period. 2106 * 2107 * @param dayOfWeek The {@link #UCalendarDateFields DAY_OF_WEEK} for the day 2108 * corresponding to the <code>knownDayOfPeriod</code> parameter. 2109 * 1-based with 1=Sunday. 2110 * 2111 * @return The week number (one-based), or zero if the day falls before 2112 * the first week because 2113 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} 2114 * is more than one. 2115 * 2116 * @stable ICU 2.8 2117 */ 2118 int32_t weekNumber(int32_t desiredDay, int32_t dayOfPeriod, int32_t dayOfWeek); 2119 2120 2121 #ifndef U_HIDE_INTERNAL_API 2122 /** 2123 * Return the week number of a day, within a period. This may be the week number in 2124 * a year, or the week number in a month. Usually this will be a value >= 1, but if 2125 * some initial days of the period are excluded from week 1, because 2126 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} is > 1, 2127 * then the week number will be zero for those 2128 * initial days. This method requires the day of week for the given date in order to 2129 * determine the result. 2130 * <p> 2131 * <b>Subclassing:</b> 2132 * <br> 2133 * This method is intended for use by subclasses in implementing their 2134 * {@link #computeTime computeTime} and/or {@link #computeFields computeFields} methods. 2135 * It is often useful in {@link #getActualMinimum getActualMinimum} and 2136 * {@link #getActualMaximum getActualMaximum} as well. 2137 * <p> 2138 * @param dayOfPeriod The {@link #UCalendarDateFields DAY_OF_YEAR} or 2139 * {@link #UCalendarDateFields DAY_OF_MONTH} whose week number is desired. 2140 * Should be 1 for the first day of the period. 2141 * 2142 * @param dayOfWeek The {@link #UCalendarDateFields DAY_OF_WEEK} for the day 2143 * corresponding to the <code>dayOfPeriod</code> parameter. 2144 * 1-based with 1=Sunday. 2145 * 2146 * @return The week number (one-based), or zero if the day falls before 2147 * the first week because 2148 * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} 2149 * is more than one. 2150 * @internal 2151 */ 2152 inline int32_t weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek); 2153 2154 /** 2155 * returns the local DOW, valid range 0..6 2156 * @internal 2157 */ 2158 int32_t getLocalDOW(); 2159 #endif /* U_HIDE_INTERNAL_API */ 2160 2161 private: 2162 2163 /** 2164 * The next available value for fStamp[] 2165 */ 2166 int32_t fNextStamp;// = MINIMUM_USER_STAMP; 2167 2168 /** 2169 * Recalculates the time stamp array (fStamp). 2170 * Resets fNextStamp to lowest next stamp value. 2171 */ 2172 void recalculateStamp(); 2173 2174 /** 2175 * The current time set for the calendar. 2176 */ 2177 UDate fTime; 2178 2179 /** 2180 * @see #setLenient 2181 */ 2182 UBool fLenient; 2183 2184 /** 2185 * Time zone affects the time calculation done by Calendar. Calendar subclasses use 2186 * the time zone data to produce the local time. Always set; never nullptr. 2187 */ 2188 TimeZone* fZone; 2189 2190 /** 2191 * Option for repeated wall time 2192 * @see #setRepeatedWallTimeOption 2193 */ 2194 UCalendarWallTimeOption fRepeatedWallTime; 2195 2196 /** 2197 * Option for skipped wall time 2198 * @see #setSkippedWallTimeOption 2199 */ 2200 UCalendarWallTimeOption fSkippedWallTime; 2201 2202 /** 2203 * Both firstDayOfWeek and minimalDaysInFirstWeek are locale-dependent. They are 2204 * used to figure out the week count for a specific date for a given locale. These 2205 * must be set when a Calendar is constructed. For example, in US locale, 2206 * firstDayOfWeek is SUNDAY; minimalDaysInFirstWeek is 1. They are used to figure 2207 * out the week count for a specific date for a given locale. These must be set when 2208 * a Calendar is constructed. 2209 */ 2210 UCalendarDaysOfWeek fFirstDayOfWeek; 2211 uint8_t fMinimalDaysInFirstWeek; 2212 UCalendarDaysOfWeek fWeekendOnset; 2213 int32_t fWeekendOnsetMillis; 2214 UCalendarDaysOfWeek fWeekendCease; 2215 int32_t fWeekendCeaseMillis; 2216 2217 /** 2218 * Sets firstDayOfWeek and minimalDaysInFirstWeek. Called at Calendar construction 2219 * time. 2220 * 2221 * @param desiredLocale The given locale. 2222 * @param type The calendar type identifier, e.g: gregorian, buddhist, etc. 2223 * @param success Indicates the status of setting the week count data from 2224 * the resource for the given locale. Returns U_ZERO_ERROR if 2225 * constructed successfully. 2226 */ 2227 void setWeekData(const Locale& desiredLocale, const char *type, UErrorCode& success); 2228 2229 /** 2230 * Recompute the time and update the status fields isTimeSet 2231 * and areFieldsSet. Callers should check isTimeSet and only 2232 * call this method if isTimeSet is false. 2233 * 2234 * @param status Output param set to success/failure code on exit. If any value 2235 * previously set in the time field is invalid or restricted by 2236 * leniency, this will be set to an error status. 2237 */ 2238 void updateTime(UErrorCode& status); 2239 2240 /** 2241 * The Gregorian year, as computed by computeGregorianFields() and 2242 * returned by getGregorianYear(). 2243 * @see #computeGregorianFields 2244 */ 2245 int32_t fGregorianYear; 2246 2247 /** 2248 * The Gregorian month, as computed by computeGregorianFields() and 2249 * returned by getGregorianMonth(). 2250 * @see #computeGregorianFields 2251 */ 2252 int32_t fGregorianMonth; 2253 2254 /** 2255 * The Gregorian day of the year, as computed by 2256 * computeGregorianFields() and returned by getGregorianDayOfYear(). 2257 * @see #computeGregorianFields 2258 */ 2259 int32_t fGregorianDayOfYear; 2260 2261 /** 2262 * The Gregorian day of the month, as computed by 2263 * computeGregorianFields() and returned by getGregorianDayOfMonth(). 2264 * @see #computeGregorianFields 2265 */ 2266 int32_t fGregorianDayOfMonth; 2267 2268 /* calculations */ 2269 2270 /** 2271 * Compute the Gregorian calendar year, month, and day of month from 2272 * the given Julian day. These values are not stored in fields, but in 2273 * member variables gregorianXxx. Also compute the DAY_OF_WEEK and 2274 * DOW_LOCAL fields. 2275 */ 2276 void computeGregorianAndDOWFields(int32_t julianDay, UErrorCode &ec); 2277 2278 protected: 2279 2280 /** 2281 * Compute the Gregorian calendar year, month, and day of month from the 2282 * Julian day. These values are not stored in fields, but in member 2283 * variables gregorianXxx. They are used for time zone computations and by 2284 * subclasses that are Gregorian derivatives. Subclasses may call this 2285 * method to perform a Gregorian calendar millis->fields computation. 2286 */ 2287 void computeGregorianFields(int32_t julianDay, UErrorCode &ec); 2288 2289 private: 2290 2291 /** 2292 * Compute the fields WEEK_OF_YEAR, YEAR_WOY, WEEK_OF_MONTH, 2293 * DAY_OF_WEEK_IN_MONTH, and DOW_LOCAL from EXTENDED_YEAR, YEAR, 2294 * DAY_OF_WEEK, and DAY_OF_YEAR. The latter fields are computed by the 2295 * subclass based on the calendar system. 2296 * 2297 * <p>The YEAR_WOY field is computed simplistically. It is equal to YEAR 2298 * most of the time, but at the year boundary it may be adjusted to YEAR-1 2299 * or YEAR+1 to reflect the overlap of a week into an adjacent year. In 2300 * this case, a simple increment or decrement is performed on YEAR, even 2301 * though this may yield an invalid YEAR value. For instance, if the YEAR 2302 * is part of a calendar system with an N-year cycle field CYCLE, then 2303 * incrementing the YEAR may involve incrementing CYCLE and setting YEAR 2304 * back to 0 or 1. This is not handled by this code, and in fact cannot be 2305 * simply handled without having subclasses define an entire parallel set of 2306 * fields for fields larger than or equal to a year. This additional 2307 * complexity is not warranted, since the intention of the YEAR_WOY field is 2308 * to support ISO 8601 notation, so it will typically be used with a 2309 * proleptic Gregorian calendar, which has no field larger than a year. 2310 */ 2311 void computeWeekFields(UErrorCode &ec); 2312 2313 2314 /** 2315 * Ensure that each field is within its valid range by calling {@link 2316 * #validateField(int, int&)} on each field that has been set. This method 2317 * should only be called if this calendar is not lenient. 2318 * @see #isLenient 2319 * @see #validateField(int, int&) 2320 */ 2321 void validateFields(UErrorCode &status); 2322 2323 /** 2324 * Validate a single field of this calendar given its minimum and 2325 * maximum allowed value. If the field is out of range, 2326 * <code>U_ILLEGAL_ARGUMENT_ERROR</code> will be set. Subclasses may 2327 * use this method in their implementation of {@link 2328 * #validateField(int, int&)}. 2329 */ 2330 void validateField(UCalendarDateFields field, int32_t min, int32_t max, UErrorCode& status); 2331 2332 protected: 2333 #ifndef U_HIDE_INTERNAL_API 2334 /** 2335 * Convert a quasi Julian date to the day of the week. The Julian date used here is 2336 * not a true Julian date, since it is measured from midnight, not noon. Return 2337 * value is one-based. 2338 * 2339 * @param julian The given Julian date number. 2340 * @return Day number from 1..7 (SUN..SAT). 2341 * @internal 2342 */ 2343 static uint8_t julianDayToDayOfWeek(double julian); 2344 #endif /* U_HIDE_INTERNAL_API */ 2345 2346 private: 2347 char validLocale[ULOC_FULLNAME_CAPACITY]; 2348 char actualLocale[ULOC_FULLNAME_CAPACITY]; 2349 2350 public: 2351 #if !UCONFIG_NO_SERVICE 2352 /** 2353 * INTERNAL FOR 2.6 -- Registration. 2354 */ 2355 2356 #ifndef U_HIDE_INTERNAL_API 2357 /** 2358 * Return a StringEnumeration over the locales available at the time of the call, 2359 * including registered locales. 2360 * @return a StringEnumeration over the locales available at the time of the call 2361 * @internal 2362 */ 2363 static StringEnumeration* getAvailableLocales(void); 2364 2365 /** 2366 * Register a new Calendar factory. The factory will be adopted. 2367 * INTERNAL in 2.6 2368 * 2369 * Because ICU may choose to cache Calendars internally, this must 2370 * be called at application startup, prior to any calls to 2371 * Calendar::createInstance to avoid undefined behavior. 2372 * 2373 * @param toAdopt the factory instance to be adopted 2374 * @param status the in/out status code, no special meanings are assigned 2375 * @return a registry key that can be used to unregister this factory 2376 * @internal 2377 */ 2378 static URegistryKey registerFactory(ICUServiceFactory* toAdopt, UErrorCode& status); 2379 2380 /** 2381 * Unregister a previously-registered CalendarFactory using the key returned from the 2382 * register call. Key becomes invalid after a successful call and should not be used again. 2383 * The CalendarFactory corresponding to the key will be deleted. 2384 * INTERNAL in 2.6 2385 * 2386 * Because ICU may choose to cache Calendars internally, this should 2387 * be called during application shutdown, after all calls to 2388 * Calendar::createInstance to avoid undefined behavior. 2389 * 2390 * @param key the registry key returned by a previous call to registerFactory 2391 * @param status the in/out status code, no special meanings are assigned 2392 * @return true if the factory for the key was successfully unregistered 2393 * @internal 2394 */ 2395 static UBool unregister(URegistryKey key, UErrorCode& status); 2396 #endif /* U_HIDE_INTERNAL_API */ 2397 2398 /** 2399 * Multiple Calendar Implementation 2400 * @internal 2401 */ 2402 friend class CalendarFactory; 2403 2404 /** 2405 * Multiple Calendar Implementation 2406 * @internal 2407 */ 2408 friend class CalendarService; 2409 2410 /** 2411 * Multiple Calendar Implementation 2412 * @internal 2413 */ 2414 friend class DefaultCalendarFactory; 2415 #endif /* !UCONFIG_NO_SERVICE */ 2416 2417 /** 2418 * @return true if this calendar has a default century (i.e. 03 -> 2003) 2419 * @internal 2420 */ 2421 virtual UBool haveDefaultCentury() const = 0; 2422 2423 /** 2424 * @return the start of the default century, as a UDate 2425 * @internal 2426 */ 2427 virtual UDate defaultCenturyStart() const = 0; 2428 /** 2429 * @return the beginning year of the default century, as a year 2430 * @internal 2431 */ 2432 virtual int32_t defaultCenturyStartYear() const = 0; 2433 2434 /** Get the locale for this calendar object. You can choose between valid and actual locale. 2435 * @param type type of the locale we're looking for (valid or actual) 2436 * @param status error code for the operation 2437 * @return the locale 2438 * @stable ICU 2.8 2439 */ 2440 Locale getLocale(ULocDataLocaleType type, UErrorCode &status) const; 2441 2442 /** 2443 * @return The related Gregorian year; will be obtained by modifying the value 2444 * obtained by get from UCAL_EXTENDED_YEAR field 2445 * @internal 2446 */ 2447 virtual int32_t getRelatedYear(UErrorCode &status) const; 2448 2449 /** 2450 * @param year The related Gregorian year to set; will be modified as necessary then 2451 * set in UCAL_EXTENDED_YEAR field 2452 * @internal 2453 */ 2454 virtual void setRelatedYear(int32_t year); 2455 2456 #ifndef U_HIDE_INTERNAL_API 2457 /** Get the locale for this calendar object. You can choose between valid and actual locale. 2458 * @param type type of the locale we're looking for (valid or actual) 2459 * @param status error code for the operation 2460 * @return the locale 2461 * @internal 2462 */ 2463 const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const; 2464 #endif /* U_HIDE_INTERNAL_API */ 2465 2466 private: 2467 /** 2468 * Cast TimeZone used by this object to BasicTimeZone, or nullptr if the TimeZone 2469 * is not an instance of BasicTimeZone. 2470 */ 2471 BasicTimeZone* getBasicTimeZone() const; 2472 2473 /** 2474 * Find the previous zone transition near the given time. 2475 * @param base The base time, inclusive 2476 * @param transitionTime Receives the result time 2477 * @param status The error status 2478 * @return true if a transition is found. 2479 */ 2480 UBool getImmediatePreviousZoneTransition(UDate base, UDate *transitionTime, UErrorCode& status) const; 2481 2482 public: 2483 #ifndef U_HIDE_INTERNAL_API 2484 /** 2485 * Creates a new Calendar from a Locale for the cache. 2486 * This method does not set the time or timezone in returned calendar. 2487 * @param locale the locale. 2488 * @param status any error returned here. 2489 * @return the new Calendar object with no time or timezone set. 2490 * @internal For ICU use only. 2491 */ 2492 static Calendar * U_EXPORT2 makeInstance( 2493 const Locale &locale, UErrorCode &status); 2494 2495 /** 2496 * Get the calendar type for given locale. 2497 * @param locale the locale 2498 * @param typeBuffer calendar type returned here 2499 * @param typeBufferSize The size of typeBuffer in bytes. If the type 2500 * can't fit in the buffer, this method sets status to 2501 * U_BUFFER_OVERFLOW_ERROR 2502 * @param status error, if any, returned here. 2503 * @internal For ICU use only. 2504 */ 2505 static void U_EXPORT2 getCalendarTypeFromLocale( 2506 const Locale &locale, 2507 char *typeBuffer, 2508 int32_t typeBufferSize, 2509 UErrorCode &status); 2510 #endif /* U_HIDE_INTERNAL_API */ 2511 }; 2512 2513 // ------------------------------------- 2514 2515 inline Calendar* 2516 Calendar::createInstance(TimeZone* zone, UErrorCode& errorCode) 2517 { 2518 // since the Locale isn't specified, use the default locale 2519 return createInstance(zone, Locale::getDefault(), errorCode); 2520 } 2521 2522 // ------------------------------------- 2523 2524 inline void 2525 Calendar::roll(UCalendarDateFields field, UBool up, UErrorCode& status) 2526 { 2527 roll(field, (int32_t)(up ? +1 : -1), status); 2528 } 2529 2530 #ifndef U_HIDE_DEPRECATED_API 2531 inline void 2532 Calendar::roll(EDateFields field, UBool up, UErrorCode& status) 2533 { 2534 roll((UCalendarDateFields) field, up, status); 2535 } 2536 #endif /* U_HIDE_DEPRECATED_API */ 2537 2538 2539 // ------------------------------------- 2540 2541 /** 2542 * Fast method for subclasses. The caller must maintain fUserSetDSTOffset and 2543 * fUserSetZoneOffset, as well as the isSet[] array. 2544 */ 2545 2546 inline void 2547 Calendar::internalSet(UCalendarDateFields field, int32_t value) 2548 { 2549 fFields[field] = value; 2550 fStamp[field] = kInternallySet; 2551 fIsSet[field] = true; // Remove later 2552 } 2553 2554 2555 #ifndef U_HIDE_INTERNAL_API 2556 inline int32_t Calendar::weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek) 2557 { 2558 return weekNumber(dayOfPeriod, dayOfPeriod, dayOfWeek); 2559 } 2560 #endif /* U_HIDE_INTERNAL_API */ 2561 2562 U_NAMESPACE_END 2563 2564 #endif /* #if !UCONFIG_NO_FORMATTING */ 2565 2566 #endif /* U_SHOW_CPLUSPLUS_API */ 2567 2568 #endif // _CALENDAR
Contact us
|
About us
|
Term of use
|
Copyright © 2000-2025 MyWebUniversity.com ™
