Speaking JavaScript

Chapter 20. Dates

JavaScript’s Date constructor helps with parsing, managing, and displaying dates. This chapter describes how it works.

The date API uses the term UTC (Coordinated Universal Time). For most purposes, UTC is a synonym for GMT (Greenwich Mean Time) and roughly means the time zone of London, UK.

The Date Constructor

There are four ways of invoking the constructor of Date:

new Date(year, month, date?, hours?, minutes?, seconds?, milliseconds?)

Constructs a new date from the given data. The time is interpreted relative to the current time zone. Date.UTC() provides similar functionality, but relative to UTC. The parameters have the following ranges:

• year: For 0 ≤ year ≤ 99, 1900 is added.
• month: 0–11 (0 is January, 1 is February, etc.)
• date: 1–31
• hours: 0–23
• minutes: 0–59
• seconds: 0–59
• milliseconds: 0–999

Here are some examples:

> new Date(2001, 1, 27, 14, 55)
Date {Tue Feb 27 2001 14:55:00 GMT+0100 (CET)}
> new Date(01, 1, 27, 14, 55)
Date {Wed Feb 27 1901 14:55:00 GMT+0100 (CET)}

As an aside, JavaScript has inherited the slightly weird convention of interpreting 0 as January, 1 as February, and so on, from Java.

new Date(dateTimeStr)

This is a date time string that is converted into a number, with which new Date(number) is invoked. Date Time Formats explains the date time formats. For example:

> new Date('2004-08-29')
Date {Sun Aug 29 2004 02:00:00 GMT+0200 (CEST)}

Illegal date time strings lead to NaN being passed to new Date(number).

new Date(timeValue)

Creates ...