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