Internationalization: Support for IANA time zones

L. David Baron dbaron at dbaron.org
Mon Mar 4 23:12:41 PST 2013


On Saturday 2013-03-02 10:34 -0800, Norbert Lindenberg wrote:
> I think a better solution would be API that either lets you easily
> generate a series of Date instances representing midnight (of
> every day, of every Monday, of every first day of the month, ...)
> in a specified time zone and calendar, or that lets you convert a
> Date to field-based time information in a specified time zone and
> calendar so that you can apply your own criteria.

The first of these is insufficient around daylight-savings time
cases for some uses, since it doesn't tell you when in the day the
time change is.

I think the second is also somewhat difficult to work with unless
one of the fields in question is a UTC offset; I believe (though I
admit I haven't written a large amount of timezone handling code).
It's often useful to work with epoch-based times and UTC offsets
rather than field-based times.

In my library that packed the tz database into JSON (one of many, it
sounds like), the API that I exposed was the following, quoting:
https://github.com/dbaron/tz.js/blob/3489978e9422c49f1bb4aafdfeee429a3e665136/tz.js.in#L191

    // Exports:
    window.tz = {
        /**
         * zoneAt(zone, dateObj)
         *   Given a valid named time zone and a JavaScript date object,
         *   return a zone object with two properties:
         *     offset: the UTC offset for the zone, in seconds
         *     abbr: the correct short name for the zone
         * For example,
         *   tz.zoneAt("America/Los_Angeles",
         *             new Date(Date.UTC(1976,6,4,18,0,0)))
         * (the time there is 1976-07-04 18:00:00 UTC) should return
         * an object like this:
         *   { offset: -25200, abbr: "PDT" }
         * since the America/Los_Angeles time zone observed summer time
         * at the time given, and was thus at offset UTC minus 7 hours
         * (or 25200 seconds), and used the abbreviation PDT (for
         * Pacific Daylight Time).
         */
        zoneAt: public_zoneAt,

        /**
         * datesFor(zone, year, month, day, hour, minute, second)
         *   Given a valid named time zone and a local time with:
         *     year >= 1970 (but not on January 1)
         *     month 1-12
         *     day 1-31
         *     hour 0-23
         *     minute 0-59
         *     second 0-59
         * returns an *array* of objects with three properties, the two
         * described above for zoneAt, and then a "date" property with a
         * JavaScript date object.  This array may have 0, 1, or 2
         * elements (and in theory it may have more in the future,
         * though the current code never produces such results).
         *
         * For example,
         *   tz.datesFor("America/Los_Angeles", 2011, 1, 1, 0, 0, 0)
         * will produce one result:
         * [
         *   { offset: -28800, abbr: "PST", date: (new Date(1293868800000)) }
         * ]
         * representing the moment of the new year 2011 in Los Angeles.
         * This is the common case.
         *
         * However, around summer time changes zero or two results can
         * occur.  For example:
         *   tz.datesFor("America/Los_Angeles", 2011, 3, 13, 2, 30, 0)
         * will produce an empty array since the start of summer time
         * causes the clock to jump from 2011-03-13 01:59:59 PST to
         * 2011-03-13 03:00:00 PDT.
         *
         * But this example:
         *   tz.datesFor("America/Los_Angeles", 2011, 11, 6, 1, 30, 0)
         * will produce two results:
         * [
         *   { offset: -25200, abbr: "PDT", date: (new Date(1320568200000)) }
         *   { offset: -28800, abbr: "PST", date: (new Date(1320571800000)) }
         * ]
         * representing times one hour apart, since the summer time
         * change makes the clock jump from 2011-11-06 01:59:59 PDT to
         * 2011-11-06 01:00:00 PST, and thus it passes 01:30 twice that
         * day.
         */
        datesFor: public_datesFor,

        /**
         * Return an array listing all supported named time zones, in
         * alphabetical order.  The same array will be returned from
         * each call.
         */
        allZones: public_allZones
    };

-David

-- 
𝄞   L. David Baron                         http://dbaron.org/   𝄂
𝄢   Mozilla                           http://www.mozilla.org/   𝄂


More information about the es-discuss mailing list