JavaScript
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.
Syntax
Note: 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.
Parameters
Note: The argument monthIndex
is 0-based. This means that January = 0
and December = 11
.
Note: Where Date
is called as a constructor with more than one argument, if values are greater than their logical range (e.g. 13 is provided as the month value or 70 for the minute value), the adjacent value will be adjusted. E.g. new Date(2013, 13, 1)
is equivalent to new Date(2014, 1, 1)
, both create a date for 2014-02-01
(note that the month is 0-based). Similarly for other values: new Date(2013, 2, 1, 0, 70)
is equivalent to new Date(2013, 2, 1, 1, 10)
which both create a date for 2013-03-01T01:10:00
.
Note: Where Date
is called as a constructor with more than one argument, the specified arguments represent local time. If UTC is desired, use new Date(
Date.UTC(...)
) with the same arguments.
value
Integer value representing the number of milliseconds since January 1, 1970, 00:00:00 UTC, with leap seconds ignored (Unix Epoch; but consider that most Unix timestamp functions count in seconds).
dateString
String value representing a date. The string should be in a format recognised by the Date.parse()
method (IETF-compliant RFC 2822 timestamps and also a version of ISO8601).
Note: parsing of date strings with the Date
constructor (and Date.parse
, they are equivalent) is strongly discouraged due to browser differences and inconsistencies. Support for RFC 2822 format strings is by convention only. Support for ISO 8601 formats differs in that date-only strings (e.g. "1970-01-01") are treated as UTC, not local.
year
Integer value representing the year. Values from 0 to 99 map to the years 1900 to 1999. See the example below.
monthIndex
Integer value representing the month, beginning with 0 for January to 11 for December.
day
Optional. Integer value representing the day of the month.
hours
Optional. Integer value representing the hour of the day.
minutes
Optional. Integer value representing the minute segment of a time.
seconds
Optional. Integer value representing the second segment of a time.
milliseconds
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 for timezone offset.If at least two arguments are supplied, missing arguments are either set to 1 (if the day is missing) or 0 for all others.
The JavaScript date is based on a time value that is milliseconds since midnight January 1, 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 January 1, 1970 UTC.The JavaScript
Date
object provides uniform behavior across platforms. The time value can be passed between systems to create a date that represents the same moment in 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 thenew
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.
Examples
Several ways to create a Date
object
Date
objectThe following examples show several ways to create JavaScript dates:
Note: parsing of date strings with the Date constructor (and Date.parse, they are equivalent) is strongly discouraged due to browser differences and inconsistencies.
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.
Calculating elapsed time
The following examples show how to determine the elapsed time between two JavaScript dates in milliseconds.
Due to the differing lengths of days (due to daylight saving changeover), months and years, expressing elapsed time in units greater than hours, minutes and seconds requires addressing a number of issues and should be thoroughly researched before being attempted.
Note: In browsers that support the Web Performance API's high-resolution time feature, Performance.now()
can provide more reliable and precise measurements of elapsed time than Date.now()
.
Get the number of seconds since Unix Epoch
In this case it's important to return only a whole number (so a simple division won't do), and also to only return actually elapsed seconds (that's why this code uses Math.floor()
and not Math.round()
).
References
Contributors to this page
Uros Durdevic
Last updated