// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /* ******************************************************************************** * Copyright (C) 1997-2014, International Business Machines * Corporation and others. All Rights Reserved. ******************************************************************************** * * File CALENDAR.H * * Modification History: * * Date Name Description * 04/22/97 aliu Expanded and corrected comments and other header * contents. * 05/01/97 aliu Made equals(), before(), after() arguments const. * 05/20/97 aliu Replaced fAreFieldsSet with fAreFieldsInSync and * fAreAllFieldsSet. * 07/27/98 stephen Sync up with JDK 1.2 * 11/15/99 weiv added YEAR_WOY and DOW_LOCAL * to EDateFields * 8/19/2002 srl Removed Javaisms * 11/07/2003 srl Update, clean up documentation. ******************************************************************************** */ #ifndef CALENDAR_H #define CALENDAR_H #include "unicode/utypes.h" #if U_SHOW_CPLUSPLUS_API /** * \file * \brief C++ API: Calendar object */ #if !UCONFIG_NO_FORMATTING #include "unicode/uobject.h" #include "unicode/locid.h" #include "unicode/timezone.h" #include "unicode/ucal.h" #include "unicode/umisc.h" U_NAMESPACE_BEGIN class ICUServiceFactory; // Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API, // it is a return type for a virtual method (@internal) /** * @internal */ UFieldResolutionTable; class BasicTimeZone; /** * `Calendar` is an abstract base class for converting between * a `UDate` object and a set of integer fields such as * `YEAR`, `MONTH`, `DAY`, `HOUR`, and so on. * (A `UDate` object represents a specific instant in * time with millisecond precision. See UDate * for information about the `UDate` class.) * * Subclasses of `Calendar` interpret a `UDate` * according to the rules of a specific calendar system. * The most commonly used subclass of `Calendar` is * `GregorianCalendar`. Other subclasses could represent * the various types of lunar calendars in use in many parts of the world. * * **NOTE**: (ICU 2.6) The subclass interface should be considered unstable - * it WILL change. * * Like other locale-sensitive classes, `Calendar` provides a * static method, `createInstance`, for getting a generally useful * object of this type. `Calendar`'s `createInstance` method * returns the appropriate `Calendar` subclass whose * time fields have been initialized with the current date and time: * * Calendar *rightNow = Calendar::createInstance(errCode); * * A `Calendar` object can produce all the time field values * needed to implement the date-time formatting for a particular language * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional). * * When computing a `UDate` from time fields, some special circumstances * may arise: there may be insufficient information to compute the * `UDate` (such as only year and month but no day in the month), * there may be inconsistent information (such as "Tuesday, July 15, 1996" * -- July 15, 1996 is actually a Monday), or the input time might be ambiguous * because of time zone transition. * * **Insufficient information.** The calendar will use default * information to specify the missing fields. This may vary by calendar; for * the Gregorian calendar, the default for a field is the same as that of the * start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. * * **Inconsistent information.** If fields conflict, the calendar * will give preference to fields set more recently. For example, when * determining the day, the calendar will look for one of the following * combinations of fields. The most recent combination, as determined by the * most recently set single field, will be used. * * MONTH + DAY_OF_MONTH * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK * DAY_OF_YEAR * DAY_OF_WEEK + WEEK_OF_YEAR * * For the time of day: * * HOUR_OF_DAY * AM_PM + HOUR * * **Ambiguous Wall Clock Time.** When time offset from UTC has * changed, it produces an ambiguous time slot around the transition. For example, * many US locations observe daylight saving time. On the date switching to daylight * saving time in US, wall clock time jumps from 12:59 AM (standard) to 2:00 AM * (daylight). Therefore, wall clock time from 1:00 AM to 1:59 AM do not exist on * the date. When the input wall time fall into this missing time slot, the ICU * Calendar resolves the time using the UTC offset before the transition by default. * In this example, 1:30 AM is interpreted as 1:30 AM standard time (non-exist), * so the final result will be 2:30 AM daylight time. * * On the date switching back to standard time, wall clock time is moved back one * hour at 2:00 AM. So wall clock time from 1:00 AM to 1:59 AM occur twice. In this * case, the ICU Calendar resolves the time using the UTC offset after the transition * by default. For example, 1:30 AM on the date is resolved as 1:30 AM standard time. * * Ambiguous wall clock time resolution behaviors can be customized by Calendar APIs * {@link #setRepeatedWallTimeOption} and {@link #setSkippedWallTimeOption}. * These methods are available in ICU 49 or later versions. * * **Note:** for some non-Gregorian calendars, different * fields may be necessary for complete disambiguation. For example, a full * specification of the historical Arabic astronomical calendar requires year, * month, day-of-month *and* day-of-week in some cases. * * **Note:** There are certain possible ambiguities in * interpretation of certain singular times, which are resolved in the * following ways: * * 1. 24:00:00 "belongs" to the following day. That is, * 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970 * 2. Although historically not precise, midnight also belongs to "am", * and noon belongs to "pm", so on the same day, * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm * * The date or time format strings are not part of the definition of a * calendar, as those must be modifiable or overridable by the user at * runtime. Use `DateFormat` to format dates. * * `Calendar` provides an API for field "rolling", where fields * can be incremented or decremented, but wrap around. For example, rolling the * month up in the date December 12, **1996** results in * January 12, **1996**. * * `Calendar` also provides a date arithmetic function for * adding the specified (signed) amount of time to a particular time field. * For example, subtracting 5 days from the date `September 12, 1996` * results in `September 7, 1996`. * * ***Supported range*** * * The allowable range of `Calendar` has been narrowed. `GregorianCalendar` used * to attempt to support the range of dates with millisecond values from * `Long.MIN_VALUE` to `Long.MAX_VALUE`. The new `Calendar` protocol specifies the * maximum range of supportable dates as those having Julian day numbers * of `-0x7F000000` to `+0x7F000000`. This corresponds to years from ~5,800,000 BCE * to ~5,800,000 CE. Programmers should use the protected constants in `Calendar` to * specify an extremely early or extremely late date. * * <p> * The Japanese calendar uses a combination of era name and year number. * When an emperor of Japan abdicates and a new emperor ascends the throne, * a new era is declared and year number is reset to 1. Even if the date of * abdication is scheduled ahead of time, the new era name might not be * announced until just before the date. In such case, ICU4C may include * a start date of future era without actual era name, but not enabled * by default. ICU4C users who want to test the behavior of the future era * can enable the tentative era by: * <ul> * <li>Environment variable <code>ICU_ENABLE_TENTATIVE_ERA=true</code>.</li> * </ul> * * @stable ICU 2.0 */ class U_I18N_API Calendar : public UObject { … }; // ------------------------------------- inline Calendar* Calendar::createInstance(TimeZone* zone, UErrorCode& errorCode) { … } // ------------------------------------- inline void Calendar::roll(UCalendarDateFields field, UBool up, UErrorCode& status) { … } #ifndef U_HIDE_DEPRECATED_API inline void Calendar::roll(EDateFields field, UBool up, UErrorCode& status) { … } #endif /* U_HIDE_DEPRECATED_API */ // ------------------------------------- /** * Fast method for subclasses. The caller must maintain fUserSetDSTOffset and * fUserSetZoneOffset, as well as the isSet[] array. */ inline void Calendar::internalSet(UCalendarDateFields field, int32_t value) { … } #ifndef U_HIDE_INTERNAL_API inline int32_t Calendar::weekNumber(int32_t dayOfPeriod, int32_t dayOfWeek) { … } #endif /* U_HIDE_INTERNAL_API */ U_NAMESPACE_END #endif /* #if !UCONFIG_NO_FORMATTING */ #endif /* U_SHOW_CPLUSPLUS_API */ #endif // _CALENDAR
Codebase Browser
chromium