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