Date

Summary

Creates a JavaScript Date instance that represents a single moment in time. Date objects are based on a time value that is the number of milliseconds since 1 January, 1970 UTC.

Constructor

new Date();
new Date(value);
new Date(dateString);
new Date(year, month[, day[, hour[, minutes[, seconds[, milliseconds]]]]]);

Parameters

value

Integer value representing the number of milliseconds since 1 January 1970 00:00:00 UTC (Unix Epoch).

dateString

String value representing a date. The string should be in a format recognized by the Date.parse() method (IETF-compliant RFC 2822 timestamps and also a version of ISO8601).

year

Integer value representing the year. Values from 0 to 99 map to the years 1900 to 1999. See the example below.

month

Integer value representing the month, beginning with 0 for January to 11 for December.

day

Optional. Integer value representing the day of the month.

hour

Optional. Integer value representing the hour of the day.

minute

Optional. Integer value representing the minute segment of a time.

second

Optional. Integer value representing the second segment of a time.

millisecond

Optional. Integer value representing the millisecond segment of a time.

Description

• If no arguments are provided, the constructor creates a JavaScript Date object for the current date and time according to system settings.
• If at least two arguments are supplied, missing arguments are either set to 1 (if day is missing) or 0 for all others.
• The JavaScript date is based on a time value that is milliseconds since midnight 01 January, 1970 UTC. A day holds 86,400,000 milliseconds. The JavaScript Date object range is -100,000,000 days to 100,000,000 days relative to 01 January, 1970 UTC.
• The JavaScript Date object provides uniform behavior across platforms. The time value can be passed between systems to represent the same moment in time and if used to create a local date object, will reflect the local equivalent of the time.
• The JavaScript Date object supports a number of UTC (universal) methods, as well as local time methods. UTC, also known as Greenwich Mean Time (GMT), refers to the time as set by the World Time Standard. The local time is the time known to the computer where JavaScript is executed.
• Invoking JavaScript Date as a function (i.e., without the new operator) will return a string representing the current date and time.

Properties

Date.prototype

Allows the addition of properties to a JavaScript Date object.

Date.length

The value of Date.length is 7. This is the number of arguments handled by the constructor.

Methods

Date.now()

Returns the numeric value corresponding to the current time - the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC.

Date.parse()

Parses a string representation of a date and returns the number of milliseconds since 1 January, 1970, 00:00:00, UTC.

Date.UTC()

Accepts the same parameters as the longest form of the constructor (i.e. 2 to 7) and returns the number of milliseconds since 1 January, 1970, 00:00:00 UTC.

JavaScript Date instances

All Date instances inherit from Date.prototype. The prototype object of the Date constructor can be modified to affect all Date instances.

Date.prototype Methods

Examples

Example: Several ways to create a Date object

The following examples show several ways to create JavaScript dates:

var today = new Date();
var birthday = new Date('December 17, 1995 03:24:00');
var birthday = new Date('1995-12-17T03:24:00');
var birthday = new Date(1995, 11, 17);
var birthday = new Date(1995, 11, 17, 3, 24, 0);

Example: Two digit years map to 1900 - 1999

In order to create and get dates between the years 0 and 99 the Date.prototype.setFullYear() and Date.prototype.getFullYear() methods should be used.

var date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

// Deprecated method, 98 maps to 1998 here as well
date.setYear(98);           // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

date.setFullYear(98);       // Sat Feb 01 0098 00:00:00 GMT+0000 (BST)

Example: Calculating elapsed time

The following examples show how to determine the elapsed time between two JavaScript dates:

// using Date objects
var start = Date.now();

// the event to time goes here:
doSomethingForALongTime();
var end = Date.now();
var elapsed = end - start; // elapsed time in milliseconds

// using built-in methods
var start = new Date();

// the event to time goes here:
doSomethingForALongTime();
var end = new Date();
var elapsed = end.getTime() - start.getTime(); // elapsed time in milliseconds

// to test a function and get back its return
function printElapsedTime(fTest) {
  var nStartTime = Date.now(),
      vReturn = fTest(),
      nEndTime = Date.now();

  console.log('Elapsed time: ' + String(nEndTime - nStartTime) + ' milliseconds');
  return vReturn;
}

yourFunctionReturn = printElapsedTime(yourFunction);

Specifications

Browser compatibility

Reports of browser compatibility

• 4/2012 gist from Yaffle about toISOString/fromISOString/Native Date.parse cross-browser issues
• 3/14/2012 blog from danvk Comparing FF/IE/Chrome on Parsing Date Strings

Internet Explorer specific notes

ISO8601 Date Format is not supported in Internet Explorer 8.