From 7fe5d0654fe0fc384766781e37c05053aa28148f Mon Sep 17 00:00:00 2001 From: Yoshito Umaoka Date: Mon, 18 Jun 2012 17:56:55 +0000 Subject: [PATCH] ICU-8918 Added a small section explaining ambiguous wall time resolution in the class doc. X-SVN-Rev: 31962 --- .../core/src/com/ibm/icu/util/Calendar.java | 26 ++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/icu4j/main/classes/core/src/com/ibm/icu/util/Calendar.java b/icu4j/main/classes/core/src/com/ibm/icu/util/Calendar.java index e4727b85adc..a1f471e7a52 100644 --- a/icu4j/main/classes/core/src/com/ibm/icu/util/Calendar.java +++ b/icu4j/main/classes/core/src/com/ibm/icu/util/Calendar.java @@ -100,11 +100,12 @@ import com.ibm.icu.util.ULocale.Category; * designate the week before week 1 of a year as week n of the previous * year. * - *

When computing a Date from time fields, two special + *

When computing a Date from time fields, some special * circumstances may arise: there may be insufficient information to compute the - * Date (such as only year and month but no day in the month), or + * Date (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). + * 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 @@ -133,6 +134,25 @@ import com.ibm.icu.util.ULocale.Category; * HOUR_OF_DAY * AM_PM + HOUR * + * + *

Ambiguous Wall Clock Time. When time offset from UTC has + * changed, it produces 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 1:00 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(int)} and {@link #setSkippedWallTimeOption(int)}. + * 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 -- 2.40.0