JavaScript Date Class



Navigation Aids -- This Page        Navigation Aids -- This Topic        Navigation Aids -- This Site








Quick Reference for the Date Class



The Date Class Reference Table
Native class
Inherits From Object
Constants Properties Methods Constructors
Method Name UTC Syntax Arguments Returns
Footnote  UTC Column: Many of the "get" and "set" methods have an UTC version where "UTC" is built into the method's name. They either return or accept GMT time.
None None Class Methods
Date.parse( )
Date.UTC( )
Instance Methods
getDate( )
getDay( )
getFullYear( )
getHours( )
getMilliseconds( )
getMinutes( )
getMonth( )
getSeconds( )
getTime( )
getTimezoneOffset( )
getYear( )
setDate( )
setFullYear( )
setHours( )
setMilliseconds( )
setMinutes( )
setMonth( )
setSeconds( )
setTime( )
setYear( )
toDateString( )
toGMTString( )
toLocaleDateString( )
tolocaleString( )
toLocaleTimeString( )
toString( )
toTimeString( )
toUTCString( )
valueOf( )



getUTCDate( )
getUTCDay( )
getUTCFullYear( )
getUTCHours( )
getUTCMilliseconds( )
getUTCMinutes( )
getUTCMonth( )
getUTCSeconds( )



setUTCDate( )
setUTCFullYear( )
setUTCHours( )
setUTCMilliseconds( )
setUTCMinutes( )
setUTCMonth( )
setUTCSeconds( )










new Date( )

new Date(milliseconds)

new Date(datestring)

new Date(year,
month,
day,
hours,
minutes,
seconds,
ms)


milliseconds

datestring

year
month
day
hours
minutes
seconds
ms
A new Date.




Date Class Description

The Date class is a native class that provides and facilitates date and time capabilities in ECMAScript. Each date object encapsulates an internal number that represents milliseconds. In effect, the milliseconds number is the internal date (and time). The internal date is based on the Coordinated Universal Time (UTC) standard. The UTC standard has a starting point that begins on 01, January, 1970. On this date at exactly midnight the internal date would be zero at the GMT time zone. All dates beyond the starting point are incremented (86,400,000 milliseconds per day) accordingly. Date and times for each time zone (other than the GMT/UTC time zone) are computed from the UTC internal date using a time zone offset. Pacific Time has an eight hour (or 28,800,000 millisecond) offset from the internal UTC time.

To clarify the above, when you instantiate a new date object, the internal time for that date object is the UTC time at the GMT time zone. The internal date was not generated to include the time zone adjustment offset for local time. The Date class methods apply the time zone adjustment to arrive at the appropriate time. The Date class methods that contain "UTC" in the method name do not apply the time zone offset adjustment. These methods give you the time based on the exact value of the internal date (which is the UTC time of the GMT time zone at the time you instantiated the date object).

To illustrate, the date and time of "Sun, 18 Feb 2007 23:57:08 UTC" has the internal date of 1171843028375 milliseconds.





Date Class Constants

There are no explicit constants for the class.





Date Class Instance Properties

There are no explicit properties for the class. All access to date and time values is accomplished through the many "get" methods.

The Date class does inherit the following properties from the base Object class.





Date Class Methods

A class method is a static method. Class methods are not invoked through an object. Instead, they are invoked through the class. Class methods are prefixed with the constructor name of the class, followed by the access operator, and then the name of the method. Static methods have global scope, allowing their access from anywhere in your program. The Date class has exactly two static methods:



The Class Methods for the Date Class
Method
Syntax / Arguments
Method Returns Description / Example
 
Syntax:
Date.parse(date-part string)

Arguments: date-parts
the format of string is:

DOW MON DD hh:mm:ss TZD CCYY

  where:

DOW = Day of Week
MON = Month
DD = Day of Month
hh = hour (military)
mm = minute
ss = Second
TZD = Time Zone
CCYY = Century and Year
Returns a number representing the internal date in Milliseconds. The Date.parse( ) method behaves as follows:
  • returns milliseconds that represent the equivalent internal date
  • if the string passed into Date.parse() can not be converted to a date, the method will return NaN
  • the sequence of date parts is flexible, however CCYY, DD and MON are required
  • the appropriate punctuation for time is required or NaN will result
  • most implementation will accept MM/DD/CCYY format for date
  • AM and PM designators (as opposed to military time) are allowed to indicate time of day
  • the date parts applicable to the Date.parse() methods's argument are also applicable to the the Date constructor with the "datestring" argument option
  • be aware that ECMAScript does not specify the format for date and time that is parsed in the Date.parse string argument; some implementations could very from the format given here

Example:
//the next statement returns:1171751947000 (milliseconds) Date.parse("Sat Feb 17 14:39:07 PST 2007"); //the next examples are date part options Date.parse("Feb 17 2007");//minimum parts Date.parse("Feb 17 2007 14:");//add hour Date.parse("Feb 17 2007 14:39:07");//time parts Date.parse("Feb 17 2007 02:39:07PM");//PM works Date.parse("02/17/2007");//optional date format Date.parse("17 Feb 2007");//alternate date order Date.parse("2007");//returns NaN
Syntax:
Date.UTC(date-part)

Arguments: date-parts
the format is:

year, month, day, hours, minutes, seconds, ms

  where:
year: CCYY
month: 0 - 11
day: 1 - 31
hours: 1 - 23
minutes: 0 - 59
seconds: 0 - 59
ms: 0 - 999
Returns a number representing the internal date in Milliseconds. The Date.UTC( ) method behaves as follows:
  • returns milliseconds that represent the equivalent internal date
  • if the argument passed into Date.UTC() can not be converted to a date, the method will return NaN
  • the sequence of date parts as specified in the argument is fixed
  • the argument is not a string, it resembles a list where the date parts must be separated by commas
  • all date parts are optional except for the first two (year and month)
  • with the exception of day, all date parts start relative to zero, including month (January = 0)
  • the hour date part is military time (0 - 23)

Example:
//the next statement returns:1171751947625 (milliseconds) Date.UTC(2007, 1, 17, 14, 39, 07, 625); //the next examples are date part options Date.UTC(2007);//returns NaN Date.UTC(2007, 1, 17);//Feb 17 2007 Date.UTC(2007, 1, 17, 14, 39, 07);//date&time Date.UTC(2007, 1, 17, 14, 39, 07, 625); //an internal date can be reconstructed down to the last millisecond




Date Class Instance Methods

Other than the two true class methods discussed above, the remaining Date class methods are instance methods. Many of the Date instance methods come in two forms. One version of the methods will operate using local time. The methods with "UTC" as part of there name will operate using UTC time.

The Date class does inherit some methods from the base Object class. The explicit methods of the Date class are numerous. Three of these methods (toString, toLocaleString and valueOf) override the corresponding methods of the base Object class.

Three of the date methods are deprecated as of ECMAScript v3. The deprecated methods are: getYear(), setYear() and toGMTString().

The instance methods of the Date class are many. We have arbitrarily grouped the Date methods into the following groupings.

  1.  Local Time Date Part Methods
  2.  UTC Time Date Part Methods
  3.  toString Methods
  4.  Composite Methods




Local Time Date Part Methods

These local time methods have been isolated as a unique group for discussion purposes. There uniqueness revolves around the fact that they return or alter local time rather than GMT time. Recall that the internal date of an instantiated date object actually represents the UTC time of the GMT time zone. So, to express time for the local time zone, the internal date must be adjusted with the local time zone offset. All of the methods detailed in the following two tables apply the offset for local time.

The first table below shows the date part that is associated with each local time methods. The second table gives more specifics and examples.

Get Methods Set Methods Date Part Date Part Values
getDate( ) setDate( ) DD day of month values: 1 - 31
getDay( ) ---- DOW day of week values: 0 - 6
0 = Sunday
1 = Monday
2 = Tuesday
3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday
getFullYear( ) setFullYear( ) CCYY 2-digit century; 2-digit year
getHours( ) setHours( ) hh hour values: 0 - 23
getMilliseconds( ) setMilliseconds( ) ms milliseconds values: 0 - 999
getMinutes( ) setMinutes( ) mm minute values: 0 - 59
getMonth( ) setMonth( ) MON month values: 0 - 11
getSeconds( ) setSeconds( ) ss second values: 0 - 59
getTimezoneOffset( ) ---- offset offset values: minutes
getYear( ) setYear( ) CCYY 2-digit century; 2-digit year


The Methods That Work With Local Time Date Parts
Method
Syntax / Arguments
Method Returns Description / Example
 
Syntax:
getDate( )

Arguments: None
returns DD
values: 1 - 31
these get methods behaves as follows:
  • returns a string version of all or part of the internal date
  • the returned date parts are for local time of clients time zone
  • these methods use the time zone offset between local time and GMT time
  • the daylight savings time offset is also applied if applicable
  • warning: getMonth() return values are between 0 and 11, not 1 and 12
  • getTimezoneOffset() returns the number of minutes between GMT time zone and local time zone
  • the getYear() method is not standard ECMAScript; it returns the 4 - digit year from the internal date; for years between 1900 and 1999, some implementation may return a two digit year (subtract 1900 from year)
  • The deprecated getYear() should be avoided in favor of getFullYear()
  • valueOf() and getTime() return same value (the internal date)
  • when you establish your date with Date.parse(), the ms time part will be zero
  • when you establish your date using just the Date constructor and no arguments, the ms time part will be from zero to 999

Example:
//date and time is: Mar 5, 2007 14:39:07 //internal date is: 1173134347000 var mydate = new Date(Date.parse("March 5, 2007 14:39:07")); mydate.valueOf();//returns 1173134347000 mydate.getTime();//returns 1173134347000 mydate.getTimezoneOffset();//returns 480 mydate.getYear();//returns 2007 mydate.getFullYear();returns 2007 mydate.getMonth();returns 2 mydate.getHours();returns 14 mydate.getMinutes();returns 39 mydate.getSeconds();returns 7 mydate.getDate();returns 5 mydate.getDay();returns 1 (for Monday) mydate.getMilliseconds();returns 0 //ms are zero since we brought are date in with the Date.parse() method
Syntax:
getDay( )

Arguments: None
returns DOW
values: 0 - 6
where 0 = Sunday
Syntax:
getFullYear( )

Arguments: None
returns CCYY
Syntax:
getHours( )

Arguments: None
returns hh:
values are between
0 (midnight) and
23 (11 PM)
Syntax:
getMilliseconds( )

Arguments: None
returns ms:
values are between
0 and 999
Syntax:
getMinutes( )

Arguments: None
returns mm:
values are between
0 and 59
Syntax:
getMonth( )

Arguments: None
returns MON:
values are between
0 and 11
Syntax:
getSeconds( )

Arguments: None
returns ss:
values are between
0 and 59
Syntax:
getTimezoneOffset( )

Arguments: None
returns offset:
value is minutes
Syntax:
getYear( )

Arguments: None
returns CCYY
Syntax:
setDate(DD)

Arguments:
date part: DD
returns the adjusted date in milliseconds these set methods behaves as follows:
  • returns an integer in milliseconds representing the adjusted date
  • the date part of the argument replaces the corresponding internal date equivalent
  • the date parts used in method arguments are all integers
  • the date and time being adjusted is for local time
  • these methods use the time zone offset between local time and GMT time
  • the daylight savings time offset is also applied if applicable
  • warning: setMonth() arguments are between 0 and 11, not 1 and 12
  • The deprecated setYear() should be avoided in favor of setFullYear()
  • do not use negative date parts; although they seem to work for milliseconds

Example:
//date and time is: mar 5, 2007 14:39:07 //internal date is: 1173134347000 //each stmt below adjusts the above date //the adjustments are not accumulative //all adjustments reduce the date or time down one unit for that date part var mydate = new Date(Date.parse("March 5, 2007 14:39:07")); mydate.valueOf();//returns 1173134347000 mydate.setFullYear(2006);returns 1141598347000 mydate.setMonth(1);returns 1170715147000 mydate.setDate(4);returns 1173047947000 mydate.setHours(13);returns 1173130747000 mydate.setMinutes(38);returns 1173134287000 mydate.setSeconds(6);returns 1173134346000 mydate.setMilliseconds(-1);returns 1173134346999 //ms are zero since we brought are date in with the Date.parse() method
Syntax:
setFullYear(CCYY)
setFullYear(CCYY, MON)
setFullYear(CCYY, MON, DD)

Arguments:
date part: CCYY
optional: MON and DD
returns the adjusted date in milliseconds
Syntax:
setHours(hh)
setHours(hh, mm)
setHours(hh, mm, ss)
setHours(hh, mm, ss, ms)

Arguments:
date part: hh
optional: mm, ss, ms
returns the adjusted date in milliseconds
Syntax:
setMilliseconds(ms)

Arguments:
date part: ms
returns the adjusted date in milliseconds
Syntax:
setMinutes(mm)
setMinutes(mm, ss)
setMinutes(mm, ss, ms)

Arguments:
date part: mm
optional: ss, ms
returns the adjusted date in milliseconds
Syntax:
setMonth(MON)
setMonth(MON, DD)

Arguments:
date part: MON
optional: DD
returns the adjusted date in milliseconds
Syntax:
setSeconds(ss)
setSeconds(ss, ms)

Arguments:
date part: ss
optional: ms
returns the adjusted date in milliseconds
Syntax:
setYear( )

Arguments:
CCYY
returns the adjusted date in milliseconds




UTC Time Date Part Methods

These UTC time methods return or alter GMT time (rather than local time). Recall that the internal date of an instantiated date object actually represents the UTC time of the GMT time zone. Therefore, the UTC time methods do not apply a local time offset to arrive at the desired GMT time.

The first table below shows the date part that is associated with each UTC time method. The second table gives more specifics of the UTC time methods.

Get Methods Set Methods Date Part Date Part Values
getUTCDate( ) setUTCDate( ) day day of month values: 1 - 31
getUTCDay( ) ---- day of week day of week values: 0 - 6
0 = Sunday
1 = Monday
2 = Tuesday
3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday
getUTCFullYear( ) setUTCFullYear( ) year 2-digit century; 2-digit year
getUTCHours( ) setUTCHours( ) hours hour values: 0 - 23
getUTCMilliseconds( ) setUTCMilliseconds( ) millis milliseconds values: 0 - 999
getUTCMinutes( ) setUTCMinutes( ) minutes minute values: 0 - 59
getUTCMonth( ) setUTCMonth( ) month month values: 0 - 11
getUTCSeconds( ) setUTCSeconds( ) seconds second values: 0 - 59


The Methods That Work With UTC Time
Method
Syntax / Arguments
Method Returns Description / Example
 
Syntax:
getUTCDate( )

Arguments: None
returns day
values: 1 - 31
these get methods behaves as follows:
  • returns a string version of all or part of the internal date
  • the returned date parts are for UTC time of GMT time zone
  • these methods do not use the time zone offset between local time and GMT time
  • warning: getUTCMonth() return values are between 0 and 11, not 1 and 12

Example:
var mydate = new Date(Date.parse(2007, 2, 5, 23, 48, 22, 999)); mydate.valueOf();//returns 1173138502999 mydate.toUTCString();//returns Mon, 5 Mar 2007 23:48:22 UTC mydate.getUTCFullYear();returns 2007 mydate.getUTCMonth();returns 2 mydate.getUTCDay();returns 1 (for Monday) mydate.getUTCDate();returns 22 mydate.getUTCHours();returns 23 mydate.getUTCMinutes();returns 48 mydate.getUTCSeconds();returns 7 mydate.getUTCMilliseconds();returns 99
Syntax:
getUTCDay( )

Arguments: None
returns day of week
values: 0 - 6
where 0 = Sunday
Syntax:
getUTCFullYear( )

Arguments: None
returns 4-digit year
Syntax:
getUTCHours( )

Arguments: None
returns hours:
values are between
0 (midnight) and
23 (11 PM)
Syntax:
getUTCMilliseconds( )

Arguments: None
returns milliseconds:
values are between
0 and 999
Syntax:
getUTCMinutes( )

Arguments: None
returns minutes:
values are between
0 and 59
Syntax:
getUTCMonth( )

Arguments: None
returns month:
values are between
0 and 11
Syntax:
getUTCSeconds( )

Arguments: None
returns seconds:
values are between
0 and 59
Syntax:
setUTCDate(day)

Arguments:
date part: day
returns the adjusted date in milliseconds these set methods behaves as follows:
  • returns an integer in milliseconds representing the adjusted date
  • the date part of the argument replaces the corresponding internal date equivalent
  • the date parts used in method arguments are all integers
  • the date and time being adjusted is for local time
  • these methods use the time zone offset between local time and GMT time
  • the daylight savings time offset is also applied if applicable
  • warning: setMonth() arguments are between 0 and 11, not 1 and 12
  • do not use negative date parts; although they seem to work for milliseconds

Example:
//date and time is: mar 5, 2007 14:39:07 //internal date is: 1173134347000 //each stmt below adjusts the above date //the adjustments are not accumulative //all adjustments reduce the date or time down one unit for that date part var mydate = new Date(Date.parse("March 5, 2007 14:39:07")); mydate.valueOf();//returns 1173134347000 mydate.setFullYear(2006);returns 1141598347000 mydate.setMonth(1);returns 1170715147000 mydate.setDate(4);returns 1173047947000 mydate.setHours(13);returns 1173130747000 mydate.setMinutes(38);returns 1173134287000 mydate.setSeconds(6);returns 1173134346000 mydate.setMilliseconds(-1);returns 1173134346999 //ms are zero since we brought are date in with the Date.parse() method
Syntax:
setUTCFullYear(year)
setUTCFullYear(year, month)
setUTCFullYear(year, month, day)

Arguments:
date part: year
optional: month and day
returns the adjusted date in milliseconds
Syntax:
setUTCHours(hours)
setUTCHours(hours, minutes)
setUTCHours(hours, minutes, seconds)
setUTCHours(hours, minutes, seconds, millis)

Arguments:
date part: hours
optional: minutes, seconds, millis
returns the adjusted date in milliseconds
Syntax:
setUTCMilliseconds(millis)

Arguments:
date part: millis
returns the adjusted date in milliseconds
Syntax:
setUTCMinutes(minutes)
setUTCMinutes(minutes, seconds)
setUTCMinutes(minutes, seconds, millis)

Arguments:
date part: minutes
optional: seconds, millis
returns the adjusted date in milliseconds
Syntax:
setUTCMonth(month)
setUTCMonth(month, day)

Arguments:
date part: month
optional: day
returns the adjusted date in milliseconds
Syntax:
setUTCSeconds(seconds)
setUTCSeconds(seconds, millis)

Arguments:
date part: seconds
optional: millis
returns the adjusted date in milliseconds




Date Class toString Methods

Thus far we have described the methods that work with date parts (both local time and UTC time). The next group of methods are the date string methods. These methods return a string representing all or parts of the date and time for the object. Some assume UTC time and some assume local time. The toGMTString method is deprecate with ECMAScript v3 in favor of toUTCString.

Method Name Time Zone Returns/Example comment
toString( ) Local string representing the date and time
(Mon Mar 5 15:48:22 PST 2007)
The contents of the string are implementation-dependent, but are intended to represent the Date in the current time zone in a convenient, human-readable form.
toDateString( ) Local string representing the date
(Mon Mar 5 2007)
implementation dependent
toGMTString( ) UTC string representing the date and time
(Mon, 5 Mar 2007 23:48:22 UTC)
toGMTString( ) is deprecated in favor of toUTCString()
toLocaleDateString( ) Local string representing the date
(Monday, March 05, 2007)
implementation dependent
using local conventions
toLocaleString( ) Local string representing the date and time
(Monday, March 05, 2007 3:48:22 PM)
implementation dependent
using local conventions
toLocaleTimeString( ) Local string representing the time
(3:48:22 PM)
implementation dependent
using local conventions
toTimeString( ) Local string representing the time
(15:48:22 PST)
implementation dependent
toUTCString( ) UTC string representing the date
(Mon, 5 Mar 2007 23:48:22 UTC)
implementation dependent
uses universal time




Date Class Composite Methods

The composite methods all return the internal date of a date object that represents a given point in time (GMT time). The internal date is an integer representing milliseconds. The milliseconds represent the elapsed time between the moment the date object was instantiated and the official UTC starting point (The exact moment of midnight at the beginning of 01, January, 1970 UTC time).

The milliseconds represent an integer that is a composite of both date and time. The date and time parts can be derived from the composite integer by applying simple elapsed time formulas.



Method Name Time Zone Argument/Returns/Example comment
getTime( ) independent returns internal date
(1173134346999)
returns the internal date in milliseconds
setTime( ) independent the argument is an integer representing milliseconds
returns same value
date.setTime(1173134346999);
returns the internal date in milliseconds
valueOf( ) independent returns internal date
(1173134346999)
returns the internal date in milliseconds
valueOf and getTime methods will return identical data




Date Class Constructor





Date Class Constructor Example



Top            

Rx4AJAX        About Us | Topic Index | Contact Us | Privacy Policy | 2008 This Site Built By PPThompson