diff options
Diffstat (limited to 'deps/icu-small/source/i18n/unicode/calendar.h')
| -rw-r--r-- | deps/icu-small/source/i18n/unicode/calendar.h | 161 |
1 files changed, 71 insertions, 90 deletions
diff --git a/deps/icu-small/source/i18n/unicode/calendar.h b/deps/icu-small/source/i18n/unicode/calendar.h index 48021534b4..023cf053f2 100644 --- a/deps/icu-small/source/i18n/unicode/calendar.h +++ b/deps/icu-small/source/i18n/unicode/calendar.h @@ -52,83 +52,64 @@ typedef int32_t UFieldResolutionTable[12][8]; class BasicTimeZone; /** - * <code>Calendar</code> is an abstract base class for converting between - * a <code>UDate</code> object and a set of integer fields such as - * <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>, <code>HOUR</code>, - * and so on. (A <code>UDate</code> object represents a specific instant in + * `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 <code>UDate</code> class.) + * for information about the `UDate` class.) * - * <p> - * Subclasses of <code>Calendar</code> interpret a <code>UDate</code> + * Subclasses of `Calendar` interpret a `UDate` * according to the rules of a specific calendar system. - * The most commonly used subclass of <code>Calendar</code> is - * <code>GregorianCalendar</code>. Other subclasses could represent + * 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. * - * <p> - * <b>NOTE</b>: (ICU 2.6) The subclass interface should be considered unstable - * - it WILL change. + * **NOTE**: (ICU 2.6) The subclass interface should be considered unstable - + * it WILL change. * - * <p> - * Like other locale-sensitive classes, <code>Calendar</code> provides a - * static method, <code>createInstance</code>, for getting a generally useful - * object of this type. <code>Calendar</code>'s <code>createInstance</code> method - * returns the appropriate <code>Calendar</code> subclass whose + * 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: - * \htmlonly<blockquote>\endhtmlonly - * <pre> - * Calendar *rightNow = Calendar::createInstance(errCode); - * </pre> - * \htmlonly</blockquote>\endhtmlonly * - * <p> - * A <code>Calendar</code> object can produce all the time field values + * 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). * - * <p> - * When computing a <code>UDate</code> from time fields, some special circumstances + * When computing a `UDate` from time fields, some special circumstances * may arise: there may be insufficient information to compute the - * <code>UDate</code> (such as only year and month but no day in the month), + * `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. * - * <p> - * <strong>Insufficient information.</strong> The calendar will use default + * **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. * - * <p> - * <strong>Inconsistent information.</strong> If fields conflict, the calendar + * **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. * - * \htmlonly<blockquote>\endhtmlonly - * <pre> - * 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 - * </pre> - * \htmlonly</blockquote>\endhtmlonly + * 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: * - * \htmlonly<blockquote>\endhtmlonly - * <pre> - * HOUR_OF_DAY - * AM_PM + HOUR - * </pre> - * \htmlonly</blockquote>\endhtmlonly + * HOUR_OF_DAY + * AM_PM + HOUR * - * <p> - * <strong>Ambiguous Wall Clock Time.</strong> When time offset from UTC has + * **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 @@ -138,64 +119,66 @@ class BasicTimeZone; * 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. * - * <p>On the date switching back to standard time, wall clock time is moved back one + * 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. * - * <p>Ambiguous wall clock time resolution behaviors can be customized by Calendar APIs + * 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. * - * <p> - * <strong>Note:</strong> for some non-Gregorian calendars, different + * **Note:** for some non-Gregorian calendars, different * fields may be necessary for complete disambiguation. For example, a full - * specification of the historial Arabic astronomical calendar requires year, - * month, day-of-month <em>and</em> day-of-week in some cases. + * specification of the historical Arabic astronomical calendar requires year, + * month, day-of-month *and* day-of-week in some cases. * - * <p> - * <strong>Note:</strong> There are certain possible ambiguities in + * **Note:** There are certain possible ambiguities in * interpretation of certain singular times, which are resolved in the * following ways: - * <ol> - * <li> 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 * - * <li> 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 - * </ol> + * 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 * - * <p> * 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 {@link DateFormat} - * to format dates. + * runtime. Use `DateFormat` to format dates. * - * <p> - * <code>Calendar</code> provides an API for field "rolling", where fields + * `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 <code>December 12, <b>1996</b></code> results in - * <code>January 12, <b>1996</b></code>. + * month up in the date December 12, **1996** results in + * January 12, **1996**. * - * <p> - * <code>Calendar</code> also provides a date arithmetic function for + * `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 <code>September 12, 1996</code> - * results in <code>September 7, 1996</code>. + * For example, subtracting 5 days from the date `September 12, 1996` + * results in `September 7, 1996`. * - * <p><big><b>Supported range</b></big> + * ***Supported range*** * - * <p>The allowable range of <code>Calendar</code> has been - * narrowed. <code>GregorianCalendar</code> used to attempt to support - * the range of dates with millisecond values from - * <code>Long.MIN_VALUE</code> to <code>Long.MAX_VALUE</code>. - * The new <code>Calendar</code> protocol specifies the + * 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 <code>-0x7F000000</code> to <code>+0x7F000000</code>. This - * corresponds to years from ~5,800,000 BCE to ~5,800,000 CE. Programmers - * should use the protected constants in <code>Calendar</code> to - * specify an extremely early or extremely late date.</p> + * 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 */ @@ -903,7 +886,7 @@ public: /** * Sets the behavior for handling wall time repeating multiple times * at negative time zone offset transitions. For example, 1:30 AM on - * November 6, 2011 in US Eastern time (Ameirca/New_York) occurs twice; + * November 6, 2011 in US Eastern time (America/New_York) occurs twice; * 1:30 AM EDT, then 1:30 AM EST one hour later. When <code>UCAL_WALLTIME_FIRST</code> * is used, the wall time 1:30AM in this example will be interpreted as 1:30 AM EDT * (first occurrence). When <code>UCAL_WALLTIME_LAST</code> is used, it will be @@ -1718,9 +1701,7 @@ protected: /** * Validate a single field of this calendar. Subclasses should * override this method to validate any calendar-specific fields. - * Generic fields can be handled by - * <code>Calendar::validateField()</code>. - * @see #validateField(int, int, int, int&) + * Generic fields can be handled by `Calendar::validateField()`. * @internal */ virtual void validateField(UCalendarDateFields field, UErrorCode &status); @@ -2171,7 +2152,7 @@ private: TimeZone* fZone; /** - * Option for rpeated wall time + * Option for repeated wall time * @see #setRepeatedWallTimeOption */ UCalendarWallTimeOption fRepeatedWallTime; @@ -2456,7 +2437,7 @@ private: BasicTimeZone* getBasicTimeZone() const; /** - * Find the previous zone transtion near the given time. + * Find the previous zone transition near the given time. * @param base The base time, inclusive * @param transitionTime Receives the result time * @param status The error status |