organicmaps/icu
13
Fork 0
mirror of https://github.com/unicode-org/icu.git synced 2025-04-21 12:40:02 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions 1

ICU-8918 Added a small section explaining ambiguous wall time resolution in the class doc.

Browse source 
X-SVN-Rev: 31962
This commit is contained in:
Yoshito Umaoka 2012-06-18 17:56:55 +00:00
parent fefba73e1d
commit 7fe5d0654f
1 changed files with 23 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
icu4j/main/classes/core/src/com/ibm/icu/util/Calendar.java
View file

@ -100,11 +100,12 @@ import com.ibm.icu.util.ULocale.Category;
* designate the week before week 1 of a year as week <em>n</em> of the previous
* year.
*
* <p> When computing a <code>Date</code> from time fields, two special
* <p> When computing a <code>Date</code> from time fields, some special
* circumstances may arise: there may be insufficient information to compute the
* <code>Date</code> (such as only year and month but no day in the month), or
* <code>Date</code> (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.
*
* <p><strong>Insufficient information.</strong> 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</pre>
* </blockquote>
*
* <p><strong>Ambiguous Wall Clock Time.</strong> 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.
*
* <p>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
* {@link #setRepeatedWallTimeOption(int)} and {@link #setSkippedWallTimeOption(int)}.
* These methods are available in ICU 49 or later versions.
*
* <p><strong>Note:</strong> for some non-Gregorian calendars, different
* fields may be necessary for complete disambiguation. For example, a full