Sams Teach Yourself JavaScript in 24 Hours

Working with Dates

The Date object is a built-in JavaScript object that enables you to conveniently work with dates and times. You can create a Date object anytime you need to store a date, and use the Date object's methods to work with the date.

You encountered one example of a Date object in Hour 2, "Creating Simple Scripts," with the time/date script. The Date object has no properties. To set or obtain values from a Date object, you must use the methods described in the next section.

Creating a Date Object

You can create a Date object using the new keyword. You can also optionally specify the date to store in the object when you create it. You can use any of the following formats:

birthday = new Date();
birthday = new Date("June 20, 2003 08:00:00");
birthday = new Date(6, 20, 2003);
birthday = new Date(6, 20, 2003, 8, 0, 0);

You can choose any of these formats, depending on which values you wish to set. If you use no parameters, as in the first example, the current date is stored in the object. You can then set the values using the set methods, described in the next section.

Setting Date Values

A variety of set methods enable you to set components of a Date object to values:

• setDate() sets the day of the month.

• setMonth() sets the month. JavaScript numbers the months from 0 to 11, starting with January (0).

• setFullYear() sets the year.

• setTime() sets the time (and the date) by specifying the number of milliseconds since January 1, 1970.

• setHours(), setMinutes(), and setSeconds() set the time.

As an example, the following statement sets the year of a Date object called holiday to 2003:

holiday.setFullYear(2003);

Reading Date Values

You can use the get methods to get values from a Date object. This is the only way to obtain these values, because they are not available as properties. Here are the available get methods for dates:

• getdate() gets the day of the month.

• getMonth() gets the month.

• getFullYear() gets the year.

• getTime() gets the time (and the date) as the number of milliseconds since January 1, 1970.

• getHours(), getMinutes(), getSeconds(), and getMilliseconds() get the components of the time.

Working with Time Zones

Finally, a few functions are available to help your Date objects work with local time values and time zones:

• getTimeZoneOffset() gives you the local time zone's offset from UTC (Coordinated Universal Time, based on the old Greenwich Mean Time standard). In this case, local refers to the location of the browser. (Of course, this only works if the user has set his or her system clock accurately.)

• toUTCString() converts the date object's time value to text, using UTC. This method was introduced in JavaScript 1.2 to replace the toGMTString method, which still works but should be avoided.

• toLocalString() converts the date object's time value to text, using local time.

Along with these basic functions, JavaScript 1.2 and later include UTC versions of several of the functions described previously. These are identical to the regular commands, but work with UTC instead of local time:

• getUTCDate() gets the day of the month in UTC time.

• getUTCDay() gets the day of the week in UTC time.

• getUTCFullYear() gets the four-digit year in UTC time.

• getUTCMonth() returns the month of the year in UTC time.

• getUTCHours(), getUTCMinutes(), getUTCSeconds(), and getUTCMilliseconds() return the components of the time in UTC.

• setUTCDate(), setUTCFullYear(), setUTCMonth(), setUTCHours(), setUTCMinutes(), setUTCSeconds(), and setUTCMilliseconds() set the time in UTC.

Converting Between Date Formats

Two special methods of the Date object allow you to convert between date formats. Instead of using these methods with a Date object you created, you use them with the built-in object Date itself. These include the following:

• Date.parse() converts a date string, such as June 20, 1996, to a Date object (number of milliseconds since 1/1/1970).

• Date.UTC() does the opposite. It converts a Date object value (number of milliseconds) to a UTC (GMT) time.