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