Re: [icu-design] ICU API Proposal: Calendar APIs for controlling ambiguous wall time

[<yos...@us...>]

If there are no objections from you by the end of today, I'll commit this 
work with the enum name WALLTIME_NEXT_AVAILABLE (instead of 
WALLTIME_MIN_LAST - which we discussed in the PMC) for the reason as 
stated in the message I sent a couple days ago.

Thanks,
Yoshito



From:   yos...@us...
To:     icu...@li..., 
Date:   02/16/2012 12:06 AM
Subject:        Re: [icu-design] ICU API Proposal: Calendar APIs for 
controlling     ambiguous wall time



In the PMC today, we agreed on the APIs with once comment. 

Change WALLTIME_NEXT_AVAILABLE to WALLTIME_MIN_LAST. I thought it might be 
OK, at that time. However, after the meeting, I was thinking about if the 
name really reflects what it does - Now I'm feeling the name MIN_LAST 
might not be appropriate. 

WALLTIME_FIRST/WALLTIME_LAST - are relatively easy to understand. 
Ambiguous time (without zone offset information) occurs both positive and 
negative zone transitions, because a wall time fall into these range have 
two possible interpretations. 

On negative transition (for example, fall transition - from DST to STD in 
US), 1:30 can be interpreted in two ways. 1:30 DST and 1:30 STD. They are 
both valid - and 1:30 DST occurs first, then 1:30 STD occurs later. 
WALLTIME_FIRST resolves 1:30 (with no zone offset info) as 1:30 DST (first 
occurrence of 1:30) and WALLTIME_LAST resolves 1:30 as 1:30 STD (last 
occurrence of 1:30). 

On positive transition (for example, spring transition - from STD to DST 
in US), 2:30 can be also interpreted in two ways. 31 minutes after 1:59 
STD and 30 minutes before 3:00 DST. Both are "virtual" thing - but 30 
minutes before 3:00 DST happens first, then 31 minutes after 1:59 STD 
happens later. WALLTIME_FIRST resolves 2:30 (with no zone offset info) as 
1:30 STD (30 minutes before 3:00 DST) and WALLTIME_LAST resolves 2:30 as 
3:30 DST (31 minutes after 1:59 STD). 

So, WALLTIME_FIRST simply species the earliest occurrence among two 
different interpretations and WALLTIME_LAST specifies the last occurrence 
among two interpretations. 

Now, WALLTIME_NEXT_AVAILABLE or WALLTIME_MIN_LAST. Let's think about how 
it works in Calendar 

// set 2011-03-13 02:30:00 
cal.set(2011, Calendar.MARCH, 13, 2, 30, 0); 

When "actual" time is being calculated, calendar detects the given wall 
time does not exist. With the option, the calendar resolves time/fields as 
2011-03-13 03:00 daylight saving time. 
The wall time jumps from 1:59:59.999 (in standard time) to 3:00:00.000 (in 
daylight time) on that day. The behavior of the option 
(WALLTIME_NEXT_AVAILABLE in the original proposal = WALLTIME_MIN_LAST 
updated by the PMC discussion) is simply picking up earliest valid wall 
time, but after the specified hour of day and minute. 
Operation 
The specified time exists? 
Local time resolved with WALLTIME_NEXT_AVAILABLE(WALLTIME_MIN_LAST) 
cal.set(2011, Calendar.MARCH, 13,1,59,59) 
Yes 
1:59:59 standard time 
cal.set(2011, Calendar.MARCH, 13,2,0,0) 
No 
3:00:00 daylight saving time 
cal.set(2011, Calendar.MARCH, 13,2,0,1) 
No 
3:00:00 daylight saving time 
... 
No 
3:00:00 daylight saving time 
cal.set(2011, Calendar.MARCH, 13,2,59,59) 
No 
3:00:00 daylight saving time 
cal.set(2011, Calendar.MARCH, 13,3,0,0) 
Yes 
3:00:00 daylight saving time 
cal.set(2011, Calendar.MARCH, 13,3,0,1) 
Yes 
3:00:01 daylight saving time


When you set a time fall into the non-existing range, the option behaves 
like - resolve the time as next valid/available moment on a wall clock. 
Input time in range between 02:00:00 and 02:59:59 will be resolved as 
03:00:00 with the option. 

I was initially thinking about several options for the naming - 1) next 
available 2) next valid 3) earliest future valid and etc. 2:30 AM on that 
day does not exist - so I'm not 100% sure the term - "next" or "future" is 
not crystal clear. But, I do not think "minimum last" is the right term. 

Do you think "minimum last" represents the behavior better than "next 
available" or "next valid"? I'm proposing to change it back to 
WALLTIME_NEXT_AVAILABLE (or NEXT_VALID). 

Please reply to this message ASAP if you still feel MIN_LAST is better. 


Thanks, 
Yoshito