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