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