Revision 371565 of Date

  • Revision slug: JavaScript/Reference/Global_Objects/Date
  • Revision title: Date
  • Revision id: 371565
  • Created:
  • Creator: jlebar
  • Is current revision? No
  • Comment
Tags: 

Revision Content

Summary

Creates JavaScript Date instances which let you work with dates and times.

Syntax

new Date();
new Date(value);
new Date(dateString);
new Date(year, month, day [, hour, minute, second, millisecond]);

{{ note('Note that JavaScript Date objects can only be instantiated by calling JavaScript Date as a constructor: calling it as a regular function (i.e. without the new operator) will return a string rather than a Date object; unlike other JavaScript object types, JavaScript Date objects have no literal syntax.') }}

Date constructor 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 parse method (IETF-compliant RFC 2822 timestamps).
year
Integer value representing the year. For compatibility (in order to avoid the Y2K problem), you should always specify the year in full; use 1998, rather than 98.
month
Integer value representing the month, beginning with 0 for January to 11 for December.
day
Integer value representing the day of the month (1-31).
hour
Integer value representing the hour of the day (0-23).
minute
Integer value representing the minute segment (0-59) of a time reading.
second
Integer value representing the second segment (0-59) of a time reading.
millisecond
Integer value representing the millisecond segment (0-999) of a time reading.

Description

If you supply no arguments, the constructor creates a JavaScript Date object for today's date and time according to local time. If you supply some arguments but not others, the missing arguments are set to 0. If you supply any arguments, you must supply at least the year, month, and day. You can omit the hours, minutes, seconds, and milliseconds.

The JavaScript date is measured in 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 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 in a non-constructor context (i.e., without the new operator) will return a string representing the current time.

Properties

{{ Js_see_prototype("Date", "Properties") }}

prototype
Allows the addition of properties to a JavaScript Date object.

{{ jsOverrides("Function", "properties", "prototype") }}

Methods

{{ Js_see_prototype("Date", "Methods") }}

now
Returns the numeric value corresponding to the current time.
parse
Parses a string representation of a JavaScript date, and returns the number of milliseconds since January 1, 1970, 00:00:00, local time.
UTC
Accepts the same parameters as the longest form of the constructor, and returns the number of milliseconds in a JavaScript Date object since January 1, 1970, 00:00:00, universal time.

{{ jsOverrides("Function", "Methods", "now", "parse", "UTC") }}

JavaScript Date instances

{{ page("/en-US/docs/JavaScript/Reference/Global_Objects/Date/prototype") }}

Examples

Example: Several ways to assign dates

The following examples show several ways to assign JavaScript dates:

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

Example: Calculating elapsed time

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

// using static methods
var start = Date.now();
// the event you'd like to time goes here:
doSomethingForALongTime();
var end = Date.now();
var elapsed = end - start; // time in milliseconds
// if you have Date objects
var start = new Date();
// the event you'd like to time goes here:
doSomethingForALongTime();
var end = new Date();
var elapsed = end.getTime() - start.getTime(); // time in milliseconds
// if you want to test a function and get back its return
function printElapsedTime (fTest) {
	var nStartTime = Date.now(), vReturn = fTest(), nEndTime = Date.now();
	alert("Elapsed time: " + String(nEndTime - nStartTime) + " milliseconds");
	return vReturn;
}

yourFunctionReturn = printElapsedTime(yourFunction);

Example: ISO 8601 formatted dates

Date.toISOString() is now supported, so you can use that.

The following example demonstrates how to manually format a JavaScript date, in an ISO 8601 format using UTC:

/* use a function for the exact format desired... */
function ISODateString(d){
  function pad(n){return n<10 ? '0'+n : n}
  return d.getUTCFullYear()+'-'
      + pad(d.getUTCMonth()+1)+'-'
      + pad(d.getUTCDate())+'T'
      + pad(d.getUTCHours())+':'
      + pad(d.getUTCMinutes())+':'
      + pad(d.getUTCSeconds())+'Z'
}

var d = new Date();
console.log(ISODateString(d)); // prints something like 2009-09-28T19:03:12Z

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support {{ CompatUnknown() }} {{ CompatVersionUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatVersionUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

reports of browser compatibility

 

Revision Source

<h2 id="Summary" name="Summary">Summary</h2>
<p>Creates JavaScript&nbsp;<code>Date</code> instances which let you work with dates and times.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="brush: js">
new Date();
new Date(value);
new Date(dateString);
new Date(year, month, day [, hour, minute, second, millisecond]);
</pre>
<p>{{ note('Note that JavaScript <code>Date</code> objects can only be instantiated by calling JavaScript <code>Date</code> as a constructor: calling it as a regular function (i.e. without the <a href="/en-US/docs/JavaScript/Reference/Operators/new">new</a> operator) will return a string rather than a <code>Date</code> object; unlike other JavaScript object types, JavaScript <code>Date</code> objects have no literal syntax.') }}</p>
<h2 id="Parameters" name="Parameters">Date constructor parameters</h2>
<dl>
  <dt>
    <code>value</code></dt>
  <dd>
    Integer value representing the number of milliseconds since 1 January 1970 00:00:00 UTC (Unix Epoch).</dd>
</dl>
<dl>
  <dt>
    <code>dateString</code></dt>
  <dd>
    String value representing a date. The string should be in a format recognized by the <a href="/en/JavaScript/Reference/Global_Objects/Date/parse" title="en/JavaScript/Reference/Global_Objects/Date/parse">parse</a> method (<a class="external" href="http://tools.ietf.org/html/rfc2822#page-14" title="http://tools.ietf.org/html/rfc2822#page-14">IETF-compliant RFC 2822 timestamps</a>).</dd>
</dl>
<dl>
  <dt>
    <code>year</code></dt>
  <dd>
    Integer value representing the year. For compatibility (in order to avoid the Y2K problem), you should always specify the year in full; use <code>1998</code>, rather than <code>98</code>.</dd>
</dl>
<dl>
  <dt>
    <code>month</code></dt>
  <dd>
    Integer value representing the month, beginning with 0 for January to 11 for December.</dd>
</dl>
<dl>
  <dt>
    <code>day</code></dt>
  <dd>
    Integer value representing the day of the month (1-31).</dd>
</dl>
<dl>
  <dt>
    <code>hour</code></dt>
  <dd>
    Integer value representing the hour of the day (0-23).</dd>
</dl>
<dl>
  <dt>
    <code>minute</code></dt>
  <dd>
    Integer value representing the minute segment (0-59) of a time reading.</dd>
</dl>
<dl>
  <dt>
    <code>second</code></dt>
  <dd>
    Integer value representing the second segment (0-59) of a time reading.</dd>
</dl>
<dl>
  <dt>
    <code>millisecond</code></dt>
  <dd>
    Integer value representing the millisecond segment (0-999) of a time reading.</dd>
</dl>
<h2 id="Description" name="Description">Description</h2>
<p>If you supply no arguments, the constructor creates a JavaScript <code>Date</code> object for today's date and time according to local time. If you supply some arguments but not others, the missing arguments are set to 0. If you supply any arguments, you must supply at least the year, month, and day. You can omit the hours, minutes, seconds, and milliseconds.</p>
<p>The JavaScript&nbsp;date is measured in 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.</p>
<p>The JavaScript <code>Date</code> object provides uniform behavior across platforms.</p>
<p>The JavaScript&nbsp;<code>Date</code> 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.</p>
<p>Invoking JavaScript&nbsp;<code>Date</code> in a non-constructor context (i.e., without the <a href="/en/JavaScript/Reference/Operators/new" title="en/JavaScript/Reference/Operators/Special_Operators/new_Operator">new</a> operator) will return a string representing the current time.</p>
<h2 id="Properties" name="Properties">Properties</h2>
<p>{{ Js_see_prototype("Date", "Properties") }}</p>
<dl>
  <dt>
    <a href="/en/JavaScript/Reference/Global_Objects/Date/prototype" title="en/JavaScript/Reference/Global_Objects/Date/prototype">prototype</a></dt>
  <dd>
    Allows the addition of properties to a JavaScript&nbsp;<code>Date</code> object.</dd>
</dl>
<p>{{ jsOverrides("Function", "properties", "prototype") }}</p>
<h2 id="Methods" name="Methods">Methods</h2>
<p>{{ Js_see_prototype("Date", "Methods") }}</p>
<dl>
  <dt>
    <a href="/en/JavaScript/Reference/Global_Objects/Date/now" title="en/JavaScript/Reference/Global_Objects/Date/now">now</a></dt>
  <dd>
    Returns the numeric value corresponding to the current time.</dd>
  <dt>
    <a href="/en/JavaScript/Reference/Global_Objects/Date/parse" title="en/JavaScript/Reference/Global_Objects/Date/parse">parse</a></dt>
  <dd>
    Parses a string representation of a JavaScript date, and returns the number of milliseconds since January 1, 1970, 00:00:00, local time.</dd>
  <dt>
    <a href="/en/JavaScript/Reference/Global_Objects/Date/UTC" title="en/JavaScript/Reference/Global_Objects/Date/UTC">UTC</a></dt>
  <dd>
    Accepts the same parameters as the longest form of the constructor, and returns the number of milliseconds in a JavaScript&nbsp;<code>Date</code> object since January 1, 1970, 00:00:00, universal time.</dd>
</dl>
<p>{{ jsOverrides("Function", "Methods", "now", "parse", "UTC") }}</p>
<h2 id="Date_instances" name="Date_instances">JavaScript&nbsp;<code>Date</code> instances</h2>
<p>{{ page("/en-US/docs/JavaScript/Reference/Global_Objects/Date/prototype") }}</p>
<h2 id="Examples" name="Examples">Examples</h2>
<h3 id="Example:_Several_ways_to_assign_dates" name="Example:_Several_ways_to_assign_dates">Example: Several ways to assign dates</h3>
<p>The following examples show several ways to assign JavaScript&nbsp;dates:</p>
<pre class="brush: js">
var today = new Date();
var birthday = new Date("December 17, 1995 03:24:00");
var birthday = new Date(1995,11,17);
var birthday = new Date(1995,11,17,3,24,0);
</pre>
<h3 id="Example:_Calculating_elapsed_time" name="Example:_Calculating_elapsed_time">Example: Calculating elapsed time</h3>
<p>The following examples show how to determine the elapsed time between two JavaScript&nbsp;dates:</p>
<pre class="brush: js">
// using static methods
var start = Date.now();
// the event you'd like to time goes here:
doSomethingForALongTime();
var end = Date.now();
var elapsed = end - start; // time in milliseconds
</pre>
<pre class="brush: js">
// if you have Date objects
var start = new Date();
// the event you'd like to time goes here:
doSomethingForALongTime();
var end = new Date();
var elapsed = end.getTime() - start.getTime(); // time in milliseconds
</pre>
<pre class="brush: js">
// if you want to test a function and get back its return
function printElapsedTime (fTest) {
	var nStartTime = Date.now(), vReturn = fTest(), nEndTime = Date.now();
	alert("Elapsed time: " + String(nEndTime - nStartTime) + " milliseconds");
	return vReturn;
}

yourFunctionReturn =&nbsp;printElapsedTime(yourFunction);
</pre>
<h3 id="Example.3A_ISO_8601_formatted_dates">Example: ISO 8601 formatted dates</h3>
<p><a href="/en/JavaScript/Reference/Global_Objects/Date/toISOString" title="en/JavaScript/Reference/Global_Objects/Date/toISOString"><code>Date.toISOString()</code></a> is now supported, so you can use that.</p>
<p>The following example demonstrates how to manually format a JavaScript date, in an ISO 8601 format using UTC:</p>
<pre class="brush: js">
/* use a function for the exact format desired... */
function ISODateString(d){
  function pad(n){return n&lt;10 ? '0'+n : n}
  return d.getUTCFullYear()+'-'
      + pad(d.getUTCMonth()+1)+'-'
      + pad(d.getUTCDate())+'T'
      + pad(d.getUTCHours())+':'
      + pad(d.getUTCMinutes())+':'
      + pad(d.getUTCSeconds())+'Z'
}

var d = new Date();
console.log(ISODateString(d)); // prints something like 2009-09-28T19:03:12Z
</pre>
<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari (WebKit)</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE&nbsp;Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatVersionUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h3 id="reports_of_browser_compatibility">reports of browser compatibility</h3>
<ul>
  <li><a href="https://gist.github.com/2312309" title="https://gist.github.com/2312309">4/2012 </a><a href="https://gist.github.com/2312309" title="https://gist.github.com/2312309"><span class="edit instapaper_title" id="description">gist from </span>Yaffle <span class="edit instapaper_title" id="description">about toISOString/fromISOString/Native Date.parse cross-browser issues</span></a></li>
  <li><a href="http://dygraphs.com/date-formats.html" title="http://dygraphs.com/date-formats.html">3/14/2012 blog from danvk Comparing FF/IE/Chrome on Parsing Date Strings</a></li>
</ul>
<p>&nbsp;</p>
Revert to this revision