From 2b19607bfae6f516a67740a5d89d8e004a53dbec Mon Sep 17 00:00:00 2001 From: Yoshito Umaoka Date: Mon, 18 Jun 2012 19:19:31 +0000 Subject: [PATCH] ICU-8918 Documentation update explaining ambiguous wall time resolution in the class doc. X-SVN-Rev: 31963 --- icu4c/source/i18n/unicode/calendar.h | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/icu4c/source/i18n/unicode/calendar.h b/icu4c/source/i18n/unicode/calendar.h index 7f28b84d706..b138df80f73 100644 --- a/icu4c/source/i18n/unicode/calendar.h +++ b/icu4c/source/i18n/unicode/calendar.h @@ -86,11 +86,12 @@ class BasicTimeZone; * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional). * *

- * When computing a UDate from time fields, two special circumstances + * 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), - * or there may be inconsistent information (such as "Tuesday, July 15, 1996" - * -- July 15, 1996 is actually a Monday). + * 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 @@ -125,6 +126,26 @@ class BasicTimeZone; * \htmlonly\endhtmlonly * *

+ * 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} 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 historial Arabic astronomical calendar requires year, -- 2.40.0