| Date | NN 2 IE 3 ECMA 1 | |||||||||||||||||||||||||||||||||||||||||||||||
|
The Date object is a static object that generates instances by way of several constructor functions. Each instance of a Date object is a snapshot of the date and time, measured in milliseconds relative to zero hours on January 1, 1970. Negative millisecond values represent time before that date; positive values represent time since that date. |
||||||||||||||||||||||||||||||||||||||||||||||||
The typical way to work with dates is to generate a new instance of the Date object, either for now or for a specific date and time (past or future, using the client local time). Then use the myriad of available date methods to get or set components of that time (e.g., minutes, hours, date, month). Browsers internally store a date as the millisecond value at Coordinated Universal Time (UTC, which is essentially the same as Greenwich Mean Time, or GMT). When you ask a browser for a component of that time, it automatically converts the value to the local time zone of the browser based on the client computer's control panel setting for the clock and time zone. If the control panel is set incorrectly, time and date calculations may go awry. |
||||||||||||||||||||||||||||||||||||||||||||||||
Early versions of scriptable browsers had numerous bugs when working with the Date object. One resource that explains the fundamental operations within the Date object (and bugs) can be found at http://developer.netscape.com/viewsource/goodman_dateobject.html. |
||||||||||||||||||||||||||||||||||||||||||||||||
| Properties | ||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||
| Methods | ||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||
| Creating a Date Object | ||||||||||||||||||||||||||||||||||||||||||||||||
var now = new Date( );
var myDate = new Date("month dd, yyyy hh:mm:ss");
var myDate = new Date("month dd, yyyy");
var myDate = new Date(yy, mm, dd, hh, mm, ss);
var myDate = new Date(yy, mm, dd);
var myDate = new Date(milliseconds);
|
||||||||||||||||||||||||||||||||||||||||||||||||
| constructor | NN 4 IE 4 ECMA 1 |
| Read/Write | |
|
This is a reference to the function that created the instance of a Date objectthe native Date( ) constructor function in browsers. |
|
| Example | |
if (myVar.constructor == Date) {
// process native string
}
|
|
| Value | |
Function object reference. |
|
| prototype | NN 3 IE 4 ECMA 1 |
| Read/Write | |
|
This is a property of the static Date object. Use the prototype property to assign new properties and methods to future instances of a Date value created in the current document. See the Array.prototype property description for examples. |
|
| Example | |
Date.prototype.author = "DG"; |
|
| Value | |
Any data, including function references. |
|
| getDate( ) | NN 2 IE 3 ECMA 1 |
|
Returns the calendar date within the month specified by an instance of the Date object. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 1 and 31. |
|
| getDay( ) | NN 2 IE 3 ECMA 1 |
|
Returns an integer corresponding to a day of the week for the date specified by an instance of the Date object. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 6. Sunday is 0, Monday is 1, and Saturday is 6. |
|
| getFullYear( ) | NN 4 IE 4 ECMA 1 |
|
Returns all digits of the year for the date specified by an instance of the Date object. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer. Navigator 4 goes no lower than zero. Internet Explorer and Netscape 6 return negative year values. |
|
| getHours( ) | NN 2 IE 3 ECMA 1 |
|
Returns a zero-based integer corresponding to the hours of the day for the date specified by an instance of the Date object. The 24-hour time system is used. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 23. |
|
| getMilliseconds( ) | NN 4 IE 4 ECMA 1 |
|
Returns a zero-based integer corresponding to the number of milliseconds past the seconds value of the date specified by an instance of the Date object. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 999. |
|
| getMinutes( ) | NN 2 IE 3 ECMA 1 |
|
Returns a zero-based integer corresponding to the minute value for the hour and date specified by an instance of the Date object. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 59. |
|
| getMonth( ) | NN 2 IE 3 ECMA 1 |
|
Returns a zero-based integer corresponding to the month value for the date specified by an instance of the Date object. That this method's values are zero-based frequently confuses scripters at first. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 11. January is 0, February is 1, and December is 11. |
|
| getSeconds( ) | NN 2 IE 3 ECMA 1 |
|
Returns a zero-based integer corresponding to the seconds past the nearest full minute for the date specified by an instance of the Date object. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 59. |
|
| getTime( ) | NN 2 IE 3 ECMA 1 |
|
Returns a zero-based integer corresponding to the number of milliseconds since January 1, 1970, to the date specified by an instance of the Date object. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer. |
|
| getTimezoneOffset( ) | NN 2 IE 3 ECMA 1 |
|
Returns a zero-based integer corresponding to the number of minutes difference between GMT and the client computer's clock for an instance of the Date object. Time zones to the west of GMT are positive values; time zones to the east are negative values. Numerous bugs plagued this method in early browsers, especially Macintosh versions. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between -720 and 720. |
|
| getUTCDate( ) | NN 4 IE 4 ECMA 1 |
|
Returns the calendar date within the month specified by an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 1 and 31. |
|
| getUTCDay( ) | NN 4 IE 4 ECMA 1 |
|
Returns an integer corresponding to a day of the week for the date specified by an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 6. Sunday is 0, Monday is 1, and Saturday is 6. |
|
| getUTCFullYear( ) | NN 4 IE 4 ECMA 1 |
|
Returns all digits of the year for the date specified by an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer. Navigator 4 goes no lower than zero. Internet Explorer and Netscape 6 return negative year values. |
|
| getUTCHours( ) | NN 4 IE 4 ECMA 1 |
|
Returns a zero-based integer corresponding to the hours of the day for the date specified by an instance of the Date object but in the UTC time stored internally by the browser. The 24-hour time system is used. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 23. |
|
| getUTCMilliseconds( ) | NN 4 IE 4 ECMA 1 |
|
Returns a zero-based integer corresponding to the number of milliseconds past the seconds value of the date specified by an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 999. |
|
| getUTCMinutes( ) | NN 4 IE 4 ECMA 1 |
|
Returns a zero-based integer corresponding to the minute value for the hour and date specified by an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 59. |
|
| getUTCMonth( ) | NN 4 IE 4 ECMA 1 |
|
Returns a zero-based integer corresponding to the month value for the date specified by an instance of the Date object but in the UTC time stored internally by the browser. That this method's values are zero-based frequently confuses scripters at first. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 11. January is 0, February is 1, and December is 11. |
|
| getUTCSeconds( ) | NN 4 IE 4 ECMA 1 |
|
Returns a zero-based integer corresponding to the seconds value past the nearest full minute of the date specified by an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 59. |
|
| getVarDate( ) | NN n/a IE 4 ECMA n/a |
|
Returns a date value in a format (called VT_DATE) suitable for a variety of Windows-oriented applications, such as ActiveX controls and VBScript. Not for use with JavaScript date calculations. |
|
| Parameters | |
None. |
|
| Returned Value | |
VT_DATE format value (not for JavaScript use). |
|
| getYear( ) | NN 2 IE 3 ECMA n/a |
|
Returns a number corresponding to the year of an instance of the Date object, but exhibits irregular behavior. In theory, the method should return the number of years the date object represents since 1900. This would produce a one- or two-digit value for all years between 1900 and 1999. However, when you reach 2000, the pattern fails. Instead of producing values starting with 100, the getYear( ) method, some browsers return the same four-digit value as getFullYear( ). For this reason, it is best to use getFullYear( ) whenever possible (but observe the browser compatibility for that method). Note that this method is not an ECMA-supported method, whereas getFullYear( ) is. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer between 0 and 99 for the years 1900 to 1999; four-digit integer starting with 2000 for some browsers, or a continuation (100+) for others. |
|
| parse( ) | NN 2 IE 3 ECMA 1 |
parse("dateString") | |
|
Static Date object method that returns the millisecond equivalent of the date specified as a string in the parameter. |
|
| Parameters | |
|
|
| Returned Value | |
Date in milliseconds. |
|
| setDate( ) | NN 2 IE 3 ECMA 1 |
setDate(dateInt) | |
|
Sets the date within the month for an instance of the Date object. If you specify a date beyond the end of the object's current month, the object recalculates the date in the succeeding month. For example, if a Date object is set to December 25, 2002, you can find out the calendar date ten days later with the following construction: myDate.setDate(myDate.getDate( ) + 10); |
|
After this calculation, the value of myDate is the equivalent of January 4, 2003. |
|
| Parameters | |
|
|
| Returned Value | |
New date in milliseconds. |
|
| setFullYear( ) | NN 4 IE 4 ECMA 1 |
setFullYear(yearInt) | |
|
Assigns the year for an instance of the Date object. |
|
| Parameters | |
|
|
| Returned Value | |
New date in milliseconds. |
|
| setHours( ) | NN 2 IE 3 ECMA 1 |
setHours(hourInt) | |
|
Sets the hours of the day for an instance of the Date object. The 24-hour time system is used. If you specify an hour beyond the end of the object's current day, the object recalculates the time in the succeeding day(s). |
|
| Parameters | |
|
|
| Returned Value | |
New date in milliseconds. |
|
| setMilliseconds( ) | NN 4 IE 4 ECMA 1 |
setMilliseconds(msInt) | |
|
Sets the number of milliseconds past the seconds value for an instance of the Date object. |
|
| Parameters | |
|
|
| Returned Value | |
New date in milliseconds. |
|
| setMinutes( ) | NN 2 IE 3 ECMA 1 |
setMinutes(minuteInt) | |
|
Sets the minute value for the hour and date of an instance of the Date object. |
|
| Parameters | |
|
|
| Returned Value | |
New date in milliseconds. |
|
| setMonth( ) | NN 2 IE 3 ECMA 1 |
setMonth(monthInt) | |
|
Sets the month value for the date of an instance of the Date object. That this method's values are zero-based frequently confuses scripters at first. |
|
| Parameters | |
|
|
| Returned Value | |
New date in milliseconds. |
|
| setSeconds( ) | NN 2 IE 3 ECMA 1 |
setSeconds(secInt) | |
|
Sets the seconds value past the nearest full minute for an instance of the Date object. |
|
| Parameters | |
|
|
| Returned Value | |
New date in milliseconds. |
|
| setTime( ) | NN 2 IE 3 ECMA 1 |
setTime(msInt) | |
|
Sets an instance of the Date object to the number of milliseconds since January 1, 1970. |
|
| Parameters | |
|
|
| Returned Value | |
New date in milliseconds. |
|
| setUTCDate( ) | NN 4 IE 4 ECMA 1 |
setUTCDate(dateInt) | |
|
Sets the date within the month of an instance of the Date object but in the UTC time stored internally by the browser. If you specify a date beyond the end of the object's current month, the object recalculates the date in the succeeding month. |
|
| Parameters | |
|
|
| Returned Value | |
New UTC date in milliseconds. |
|
| setUTCFullYear( ) | NN 4 IE 4 ECMA 1 |
setUTCFullYear(yearInt) | |
|
Sets all digits of the year for an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
|
|
| Returned Value | |
New UTC date in milliseconds. |
|
| setUTCHours( ) | NN 4 IE 4 ECMA 1 |
setUTCHours(hourInt) | |
|
Sets the hours of the day for an instance of the Date object but in the UTC time stored internally by the browser. The 24-hour time system is used. |
|
| Parameters | |
|
|
| Returned Value | |
New UTC date in milliseconds. |
|
| setUTCMilliseconds( ) | NN 4 IE 4 ECMA 1 |
setUTCMilliseconds(msInt) | |
|
Sets the number of milliseconds past the seconds value of an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
|
|
| Returned Value | |
New UTC date in milliseconds. |
|
| setUTCMinutes( ) | NN 4 IE 4 ECMA 1 |
setUTCMinutes(minuteInt) | |
|
Sets the minute value for the hour and date of an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
|
|
| Returned Value | |
New UTC date in milliseconds. |
|
| setUTCMonth( ) | NN 4 IE 4 ECMA 1 |
setUTCMonth(monthInt) | |
|
Sets the month value for an instance of the Date object but in the UTC time stored internally by the browser. That this method's values are zero-based frequently confuses scripters at first. |
|
| Parameters | |
|
|
| Returned Value | |
New UTC date in milliseconds. |
|
| setUTCSeconds( ) | NN 4 IE 4 ECMA 1 |
setUTCSeconds(secInt) | |
|
Sets the seconds value past the nearest full for an instance of the Date object but in the UTC time stored internally by the browser. |
|
| Parameters | |
|
|
| Returned Value | |
New UTC date in milliseconds. |
|
| setYear( ) | NN 2 IE 3 ECMA n/a |
setYear(yearInt) | |
|
Sets the year of an instance of a Date object. Use setFullYear( ) if the browser versions you support allow it. Note that this method is not an ECMA-supported method, whereas setFullYear( ) is. |
|
| Parameters | |
|
|
| Returned Value | |
New date in milliseconds. |
|
| toDateString( ) | NN 6 IE 5.5(Win) ECMA 3 |
|
Returns a string consisting only of the date portion of an instance of a Date object. The precise format is under the control of the browser and language, but U.S. English versions of both IE 6 for Windows and Netscape 6 return values in the format Ddd Mmm dd yyyy. |
|
| Parameters | |
None. |
|
| Returned Value | |
String. |
|
| toGMTString( ) | NN 2 IE 3 ECMA 1 |
|
Returns a string version of the GMT value of a Date object instance in a standardized format. This method does not alter the original Date object. For use in newer browsers, the toUTCString( ) method is recommended in favor of toGMTString( ). |
|
| Parameters | |
None. |
|
| Returned Value | |
String in the following format: dayAbbrev, dd mmm yyyy hh:mm:ss GMT. For example: Mon 05 Aug 2002 02:33:22 GMT |
|
| toLocaleDateString( ) | NN 6 IE 5.5(Win) ECMA 3 |
|
Returns a string consisting only of the date portion of an instance of a Date object. The precise format is under the control of the browser and language. IE 6 for Windows returns a value in the format fullDay, fullMonth dd, yyyy; Netscape 6 returns fullDay fullMonth dd yyyy. |
|
| Parameters | |
None. |
|
| Returned Value | |
String. |
|
| toLocaleString( ) | NN 2 IE 3 ECMA 1 | |||||||||
|
Returns a string version of the local time zone value of both the date and time from a Date object instance. The format may be localized for a particular country or an operating system's convention. |
||||||||||
| Parameters | ||||||||||
None. |
||||||||||
| Returned Value | ||||||||||
String in a variety of possible formats. Examples of U.S. versions of browsers include the following. |
||||||||||
|
||||||||||
| toLocaleTimeString( ) | NN 6 IE 5.5(Win) ECMA 3 |
|
Returns a string consisting only of the time portion of an instance of a Date object. The precise format is under the control of the browser and language. IE 6 for Windows returns a value in the format [h]h:mm:ss xM; Netscape 6 returns hh:mm:ss. |
|
| Parameters | |
None. |
|
| Returned Value | |
String. |
|
| toString( ) | NN 2 IE 4 ECMA 1 | |||||||||
|
This is a method used mostly by the browser itself to obtain a string version of an instance of a Date object when needed for display in dialog boxes or on-screen rendering. |
||||||||||
| Parameters | ||||||||||
None. |
||||||||||
| Returned Value | ||||||||||
String in a variety of possible formats. Here are examples for U.S. versions of browsers. |
||||||||||
|
||||||||||
| toTimeString( ) | NN 6 IE 5.5(Win) ECMA 3 |
|
Returns a string consisting only of the time portion of an instance of a Date object. The precise format is under the control of the browser and language. |
|
| Parameters | |
None. |
|
| Returned Value | |
String. |
|
| toUTCString( ) | NN 4 IE 4 ECMA 1 |
|
Returns a string version of the UTC value of a Date object instance in a standardized format. This method does not alter the original Date object. For use in newer browsers, the toUTCString( ) method is recommended in favor of toGMTString( ). |
|
| Parameters | |
None. |
|
| Returned Value | |
String in the following format: dayAbbrev dd mmm yyyy hh:mm:ss GMT. For example: Mon 05 Aug 2002 02:33:22 GMT |
|
| UTC( ) | NN 2 IE 3 ECMA 1 |
UTC(yyyy, mm, dd[, hh[, mm[, ss[, msecs]]]]) | |
|
This is a static method of the Date object that returns a numeric version of the date as stored internally by the browser for a Date object. Unlike parameters to the Date object constructor, the parameter values for the UTC( ) method must be in UTC time for the returned value to be accurate. This method does not generate a date object, as the Date object constructor does. |
|
| Parameters | |
|
|
| Returned Value | |
Integer of the UTC millisecond value of the date specified as parameters. |
|
| valueOf( ) | NN 4 IE 4 ECMA 1 |
|
Returns the object's value. |
|
| Parameters | |
None. |
|
| Returned Value | |
Integer millisecond count. |
|