Proposal: TimeZone::getOffset() (Jitterbug 2966)

Jitterbug 2966
Expires September 3 2003

This proposal is to add a new method in the class TimeZone in ICU4C:

    /**
     * Returns the time zone raw and GMT offset for the given moment
     * in time.  Upon return, local-millis = GMT-millis + rawOffset +
     * dstOffset.  All computations are performed in the proleptic
     * Gregorian calendar.  The default implementation in the TimeZone
     * class delegates to the 8-argument getOffset().
     *
     * @param date moment in time for which to return offsets, in
     * units of milliseconds from January 1, 1970 0:00 GMT, either GMT
     * time or local wall time, depending on `local'.
     * @param local if true, `date' is local wall time; otherwise it
     * is in GMT time.
     * @param rawOffset output parameter to receive the raw offset, that
     * is, the offset not including DST adjustments
     * @param dstOffset output parameter to receive the DST offset,
     * that is, the offset to be added to `rawOffset' to obtain the
     * total offset between local and GMT time. If DST is not in
     * effect, this value is zero; otherwise it is a positive value,
     * typically one hour.
     * @param ec input-output error code
     *
     * @draft ICU 2.8
     */
    virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
                           int32_t& dstOffset, UErrorCode& ec) const;

Motivation: As of release 2.8, ICU4C will upgrade its implementation of 
time zone support to include full historical zoneinfo data (aka "Olson" 
data).  In release 2.6 and earlier, ICU only supported a subset of the 
zoneinfo data, specifically, those zones relevant to present practice, 
without the zoneinfo compatibility IDs.

Previously, calendars could assume that time zones that observed daylight 
savings time had a fixed "raw" offset from GMT (e.g., -8:00) together with 
a dst savings (e.g., 1:00) to be added to the raw offset at certain times 
of the year.  Time zones that did not observe DST were treated as having a 
fixed "raw" offset for all time.

With the inclusion of historical data, the way that calendars interact 
with TimeZone must change.  Now both the "raw" offset and the DST savings 
can change over time, and whether or not a time zone observes DST can also 
change.  As a result the old API combination of getRawOffset() + 
getOffset(<fields>) is insufficient.  Both the raw offset and the dst 
savings should be returned simultaneously for one moment in time.

Existing subclasses should not be affected, since the base class 
(TimeZone) will implement the new method to call existing methods.

Subclasses that are able to implement getOffset(UDate...) more efficiently 
should do so.

Alan Liu
IBM GCoC - San Jose