December 6, 1999 - GMT and Local Dates | WebReference

December 6, 1999 - GMT and Local Dates

Yehuda Shiran December 6, 1999
GMT and Local Dates
Tips: December 1999

Yehuda Shiran, Ph.D.
Doc JavaScript

JavaScript's Date object features various methods that deal with dates. The following statement creates an instance of the Date object, representing the current date:

var myDate = new Date(); // current date

JavaScript stores all dates as the number of milliseconds before (positive) or after (negative) zero hours Greenwich Mean Time (GMT) on January 1, 1970. Therefore, the getTime() method returns the number of milliseconds (+ or -) since zero hours GMT, January 1, 1970. However, most of the methods work with the local time. When designing your script, bear in mind that visitors are most likely to be located in time zones other than yours. Take a look at the following statement:

var myDate = new Date(1999, 1, 18, 1, 0, 0);

The numbers handed to the Date object stand for 1:00 A.M. on February 18, 1999. JavaScript treats these numbers as local specifications. Therefore, the actual GMT time differs depending on the user's local time zone. For someone in Israel (GMT +02:00), the object's GMT value is 11:00 P.M. on February 17, 1999. For someone in California (GMT -08:00) the GMT value would be 9:00 A.M. on February 18, 1999. We'll use the Date.UTC() method to solve this problem by defining the accurate GMT time:

var myDate = new Date(Date.UTC(1999, 1, 18, 1, 0, 0));

Notice that UTC() is a static method of Date, so you always use it as Date.UTC(), rather than as a method of a Date object you created. It returns the number of milliseconds between midnight, January 1, 1970 Universal Coordinated Time (UTC) and the supplied date. Universal Coordinated Time refers to the time as set by the World Time Standard, previously referred to as Greenwich Mean Time or GMT.

The general syntax of the Date.UTC() method is:

Date.UTC(year, month, day[, hours[, minutes[, seconds[, ms]]]])

The method's arguments are:

year (required): The full year is required for cross-century date accuracy. If year between 0 and 99 is used, then year is assumed to be 1900 + year.
  • month (required): The month as an integer between 0 and 11 (January to December).
  • date (required): The date as an integer between 1 and 31.
  • hours (optional): Must be supplied if minutes is supplied. An integer from 0 to 23 (midnight to 11pm) that specifies the hour.
  • minutes (optional): Must be supplied if seconds is supplied. An integer from 0 to 59 that specifies the minutes.
  • seconds (optional): Must be supplied if milliseconds is supplied. An integer from 0 to 59 that specifies the seconds.
  • ms (optional): An integer from 0 to 999 that specifies the milliseconds.

    If a parameter you specify is outside of the expected range, the UTC() method updates the other parameters to allow for your number. For example, if you use 15 for month, the year will be incremented by 1, and 3 will be used for the month. The difference between the UTC() method and the Date object constructor that accepts a date is that the UTC() method assumes UTC, and the Date object constructor assumes local time.

    The Date object accepts different types of arguments. We have already worked with an integer argument, specifying the number of milliseconds between midnight, January 1, 1970 Universal Coordinated Time (UTC) and the supplied date. Likewise, we can specify a date string:

    var myDate1 = new Date("18 Feb 1999 6:00:00 GMT");
var myDate2 = new Date("18 Feb 1999 1:00:00 GMT-0500");
var myDate3 = new Date("18 Feb 1999 1:00:00 EST");

    These definitions reflect the same date. The first statement specifies the time in standard GMT (UTC) time. The second statement specifies the time in a zone that is five hours west of GMT (such as EST). The third statement uses one of the common time zone abbreviations used in the western hemisphere (EST, EDT, CST, CDT, MST, MDT, PST, and PDT). Note that JavaScript also handles the GMT and UTC abbreviations.

    For more information about GMT time, refer to the U.S. Naval Observatory's Time Service Department. Related JavaScript issues are discussed in JavaScript Date Object Techniques, by Danny Goodman.