Date With Offset
In JavaScript, all Date
s have a local time zone. On my computer:
var now = ;// Sun Apr 14 2013 09:49:16 GMT-0700 (PDT)
This makes working with time zones difficult. You can represent that date in
UTC with Date.prototype.toISOString
:
now;// "2013-04-14T16:49:16.576Z"
Unfortunately, you can't pass around an actual Date
in any other time zone.
Instead, create a DateWithOffset
:
var nowInUTC = 0;// Sun Apr 14 2013 16:49:16 GMT+0000
DateWithOffset
s
Creating The DateWithOffset
constructor works just like the Date
constructor, but
the last argument is always the offset from UTC in minutes. Some examples:
var nowInParis = 60;// Sun Apr 14 2013 17:49:16 GMT+0100 var theSameTimeInMelbourne = nowInParis 600;// Mon Apr 15 2013 02:49:16 GMT+1000
Date Parsing
If the first argument is a String and contains an offset end with "Z", it is treated as UTC time:
var newYearsGMTInBoston = new DateWithOffset("Jan 1 2013 00:00Z", -300);
// Mon Dec 31 2012 19:00:00 GMT-0500
If it's a String and doesn't contain an offset of end with "Z", it is treated as local to the given offset:
var newYearsInBoston = new DateWithOffset("Jan 1 2013 00:00", -300);
// Tue Jan 01 2013 00:00:00 GMT-0500
Similarly, DateWithOffset
s created with individual year, month, and day
(and, optionally, hours, minutes, seconds, and milliseconds) arguments are
treated as local to the given offset:
var newYearsInChicago = new DateWithOffset(2013, 0, 1, -360);
Note this behavior differs from that of the normal Date
constructor,
which treats such strings as local to the browser (or server execution
environment).
Rich Offset Objects
The last argument can be a Number
(as above) or anything that responds to
valueOf
. If you have richer time zone objects, you can pass them directly
into new DateWithOffset
:
var tokyo = name: 'Tokyo' { return 'Tokyo (GMT+0900)' } { return 540; }; var nowInTokyo = now tokyo;// Mon Apr 15 2013 01:49:16 GMT+0900
Note: the offset is that between this object and UTC, which means
that it is positive if the object's time zone is ahead of UTC and negative
if it is behind. This is the opposite of what
Date.prototype.getTimezoneOffset
returns.
Date
Compatibility with You can use a DateWithOffset
anywhere you use a Date
:
nowInUTC; // 16nowInParis; // 1365958156000theSameTimeInMelbourne; // 1365958156000newYearsInBoston; // 300 newYearsInBoston;newYearsInBoston; // Tue Jan 15 2013 00:00:00 GMT-0500
Additional Features
Get back the original offset:
nowInBoston.offset();
// -300
nowInTokyo.offset().toString();
// "Tokyo (GMT+0900)"
Get a new DateWithOffset
representing the same point in time at a
different UTC offset:
var nowInChicago = nowInBoston.withOffset(-300)
Get a plain Date
representing the same point in time at the local offset:
var nowInLocal = nowInParis.date();
Related Projects
node-time provides very similar functionality with a different API. It supports time zone names (not just offsets), but only runs in Node.
If you want time zone parsing support, try timezone-js or timezone.
If you want a richer library for parsing, validating, manipulating, and formatting dates, try Moment.js.
If all you need to do is map Rails time zone names to IANA ones, you'll love rails-timezone-js.