1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/calendar.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,2486 @@
1.4 +/*
1.5 +********************************************************************************
1.6 +* Copyright (C) 1997-2013, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +********************************************************************************
1.9 +*
1.10 +* File CALENDAR.H
1.11 +*
1.12 +* Modification History:
1.13 +*
1.14 +* Date Name Description
1.15 +* 04/22/97 aliu Expanded and corrected comments and other header
1.16 +* contents.
1.17 +* 05/01/97 aliu Made equals(), before(), after() arguments const.
1.18 +* 05/20/97 aliu Replaced fAreFieldsSet with fAreFieldsInSync and
1.19 +* fAreAllFieldsSet.
1.20 +* 07/27/98 stephen Sync up with JDK 1.2
1.21 +* 11/15/99 weiv added YEAR_WOY and DOW_LOCAL
1.22 +* to EDateFields
1.23 +* 8/19/2002 srl Removed Javaisms
1.24 +* 11/07/2003 srl Update, clean up documentation.
1.25 +********************************************************************************
1.26 +*/
1.27 +
1.28 +#ifndef CALENDAR_H
1.29 +#define CALENDAR_H
1.30 +
1.31 +#include "unicode/utypes.h"
1.32 +
1.33 +/**
1.34 + * \file
1.35 + * \brief C++ API: Calendar object
1.36 + */
1.37 +#if !UCONFIG_NO_FORMATTING
1.38 +
1.39 +#include "unicode/uobject.h"
1.40 +#include "unicode/locid.h"
1.41 +#include "unicode/timezone.h"
1.42 +#include "unicode/ucal.h"
1.43 +#include "unicode/umisc.h"
1.44 +
1.45 +U_NAMESPACE_BEGIN
1.46 +
1.47 +class ICUServiceFactory;
1.48 +
1.49 +/**
1.50 + * @internal
1.51 + */
1.52 +typedef int32_t UFieldResolutionTable[12][8];
1.53 +
1.54 +class BasicTimeZone;
1.55 +/**
1.56 + * <code>Calendar</code> is an abstract base class for converting between
1.57 + * a <code>UDate</code> object and a set of integer fields such as
1.58 + * <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>, <code>HOUR</code>,
1.59 + * and so on. (A <code>UDate</code> object represents a specific instant in
1.60 + * time with millisecond precision. See UDate
1.61 + * for information about the <code>UDate</code> class.)
1.62 + *
1.63 + * <p>
1.64 + * Subclasses of <code>Calendar</code> interpret a <code>UDate</code>
1.65 + * according to the rules of a specific calendar system.
1.66 + * The most commonly used subclass of <code>Calendar</code> is
1.67 + * <code>GregorianCalendar</code>. Other subclasses could represent
1.68 + * the various types of lunar calendars in use in many parts of the world.
1.69 + *
1.70 + * <p>
1.71 + * <b>NOTE</b>: (ICU 2.6) The subclass interface should be considered unstable
1.72 + * - it WILL change.
1.73 + *
1.74 + * <p>
1.75 + * Like other locale-sensitive classes, <code>Calendar</code> provides a
1.76 + * static method, <code>createInstance</code>, for getting a generally useful
1.77 + * object of this type. <code>Calendar</code>'s <code>createInstance</code> method
1.78 + * returns the appropriate <code>Calendar</code> subclass whose
1.79 + * time fields have been initialized with the current date and time:
1.80 + * \htmlonly<blockquote>\endhtmlonly
1.81 + * <pre>
1.82 + * Calendar *rightNow = Calendar::createInstance(errCode);
1.83 + * </pre>
1.84 + * \htmlonly</blockquote>\endhtmlonly
1.85 + *
1.86 + * <p>
1.87 + * A <code>Calendar</code> object can produce all the time field values
1.88 + * needed to implement the date-time formatting for a particular language
1.89 + * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
1.90 + *
1.91 + * <p>
1.92 + * When computing a <code>UDate</code> from time fields, some special circumstances
1.93 + * may arise: there may be insufficient information to compute the
1.94 + * <code>UDate</code> (such as only year and month but no day in the month),
1.95 + * there may be inconsistent information (such as "Tuesday, July 15, 1996"
1.96 + * -- July 15, 1996 is actually a Monday), or the input time might be ambiguous
1.97 + * because of time zone transition.
1.98 + *
1.99 + * <p>
1.100 + * <strong>Insufficient information.</strong> The calendar will use default
1.101 + * information to specify the missing fields. This may vary by calendar; for
1.102 + * the Gregorian calendar, the default for a field is the same as that of the
1.103 + * start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc.
1.104 + *
1.105 + * <p>
1.106 + * <strong>Inconsistent information.</strong> If fields conflict, the calendar
1.107 + * will give preference to fields set more recently. For example, when
1.108 + * determining the day, the calendar will look for one of the following
1.109 + * combinations of fields. The most recent combination, as determined by the
1.110 + * most recently set single field, will be used.
1.111 + *
1.112 + * \htmlonly<blockquote>\endhtmlonly
1.113 + * <pre>
1.114 + * MONTH + DAY_OF_MONTH
1.115 + * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
1.116 + * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
1.117 + * DAY_OF_YEAR
1.118 + * DAY_OF_WEEK + WEEK_OF_YEAR
1.119 + * </pre>
1.120 + * \htmlonly</blockquote>\endhtmlonly
1.121 + *
1.122 + * For the time of day:
1.123 + *
1.124 + * \htmlonly<blockquote>\endhtmlonly
1.125 + * <pre>
1.126 + * HOUR_OF_DAY
1.127 + * AM_PM + HOUR
1.128 + * </pre>
1.129 + * \htmlonly</blockquote>\endhtmlonly
1.130 + *
1.131 + * <p>
1.132 + * <strong>Ambiguous Wall Clock Time.</strong> When time offset from UTC has
1.133 + * changed, it produces ambiguous time slot around the transition. For example,
1.134 + * many US locations observe daylight saving time. On the date switching to daylight
1.135 + * saving time in US, wall clock time jumps from 1:00 AM (standard) to 2:00 AM
1.136 + * (daylight). Therefore, wall clock time from 1:00 AM to 1:59 AM do not exist on
1.137 + * the date. When the input wall time fall into this missing time slot, the ICU
1.138 + * Calendar resolves the time using the UTC offset before the transition by default.
1.139 + * In this example, 1:30 AM is interpreted as 1:30 AM standard time (non-exist),
1.140 + * so the final result will be 2:30 AM daylight time.
1.141 + *
1.142 + * <p>On the date switching back to standard time, wall clock time is moved back one
1.143 + * hour at 2:00 AM. So wall clock time from 1:00 AM to 1:59 AM occur twice. In this
1.144 + * case, the ICU Calendar resolves the time using the UTC offset after the transition
1.145 + * by default. For example, 1:30 AM on the date is resolved as 1:30 AM standard time.
1.146 + *
1.147 + * <p>Ambiguous wall clock time resolution behaviors can be customized by Calendar APIs
1.148 + * {@link #setRepeatedWallTimeOption} and {@link #setSkippedWallTimeOption}.
1.149 + * These methods are available in ICU 49 or later versions.
1.150 + *
1.151 + * <p>
1.152 + * <strong>Note:</strong> for some non-Gregorian calendars, different
1.153 + * fields may be necessary for complete disambiguation. For example, a full
1.154 + * specification of the historial Arabic astronomical calendar requires year,
1.155 + * month, day-of-month <em>and</em> day-of-week in some cases.
1.156 + *
1.157 + * <p>
1.158 + * <strong>Note:</strong> There are certain possible ambiguities in
1.159 + * interpretation of certain singular times, which are resolved in the
1.160 + * following ways:
1.161 + * <ol>
1.162 + * <li> 24:00:00 "belongs" to the following day. That is,
1.163 + * 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970
1.164 + *
1.165 + * <li> Although historically not precise, midnight also belongs to "am",
1.166 + * and noon belongs to "pm", so on the same day,
1.167 + * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm
1.168 + * </ol>
1.169 + *
1.170 + * <p>
1.171 + * The date or time format strings are not part of the definition of a
1.172 + * calendar, as those must be modifiable or overridable by the user at
1.173 + * runtime. Use {@link DateFormat}
1.174 + * to format dates.
1.175 + *
1.176 + * <p>
1.177 + * <code>Calendar</code> provides an API for field "rolling", where fields
1.178 + * can be incremented or decremented, but wrap around. For example, rolling the
1.179 + * month up in the date <code>December 12, <b>1996</b></code> results in
1.180 + * <code>January 12, <b>1996</b></code>.
1.181 + *
1.182 + * <p>
1.183 + * <code>Calendar</code> also provides a date arithmetic function for
1.184 + * adding the specified (signed) amount of time to a particular time field.
1.185 + * For example, subtracting 5 days from the date <code>September 12, 1996</code>
1.186 + * results in <code>September 7, 1996</code>.
1.187 + *
1.188 + * <p><big><b>Supported range</b></big>
1.189 + *
1.190 + * <p>The allowable range of <code>Calendar</code> has been
1.191 + * narrowed. <code>GregorianCalendar</code> used to attempt to support
1.192 + * the range of dates with millisecond values from
1.193 + * <code>Long.MIN_VALUE</code> to <code>Long.MAX_VALUE</code>.
1.194 + * The new <code>Calendar</code> protocol specifies the
1.195 + * maximum range of supportable dates as those having Julian day numbers
1.196 + * of <code>-0x7F000000</code> to <code>+0x7F000000</code>. This
1.197 + * corresponds to years from ~5,800,000 BCE to ~5,800,000 CE. Programmers
1.198 + * should use the protected constants in <code>Calendar</code> to
1.199 + * specify an extremely early or extremely late date.</p>
1.200 + *
1.201 + * @stable ICU 2.0
1.202 + */
1.203 +class U_I18N_API Calendar : public UObject {
1.204 +public:
1.205 +
1.206 + /**
1.207 + * Field IDs for date and time. Used to specify date/time fields. ERA is calendar
1.208 + * specific. Example ranges given are for illustration only; see specific Calendar
1.209 + * subclasses for actual ranges.
1.210 + * @deprecated ICU 2.6. Use C enum UCalendarDateFields defined in ucal.h
1.211 + */
1.212 + enum EDateFields {
1.213 +#ifndef U_HIDE_DEPRECATED_API
1.214 +/*
1.215 + * ERA may be defined on other platforms. To avoid any potential problems undefined it here.
1.216 + */
1.217 +#ifdef ERA
1.218 +#undef ERA
1.219 +#endif
1.220 + ERA, // Example: 0..1
1.221 + YEAR, // Example: 1..big number
1.222 + MONTH, // Example: 0..11
1.223 + WEEK_OF_YEAR, // Example: 1..53
1.224 + WEEK_OF_MONTH, // Example: 1..4
1.225 + DATE, // Example: 1..31
1.226 + DAY_OF_YEAR, // Example: 1..365
1.227 + DAY_OF_WEEK, // Example: 1..7
1.228 + DAY_OF_WEEK_IN_MONTH, // Example: 1..4, may be specified as -1
1.229 + AM_PM, // Example: 0..1
1.230 + HOUR, // Example: 0..11
1.231 + HOUR_OF_DAY, // Example: 0..23
1.232 + MINUTE, // Example: 0..59
1.233 + SECOND, // Example: 0..59
1.234 + MILLISECOND, // Example: 0..999
1.235 + ZONE_OFFSET, // Example: -12*U_MILLIS_PER_HOUR..12*U_MILLIS_PER_HOUR
1.236 + DST_OFFSET, // Example: 0 or U_MILLIS_PER_HOUR
1.237 + YEAR_WOY, // 'Y' Example: 1..big number - Year of Week of Year
1.238 + DOW_LOCAL, // 'e' Example: 1..7 - Day of Week / Localized
1.239 +
1.240 + EXTENDED_YEAR,
1.241 + JULIAN_DAY,
1.242 + MILLISECONDS_IN_DAY,
1.243 + IS_LEAP_MONTH,
1.244 +
1.245 + FIELD_COUNT = UCAL_FIELD_COUNT // See ucal.h for other fields.
1.246 +#endif /* U_HIDE_DEPRECATED_API */
1.247 + };
1.248 +
1.249 +#ifndef U_HIDE_DEPRECATED_API
1.250 + /**
1.251 + * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
1.252 + * who create locale resources for the field of first-day-of-week should be aware of
1.253 + * this. For instance, in US locale, first-day-of-week is set to 1, i.e., SUNDAY.
1.254 + * @deprecated ICU 2.6. Use C enum UCalendarDaysOfWeek defined in ucal.h
1.255 + */
1.256 + enum EDaysOfWeek {
1.257 + SUNDAY = 1,
1.258 + MONDAY,
1.259 + TUESDAY,
1.260 + WEDNESDAY,
1.261 + THURSDAY,
1.262 + FRIDAY,
1.263 + SATURDAY
1.264 + };
1.265 +
1.266 + /**
1.267 + * Useful constants for month. Note: Calendar month is 0-based.
1.268 + * @deprecated ICU 2.6. Use C enum UCalendarMonths defined in ucal.h
1.269 + */
1.270 + enum EMonths {
1.271 + JANUARY,
1.272 + FEBRUARY,
1.273 + MARCH,
1.274 + APRIL,
1.275 + MAY,
1.276 + JUNE,
1.277 + JULY,
1.278 + AUGUST,
1.279 + SEPTEMBER,
1.280 + OCTOBER,
1.281 + NOVEMBER,
1.282 + DECEMBER,
1.283 + UNDECIMBER
1.284 + };
1.285 +
1.286 + /**
1.287 + * Useful constants for hour in 12-hour clock. Used in GregorianCalendar.
1.288 + * @deprecated ICU 2.6. Use C enum UCalendarAMPMs defined in ucal.h
1.289 + */
1.290 + enum EAmpm {
1.291 + AM,
1.292 + PM
1.293 + };
1.294 +#endif /* U_HIDE_DEPRECATED_API */
1.295 +
1.296 + /**
1.297 + * destructor
1.298 + * @stable ICU 2.0
1.299 + */
1.300 + virtual ~Calendar();
1.301 +
1.302 + /**
1.303 + * Create and return a polymorphic copy of this calendar.
1.304 + *
1.305 + * @return a polymorphic copy of this calendar.
1.306 + * @stable ICU 2.0
1.307 + */
1.308 + virtual Calendar* clone(void) const = 0;
1.309 +
1.310 + /**
1.311 + * Creates a Calendar using the default timezone and locale. Clients are responsible
1.312 + * for deleting the object returned.
1.313 + *
1.314 + * @param success Indicates the success/failure of Calendar creation. Filled in
1.315 + * with U_ZERO_ERROR if created successfully, set to a failure result
1.316 + * otherwise. U_MISSING_RESOURCE_ERROR will be returned if the resource data
1.317 + * requests a calendar type which has not been installed.
1.318 + * @return A Calendar if created successfully. NULL otherwise.
1.319 + * @stable ICU 2.0
1.320 + */
1.321 + static Calendar* U_EXPORT2 createInstance(UErrorCode& success);
1.322 +
1.323 + /**
1.324 + * Creates a Calendar using the given timezone and the default locale.
1.325 + * The Calendar takes ownership of zoneToAdopt; the
1.326 + * client must not delete it.
1.327 + *
1.328 + * @param zoneToAdopt The given timezone to be adopted.
1.329 + * @param success Indicates the success/failure of Calendar creation. Filled in
1.330 + * with U_ZERO_ERROR if created successfully, set to a failure result
1.331 + * otherwise.
1.332 + * @return A Calendar if created successfully. NULL otherwise.
1.333 + * @stable ICU 2.0
1.334 + */
1.335 + static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, UErrorCode& success);
1.336 +
1.337 + /**
1.338 + * Creates a Calendar using the given timezone and the default locale. The TimeZone
1.339 + * is _not_ adopted; the client is still responsible for deleting it.
1.340 + *
1.341 + * @param zone The timezone.
1.342 + * @param success Indicates the success/failure of Calendar creation. Filled in
1.343 + * with U_ZERO_ERROR if created successfully, set to a failure result
1.344 + * otherwise.
1.345 + * @return A Calendar if created successfully. NULL otherwise.
1.346 + * @stable ICU 2.0
1.347 + */
1.348 + static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, UErrorCode& success);
1.349 +
1.350 + /**
1.351 + * Creates a Calendar using the default timezone and the given locale.
1.352 + *
1.353 + * @param aLocale The given locale.
1.354 + * @param success Indicates the success/failure of Calendar creation. Filled in
1.355 + * with U_ZERO_ERROR if created successfully, set to a failure result
1.356 + * otherwise.
1.357 + * @return A Calendar if created successfully. NULL otherwise.
1.358 + * @stable ICU 2.0
1.359 + */
1.360 + static Calendar* U_EXPORT2 createInstance(const Locale& aLocale, UErrorCode& success);
1.361 +
1.362 + /**
1.363 + * Creates a Calendar using the given timezone and given locale.
1.364 + * The Calendar takes ownership of zoneToAdopt; the
1.365 + * client must not delete it.
1.366 + *
1.367 + * @param zoneToAdopt The given timezone to be adopted.
1.368 + * @param aLocale The given locale.
1.369 + * @param success Indicates the success/failure of Calendar creation. Filled in
1.370 + * with U_ZERO_ERROR if created successfully, set to a failure result
1.371 + * otherwise.
1.372 + * @return A Calendar if created successfully. NULL otherwise.
1.373 + * @stable ICU 2.0
1.374 + */
1.375 + static Calendar* U_EXPORT2 createInstance(TimeZone* zoneToAdopt, const Locale& aLocale, UErrorCode& success);
1.376 +
1.377 + /**
1.378 + * Gets a Calendar using the given timezone and given locale. The TimeZone
1.379 + * is _not_ adopted; the client is still responsible for deleting it.
1.380 + *
1.381 + * @param zone The given timezone.
1.382 + * @param aLocale The given locale.
1.383 + * @param success Indicates the success/failure of Calendar creation. Filled in
1.384 + * with U_ZERO_ERROR if created successfully, set to a failure result
1.385 + * otherwise.
1.386 + * @return A Calendar if created successfully. NULL otherwise.
1.387 + * @stable ICU 2.0
1.388 + */
1.389 + static Calendar* U_EXPORT2 createInstance(const TimeZone& zone, const Locale& aLocale, UErrorCode& success);
1.390 +
1.391 + /**
1.392 + * Returns a list of the locales for which Calendars are installed.
1.393 + *
1.394 + * @param count Number of locales returned.
1.395 + * @return An array of Locale objects representing the set of locales for which
1.396 + * Calendars are installed. The system retains ownership of this list;
1.397 + * the caller must NOT delete it. Does not include user-registered Calendars.
1.398 + * @stable ICU 2.0
1.399 + */
1.400 + static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
1.401 +
1.402 +
1.403 + /**
1.404 + * Given a key and a locale, returns an array of string values in a preferred
1.405 + * order that would make a difference. These are all and only those values where
1.406 + * the open (creation) of the service with the locale formed from the input locale
1.407 + * plus input keyword and that value has different behavior than creation with the
1.408 + * input locale alone.
1.409 + * @param key one of the keys supported by this service. For now, only
1.410 + * "calendar" is supported.
1.411 + * @param locale the locale
1.412 + * @param commonlyUsed if set to true it will return only commonly used values
1.413 + * with the given locale in preferred order. Otherwise,
1.414 + * it will return all the available values for the locale.
1.415 + * @param status ICU Error Code
1.416 + * @return a string enumeration over keyword values for the given key and the locale.
1.417 + * @stable ICU 4.2
1.418 + */
1.419 + static StringEnumeration* U_EXPORT2 getKeywordValuesForLocale(const char* key,
1.420 + const Locale& locale, UBool commonlyUsed, UErrorCode& status);
1.421 +
1.422 + /**
1.423 + * Returns the current UTC (GMT) time measured in milliseconds since 0:00:00 on 1/1/70
1.424 + * (derived from the system time).
1.425 + *
1.426 + * @return The current UTC time in milliseconds.
1.427 + * @stable ICU 2.0
1.428 + */
1.429 + static UDate U_EXPORT2 getNow(void);
1.430 +
1.431 + /**
1.432 + * Gets this Calendar's time as milliseconds. May involve recalculation of time due
1.433 + * to previous calls to set time field values. The time specified is non-local UTC
1.434 + * (GMT) time. Although this method is const, this object may actually be changed
1.435 + * (semantically const).
1.436 + *
1.437 + * @param status Output param set to success/failure code on exit. If any value
1.438 + * previously set in the time field is invalid or restricted by
1.439 + * leniency, this will be set to an error status.
1.440 + * @return The current time in UTC (GMT) time, or zero if the operation
1.441 + * failed.
1.442 + * @stable ICU 2.0
1.443 + */
1.444 + inline UDate getTime(UErrorCode& status) const { return getTimeInMillis(status); }
1.445 +
1.446 + /**
1.447 + * Sets this Calendar's current time with the given UDate. The time specified should
1.448 + * be in non-local UTC (GMT) time.
1.449 + *
1.450 + * @param date The given UDate in UTC (GMT) time.
1.451 + * @param status Output param set to success/failure code on exit. If any value
1.452 + * set in the time field is invalid or restricted by
1.453 + * leniency, this will be set to an error status.
1.454 + * @stable ICU 2.0
1.455 + */
1.456 + inline void setTime(UDate date, UErrorCode& status) { setTimeInMillis(date, status); }
1.457 +
1.458 + /**
1.459 + * Compares the equality of two Calendar objects. Objects of different subclasses
1.460 + * are considered unequal. This comparison is very exacting; two Calendar objects
1.461 + * must be in exactly the same state to be considered equal. To compare based on the
1.462 + * represented time, use equals() instead.
1.463 + *
1.464 + * @param that The Calendar object to be compared with.
1.465 + * @return True if the given Calendar is the same as this Calendar; false
1.466 + * otherwise.
1.467 + * @stable ICU 2.0
1.468 + */
1.469 + virtual UBool operator==(const Calendar& that) const;
1.470 +
1.471 + /**
1.472 + * Compares the inequality of two Calendar objects.
1.473 + *
1.474 + * @param that The Calendar object to be compared with.
1.475 + * @return True if the given Calendar is not the same as this Calendar; false
1.476 + * otherwise.
1.477 + * @stable ICU 2.0
1.478 + */
1.479 + UBool operator!=(const Calendar& that) const {return !operator==(that);}
1.480 +
1.481 + /**
1.482 + * Returns TRUE if the given Calendar object is equivalent to this
1.483 + * one. An equivalent Calendar will behave exactly as this one
1.484 + * does, but it may be set to a different time. By contrast, for
1.485 + * the operator==() method to return TRUE, the other Calendar must
1.486 + * be set to the same time.
1.487 + *
1.488 + * @param other the Calendar to be compared with this Calendar
1.489 + * @stable ICU 2.4
1.490 + */
1.491 + virtual UBool isEquivalentTo(const Calendar& other) const;
1.492 +
1.493 + /**
1.494 + * Compares the Calendar time, whereas Calendar::operator== compares the equality of
1.495 + * Calendar objects.
1.496 + *
1.497 + * @param when The Calendar to be compared with this Calendar. Although this is a
1.498 + * const parameter, the object may be modified physically
1.499 + * (semantically const).
1.500 + * @param status Output param set to success/failure code on exit. If any value
1.501 + * previously set in the time field is invalid or restricted by
1.502 + * leniency, this will be set to an error status.
1.503 + * @return True if the current time of this Calendar is equal to the time of
1.504 + * Calendar when; false otherwise.
1.505 + * @stable ICU 2.0
1.506 + */
1.507 + UBool equals(const Calendar& when, UErrorCode& status) const;
1.508 +
1.509 + /**
1.510 + * Returns true if this Calendar's current time is before "when"'s current time.
1.511 + *
1.512 + * @param when The Calendar to be compared with this Calendar. Although this is a
1.513 + * const parameter, the object may be modified physically
1.514 + * (semantically const).
1.515 + * @param status Output param set to success/failure code on exit. If any value
1.516 + * previously set in the time field is invalid or restricted by
1.517 + * leniency, this will be set to an error status.
1.518 + * @return True if the current time of this Calendar is before the time of
1.519 + * Calendar when; false otherwise.
1.520 + * @stable ICU 2.0
1.521 + */
1.522 + UBool before(const Calendar& when, UErrorCode& status) const;
1.523 +
1.524 + /**
1.525 + * Returns true if this Calendar's current time is after "when"'s current time.
1.526 + *
1.527 + * @param when The Calendar to be compared with this Calendar. Although this is a
1.528 + * const parameter, the object may be modified physically
1.529 + * (semantically const).
1.530 + * @param status Output param set to success/failure code on exit. If any value
1.531 + * previously set in the time field is invalid or restricted by
1.532 + * leniency, this will be set to an error status.
1.533 + * @return True if the current time of this Calendar is after the time of
1.534 + * Calendar when; false otherwise.
1.535 + * @stable ICU 2.0
1.536 + */
1.537 + UBool after(const Calendar& when, UErrorCode& status) const;
1.538 +
1.539 + /**
1.540 + * UDate Arithmetic function. Adds the specified (signed) amount of time to the given
1.541 + * time field, based on the calendar's rules. For example, to subtract 5 days from
1.542 + * the current time of the calendar, call add(Calendar::DATE, -5). When adding on
1.543 + * the month or Calendar::MONTH field, other fields like date might conflict and
1.544 + * need to be changed. For instance, adding 1 month on the date 01/31/96 will result
1.545 + * in 02/29/96.
1.546 + * Adding a positive value always means moving forward in time, so for the Gregorian calendar,
1.547 + * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
1.548 + * the numeric value of the field itself).
1.549 + *
1.550 + * @param field Specifies which date field to modify.
1.551 + * @param amount The amount of time to be added to the field, in the natural unit
1.552 + * for that field (e.g., days for the day fields, hours for the hour
1.553 + * field.)
1.554 + * @param status Output param set to success/failure code on exit. If any value
1.555 + * previously set in the time field is invalid or restricted by
1.556 + * leniency, this will be set to an error status.
1.557 + * @deprecated ICU 2.6. use add(UCalendarDateFields field, int32_t amount, UErrorCode& status) instead.
1.558 + */
1.559 + virtual void add(EDateFields field, int32_t amount, UErrorCode& status);
1.560 +
1.561 + /**
1.562 + * UDate Arithmetic function. Adds the specified (signed) amount of time to the given
1.563 + * time field, based on the calendar's rules. For example, to subtract 5 days from
1.564 + * the current time of the calendar, call add(Calendar::DATE, -5). When adding on
1.565 + * the month or Calendar::MONTH field, other fields like date might conflict and
1.566 + * need to be changed. For instance, adding 1 month on the date 01/31/96 will result
1.567 + * in 02/29/96.
1.568 + * Adding a positive value always means moving forward in time, so for the Gregorian calendar,
1.569 + * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
1.570 + * the numeric value of the field itself).
1.571 + *
1.572 + * @param field Specifies which date field to modify.
1.573 + * @param amount The amount of time to be added to the field, in the natural unit
1.574 + * for that field (e.g., days for the day fields, hours for the hour
1.575 + * field.)
1.576 + * @param status Output param set to success/failure code on exit. If any value
1.577 + * previously set in the time field is invalid or restricted by
1.578 + * leniency, this will be set to an error status.
1.579 + * @stable ICU 2.6.
1.580 + */
1.581 + virtual void add(UCalendarDateFields field, int32_t amount, UErrorCode& status);
1.582 +
1.583 +#ifndef U_HIDE_DEPRECATED_API
1.584 + /**
1.585 + * Time Field Rolling function. Rolls (up/down) a single unit of time on the given
1.586 + * time field. For example, to roll the current date up by one day, call
1.587 + * roll(Calendar::DATE, true). When rolling on the year or Calendar::YEAR field, it
1.588 + * will roll the year value in the range between getMinimum(Calendar::YEAR) and the
1.589 + * value returned by getMaximum(Calendar::YEAR). When rolling on the month or
1.590 + * Calendar::MONTH field, other fields like date might conflict and, need to be
1.591 + * changed. For instance, rolling the month up on the date 01/31/96 will result in
1.592 + * 02/29/96. Rolling up always means rolling forward in time (unless the limit of the
1.593 + * field is reached, in which case it may pin or wrap), so for Gregorian calendar,
1.594 + * starting with 100 BC and rolling the year up results in 99 BC.
1.595 + * When eras have a definite beginning and end (as in the Chinese calendar, or as in
1.596 + * most eras in the Japanese calendar) then rolling the year past either limit of the
1.597 + * era will cause the year to wrap around. When eras only have a limit at one end,
1.598 + * then attempting to roll the year past that limit will result in pinning the year
1.599 + * at that limit. Note that for most calendars in which era 0 years move forward in
1.600 + * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to
1.601 + * result in negative years for era 0 (that is the only way to represent years before
1.602 + * the calendar epoch).
1.603 + * When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the
1.604 + * hour value in the range between 0 and 23, which is zero-based.
1.605 + * <P>
1.606 + * NOTE: Do not use this method -- use roll(EDateFields, int, UErrorCode&) instead.
1.607 + *
1.608 + * @param field The time field.
1.609 + * @param up Indicates if the value of the specified time field is to be rolled
1.610 + * up or rolled down. Use true if rolling up, false otherwise.
1.611 + * @param status Output param set to success/failure code on exit. If any value
1.612 + * previously set in the time field is invalid or restricted by
1.613 + * leniency, this will be set to an error status.
1.614 + * @deprecated ICU 2.6. Use roll(UCalendarDateFields field, UBool up, UErrorCode& status) instead.
1.615 + */
1.616 + inline void roll(EDateFields field, UBool up, UErrorCode& status);
1.617 +#endif /* U_HIDE_DEPRECATED_API */
1.618 +
1.619 + /**
1.620 + * Time Field Rolling function. Rolls (up/down) a single unit of time on the given
1.621 + * time field. For example, to roll the current date up by one day, call
1.622 + * roll(Calendar::DATE, true). When rolling on the year or Calendar::YEAR field, it
1.623 + * will roll the year value in the range between getMinimum(Calendar::YEAR) and the
1.624 + * value returned by getMaximum(Calendar::YEAR). When rolling on the month or
1.625 + * Calendar::MONTH field, other fields like date might conflict and, need to be
1.626 + * changed. For instance, rolling the month up on the date 01/31/96 will result in
1.627 + * 02/29/96. Rolling up always means rolling forward in time (unless the limit of the
1.628 + * field is reached, in which case it may pin or wrap), so for Gregorian calendar,
1.629 + * starting with 100 BC and rolling the year up results in 99 BC.
1.630 + * When eras have a definite beginning and end (as in the Chinese calendar, or as in
1.631 + * most eras in the Japanese calendar) then rolling the year past either limit of the
1.632 + * era will cause the year to wrap around. When eras only have a limit at one end,
1.633 + * then attempting to roll the year past that limit will result in pinning the year
1.634 + * at that limit. Note that for most calendars in which era 0 years move forward in
1.635 + * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to
1.636 + * result in negative years for era 0 (that is the only way to represent years before
1.637 + * the calendar epoch).
1.638 + * When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the
1.639 + * hour value in the range between 0 and 23, which is zero-based.
1.640 + * <P>
1.641 + * NOTE: Do not use this method -- use roll(UCalendarDateFields, int, UErrorCode&) instead.
1.642 + *
1.643 + * @param field The time field.
1.644 + * @param up Indicates if the value of the specified time field is to be rolled
1.645 + * up or rolled down. Use true if rolling up, false otherwise.
1.646 + * @param status Output param set to success/failure code on exit. If any value
1.647 + * previously set in the time field is invalid or restricted by
1.648 + * leniency, this will be set to an error status.
1.649 + * @stable ICU 2.6.
1.650 + */
1.651 + inline void roll(UCalendarDateFields field, UBool up, UErrorCode& status);
1.652 +
1.653 + /**
1.654 + * Time Field Rolling function. Rolls by the given amount on the given
1.655 + * time field. For example, to roll the current date up by one day, call
1.656 + * roll(Calendar::DATE, +1, status). When rolling on the month or
1.657 + * Calendar::MONTH field, other fields like date might conflict and, need to be
1.658 + * changed. For instance, rolling the month up on the date 01/31/96 will result in
1.659 + * 02/29/96. Rolling by a positive value always means rolling forward in time (unless
1.660 + * the limit of the field is reached, in which case it may pin or wrap), so for
1.661 + * Gregorian calendar, starting with 100 BC and rolling the year by + 1 results in 99 BC.
1.662 + * When eras have a definite beginning and end (as in the Chinese calendar, or as in
1.663 + * most eras in the Japanese calendar) then rolling the year past either limit of the
1.664 + * era will cause the year to wrap around. When eras only have a limit at one end,
1.665 + * then attempting to roll the year past that limit will result in pinning the year
1.666 + * at that limit. Note that for most calendars in which era 0 years move forward in
1.667 + * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to
1.668 + * result in negative years for era 0 (that is the only way to represent years before
1.669 + * the calendar epoch).
1.670 + * When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the
1.671 + * hour value in the range between 0 and 23, which is zero-based.
1.672 + * <P>
1.673 + * The only difference between roll() and add() is that roll() does not change
1.674 + * the value of more significant fields when it reaches the minimum or maximum
1.675 + * of its range, whereas add() does.
1.676 + *
1.677 + * @param field The time field.
1.678 + * @param amount Indicates amount to roll.
1.679 + * @param status Output param set to success/failure code on exit. If any value
1.680 + * previously set in the time field is invalid, this will be set to
1.681 + * an error status.
1.682 + * @deprecated ICU 2.6. Use roll(UCalendarDateFields field, int32_t amount, UErrorCode& status) instead.
1.683 + */
1.684 + virtual void roll(EDateFields field, int32_t amount, UErrorCode& status);
1.685 +
1.686 + /**
1.687 + * Time Field Rolling function. Rolls by the given amount on the given
1.688 + * time field. For example, to roll the current date up by one day, call
1.689 + * roll(Calendar::DATE, +1, status). When rolling on the month or
1.690 + * Calendar::MONTH field, other fields like date might conflict and, need to be
1.691 + * changed. For instance, rolling the month up on the date 01/31/96 will result in
1.692 + * 02/29/96. Rolling by a positive value always means rolling forward in time (unless
1.693 + * the limit of the field is reached, in which case it may pin or wrap), so for
1.694 + * Gregorian calendar, starting with 100 BC and rolling the year by + 1 results in 99 BC.
1.695 + * When eras have a definite beginning and end (as in the Chinese calendar, or as in
1.696 + * most eras in the Japanese calendar) then rolling the year past either limit of the
1.697 + * era will cause the year to wrap around. When eras only have a limit at one end,
1.698 + * then attempting to roll the year past that limit will result in pinning the year
1.699 + * at that limit. Note that for most calendars in which era 0 years move forward in
1.700 + * time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to
1.701 + * result in negative years for era 0 (that is the only way to represent years before
1.702 + * the calendar epoch).
1.703 + * When rolling on the hour-in-day or Calendar::HOUR_OF_DAY field, it will roll the
1.704 + * hour value in the range between 0 and 23, which is zero-based.
1.705 + * <P>
1.706 + * The only difference between roll() and add() is that roll() does not change
1.707 + * the value of more significant fields when it reaches the minimum or maximum
1.708 + * of its range, whereas add() does.
1.709 + *
1.710 + * @param field The time field.
1.711 + * @param amount Indicates amount to roll.
1.712 + * @param status Output param set to success/failure code on exit. If any value
1.713 + * previously set in the time field is invalid, this will be set to
1.714 + * an error status.
1.715 + * @stable ICU 2.6.
1.716 + */
1.717 + virtual void roll(UCalendarDateFields field, int32_t amount, UErrorCode& status);
1.718 +
1.719 + /**
1.720 + * Return the difference between the given time and the time this
1.721 + * calendar object is set to. If this calendar is set
1.722 + * <em>before</em> the given time, the returned value will be
1.723 + * positive. If this calendar is set <em>after</em> the given
1.724 + * time, the returned value will be negative. The
1.725 + * <code>field</code> parameter specifies the units of the return
1.726 + * value. For example, if <code>fieldDifference(when,
1.727 + * Calendar::MONTH)</code> returns 3, then this calendar is set to
1.728 + * 3 months before <code>when</code>, and possibly some addition
1.729 + * time less than one month.
1.730 + *
1.731 + * <p>As a side effect of this call, this calendar is advanced
1.732 + * toward <code>when</code> by the given amount. That is, calling
1.733 + * this method has the side effect of calling <code>add(field,
1.734 + * n)</code>, where <code>n</code> is the return value.
1.735 + *
1.736 + * <p>Usage: To use this method, call it first with the largest
1.737 + * field of interest, then with progressively smaller fields. For
1.738 + * example:
1.739 + *
1.740 + * <pre>
1.741 + * int y = cal->fieldDifference(when, Calendar::YEAR, err);
1.742 + * int m = cal->fieldDifference(when, Calendar::MONTH, err);
1.743 + * int d = cal->fieldDifference(when, Calendar::DATE, err);</pre>
1.744 + *
1.745 + * computes the difference between <code>cal</code> and
1.746 + * <code>when</code> in years, months, and days.
1.747 + *
1.748 + * <p>Note: <code>fieldDifference()</code> is
1.749 + * <em>asymmetrical</em>. That is, in the following code:
1.750 + *
1.751 + * <pre>
1.752 + * cal->setTime(date1, err);
1.753 + * int m1 = cal->fieldDifference(date2, Calendar::MONTH, err);
1.754 + * int d1 = cal->fieldDifference(date2, Calendar::DATE, err);
1.755 + * cal->setTime(date2, err);
1.756 + * int m2 = cal->fieldDifference(date1, Calendar::MONTH, err);
1.757 + * int d2 = cal->fieldDifference(date1, Calendar::DATE, err);</pre>
1.758 + *
1.759 + * one might expect that <code>m1 == -m2 && d1 == -d2</code>.
1.760 + * However, this is not generally the case, because of
1.761 + * irregularities in the underlying calendar system (e.g., the
1.762 + * Gregorian calendar has a varying number of days per month).
1.763 + *
1.764 + * @param when the date to compare this calendar's time to
1.765 + * @param field the field in which to compute the result
1.766 + * @param status Output param set to success/failure code on exit. If any value
1.767 + * previously set in the time field is invalid, this will be set to
1.768 + * an error status.
1.769 + * @return the difference, either positive or negative, between
1.770 + * this calendar's time and <code>when</code>, in terms of
1.771 + * <code>field</code>.
1.772 + * @deprecated ICU 2.6. Use fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status).
1.773 + */
1.774 + virtual int32_t fieldDifference(UDate when, EDateFields field, UErrorCode& status);
1.775 +
1.776 + /**
1.777 + * Return the difference between the given time and the time this
1.778 + * calendar object is set to. If this calendar is set
1.779 + * <em>before</em> the given time, the returned value will be
1.780 + * positive. If this calendar is set <em>after</em> the given
1.781 + * time, the returned value will be negative. The
1.782 + * <code>field</code> parameter specifies the units of the return
1.783 + * value. For example, if <code>fieldDifference(when,
1.784 + * Calendar::MONTH)</code> returns 3, then this calendar is set to
1.785 + * 3 months before <code>when</code>, and possibly some addition
1.786 + * time less than one month.
1.787 + *
1.788 + * <p>As a side effect of this call, this calendar is advanced
1.789 + * toward <code>when</code> by the given amount. That is, calling
1.790 + * this method has the side effect of calling <code>add(field,
1.791 + * n)</code>, where <code>n</code> is the return value.
1.792 + *
1.793 + * <p>Usage: To use this method, call it first with the largest
1.794 + * field of interest, then with progressively smaller fields. For
1.795 + * example:
1.796 + *
1.797 + * <pre>
1.798 + * int y = cal->fieldDifference(when, Calendar::YEAR, err);
1.799 + * int m = cal->fieldDifference(when, Calendar::MONTH, err);
1.800 + * int d = cal->fieldDifference(when, Calendar::DATE, err);</pre>
1.801 + *
1.802 + * computes the difference between <code>cal</code> and
1.803 + * <code>when</code> in years, months, and days.
1.804 + *
1.805 + * <p>Note: <code>fieldDifference()</code> is
1.806 + * <em>asymmetrical</em>. That is, in the following code:
1.807 + *
1.808 + * <pre>
1.809 + * cal->setTime(date1, err);
1.810 + * int m1 = cal->fieldDifference(date2, Calendar::MONTH, err);
1.811 + * int d1 = cal->fieldDifference(date2, Calendar::DATE, err);
1.812 + * cal->setTime(date2, err);
1.813 + * int m2 = cal->fieldDifference(date1, Calendar::MONTH, err);
1.814 + * int d2 = cal->fieldDifference(date1, Calendar::DATE, err);</pre>
1.815 + *
1.816 + * one might expect that <code>m1 == -m2 && d1 == -d2</code>.
1.817 + * However, this is not generally the case, because of
1.818 + * irregularities in the underlying calendar system (e.g., the
1.819 + * Gregorian calendar has a varying number of days per month).
1.820 + *
1.821 + * @param when the date to compare this calendar's time to
1.822 + * @param field the field in which to compute the result
1.823 + * @param status Output param set to success/failure code on exit. If any value
1.824 + * previously set in the time field is invalid, this will be set to
1.825 + * an error status.
1.826 + * @return the difference, either positive or negative, between
1.827 + * this calendar's time and <code>when</code>, in terms of
1.828 + * <code>field</code>.
1.829 + * @stable ICU 2.6.
1.830 + */
1.831 + virtual int32_t fieldDifference(UDate when, UCalendarDateFields field, UErrorCode& status);
1.832 +
1.833 + /**
1.834 + * Sets the calendar's time zone to be the one passed in. The Calendar takes ownership
1.835 + * of the TimeZone; the caller is no longer responsible for deleting it. If the
1.836 + * given time zone is NULL, this function has no effect.
1.837 + *
1.838 + * @param value The given time zone.
1.839 + * @stable ICU 2.0
1.840 + */
1.841 + void adoptTimeZone(TimeZone* value);
1.842 +
1.843 + /**
1.844 + * Sets the calendar's time zone to be the same as the one passed in. The TimeZone
1.845 + * passed in is _not_ adopted; the client is still responsible for deleting it.
1.846 + *
1.847 + * @param zone The given time zone.
1.848 + * @stable ICU 2.0
1.849 + */
1.850 + void setTimeZone(const TimeZone& zone);
1.851 +
1.852 + /**
1.853 + * Returns a reference to the time zone owned by this calendar. The returned reference
1.854 + * is only valid until clients make another call to adoptTimeZone or setTimeZone,
1.855 + * or this Calendar is destroyed.
1.856 + *
1.857 + * @return The time zone object associated with this calendar.
1.858 + * @stable ICU 2.0
1.859 + */
1.860 + const TimeZone& getTimeZone(void) const;
1.861 +
1.862 + /**
1.863 + * Returns the time zone owned by this calendar. The caller owns the returned object
1.864 + * and must delete it when done. After this call, the new time zone associated
1.865 + * with this Calendar is the default TimeZone as returned by TimeZone::createDefault().
1.866 + *
1.867 + * @return The time zone object which was associated with this calendar.
1.868 + * @stable ICU 2.0
1.869 + */
1.870 + TimeZone* orphanTimeZone(void);
1.871 +
1.872 + /**
1.873 + * Queries if the current date for this Calendar is in Daylight Savings Time.
1.874 + *
1.875 + * @param status Fill-in parameter which receives the status of this operation.
1.876 + * @return True if the current date for this Calendar is in Daylight Savings Time,
1.877 + * false, otherwise.
1.878 + * @stable ICU 2.0
1.879 + */
1.880 + virtual UBool inDaylightTime(UErrorCode& status) const = 0;
1.881 +
1.882 + /**
1.883 + * Specifies whether or not date/time interpretation is to be lenient. With lenient
1.884 + * interpretation, a date such as "February 942, 1996" will be treated as being
1.885 + * equivalent to the 941st day after February 1, 1996. With strict interpretation,
1.886 + * such dates will cause an error when computing time from the time field values
1.887 + * representing the dates.
1.888 + *
1.889 + * @param lenient True specifies date/time interpretation to be lenient.
1.890 + *
1.891 + * @see DateFormat#setLenient
1.892 + * @stable ICU 2.0
1.893 + */
1.894 + void setLenient(UBool lenient);
1.895 +
1.896 + /**
1.897 + * Tells whether date/time interpretation is to be lenient.
1.898 + *
1.899 + * @return True tells that date/time interpretation is to be lenient.
1.900 + * @stable ICU 2.0
1.901 + */
1.902 + UBool isLenient(void) const;
1.903 +
1.904 + /**
1.905 + * Sets the behavior for handling wall time repeating multiple times
1.906 + * at negative time zone offset transitions. For example, 1:30 AM on
1.907 + * November 6, 2011 in US Eastern time (Ameirca/New_York) occurs twice;
1.908 + * 1:30 AM EDT, then 1:30 AM EST one hour later. When <code>UCAL_WALLTIME_FIRST</code>
1.909 + * is used, the wall time 1:30AM in this example will be interpreted as 1:30 AM EDT
1.910 + * (first occurrence). When <code>UCAL_WALLTIME_LAST</code> is used, it will be
1.911 + * interpreted as 1:30 AM EST (last occurrence). The default value is
1.912 + * <code>UCAL_WALLTIME_LAST</code>.
1.913 + * <p>
1.914 + * <b>Note:</b>When <code>UCAL_WALLTIME_NEXT_VALID</code> is not a valid
1.915 + * option for this. When the argument is neither <code>UCAL_WALLTIME_FIRST</code>
1.916 + * nor <code>UCAL_WALLTIME_LAST</code>, this method has no effect and will keep
1.917 + * the current setting.
1.918 + *
1.919 + * @param option the behavior for handling repeating wall time, either
1.920 + * <code>UCAL_WALLTIME_FIRST</code> or <code>UCAL_WALLTIME_LAST</code>.
1.921 + * @see #getRepeatedWallTimeOption
1.922 + * @stable ICU 49
1.923 + */
1.924 + void setRepeatedWallTimeOption(UCalendarWallTimeOption option);
1.925 +
1.926 + /**
1.927 + * Gets the behavior for handling wall time repeating multiple times
1.928 + * at negative time zone offset transitions.
1.929 + *
1.930 + * @return the behavior for handling repeating wall time, either
1.931 + * <code>UCAL_WALLTIME_FIRST</code> or <code>UCAL_WALLTIME_LAST</code>.
1.932 + * @see #setRepeatedWallTimeOption
1.933 + * @stable ICU 49
1.934 + */
1.935 + UCalendarWallTimeOption getRepeatedWallTimeOption(void) const;
1.936 +
1.937 + /**
1.938 + * Sets the behavior for handling skipped wall time at positive time zone offset
1.939 + * transitions. For example, 2:30 AM on March 13, 2011 in US Eastern time (America/New_York)
1.940 + * does not exist because the wall time jump from 1:59 AM EST to 3:00 AM EDT. When
1.941 + * <code>UCAL_WALLTIME_FIRST</code> is used, 2:30 AM is interpreted as 30 minutes before 3:00 AM
1.942 + * EDT, therefore, it will be resolved as 1:30 AM EST. When <code>UCAL_WALLTIME_LAST</code>
1.943 + * is used, 2:30 AM is interpreted as 31 minutes after 1:59 AM EST, therefore, it will be
1.944 + * resolved as 3:30 AM EDT. When <code>UCAL_WALLTIME_NEXT_VALID</code> is used, 2:30 AM will
1.945 + * be resolved as next valid wall time, that is 3:00 AM EDT. The default value is
1.946 + * <code>UCAL_WALLTIME_LAST</code>.
1.947 + * <p>
1.948 + * <b>Note:</b>This option is effective only when this calendar is lenient.
1.949 + * When the calendar is strict, such non-existing wall time will cause an error.
1.950 + *
1.951 + * @param option the behavior for handling skipped wall time at positive time zone
1.952 + * offset transitions, one of <code>UCAL_WALLTIME_FIRST</code>, <code>UCAL_WALLTIME_LAST</code> and
1.953 + * <code>UCAL_WALLTIME_NEXT_VALID</code>.
1.954 + * @see #getSkippedWallTimeOption
1.955 + *
1.956 + * @stable ICU 49
1.957 + */
1.958 + void setSkippedWallTimeOption(UCalendarWallTimeOption option);
1.959 +
1.960 + /**
1.961 + * Gets the behavior for handling skipped wall time at positive time zone offset
1.962 + * transitions.
1.963 + *
1.964 + * @return the behavior for handling skipped wall time, one of
1.965 + * <code>UCAL_WALLTIME_FIRST</code>, <code>UCAL_WALLTIME_LAST</code>
1.966 + * and <code>UCAL_WALLTIME_NEXT_VALID</code>.
1.967 + * @see #setSkippedWallTimeOption
1.968 + * @stable ICU 49
1.969 + */
1.970 + UCalendarWallTimeOption getSkippedWallTimeOption(void) const;
1.971 +
1.972 +#ifndef U_HIDE_DEPRECATED_API
1.973 + /**
1.974 + * Sets what the first day of the week is; e.g., Sunday in US, Monday in France.
1.975 + *
1.976 + * @param value The given first day of the week.
1.977 + * @deprecated ICU 2.6. Use setFirstDayOfWeek(UCalendarDaysOfWeek value) instead.
1.978 + */
1.979 + void setFirstDayOfWeek(EDaysOfWeek value);
1.980 +#endif /* U_HIDE_DEPRECATED_API */
1.981 +
1.982 + /**
1.983 + * Sets what the first day of the week is; e.g., Sunday in US, Monday in France.
1.984 + *
1.985 + * @param value The given first day of the week.
1.986 + * @stable ICU 2.6.
1.987 + */
1.988 + void setFirstDayOfWeek(UCalendarDaysOfWeek value);
1.989 +
1.990 +#ifndef U_HIDE_DEPRECATED_API
1.991 + /**
1.992 + * Gets what the first day of the week is; e.g., Sunday in US, Monday in France.
1.993 + *
1.994 + * @return The first day of the week.
1.995 + * @deprecated ICU 2.6 use the overload with error code
1.996 + */
1.997 + EDaysOfWeek getFirstDayOfWeek(void) const;
1.998 +#endif /* U_HIDE_DEPRECATED_API */
1.999 +
1.1000 + /**
1.1001 + * Gets what the first day of the week is; e.g., Sunday in US, Monday in France.
1.1002 + *
1.1003 + * @param status error code
1.1004 + * @return The first day of the week.
1.1005 + * @stable ICU 2.6
1.1006 + */
1.1007 + UCalendarDaysOfWeek getFirstDayOfWeek(UErrorCode &status) const;
1.1008 +
1.1009 + /**
1.1010 + * Sets what the minimal days required in the first week of the year are; For
1.1011 + * example, if the first week is defined as one that contains the first day of the
1.1012 + * first month of a year, call the method with value 1. If it must be a full week,
1.1013 + * use value 7.
1.1014 + *
1.1015 + * @param value The given minimal days required in the first week of the year.
1.1016 + * @stable ICU 2.0
1.1017 + */
1.1018 + void setMinimalDaysInFirstWeek(uint8_t value);
1.1019 +
1.1020 + /**
1.1021 + * Gets what the minimal days required in the first week of the year are; e.g., if
1.1022 + * the first week is defined as one that contains the first day of the first month
1.1023 + * of a year, getMinimalDaysInFirstWeek returns 1. If the minimal days required must
1.1024 + * be a full week, getMinimalDaysInFirstWeek returns 7.
1.1025 + *
1.1026 + * @return The minimal days required in the first week of the year.
1.1027 + * @stable ICU 2.0
1.1028 + */
1.1029 + uint8_t getMinimalDaysInFirstWeek(void) const;
1.1030 +
1.1031 + /**
1.1032 + * Gets the minimum value for the given time field. e.g., for Gregorian
1.1033 + * DAY_OF_MONTH, 1.
1.1034 + *
1.1035 + * @param field The given time field.
1.1036 + * @return The minimum value for the given time field.
1.1037 + * @deprecated ICU 2.6. Use getMinimum(UCalendarDateFields field) instead.
1.1038 + */
1.1039 + virtual int32_t getMinimum(EDateFields field) const;
1.1040 +
1.1041 + /**
1.1042 + * Gets the minimum value for the given time field. e.g., for Gregorian
1.1043 + * DAY_OF_MONTH, 1.
1.1044 + *
1.1045 + * @param field The given time field.
1.1046 + * @return The minimum value for the given time field.
1.1047 + * @stable ICU 2.6.
1.1048 + */
1.1049 + virtual int32_t getMinimum(UCalendarDateFields field) const;
1.1050 +
1.1051 + /**
1.1052 + * Gets the maximum value for the given time field. e.g. for Gregorian DAY_OF_MONTH,
1.1053 + * 31.
1.1054 + *
1.1055 + * @param field The given time field.
1.1056 + * @return The maximum value for the given time field.
1.1057 + * @deprecated ICU 2.6. Use getMaximum(UCalendarDateFields field) instead.
1.1058 + */
1.1059 + virtual int32_t getMaximum(EDateFields field) const;
1.1060 +
1.1061 + /**
1.1062 + * Gets the maximum value for the given time field. e.g. for Gregorian DAY_OF_MONTH,
1.1063 + * 31.
1.1064 + *
1.1065 + * @param field The given time field.
1.1066 + * @return The maximum value for the given time field.
1.1067 + * @stable ICU 2.6.
1.1068 + */
1.1069 + virtual int32_t getMaximum(UCalendarDateFields field) const;
1.1070 +
1.1071 + /**
1.1072 + * Gets the highest minimum value for the given field if varies. Otherwise same as
1.1073 + * getMinimum(). For Gregorian, no difference.
1.1074 + *
1.1075 + * @param field The given time field.
1.1076 + * @return The highest minimum value for the given time field.
1.1077 + * @deprecated ICU 2.6. Use getGreatestMinimum(UCalendarDateFields field) instead.
1.1078 + */
1.1079 + virtual int32_t getGreatestMinimum(EDateFields field) const;
1.1080 +
1.1081 + /**
1.1082 + * Gets the highest minimum value for the given field if varies. Otherwise same as
1.1083 + * getMinimum(). For Gregorian, no difference.
1.1084 + *
1.1085 + * @param field The given time field.
1.1086 + * @return The highest minimum value for the given time field.
1.1087 + * @stable ICU 2.6.
1.1088 + */
1.1089 + virtual int32_t getGreatestMinimum(UCalendarDateFields field) const;
1.1090 +
1.1091 + /**
1.1092 + * Gets the lowest maximum value for the given field if varies. Otherwise same as
1.1093 + * getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.
1.1094 + *
1.1095 + * @param field The given time field.
1.1096 + * @return The lowest maximum value for the given time field.
1.1097 + * @deprecated ICU 2.6. Use getLeastMaximum(UCalendarDateFields field) instead.
1.1098 + */
1.1099 + virtual int32_t getLeastMaximum(EDateFields field) const;
1.1100 +
1.1101 + /**
1.1102 + * Gets the lowest maximum value for the given field if varies. Otherwise same as
1.1103 + * getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.
1.1104 + *
1.1105 + * @param field The given time field.
1.1106 + * @return The lowest maximum value for the given time field.
1.1107 + * @stable ICU 2.6.
1.1108 + */
1.1109 + virtual int32_t getLeastMaximum(UCalendarDateFields field) const;
1.1110 +
1.1111 +#ifndef U_HIDE_DEPRECATED_API
1.1112 + /**
1.1113 + * Return the minimum value that this field could have, given the current date.
1.1114 + * For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum().
1.1115 + *
1.1116 + * The version of this function on Calendar uses an iterative algorithm to determine the
1.1117 + * actual minimum value for the field. There is almost always a more efficient way to
1.1118 + * accomplish this (in most cases, you can simply return getMinimum()). GregorianCalendar
1.1119 + * overrides this function with a more efficient implementation.
1.1120 + *
1.1121 + * @param field the field to determine the minimum of
1.1122 + * @param status Fill-in parameter which receives the status of this operation.
1.1123 + * @return the minimum of the given field for the current date of this Calendar
1.1124 + * @deprecated ICU 2.6. Use getActualMinimum(UCalendarDateFields field, UErrorCode& status) instead.
1.1125 + */
1.1126 + int32_t getActualMinimum(EDateFields field, UErrorCode& status) const;
1.1127 +#endif /* U_HIDE_DEPRECATED_API */
1.1128 +
1.1129 + /**
1.1130 + * Return the minimum value that this field could have, given the current date.
1.1131 + * For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum().
1.1132 + *
1.1133 + * The version of this function on Calendar uses an iterative algorithm to determine the
1.1134 + * actual minimum value for the field. There is almost always a more efficient way to
1.1135 + * accomplish this (in most cases, you can simply return getMinimum()). GregorianCalendar
1.1136 + * overrides this function with a more efficient implementation.
1.1137 + *
1.1138 + * @param field the field to determine the minimum of
1.1139 + * @param status Fill-in parameter which receives the status of this operation.
1.1140 + * @return the minimum of the given field for the current date of this Calendar
1.1141 + * @stable ICU 2.6.
1.1142 + */
1.1143 + virtual int32_t getActualMinimum(UCalendarDateFields field, UErrorCode& status) const;
1.1144 +
1.1145 +#ifndef U_HIDE_DEPRECATED_API
1.1146 + /**
1.1147 + * Return the maximum value that this field could have, given the current date.
1.1148 + * For example, with the date "Feb 3, 1997" and the DAY_OF_MONTH field, the actual
1.1149 + * maximum would be 28; for "Feb 3, 1996" it s 29. Similarly for a Hebrew calendar,
1.1150 + * for some years the actual maximum for MONTH is 12, and for others 13.
1.1151 + *
1.1152 + * The version of this function on Calendar uses an iterative algorithm to determine the
1.1153 + * actual maximum value for the field. There is almost always a more efficient way to
1.1154 + * accomplish this (in most cases, you can simply return getMaximum()). GregorianCalendar
1.1155 + * overrides this function with a more efficient implementation.
1.1156 + *
1.1157 + * @param field the field to determine the maximum of
1.1158 + * @param status Fill-in parameter which receives the status of this operation.
1.1159 + * @return the maximum of the given field for the current date of this Calendar
1.1160 + * @deprecated ICU 2.6. Use getActualMaximum(UCalendarDateFields field, UErrorCode& status) instead.
1.1161 + */
1.1162 + int32_t getActualMaximum(EDateFields field, UErrorCode& status) const;
1.1163 +#endif /* U_HIDE_DEPRECATED_API */
1.1164 +
1.1165 + /**
1.1166 + * Return the maximum value that this field could have, given the current date.
1.1167 + * For example, with the date "Feb 3, 1997" and the DAY_OF_MONTH field, the actual
1.1168 + * maximum would be 28; for "Feb 3, 1996" it s 29. Similarly for a Hebrew calendar,
1.1169 + * for some years the actual maximum for MONTH is 12, and for others 13.
1.1170 + *
1.1171 + * The version of this function on Calendar uses an iterative algorithm to determine the
1.1172 + * actual maximum value for the field. There is almost always a more efficient way to
1.1173 + * accomplish this (in most cases, you can simply return getMaximum()). GregorianCalendar
1.1174 + * overrides this function with a more efficient implementation.
1.1175 + *
1.1176 + * @param field the field to determine the maximum of
1.1177 + * @param status Fill-in parameter which receives the status of this operation.
1.1178 + * @return the maximum of the given field for the current date of this Calendar
1.1179 + * @stable ICU 2.6.
1.1180 + */
1.1181 + virtual int32_t getActualMaximum(UCalendarDateFields field, UErrorCode& status) const;
1.1182 +
1.1183 +#ifndef U_HIDE_DEPRECATED_API
1.1184 + /**
1.1185 + * Gets the value for a given time field. Recalculate the current time field values
1.1186 + * if the time value has been changed by a call to setTime(). Return zero for unset
1.1187 + * fields if any fields have been explicitly set by a call to set(). To force a
1.1188 + * recomputation of all fields regardless of the previous state, call complete().
1.1189 + * This method is semantically const, but may alter the object in memory.
1.1190 + *
1.1191 + * @param field The given time field.
1.1192 + * @param status Fill-in parameter which receives the status of the operation.
1.1193 + * @return The value for the given time field, or zero if the field is unset,
1.1194 + * and set() has been called for any other field.
1.1195 + * @deprecated ICU 2.6. Use get(UCalendarDateFields field, UErrorCode& status) instead.
1.1196 + */
1.1197 + int32_t get(EDateFields field, UErrorCode& status) const;
1.1198 +#endif /* U_HIDE_DEPRECATED_API */
1.1199 +
1.1200 + /**
1.1201 + * Gets the value for a given time field. Recalculate the current time field values
1.1202 + * if the time value has been changed by a call to setTime(). Return zero for unset
1.1203 + * fields if any fields have been explicitly set by a call to set(). To force a
1.1204 + * recomputation of all fields regardless of the previous state, call complete().
1.1205 + * This method is semantically const, but may alter the object in memory.
1.1206 + *
1.1207 + * @param field The given time field.
1.1208 + * @param status Fill-in parameter which receives the status of the operation.
1.1209 + * @return The value for the given time field, or zero if the field is unset,
1.1210 + * and set() has been called for any other field.
1.1211 + * @stable ICU 2.6.
1.1212 + */
1.1213 + int32_t get(UCalendarDateFields field, UErrorCode& status) const;
1.1214 +
1.1215 +#ifndef U_HIDE_DEPRECATED_API
1.1216 + /**
1.1217 + * Determines if the given time field has a value set. This can affect in the
1.1218 + * resolving of time in Calendar. Unset fields have a value of zero, by definition.
1.1219 + *
1.1220 + * @param field The given time field.
1.1221 + * @return True if the given time field has a value set; false otherwise.
1.1222 + * @deprecated ICU 2.6. Use isSet(UCalendarDateFields field) instead.
1.1223 + */
1.1224 + UBool isSet(EDateFields field) const;
1.1225 +#endif /* U_HIDE_DEPRECATED_API */
1.1226 +
1.1227 + /**
1.1228 + * Determines if the given time field has a value set. This can affect in the
1.1229 + * resolving of time in Calendar. Unset fields have a value of zero, by definition.
1.1230 + *
1.1231 + * @param field The given time field.
1.1232 + * @return True if the given time field has a value set; false otherwise.
1.1233 + * @stable ICU 2.6.
1.1234 + */
1.1235 + UBool isSet(UCalendarDateFields field) const;
1.1236 +
1.1237 +#ifndef U_HIDE_DEPRECATED_API
1.1238 + /**
1.1239 + * Sets the given time field with the given value.
1.1240 + *
1.1241 + * @param field The given time field.
1.1242 + * @param value The value to be set for the given time field.
1.1243 + * @deprecated ICU 2.6. Use set(UCalendarDateFields field, int32_t value) instead.
1.1244 + */
1.1245 + void set(EDateFields field, int32_t value);
1.1246 +#endif /* U_HIDE_DEPRECATED_API */
1.1247 +
1.1248 + /**
1.1249 + * Sets the given time field with the given value.
1.1250 + *
1.1251 + * @param field The given time field.
1.1252 + * @param value The value to be set for the given time field.
1.1253 + * @stable ICU 2.6.
1.1254 + */
1.1255 + void set(UCalendarDateFields field, int32_t value);
1.1256 +
1.1257 + /**
1.1258 + * Sets the values for the fields YEAR, MONTH, and DATE. Other field values are
1.1259 + * retained; call clear() first if this is not desired.
1.1260 + *
1.1261 + * @param year The value used to set the YEAR time field.
1.1262 + * @param month The value used to set the MONTH time field. Month value is 0-based.
1.1263 + * e.g., 0 for January.
1.1264 + * @param date The value used to set the DATE time field.
1.1265 + * @stable ICU 2.0
1.1266 + */
1.1267 + void set(int32_t year, int32_t month, int32_t date);
1.1268 +
1.1269 + /**
1.1270 + * Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, and MINUTE. Other
1.1271 + * field values are retained; call clear() first if this is not desired.
1.1272 + *
1.1273 + * @param year The value used to set the YEAR time field.
1.1274 + * @param month The value used to set the MONTH time field. Month value is
1.1275 + * 0-based. E.g., 0 for January.
1.1276 + * @param date The value used to set the DATE time field.
1.1277 + * @param hour The value used to set the HOUR_OF_DAY time field.
1.1278 + * @param minute The value used to set the MINUTE time field.
1.1279 + * @stable ICU 2.0
1.1280 + */
1.1281 + void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute);
1.1282 +
1.1283 + /**
1.1284 + * Sets the values for the fields YEAR, MONTH, DATE, HOUR_OF_DAY, MINUTE, and SECOND.
1.1285 + * Other field values are retained; call clear() first if this is not desired.
1.1286 + *
1.1287 + * @param year The value used to set the YEAR time field.
1.1288 + * @param month The value used to set the MONTH time field. Month value is
1.1289 + * 0-based. E.g., 0 for January.
1.1290 + * @param date The value used to set the DATE time field.
1.1291 + * @param hour The value used to set the HOUR_OF_DAY time field.
1.1292 + * @param minute The value used to set the MINUTE time field.
1.1293 + * @param second The value used to set the SECOND time field.
1.1294 + * @stable ICU 2.0
1.1295 + */
1.1296 + void set(int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute, int32_t second);
1.1297 +
1.1298 + /**
1.1299 + * Clears the values of all the time fields, making them both unset and assigning
1.1300 + * them a value of zero. The field values will be determined during the next
1.1301 + * resolving of time into time fields.
1.1302 + * @stable ICU 2.0
1.1303 + */
1.1304 + void clear(void);
1.1305 +
1.1306 +#ifndef U_HIDE_DEPRECATED_API
1.1307 + /**
1.1308 + * Clears the value in the given time field, both making it unset and assigning it a
1.1309 + * value of zero. This field value will be determined during the next resolving of
1.1310 + * time into time fields.
1.1311 + *
1.1312 + * @param field The time field to be cleared.
1.1313 + * @deprecated ICU 2.6. Use clear(UCalendarDateFields field) instead.
1.1314 + */
1.1315 + void clear(EDateFields field);
1.1316 +#endif /* U_HIDE_DEPRECATED_API */
1.1317 +
1.1318 + /**
1.1319 + * Clears the value in the given time field, both making it unset and assigning it a
1.1320 + * value of zero. This field value will be determined during the next resolving of
1.1321 + * time into time fields.
1.1322 + *
1.1323 + * @param field The time field to be cleared.
1.1324 + * @stable ICU 2.6.
1.1325 + */
1.1326 + void clear(UCalendarDateFields field);
1.1327 +
1.1328 + /**
1.1329 + * Returns a unique class ID POLYMORPHICALLY. Pure virtual method. This method is to
1.1330 + * implement a simple version of RTTI, since not all C++ compilers support genuine
1.1331 + * RTTI. Polymorphic operator==() and clone() methods call this method.
1.1332 + * <P>
1.1333 + * Concrete subclasses of Calendar must implement getDynamicClassID() and also a
1.1334 + * static method and data member:
1.1335 + *
1.1336 + * static UClassID getStaticClassID() { return (UClassID)&fgClassID; }
1.1337 + * static char fgClassID;
1.1338 + *
1.1339 + * @return The class ID for this object. All objects of a given class have the
1.1340 + * same class ID. Objects of other classes have different class IDs.
1.1341 + * @stable ICU 2.0
1.1342 + */
1.1343 + virtual UClassID getDynamicClassID(void) const = 0;
1.1344 +
1.1345 + /**
1.1346 + * Returns the calendar type name string for this Calendar object.
1.1347 + * The returned string is the legacy ICU calendar attribute value,
1.1348 + * for example, "gregorian" or "japanese".
1.1349 + *
1.1350 + * See type="old type name" for the calendar attribute of locale IDs
1.1351 + * at http://www.unicode.org/reports/tr35/#Key_Type_Definitions
1.1352 + *
1.1353 + * Sample code for getting the LDML/BCP 47 calendar key value:
1.1354 + * \code
1.1355 + * const char *calType = cal->getType();
1.1356 + * if (0 == strcmp(calType, "unknown")) {
1.1357 + * // deal with unknown calendar type
1.1358 + * } else {
1.1359 + * string localeID("root@calendar=");
1.1360 + * localeID.append(calType);
1.1361 + * char langTag[100];
1.1362 + * UErrorCode errorCode = U_ZERO_ERROR;
1.1363 + * int32_t length = uloc_toLanguageTag(localeID.c_str(), langTag, (int32_t)sizeof(langTag), TRUE, &errorCode);
1.1364 + * if (U_FAILURE(errorCode)) {
1.1365 + * // deal with errors & overflow
1.1366 + * }
1.1367 + * string lang(langTag, length);
1.1368 + * size_t caPos = lang.find("-ca-");
1.1369 + * lang.erase(0, caPos + 4);
1.1370 + * // lang now contains the LDML calendar type
1.1371 + * }
1.1372 + * \endcode
1.1373 + *
1.1374 + * @return legacy calendar type name string
1.1375 + * @stable ICU 49
1.1376 + */
1.1377 + virtual const char * getType() const = 0;
1.1378 +
1.1379 + /**
1.1380 + * Returns whether the given day of the week is a weekday, a weekend day,
1.1381 + * or a day that transitions from one to the other, for the locale and
1.1382 + * calendar system associated with this Calendar (the locale's region is
1.1383 + * often the most determinant factor). If a transition occurs at midnight,
1.1384 + * then the days before and after the transition will have the
1.1385 + * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time
1.1386 + * other than midnight, then the day of the transition will have
1.1387 + * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the
1.1388 + * method getWeekendTransition() will return the point of
1.1389 + * transition.
1.1390 + * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY).
1.1391 + * @param status The error code for the operation.
1.1392 + * @return The UCalendarWeekdayType for the day of the week.
1.1393 + * @stable ICU 4.4
1.1394 + */
1.1395 + virtual UCalendarWeekdayType getDayOfWeekType(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const;
1.1396 +
1.1397 + /**
1.1398 + * Returns the time during the day at which the weekend begins or ends in
1.1399 + * this calendar system. If getDayOfWeekType() returns UCAL_WEEKEND_ONSET
1.1400 + * for the specified dayOfWeek, return the time at which the weekend begins.
1.1401 + * If getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
1.1402 + * return the time at which the weekend ends. If getDayOfWeekType() returns
1.1403 + * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
1.1404 + * (U_ILLEGAL_ARGUMENT_ERROR).
1.1405 + * @param dayOfWeek The day of the week for which the weekend transition time is
1.1406 + * desired (UCAL_SUNDAY..UCAL_SATURDAY).
1.1407 + * @param status The error code for the operation.
1.1408 + * @return The milliseconds after midnight at which the weekend begins or ends.
1.1409 + * @stable ICU 4.4
1.1410 + */
1.1411 + virtual int32_t getWeekendTransition(UCalendarDaysOfWeek dayOfWeek, UErrorCode &status) const;
1.1412 +
1.1413 + /**
1.1414 + * Returns TRUE if the given UDate is in the weekend in
1.1415 + * this calendar system.
1.1416 + * @param date The UDate in question.
1.1417 + * @param status The error code for the operation.
1.1418 + * @return TRUE if the given UDate is in the weekend in
1.1419 + * this calendar system, FALSE otherwise.
1.1420 + * @stable ICU 4.4
1.1421 + */
1.1422 + virtual UBool isWeekend(UDate date, UErrorCode &status) const;
1.1423 +
1.1424 + /**
1.1425 + * Returns TRUE if this Calendar's current date-time is in the weekend in
1.1426 + * this calendar system.
1.1427 + * @return TRUE if this Calendar's current date-time is in the weekend in
1.1428 + * this calendar system, FALSE otherwise.
1.1429 + * @stable ICU 4.4
1.1430 + */
1.1431 + virtual UBool isWeekend(void) const;
1.1432 +
1.1433 +protected:
1.1434 +
1.1435 + /**
1.1436 + * Constructs a Calendar with the default time zone as returned by
1.1437 + * TimeZone::createInstance(), and the default locale.
1.1438 + *
1.1439 + * @param success Indicates the status of Calendar object construction. Returns
1.1440 + * U_ZERO_ERROR if constructed successfully.
1.1441 + * @stable ICU 2.0
1.1442 + */
1.1443 + Calendar(UErrorCode& success);
1.1444 +
1.1445 + /**
1.1446 + * Copy constructor
1.1447 + *
1.1448 + * @param source Calendar object to be copied from
1.1449 + * @stable ICU 2.0
1.1450 + */
1.1451 + Calendar(const Calendar& source);
1.1452 +
1.1453 + /**
1.1454 + * Default assignment operator
1.1455 + *
1.1456 + * @param right Calendar object to be copied
1.1457 + * @stable ICU 2.0
1.1458 + */
1.1459 + Calendar& operator=(const Calendar& right);
1.1460 +
1.1461 + /**
1.1462 + * Constructs a Calendar with the given time zone and locale. Clients are no longer
1.1463 + * responsible for deleting the given time zone object after it's adopted.
1.1464 + *
1.1465 + * @param zone The given time zone.
1.1466 + * @param aLocale The given locale.
1.1467 + * @param success Indicates the status of Calendar object construction. Returns
1.1468 + * U_ZERO_ERROR if constructed successfully.
1.1469 + * @stable ICU 2.0
1.1470 + */
1.1471 + Calendar(TimeZone* zone, const Locale& aLocale, UErrorCode& success);
1.1472 +
1.1473 + /**
1.1474 + * Constructs a Calendar with the given time zone and locale.
1.1475 + *
1.1476 + * @param zone The given time zone.
1.1477 + * @param aLocale The given locale.
1.1478 + * @param success Indicates the status of Calendar object construction. Returns
1.1479 + * U_ZERO_ERROR if constructed successfully.
1.1480 + * @stable ICU 2.0
1.1481 + */
1.1482 + Calendar(const TimeZone& zone, const Locale& aLocale, UErrorCode& success);
1.1483 +
1.1484 + /**
1.1485 + * Converts Calendar's time field values to GMT as milliseconds.
1.1486 + *
1.1487 + * @param status Output param set to success/failure code on exit. If any value
1.1488 + * previously set in the time field is invalid or restricted by
1.1489 + * leniency, this will be set to an error status.
1.1490 + * @stable ICU 2.0
1.1491 + */
1.1492 + virtual void computeTime(UErrorCode& status);
1.1493 +
1.1494 + /**
1.1495 + * Converts GMT as milliseconds to time field values. This allows you to sync up the
1.1496 + * time field values with a new time that is set for the calendar. This method
1.1497 + * does NOT recompute the time first; to recompute the time, then the fields, use
1.1498 + * the method complete().
1.1499 + *
1.1500 + * @param status Output param set to success/failure code on exit. If any value
1.1501 + * previously set in the time field is invalid or restricted by
1.1502 + * leniency, this will be set to an error status.
1.1503 + * @stable ICU 2.0
1.1504 + */
1.1505 + virtual void computeFields(UErrorCode& status);
1.1506 +
1.1507 + /**
1.1508 + * Gets this Calendar's current time as a long.
1.1509 + *
1.1510 + * @param status Output param set to success/failure code on exit. If any value
1.1511 + * previously set in the time field is invalid or restricted by
1.1512 + * leniency, this will be set to an error status.
1.1513 + * @return the current time as UTC milliseconds from the epoch.
1.1514 + * @stable ICU 2.0
1.1515 + */
1.1516 + double getTimeInMillis(UErrorCode& status) const;
1.1517 +
1.1518 + /**
1.1519 + * Sets this Calendar's current time from the given long value.
1.1520 + * @param millis the new time in UTC milliseconds from the epoch.
1.1521 + * @param status Output param set to success/failure code on exit. If any value
1.1522 + * previously set in the time field is invalid or restricted by
1.1523 + * leniency, this will be set to an error status.
1.1524 + * @stable ICU 2.0
1.1525 + */
1.1526 + void setTimeInMillis( double millis, UErrorCode& status );
1.1527 +
1.1528 + /**
1.1529 + * Recomputes the current time from currently set fields, and then fills in any
1.1530 + * unset fields in the time field list.
1.1531 + *
1.1532 + * @param status Output param set to success/failure code on exit. If any value
1.1533 + * previously set in the time field is invalid or restricted by
1.1534 + * leniency, this will be set to an error status.
1.1535 + * @stable ICU 2.0
1.1536 + */
1.1537 + void complete(UErrorCode& status);
1.1538 +
1.1539 +#ifndef U_HIDE_DEPRECATED_API
1.1540 + /**
1.1541 + * Gets the value for a given time field. Subclasses can use this function to get
1.1542 + * field values without forcing recomputation of time.
1.1543 + *
1.1544 + * @param field The given time field.
1.1545 + * @return The value for the given time field.
1.1546 + * @deprecated ICU 2.6. Use internalGet(UCalendarDateFields field) instead.
1.1547 + */
1.1548 + inline int32_t internalGet(EDateFields field) const {return fFields[field];}
1.1549 +#endif /* U_HIDE_DEPRECATED_API */
1.1550 +
1.1551 +#ifndef U_HIDE_INTERNAL_API
1.1552 + /**
1.1553 + * Gets the value for a given time field. Subclasses can use this function to get
1.1554 + * field values without forcing recomputation of time. If the field's stamp is UNSET,
1.1555 + * the defaultValue is used.
1.1556 + *
1.1557 + * @param field The given time field.
1.1558 + * @param defaultValue a default value used if the field is unset.
1.1559 + * @return The value for the given time field.
1.1560 + * @internal
1.1561 + */
1.1562 + inline int32_t internalGet(UCalendarDateFields field, int32_t defaultValue) const {return fStamp[field]>kUnset ? fFields[field] : defaultValue;}
1.1563 +
1.1564 + /**
1.1565 + * Gets the value for a given time field. Subclasses can use this function to get
1.1566 + * field values without forcing recomputation of time.
1.1567 + *
1.1568 + * @param field The given time field.
1.1569 + * @return The value for the given time field.
1.1570 + * @internal
1.1571 + */
1.1572 + inline int32_t internalGet(UCalendarDateFields field) const {return fFields[field];}
1.1573 +#endif /* U_HIDE_INTERNAL_API */
1.1574 +
1.1575 +#ifndef U_HIDE_DEPRECATED_API
1.1576 + /**
1.1577 + * Sets the value for a given time field. This is a fast internal method for
1.1578 + * subclasses. It does not affect the areFieldsInSync, isTimeSet, or areAllFieldsSet
1.1579 + * flags.
1.1580 + *
1.1581 + * @param field The given time field.
1.1582 + * @param value The value for the given time field.
1.1583 + * @deprecated ICU 2.6. Use internalSet(UCalendarDateFields field, int32_t value) instead.
1.1584 + */
1.1585 + void internalSet(EDateFields field, int32_t value);
1.1586 +#endif /* U_HIDE_DEPRECATED_API */
1.1587 +
1.1588 + /**
1.1589 + * Sets the value for a given time field. This is a fast internal method for
1.1590 + * subclasses. It does not affect the areFieldsInSync, isTimeSet, or areAllFieldsSet
1.1591 + * flags.
1.1592 + *
1.1593 + * @param field The given time field.
1.1594 + * @param value The value for the given time field.
1.1595 + * @stable ICU 2.6.
1.1596 + */
1.1597 + inline void internalSet(UCalendarDateFields field, int32_t value);
1.1598 +
1.1599 + /**
1.1600 + * Prepare this calendar for computing the actual minimum or maximum.
1.1601 + * This method modifies this calendar's fields; it is called on a
1.1602 + * temporary calendar.
1.1603 + * @internal
1.1604 + */
1.1605 + virtual void prepareGetActual(UCalendarDateFields field, UBool isMinimum, UErrorCode &status);
1.1606 +
1.1607 + /**
1.1608 + * Limit enums. Not in sync with UCalendarLimitType (refers to internal fields).
1.1609 + * @internal
1.1610 + */
1.1611 + enum ELimitType {
1.1612 +#ifndef U_HIDE_INTERNAL_API
1.1613 + UCAL_LIMIT_MINIMUM = 0,
1.1614 + UCAL_LIMIT_GREATEST_MINIMUM,
1.1615 + UCAL_LIMIT_LEAST_MAXIMUM,
1.1616 + UCAL_LIMIT_MAXIMUM,
1.1617 + UCAL_LIMIT_COUNT
1.1618 +#endif /* U_HIDE_INTERNAL_API */
1.1619 + };
1.1620 +
1.1621 + /**
1.1622 + * Subclass API for defining limits of different types.
1.1623 + * Subclasses must implement this method to return limits for the
1.1624 + * following fields:
1.1625 + *
1.1626 + * <pre>UCAL_ERA
1.1627 + * UCAL_YEAR
1.1628 + * UCAL_MONTH
1.1629 + * UCAL_WEEK_OF_YEAR
1.1630 + * UCAL_WEEK_OF_MONTH
1.1631 + * UCAL_DATE (DAY_OF_MONTH on Java)
1.1632 + * UCAL_DAY_OF_YEAR
1.1633 + * UCAL_DAY_OF_WEEK_IN_MONTH
1.1634 + * UCAL_YEAR_WOY
1.1635 + * UCAL_EXTENDED_YEAR</pre>
1.1636 + *
1.1637 + * @param field one of the above field numbers
1.1638 + * @param limitType one of <code>MINIMUM</code>, <code>GREATEST_MINIMUM</code>,
1.1639 + * <code>LEAST_MAXIMUM</code>, or <code>MAXIMUM</code>
1.1640 + * @internal
1.1641 + */
1.1642 + virtual int32_t handleGetLimit(UCalendarDateFields field, ELimitType limitType) const = 0;
1.1643 +
1.1644 + /**
1.1645 + * Return a limit for a field.
1.1646 + * @param field the field, from <code>0..UCAL_MAX_FIELD</code>
1.1647 + * @param limitType the type specifier for the limit
1.1648 + * @see #ELimitType
1.1649 + * @internal
1.1650 + */
1.1651 + virtual int32_t getLimit(UCalendarDateFields field, ELimitType limitType) const;
1.1652 +
1.1653 +
1.1654 + /**
1.1655 + * Return the Julian day number of day before the first day of the
1.1656 + * given month in the given extended year. Subclasses should override
1.1657 + * this method to implement their calendar system.
1.1658 + * @param eyear the extended year
1.1659 + * @param month the zero-based month, or 0 if useMonth is false
1.1660 + * @param useMonth if false, compute the day before the first day of
1.1661 + * the given year, otherwise, compute the day before the first day of
1.1662 + * the given month
1.1663 + * @return the Julian day number of the day before the first
1.1664 + * day of the given month and year
1.1665 + * @internal
1.1666 + */
1.1667 + virtual int32_t handleComputeMonthStart(int32_t eyear, int32_t month,
1.1668 + UBool useMonth) const = 0;
1.1669 +
1.1670 + /**
1.1671 + * Return the number of days in the given month of the given extended
1.1672 + * year of this calendar system. Subclasses should override this
1.1673 + * method if they can provide a more correct or more efficient
1.1674 + * implementation than the default implementation in Calendar.
1.1675 + * @internal
1.1676 + */
1.1677 + virtual int32_t handleGetMonthLength(int32_t extendedYear, int32_t month) const ;
1.1678 +
1.1679 + /**
1.1680 + * Return the number of days in the given extended year of this
1.1681 + * calendar system. Subclasses should override this method if they can
1.1682 + * provide a more correct or more efficient implementation than the
1.1683 + * default implementation in Calendar.
1.1684 + * @stable ICU 2.0
1.1685 + */
1.1686 + virtual int32_t handleGetYearLength(int32_t eyear) const;
1.1687 +
1.1688 +
1.1689 + /**
1.1690 + * Return the extended year defined by the current fields. This will
1.1691 + * use the UCAL_EXTENDED_YEAR field or the UCAL_YEAR and supra-year fields (such
1.1692 + * as UCAL_ERA) specific to the calendar system, depending on which set of
1.1693 + * fields is newer.
1.1694 + * @return the extended year
1.1695 + * @internal
1.1696 + */
1.1697 + virtual int32_t handleGetExtendedYear() = 0;
1.1698 +
1.1699 + /**
1.1700 + * Subclasses may override this. This method calls
1.1701 + * handleGetMonthLength() to obtain the calendar-specific month
1.1702 + * length.
1.1703 + * @param bestField which field to use to calculate the date
1.1704 + * @return julian day specified by calendar fields.
1.1705 + * @internal
1.1706 + */
1.1707 + virtual int32_t handleComputeJulianDay(UCalendarDateFields bestField);
1.1708 +
1.1709 + /**
1.1710 + * Subclasses must override this to convert from week fields
1.1711 + * (YEAR_WOY and WEEK_OF_YEAR) to an extended year in the case
1.1712 + * where YEAR, EXTENDED_YEAR are not set.
1.1713 + * The Calendar implementation assumes yearWoy is in extended gregorian form
1.1714 + * @return the extended year, UCAL_EXTENDED_YEAR
1.1715 + * @internal
1.1716 + */
1.1717 + virtual int32_t handleGetExtendedYearFromWeekFields(int32_t yearWoy, int32_t woy);
1.1718 +
1.1719 +#ifndef U_HIDE_INTERNAL_API
1.1720 + /**
1.1721 + * Compute the Julian day from fields. Will determine whether to use
1.1722 + * the JULIAN_DAY field directly, or other fields.
1.1723 + * @return the julian day
1.1724 + * @internal
1.1725 + */
1.1726 + int32_t computeJulianDay();
1.1727 +
1.1728 + /**
1.1729 + * Compute the milliseconds in the day from the fields. This is a
1.1730 + * value from 0 to 23:59:59.999 inclusive, unless fields are out of
1.1731 + * range, in which case it can be an arbitrary value. This value
1.1732 + * reflects local zone wall time.
1.1733 + * @internal
1.1734 + */
1.1735 + int32_t computeMillisInDay();
1.1736 +
1.1737 + /**
1.1738 + * This method can assume EXTENDED_YEAR has been set.
1.1739 + * @param millis milliseconds of the date fields
1.1740 + * @param millisInDay milliseconds of the time fields; may be out
1.1741 + * or range.
1.1742 + * @param ec Output param set to failure code on function return
1.1743 + * when this function fails.
1.1744 + * @internal
1.1745 + */
1.1746 + int32_t computeZoneOffset(double millis, int32_t millisInDay, UErrorCode &ec);
1.1747 +
1.1748 +
1.1749 + /**
1.1750 + * Determine the best stamp in a range.
1.1751 + * @param start first enum to look at
1.1752 + * @param end last enum to look at
1.1753 + * @param bestSoFar stamp prior to function call
1.1754 + * @return the stamp value of the best stamp
1.1755 + * @internal
1.1756 + */
1.1757 + int32_t newestStamp(UCalendarDateFields start, UCalendarDateFields end, int32_t bestSoFar) const;
1.1758 +
1.1759 + /**
1.1760 + * Values for field resolution tables
1.1761 + * @see #resolveFields
1.1762 + * @internal
1.1763 + */
1.1764 + enum {
1.1765 + /** Marker for end of resolve set (row or group). */
1.1766 + kResolveSTOP = -1,
1.1767 + /** 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. */
1.1768 + kResolveRemap = 32
1.1769 + };
1.1770 +
1.1771 + /**
1.1772 + * Precedence table for Dates
1.1773 + * @see #resolveFields
1.1774 + * @internal
1.1775 + */
1.1776 + static const UFieldResolutionTable kDatePrecedence[];
1.1777 +
1.1778 + /**
1.1779 + * Precedence table for Year
1.1780 + * @see #resolveFields
1.1781 + * @internal
1.1782 + */
1.1783 + static const UFieldResolutionTable kYearPrecedence[];
1.1784 +
1.1785 + /**
1.1786 + * Precedence table for Day of Week
1.1787 + * @see #resolveFields
1.1788 + * @internal
1.1789 + */
1.1790 + static const UFieldResolutionTable kDOWPrecedence[];
1.1791 +
1.1792 + /**
1.1793 + * Given a precedence table, return the newest field combination in
1.1794 + * the table, or UCAL_FIELD_COUNT if none is found.
1.1795 + *
1.1796 + * <p>The precedence table is a 3-dimensional array of integers. It
1.1797 + * may be thought of as an array of groups. Each group is an array of
1.1798 + * lines. Each line is an array of field numbers. Within a line, if
1.1799 + * all fields are set, then the time stamp of the line is taken to be
1.1800 + * the stamp of the most recently set field. If any field of a line is
1.1801 + * unset, then the line fails to match. Within a group, the line with
1.1802 + * the newest time stamp is selected. The first field of the line is
1.1803 + * returned to indicate which line matched.
1.1804 + *
1.1805 + * <p>In some cases, it may be desirable to map a line to field that
1.1806 + * whose stamp is NOT examined. For example, if the best field is
1.1807 + * DAY_OF_WEEK then the DAY_OF_WEEK_IN_MONTH algorithm may be used. In
1.1808 + * order to do this, insert the value <code>kResolveRemap | F</code> at
1.1809 + * the start of the line, where <code>F</code> is the desired return
1.1810 + * field value. This field will NOT be examined; it only determines
1.1811 + * the return value if the other fields in the line are the newest.
1.1812 + *
1.1813 + * <p>If all lines of a group contain at least one unset field, then no
1.1814 + * line will match, and the group as a whole will fail to match. In
1.1815 + * that case, the next group will be processed. If all groups fail to
1.1816 + * match, then UCAL_FIELD_COUNT is returned.
1.1817 + * @internal
1.1818 + */
1.1819 + UCalendarDateFields resolveFields(const UFieldResolutionTable *precedenceTable);
1.1820 +#endif /* U_HIDE_INTERNAL_API */
1.1821 +
1.1822 +
1.1823 + /**
1.1824 + * @internal
1.1825 + */
1.1826 + virtual const UFieldResolutionTable* getFieldResolutionTable() const;
1.1827 +
1.1828 +#ifndef U_HIDE_INTERNAL_API
1.1829 + /**
1.1830 + * Return the field that is newer, either defaultField, or
1.1831 + * alternateField. If neither is newer or neither is set, return defaultField.
1.1832 + * @internal
1.1833 + */
1.1834 + UCalendarDateFields newerField(UCalendarDateFields defaultField, UCalendarDateFields alternateField) const;
1.1835 +#endif /* U_HIDE_INTERNAL_API */
1.1836 +
1.1837 +
1.1838 +private:
1.1839 + /**
1.1840 + * Helper function for calculating limits by trial and error
1.1841 + * @param field The field being investigated
1.1842 + * @param startValue starting (least max) value of field
1.1843 + * @param endValue ending (greatest max) value of field
1.1844 + * @param status return type
1.1845 + * @internal
1.1846 + */
1.1847 + int32_t getActualHelper(UCalendarDateFields field, int32_t startValue, int32_t endValue, UErrorCode &status) const;
1.1848 +
1.1849 +
1.1850 +protected:
1.1851 + /**
1.1852 + * The flag which indicates if the current time is set in the calendar.
1.1853 + * @stable ICU 2.0
1.1854 + */
1.1855 + UBool fIsTimeSet;
1.1856 +
1.1857 + /**
1.1858 + * True if the fields are in sync with the currently set time of this Calendar.
1.1859 + * If false, then the next attempt to get the value of a field will
1.1860 + * force a recomputation of all fields from the current value of the time
1.1861 + * field.
1.1862 + * <P>
1.1863 + * This should really be named areFieldsInSync, but the old name is retained
1.1864 + * for backward compatibility.
1.1865 + * @stable ICU 2.0
1.1866 + */
1.1867 + UBool fAreFieldsSet;
1.1868 +
1.1869 + /**
1.1870 + * True if all of the fields have been set. This is initially false, and set to
1.1871 + * true by computeFields().
1.1872 + * @stable ICU 2.0
1.1873 + */
1.1874 + UBool fAreAllFieldsSet;
1.1875 +
1.1876 + /**
1.1877 + * True if all fields have been virtually set, but have not yet been
1.1878 + * computed. This occurs only in setTimeInMillis(). A calendar set
1.1879 + * to this state will compute all fields from the time if it becomes
1.1880 + * necessary, but otherwise will delay such computation.
1.1881 + * @stable ICU 3.0
1.1882 + */
1.1883 + UBool fAreFieldsVirtuallySet;
1.1884 +
1.1885 + /**
1.1886 + * Get the current time without recomputing.
1.1887 + *
1.1888 + * @return the current time without recomputing.
1.1889 + * @stable ICU 2.0
1.1890 + */
1.1891 + UDate internalGetTime(void) const { return fTime; }
1.1892 +
1.1893 + /**
1.1894 + * Set the current time without affecting flags or fields.
1.1895 + *
1.1896 + * @param time The time to be set
1.1897 + * @return the current time without recomputing.
1.1898 + * @stable ICU 2.0
1.1899 + */
1.1900 + void internalSetTime(UDate time) { fTime = time; }
1.1901 +
1.1902 + /**
1.1903 + * The time fields containing values into which the millis is computed.
1.1904 + * @stable ICU 2.0
1.1905 + */
1.1906 + int32_t fFields[UCAL_FIELD_COUNT];
1.1907 +
1.1908 + /**
1.1909 + * The flags which tell if a specified time field for the calendar is set.
1.1910 + * @deprecated ICU 2.8 use (fStamp[n]!=kUnset)
1.1911 + */
1.1912 + UBool fIsSet[UCAL_FIELD_COUNT];
1.1913 +
1.1914 + /** Special values of stamp[]
1.1915 + * @stable ICU 2.0
1.1916 + */
1.1917 + enum {
1.1918 + kUnset = 0,
1.1919 + kInternallySet,
1.1920 + kMinimumUserStamp
1.1921 + };
1.1922 +
1.1923 + /**
1.1924 + * Pseudo-time-stamps which specify when each field was set. There
1.1925 + * are two special values, UNSET and INTERNALLY_SET. Values from
1.1926 + * MINIMUM_USER_SET to Integer.MAX_VALUE are legal user set values.
1.1927 + * @stable ICU 2.0
1.1928 + */
1.1929 + int32_t fStamp[UCAL_FIELD_COUNT];
1.1930 +
1.1931 + /**
1.1932 + * Subclasses may override this method to compute several fields
1.1933 + * specific to each calendar system. These are:
1.1934 + *
1.1935 + * <ul><li>ERA
1.1936 + * <li>YEAR
1.1937 + * <li>MONTH
1.1938 + * <li>DAY_OF_MONTH
1.1939 + * <li>DAY_OF_YEAR
1.1940 + * <li>EXTENDED_YEAR</ul>
1.1941 + *
1.1942 + * Subclasses can refer to the DAY_OF_WEEK and DOW_LOCAL fields, which
1.1943 + * will be set when this method is called. Subclasses can also call
1.1944 + * the getGregorianXxx() methods to obtain Gregorian calendar
1.1945 + * equivalents for the given Julian day.
1.1946 + *
1.1947 + * <p>In addition, subclasses should compute any subclass-specific
1.1948 + * fields, that is, fields from BASE_FIELD_COUNT to
1.1949 + * getFieldCount() - 1.
1.1950 + *
1.1951 + * <p>The default implementation in <code>Calendar</code> implements
1.1952 + * a pure proleptic Gregorian calendar.
1.1953 + * @internal
1.1954 + */
1.1955 + virtual void handleComputeFields(int32_t julianDay, UErrorCode &status);
1.1956 +
1.1957 +#ifndef U_HIDE_INTERNAL_API
1.1958 + /**
1.1959 + * Return the extended year on the Gregorian calendar as computed by
1.1960 + * <code>computeGregorianFields()</code>.
1.1961 + * @internal
1.1962 + */
1.1963 + int32_t getGregorianYear() const {
1.1964 + return fGregorianYear;
1.1965 + }
1.1966 +
1.1967 + /**
1.1968 + * Return the month (0-based) on the Gregorian calendar as computed by
1.1969 + * <code>computeGregorianFields()</code>.
1.1970 + * @internal
1.1971 + */
1.1972 + int32_t getGregorianMonth() const {
1.1973 + return fGregorianMonth;
1.1974 + }
1.1975 +
1.1976 + /**
1.1977 + * Return the day of year (1-based) on the Gregorian calendar as
1.1978 + * computed by <code>computeGregorianFields()</code>.
1.1979 + * @internal
1.1980 + */
1.1981 + int32_t getGregorianDayOfYear() const {
1.1982 + return fGregorianDayOfYear;
1.1983 + }
1.1984 +
1.1985 + /**
1.1986 + * Return the day of month (1-based) on the Gregorian calendar as
1.1987 + * computed by <code>computeGregorianFields()</code>.
1.1988 + * @internal
1.1989 + */
1.1990 + int32_t getGregorianDayOfMonth() const {
1.1991 + return fGregorianDayOfMonth;
1.1992 + }
1.1993 +#endif /* U_HIDE_INTERNAL_API */
1.1994 +
1.1995 + /**
1.1996 + * Called by computeJulianDay. Returns the default month (0-based) for the year,
1.1997 + * taking year and era into account. Defaults to 0 for Gregorian, which doesn't care.
1.1998 + * @param eyear The extended year
1.1999 + * @internal
1.2000 + */
1.2001 + virtual int32_t getDefaultMonthInYear(int32_t eyear) ;
1.2002 +
1.2003 +
1.2004 + /**
1.2005 + * Called by computeJulianDay. Returns the default day (1-based) for the month,
1.2006 + * taking currently-set year and era into account. Defaults to 1 for Gregorian.
1.2007 + * @param eyear the extended year
1.2008 + * @param month the month in the year
1.2009 + * @internal
1.2010 + */
1.2011 + virtual int32_t getDefaultDayInMonth(int32_t eyear, int32_t month);
1.2012 +
1.2013 + //-------------------------------------------------------------------------
1.2014 + // Protected utility methods for use by subclasses. These are very handy
1.2015 + // for implementing add, roll, and computeFields.
1.2016 + //-------------------------------------------------------------------------
1.2017 +
1.2018 + /**
1.2019 + * Adjust the specified field so that it is within
1.2020 + * the allowable range for the date to which this calendar is set.
1.2021 + * For example, in a Gregorian calendar pinning the {@link #UCalendarDateFields DAY_OF_MONTH}
1.2022 + * field for a calendar set to April 31 would cause it to be set
1.2023 + * to April 30.
1.2024 + * <p>
1.2025 + * <b>Subclassing:</b>
1.2026 + * <br>
1.2027 + * This utility method is intended for use by subclasses that need to implement
1.2028 + * their own overrides of {@link #roll roll} and {@link #add add}.
1.2029 + * <p>
1.2030 + * <b>Note:</b>
1.2031 + * <code>pinField</code> is implemented in terms of
1.2032 + * {@link #getActualMinimum getActualMinimum}
1.2033 + * and {@link #getActualMaximum getActualMaximum}. If either of those methods uses
1.2034 + * a slow, iterative algorithm for a particular field, it would be
1.2035 + * unwise to attempt to call <code>pinField</code> for that field. If you
1.2036 + * really do need to do so, you should override this method to do
1.2037 + * something more efficient for that field.
1.2038 + * <p>
1.2039 + * @param field The calendar field whose value should be pinned.
1.2040 + * @param status Output param set to failure code on function return
1.2041 + * when this function fails.
1.2042 + *
1.2043 + * @see #getActualMinimum
1.2044 + * @see #getActualMaximum
1.2045 + * @stable ICU 2.0
1.2046 + */
1.2047 + virtual void pinField(UCalendarDateFields field, UErrorCode& status);
1.2048 +
1.2049 + /**
1.2050 + * Return the week number of a day, within a period. This may be the week number in
1.2051 + * a year or the week number in a month. Usually this will be a value >= 1, but if
1.2052 + * some initial days of the period are excluded from week 1, because
1.2053 + * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} is > 1, then
1.2054 + * the week number will be zero for those
1.2055 + * initial days. This method requires the day number and day of week for some
1.2056 + * known date in the period in order to determine the day of week
1.2057 + * on the desired day.
1.2058 + * <p>
1.2059 + * <b>Subclassing:</b>
1.2060 + * <br>
1.2061 + * This method is intended for use by subclasses in implementing their
1.2062 + * {@link #computeTime computeTime} and/or {@link #computeFields computeFields} methods.
1.2063 + * It is often useful in {@link #getActualMinimum getActualMinimum} and
1.2064 + * {@link #getActualMaximum getActualMaximum} as well.
1.2065 + * <p>
1.2066 + * This variant is handy for computing the week number of some other
1.2067 + * day of a period (often the first or last day of the period) when its day
1.2068 + * of the week is not known but the day number and day of week for some other
1.2069 + * day in the period (e.g. the current date) <em>is</em> known.
1.2070 + * <p>
1.2071 + * @param desiredDay The {@link #UCalendarDateFields DAY_OF_YEAR} or
1.2072 + * {@link #UCalendarDateFields DAY_OF_MONTH} whose week number is desired.
1.2073 + * Should be 1 for the first day of the period.
1.2074 + *
1.2075 + * @param dayOfPeriod The {@link #UCalendarDateFields DAY_OF_YEAR}
1.2076 + * or {@link #UCalendarDateFields DAY_OF_MONTH} for a day in the period whose
1.2077 + * {@link #UCalendarDateFields DAY_OF_WEEK} is specified by the
1.2078 + * <code>knownDayOfWeek</code> parameter.
1.2079 + * Should be 1 for first day of period.
1.2080 + *
1.2081 + * @param dayOfWeek The {@link #UCalendarDateFields DAY_OF_WEEK} for the day
1.2082 + * corresponding to the <code>knownDayOfPeriod</code> parameter.
1.2083 + * 1-based with 1=Sunday.
1.2084 + *
1.2085 + * @return The week number (one-based), or zero if the day falls before
1.2086 + * the first week because
1.2087 + * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek}
1.2088 + * is more than one.
1.2089 + *
1.2090 + * @stable ICU 2.8
1.2091 + */
1.2092 + int32_t weekNumber(int32_t desiredDay, int32_t dayOfPeriod, int32_t dayOfWeek);
1.2093 +
1.2094 +
1.2095 +#ifndef U_HIDE_INTERNAL_API
1.2096 + /**
1.2097 + * Return the week number of a day, within a period. This may be the week number in
1.2098 + * a year, or the week number in a month. Usually this will be a value >= 1, but if
1.2099 + * some initial days of the period are excluded from week 1, because
1.2100 + * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} is > 1,
1.2101 + * then the week number will be zero for those
1.2102 + * initial days. This method requires the day of week for the given date in order to
1.2103 + * determine the result.
1.2104 + * <p>
1.2105 + * <b>Subclassing:</b>
1.2106 + * <br>
1.2107 + * This method is intended for use by subclasses in implementing their
1.2108 + * {@link #computeTime computeTime} and/or {@link #computeFields computeFields} methods.
1.2109 + * It is often useful in {@link #getActualMinimum getActualMinimum} and
1.2110 + * {@link #getActualMaximum getActualMaximum} as well.
1.2111 + * <p>
1.2112 + * @param dayOfPeriod The {@link #UCalendarDateFields DAY_OF_YEAR} or
1.2113 + * {@link #UCalendarDateFields DAY_OF_MONTH} whose week number is desired.
1.2114 + * Should be 1 for the first day of the period.
1.2115 + *
1.2116 + * @param dayOfWeek The {@link #UCalendarDateFields DAY_OF_WEEK} for the day
1.2117 + * corresponding to the <code>dayOfPeriod</code> parameter.
1.2118 + * 1-based with 1=Sunday.
1.2119 + *
1.2120 + * @return The week number (one-based), or zero if the day falls before
1.2121 + * the first week because
1.2122 + * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek}
1.2123 + * is more than one.
1.2124 + * @internal
1.2125 + */
1.2126 + inline int32_t weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek);
1.2127 +
1.2128 + /**
1.2129 + * returns the local DOW, valid range 0..6
1.2130 + * @internal
1.2131 + */
1.2132 + int32_t getLocalDOW();
1.2133 +#endif /* U_HIDE_INTERNAL_API */
1.2134 +
1.2135 +private:
1.2136 +
1.2137 + /**
1.2138 + * The next available value for fStamp[]
1.2139 + */
1.2140 + int32_t fNextStamp;// = MINIMUM_USER_STAMP;
1.2141 +
1.2142 + /**
1.2143 + * Recalculates the time stamp array (fStamp).
1.2144 + * Resets fNextStamp to lowest next stamp value.
1.2145 + */
1.2146 + void recalculateStamp();
1.2147 +
1.2148 + /**
1.2149 + * The current time set for the calendar.
1.2150 + */
1.2151 + UDate fTime;
1.2152 +
1.2153 + /**
1.2154 + * @see #setLenient
1.2155 + */
1.2156 + UBool fLenient;
1.2157 +
1.2158 + /**
1.2159 + * Time zone affects the time calculation done by Calendar. Calendar subclasses use
1.2160 + * the time zone data to produce the local time.
1.2161 + */
1.2162 + TimeZone* fZone;
1.2163 +
1.2164 + /**
1.2165 + * Option for rpeated wall time
1.2166 + * @see #setRepeatedWallTimeOption
1.2167 + */
1.2168 + UCalendarWallTimeOption fRepeatedWallTime;
1.2169 +
1.2170 + /**
1.2171 + * Option for skipped wall time
1.2172 + * @see #setSkippedWallTimeOption
1.2173 + */
1.2174 + UCalendarWallTimeOption fSkippedWallTime;
1.2175 +
1.2176 + /**
1.2177 + * Both firstDayOfWeek and minimalDaysInFirstWeek are locale-dependent. They are
1.2178 + * used to figure out the week count for a specific date for a given locale. These
1.2179 + * must be set when a Calendar is constructed. For example, in US locale,
1.2180 + * firstDayOfWeek is SUNDAY; minimalDaysInFirstWeek is 1. They are used to figure
1.2181 + * out the week count for a specific date for a given locale. These must be set when
1.2182 + * a Calendar is constructed.
1.2183 + */
1.2184 + UCalendarDaysOfWeek fFirstDayOfWeek;
1.2185 + uint8_t fMinimalDaysInFirstWeek;
1.2186 + UCalendarDaysOfWeek fWeekendOnset;
1.2187 + int32_t fWeekendOnsetMillis;
1.2188 + UCalendarDaysOfWeek fWeekendCease;
1.2189 + int32_t fWeekendCeaseMillis;
1.2190 +
1.2191 + /**
1.2192 + * Sets firstDayOfWeek and minimalDaysInFirstWeek. Called at Calendar construction
1.2193 + * time.
1.2194 + *
1.2195 + * @param desiredLocale The given locale.
1.2196 + * @param type The calendar type identifier, e.g: gregorian, buddhist, etc.
1.2197 + * @param success Indicates the status of setting the week count data from
1.2198 + * the resource for the given locale. Returns U_ZERO_ERROR if
1.2199 + * constructed successfully.
1.2200 + */
1.2201 + void setWeekData(const Locale& desiredLocale, const char *type, UErrorCode& success);
1.2202 +
1.2203 + /**
1.2204 + * Recompute the time and update the status fields isTimeSet
1.2205 + * and areFieldsSet. Callers should check isTimeSet and only
1.2206 + * call this method if isTimeSet is false.
1.2207 + *
1.2208 + * @param status Output param set to success/failure code on exit. If any value
1.2209 + * previously set in the time field is invalid or restricted by
1.2210 + * leniency, this will be set to an error status.
1.2211 + */
1.2212 + void updateTime(UErrorCode& status);
1.2213 +
1.2214 + /**
1.2215 + * The Gregorian year, as computed by computeGregorianFields() and
1.2216 + * returned by getGregorianYear().
1.2217 + * @see #computeGregorianFields
1.2218 + */
1.2219 + int32_t fGregorianYear;
1.2220 +
1.2221 + /**
1.2222 + * The Gregorian month, as computed by computeGregorianFields() and
1.2223 + * returned by getGregorianMonth().
1.2224 + * @see #computeGregorianFields
1.2225 + */
1.2226 + int32_t fGregorianMonth;
1.2227 +
1.2228 + /**
1.2229 + * The Gregorian day of the year, as computed by
1.2230 + * computeGregorianFields() and returned by getGregorianDayOfYear().
1.2231 + * @see #computeGregorianFields
1.2232 + */
1.2233 + int32_t fGregorianDayOfYear;
1.2234 +
1.2235 + /**
1.2236 + * The Gregorian day of the month, as computed by
1.2237 + * computeGregorianFields() and returned by getGregorianDayOfMonth().
1.2238 + * @see #computeGregorianFields
1.2239 + */
1.2240 + int32_t fGregorianDayOfMonth;
1.2241 +
1.2242 + /* calculations */
1.2243 +
1.2244 + /**
1.2245 + * Compute the Gregorian calendar year, month, and day of month from
1.2246 + * the given Julian day. These values are not stored in fields, but in
1.2247 + * member variables gregorianXxx. Also compute the DAY_OF_WEEK and
1.2248 + * DOW_LOCAL fields.
1.2249 + */
1.2250 + void computeGregorianAndDOWFields(int32_t julianDay, UErrorCode &ec);
1.2251 +
1.2252 +protected:
1.2253 +
1.2254 + /**
1.2255 + * Compute the Gregorian calendar year, month, and day of month from the
1.2256 + * Julian day. These values are not stored in fields, but in member
1.2257 + * variables gregorianXxx. They are used for time zone computations and by
1.2258 + * subclasses that are Gregorian derivatives. Subclasses may call this
1.2259 + * method to perform a Gregorian calendar millis->fields computation.
1.2260 + */
1.2261 + void computeGregorianFields(int32_t julianDay, UErrorCode &ec);
1.2262 +
1.2263 +private:
1.2264 +
1.2265 + /**
1.2266 + * Compute the fields WEEK_OF_YEAR, YEAR_WOY, WEEK_OF_MONTH,
1.2267 + * DAY_OF_WEEK_IN_MONTH, and DOW_LOCAL from EXTENDED_YEAR, YEAR,
1.2268 + * DAY_OF_WEEK, and DAY_OF_YEAR. The latter fields are computed by the
1.2269 + * subclass based on the calendar system.
1.2270 + *
1.2271 + * <p>The YEAR_WOY field is computed simplistically. It is equal to YEAR
1.2272 + * most of the time, but at the year boundary it may be adjusted to YEAR-1
1.2273 + * or YEAR+1 to reflect the overlap of a week into an adjacent year. In
1.2274 + * this case, a simple increment or decrement is performed on YEAR, even
1.2275 + * though this may yield an invalid YEAR value. For instance, if the YEAR
1.2276 + * is part of a calendar system with an N-year cycle field CYCLE, then
1.2277 + * incrementing the YEAR may involve incrementing CYCLE and setting YEAR
1.2278 + * back to 0 or 1. This is not handled by this code, and in fact cannot be
1.2279 + * simply handled without having subclasses define an entire parallel set of
1.2280 + * fields for fields larger than or equal to a year. This additional
1.2281 + * complexity is not warranted, since the intention of the YEAR_WOY field is
1.2282 + * to support ISO 8601 notation, so it will typically be used with a
1.2283 + * proleptic Gregorian calendar, which has no field larger than a year.
1.2284 + */
1.2285 + void computeWeekFields(UErrorCode &ec);
1.2286 +
1.2287 +
1.2288 + /**
1.2289 + * Ensure that each field is within its valid range by calling {@link
1.2290 + * #validateField(int, int&)} on each field that has been set. This method
1.2291 + * should only be called if this calendar is not lenient.
1.2292 + * @see #isLenient
1.2293 + * @see #validateField(int, int&)
1.2294 + * @internal
1.2295 + */
1.2296 + void validateFields(UErrorCode &status);
1.2297 +
1.2298 + /**
1.2299 + * Validate a single field of this calendar. Subclasses should
1.2300 + * override this method to validate any calendar-specific fields.
1.2301 + * Generic fields can be handled by
1.2302 + * <code>Calendar::validateField()</code>.
1.2303 + * @see #validateField(int, int, int, int&)
1.2304 + * @internal
1.2305 + */
1.2306 + virtual void validateField(UCalendarDateFields field, UErrorCode &status);
1.2307 +
1.2308 + /**
1.2309 + * Validate a single field of this calendar given its minimum and
1.2310 + * maximum allowed value. If the field is out of range,
1.2311 + * <code>U_ILLEGAL_ARGUMENT_ERROR</code> will be set. Subclasses may
1.2312 + * use this method in their implementation of {@link
1.2313 + * #validateField(int, int&)}.
1.2314 + * @internal
1.2315 + */
1.2316 + void validateField(UCalendarDateFields field, int32_t min, int32_t max, UErrorCode& status);
1.2317 +
1.2318 + protected:
1.2319 +#ifndef U_HIDE_INTERNAL_API
1.2320 + /**
1.2321 + * Convert a quasi Julian date to the day of the week. The Julian date used here is
1.2322 + * not a true Julian date, since it is measured from midnight, not noon. Return
1.2323 + * value is one-based.
1.2324 + *
1.2325 + * @param julian The given Julian date number.
1.2326 + * @return Day number from 1..7 (SUN..SAT).
1.2327 + * @internal
1.2328 + */
1.2329 + static uint8_t julianDayToDayOfWeek(double julian);
1.2330 +#endif /* U_HIDE_INTERNAL_API */
1.2331 +
1.2332 + private:
1.2333 + char validLocale[ULOC_FULLNAME_CAPACITY];
1.2334 + char actualLocale[ULOC_FULLNAME_CAPACITY];
1.2335 +
1.2336 + public:
1.2337 +#if !UCONFIG_NO_SERVICE
1.2338 + /**
1.2339 + * INTERNAL FOR 2.6 -- Registration.
1.2340 + */
1.2341 +
1.2342 +#ifndef U_HIDE_INTERNAL_API
1.2343 + /**
1.2344 + * Return a StringEnumeration over the locales available at the time of the call,
1.2345 + * including registered locales.
1.2346 + * @return a StringEnumeration over the locales available at the time of the call
1.2347 + * @internal
1.2348 + */
1.2349 + static StringEnumeration* getAvailableLocales(void);
1.2350 +
1.2351 + /**
1.2352 + * Register a new Calendar factory. The factory will be adopted.
1.2353 + * INTERNAL in 2.6
1.2354 + * @param toAdopt the factory instance to be adopted
1.2355 + * @param status the in/out status code, no special meanings are assigned
1.2356 + * @return a registry key that can be used to unregister this factory
1.2357 + * @internal
1.2358 + */
1.2359 + static URegistryKey registerFactory(ICUServiceFactory* toAdopt, UErrorCode& status);
1.2360 +
1.2361 + /**
1.2362 + * Unregister a previously-registered CalendarFactory using the key returned from the
1.2363 + * register call. Key becomes invalid after a successful call and should not be used again.
1.2364 + * The CalendarFactory corresponding to the key will be deleted.
1.2365 + * INTERNAL in 2.6
1.2366 + * @param key the registry key returned by a previous call to registerFactory
1.2367 + * @param status the in/out status code, no special meanings are assigned
1.2368 + * @return TRUE if the factory for the key was successfully unregistered
1.2369 + * @internal
1.2370 + */
1.2371 + static UBool unregister(URegistryKey key, UErrorCode& status);
1.2372 +#endif /* U_HIDE_INTERNAL_API */
1.2373 +
1.2374 + /**
1.2375 + * Multiple Calendar Implementation
1.2376 + * @internal
1.2377 + */
1.2378 + friend class CalendarFactory;
1.2379 +
1.2380 + /**
1.2381 + * Multiple Calendar Implementation
1.2382 + * @internal
1.2383 + */
1.2384 + friend class CalendarService;
1.2385 +
1.2386 + /**
1.2387 + * Multiple Calendar Implementation
1.2388 + * @internal
1.2389 + */
1.2390 + friend class DefaultCalendarFactory;
1.2391 +#endif /* !UCONFIG_NO_SERVICE */
1.2392 +
1.2393 + /**
1.2394 + * @return TRUE if this calendar has a default century (i.e. 03 -> 2003)
1.2395 + * @internal
1.2396 + */
1.2397 + virtual UBool haveDefaultCentury() const = 0;
1.2398 +
1.2399 + /**
1.2400 + * @return the start of the default century, as a UDate
1.2401 + * @internal
1.2402 + */
1.2403 + virtual UDate defaultCenturyStart() const = 0;
1.2404 + /**
1.2405 + * @return the beginning year of the default century, as a year
1.2406 + * @internal
1.2407 + */
1.2408 + virtual int32_t defaultCenturyStartYear() const = 0;
1.2409 +
1.2410 + /** Get the locale for this calendar object. You can choose between valid and actual locale.
1.2411 + * @param type type of the locale we're looking for (valid or actual)
1.2412 + * @param status error code for the operation
1.2413 + * @return the locale
1.2414 + * @stable ICU 2.8
1.2415 + */
1.2416 + Locale getLocale(ULocDataLocaleType type, UErrorCode &status) const;
1.2417 +
1.2418 +#ifndef U_HIDE_INTERNAL_API
1.2419 + /** Get the locale for this calendar object. You can choose between valid and actual locale.
1.2420 + * @param type type of the locale we're looking for (valid or actual)
1.2421 + * @param status error code for the operation
1.2422 + * @return the locale
1.2423 + * @internal
1.2424 + */
1.2425 + const char* getLocaleID(ULocDataLocaleType type, UErrorCode &status) const;
1.2426 +#endif /* U_HIDE_INTERNAL_API */
1.2427 +
1.2428 +private:
1.2429 + /**
1.2430 + * Cast TimeZone used by this object to BasicTimeZone, or NULL if the TimeZone
1.2431 + * is not an instance of BasicTimeZone.
1.2432 + */
1.2433 + BasicTimeZone* getBasicTimeZone() const;
1.2434 +};
1.2435 +
1.2436 +// -------------------------------------
1.2437 +
1.2438 +inline Calendar*
1.2439 +Calendar::createInstance(TimeZone* zone, UErrorCode& errorCode)
1.2440 +{
1.2441 + // since the Locale isn't specified, use the default locale
1.2442 + return createInstance(zone, Locale::getDefault(), errorCode);
1.2443 +}
1.2444 +
1.2445 +// -------------------------------------
1.2446 +
1.2447 +inline void
1.2448 +Calendar::roll(UCalendarDateFields field, UBool up, UErrorCode& status)
1.2449 +{
1.2450 + roll(field, (int32_t)(up ? +1 : -1), status);
1.2451 +}
1.2452 +
1.2453 +#ifndef U_HIDE_DEPRECATED_API
1.2454 +inline void
1.2455 +Calendar::roll(EDateFields field, UBool up, UErrorCode& status)
1.2456 +{
1.2457 + roll((UCalendarDateFields) field, up, status);
1.2458 +}
1.2459 +#endif
1.2460 +
1.2461 +
1.2462 +// -------------------------------------
1.2463 +
1.2464 +/**
1.2465 + * Fast method for subclasses. The caller must maintain fUserSetDSTOffset and
1.2466 + * fUserSetZoneOffset, as well as the isSet[] array.
1.2467 + */
1.2468 +
1.2469 +inline void
1.2470 +Calendar::internalSet(UCalendarDateFields field, int32_t value)
1.2471 +{
1.2472 + fFields[field] = value;
1.2473 + fStamp[field] = kInternallySet;
1.2474 + fIsSet[field] = TRUE; // Remove later
1.2475 +}
1.2476 +
1.2477 +
1.2478 +#ifndef U_HIDE_INTERNAL_API
1.2479 +inline int32_t Calendar::weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek)
1.2480 +{
1.2481 + return weekNumber(dayOfPeriod, dayOfPeriod, dayOfWeek);
1.2482 +}
1.2483 +#endif
1.2484 +
1.2485 +U_NAMESPACE_END
1.2486 +
1.2487 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.2488 +
1.2489 +#endif // _CALENDAR
