2.9 Creating a Date Object

NN 2, IE 3

2.9.1 Problem

You want to create an instance of a Date object to use for date calculations or display.

2.9.2 Solution

Use the Date object constructor method with any of the acceptable arguments signifying a date (and, optionally, a time for that date):

var myDate = new Date(yyyy, mm, dd, hh, mm, ss);
var myDate = new Date(yyyy, mm, dd);
var myDate = new Date("monthName dd, yyyy hh:mm:ss");
var myDate = new Date("monthName dd, yyyy");
var myDate = new Date(epochMilliseconds);

With all of these constructions, you can generate a date object for any point in history (reliably back to approximately 100 A.D.) or the future (thousands of millennia hence). When you create a date object without specifying the time, all time values are automatically set to zero—the very start of that day.

To create a date object with the current date and time, omit all arguments:

var now = new Date( );

The accuracy of the value assigned by the Date object constructor is entirely dependent upon the accuracy of the client computer's internal clock, control panel settings, and occasional browser anomalies. Correct setting of the computer's local time zone and daylight saving time option is essential to accurate date and time calculations based on the current date.

2.9.3 Discussion

Notice that the arguments for the Date object constructor—as specified in the ECMAScript standard—have no variation that readily accepts shortcut ways of entering dates (such as mm/dd/yyyy, or the numerous variations used around the world). Instead, numerical entries need to be broken into the component parts to be passed as discrete arguments for the constructor. If you need to generate a date object from user entries in a text box (or, better still, a series of three text boxes), you can pass the value properties of those text boxes directly as arguments of the constructor:

var dateEntry = new Date(document.myForm.year.value, 
                         document.myForm.month.value, 
                         document.myForm.date.value);

This is one of those many places where the JavaScript engine automatically attempts to cast a string value to the required number value.

Despite the lack of formal support for entry in formats such as mm/dd/yyyy or mm-dd-yyyy, browsers support them. Therefore, you can get away with supplying one of those formats to a constructor method, but remember that the sequence is only assured to work in browsers and operating systems whose date formats support that sequence. A North American browser, for instance, will misinterpret dates formatted as dd/mm/yyyy, which is a very common format outside North America.

It's important to remember that all of this date object creation and manipulation occurs strictly on the client. A client-side date object has no connection with the server's clock or time zone. At best, a server can timestamp a page as it leaves the server, but that has nothing to do with a date object on the client. Any attempt at synchronizing a client-side date object with the server clock is doomed due to latency between the serving of the page and the rendering in the client.

You are encouraged to restrict mission-critical date manipulation scripts to IE 4 or later and Navigator 4 or later. Earlier browsers contained numerous Date object bugs, especially in the area of time zone calculations.

2.9.4 See Also

Recipes 2.10 and Recipe 2.11 for date calculations; Recipe 2.12 for using regular expressions to validate date entries in a form; Recipe 15.7 and Recipe 15.8 for applications of a date object in showing much time is left before a future event.