Core JavaScript 1.5 Reference:Global Objects:Date

From MDC

Contents 1 Summary 2 Syntax 3 Parameters 4 Description 5 Properties 6 Methods 7 Date instances 7.1 Properties 7.2 Methods 8 Examples 8.1 Example: Several ways to assign dates 8.2 Example: Calculating elapsed time

Summary

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

Syntax

new Date()
new Date(milliseconds)
new Date(dateString)
new Date(year, month, date [, hour, minute, second, millisecond ])

Parameters

milliseconds 

Integer value representing the number of milliseconds since 1 January 1970 00:00:00 UTC.

dateString 

String value representing a date. The string should be in a format recognized by the parse method.

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.

date

Integer value representing the day of the month.

hour

Integer value representing the hour of the day (24-hour scale).

minute

Integer value representing the minute segment of a time reading.

second

Integer value representing the second segment of a time reading.

millisecond

Integer value representing the millisecond segment of a time reading.

Description

If you supply no arguments, the constructor creates a 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 date is measured in milliseconds since midnight 01 January, 1970 UTC. A day holds 86,400,000 milliseconds. The Date object range is -100,000,000 days to 100,000,000 days relative to 01 January, 1970 UTC.

The Date object provides uniform behavior across platforms.

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

Properties

For properties inherited by Date instances, see Properties of Date instances.

prototype

Allows the addition of properties to a Date object.

Methods

For methods inherited by Date instances, see Methods of Date instances.

now

Returns the numeric value corresponding to the current time.

parse

Parses a string representation of a 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 Date object since January 1, 1970, 00:00:00, universal time.

Date instances

Date instances inherit from Date.prototype. You can modify the constructor's prototype object to affect properties and methods inherited by Date instances.

For compatibility with millennium calculations (in other words, to take into account the year 2000), you should always specify the year in full; for example, use 1998, not 98. To assist you in specifying the complete year, JavaScript includes the methods getFullYear, setFullYear, getUTCFullYear, and setUTCFullYear.

Properties

constructor

Returns the function that created an instance. This is the Date constructor by default.

Methods

getDate

Returns the day of the month for the specified date according to local time.

getDay

Returns the day of the week for the specified date according to local time.

getFullYear

Returns the year of the specified date according to local time.

getHours

Returns the hour in the specified date according to local time.

getMilliseconds

Returns the milliseconds in the specified date according to local time.

getMinutes

Returns the minutes in the specified date according to local time.

getMonth

Returns the month in the specified date according to local time.

getSeconds

Returns the seconds in the specified date according to local time.

getTime

Returns the numeric value of the specified date as the number of milliseconds since January 1, 1970, 00:00:00 UTC.

getTimezoneOffset

Returns the time-zone offset in minutes for the current locale.

getUTCDate

Returns the day (date) of the month in the specified date according to universal time.

getUTCDay

Returns the day of the week in the specified date according to universal time.

getUTCFullYear

Returns the year in the specified date according to universal time.

getUTCHours

Returns the hours in the specified date according to universal time.

getUTCMilliseconds

Returns the milliseconds in the specified date according to universal time.

getUTCMinutes

Returns the minutes in the specified date according to universal time.

getUTCMonth

Returns the month in the specified date according to universal time.

getUTCSeconds

Returns the seconds in the specified date according to universal time.

getYear

Deprecated

Returns the year in the specified date according to local time. Use getFullYear instead.

setDate

Sets the day of the month for a specified date according to local time.

setFullYear

Sets the full year for a specified date according to local time.

setHours

Sets the hours for a specified date according to local time.

setMilliseconds

Sets the milliseconds for a specified date according to local time.

setMinutes

Sets the minutes for a specified date according to local time.

setMonth

Sets the month for a specified date according to local time.

setSeconds

Sets the seconds for a specified date according to local time.

setTime

Sets the Date object to the time represented by a number of milliseconds since January 1, 1970, 00:00:00 UTC.

setUTCDate

Sets the day of the month for a specified date according to universal time.

setUTCFullYear

Sets the full year for a specified date according to universal time.

setUTCHours

Sets the hour for a specified date according to universal time.

setUTCMilliseconds

Sets the milliseconds for a specified date according to universal time.

setUTCMinutes

Sets the minutes for a specified date according to universal time.

setUTCMonth

Sets the month for a specified date according to universal time.

setUTCSeconds

Sets the seconds for a specified date according to universal time.

setYear

Deprecated

Sets the year for a specified date according to local time. Use setFullYear instead.

toDateString

Returns the "date" portion of the Date as a human-readable string.

toGMTString

Deprecated

Converts a date to a string, using the Internet GMT conventions. Use toUTCString instead.

toLocaleDateString

Returns the "date" portion of the Date as a string, using the current locale's conventions.

toLocaleFormat

Non-standard

Converts a date to a string, using a format string.

toLocaleString

Converts a date to a string, using the current locale's conventions. Overrides the Object.toLocaleString method.

toLocaleTimeString

Returns the "time" portion of the Date as a string, using the current locale's conventions.

toSource

Non-standard

Returns a string representing the source for an equivalent Date object; you can use this value to create a new object. Overrides the Object.prototype.toSource method.

toString

Returns a string representing the specified Date object. Overrides the Object.prototype.toString method.

toTimeString

Returns the "time" portion of the Date as a human-readable string.

toUTCString

Converts a date to a string, using the universal time convention.

valueOf

Returns the primitive value of a Date object. Overrides the Object.prototype.valueOf method.

Examples

Example: Several ways to assign dates

The following examples show several ways to assign dates:

today = new Date();
birthday = new Date("December 17, 1995 03:24:00");
birthday = new Date(1995,11,17);
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 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