Section 24.23. Date: manipulate dates and times


24.23. Date: manipulate dates and times

ECMAScript v1: Object Date

24.23.1. Constructor

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

With no arguments, the Date( ) constructor creates a Date object set to the current date and time. When one numeric argument is passed, it is taken as the internal numeric representation of the date in milliseconds, as returned by the getTime( ) method. When one string argument is passed, it is a string representation of a date, in the format accepted by the Date.parse( ) method. Otherwise, the constructor is passed between two and seven numeric arguments that specify the individual fields of the date and time. All but the first two argumentsthe year and month fieldsare optional. Note that these date and time fields are specified using local time, not Coordinated Universal Time (UTC) (which is similar to Greenwich Mean Time [GMT]). See the static Date.UTC( ) method for an alternative.

Date( ) may also be called as a function, without the new operator. When invoked in this way, Date( ) ignores any arguments passed to it and returns a string representation of the current date and time.

24.23.1.1. Arguments

milliseconds

The number of milliseconds between the desired date and midnight on January 1, 1970 (UTC). For example, passing the argument 5000 creates a date that represents five seconds past midnight on 1/1/70.


datestring

A single argument that specifies the date and, optionally, the time as a string. The string should be in a format accepted by Date.parse( ).


year

The year, in four-digit format. For example, specify 2001 for the year 2001. For compatibility with early implementations of JavaScript, if this argument is between 0 and 99, 1900 is added to it.


month

The month, specified as an integer from 0 (January) to 11 (December).


day

The day of the month, specified as an integer from 1 to 31. Note that this argument uses 1 as its lowest value, while other arguments use 0 as their lowest value. Optional.


hours

The hour, specified as an integer from 0 (midnight) to 23 (11 p.m.). Optional.


minutes

The minutes in the hour, specified as an integer from 0 to 59. Optional.


seconds

The seconds in the minute, specified as an integer from 0 to 59. Optional.


ms

The milliseconds in the second, specified as an integer from 0 to 999. Optional.

24.23.2. Methods

The Date object has no properties that can be read and written directly; instead, all access to date and time values is done through methods. Most methods of the Date object come in two forms: one that operates using local time and one that operates using universal (UTC or GMT) time. If a method has "UTC" in its name, it operates using universal time. These pairs of methods are listed together below. For example, the listing for get[UTC]Day( ) refers to both the methods getday( ) and getUTCDay( ).

Date methods may be invoked only on Date objects, and they throw a TypeError exception if you attempt to invoke them on any other type of object:


get[UTC]Date( )

Returns the day of the month of a Date object, in local or universal time.


get[UTC]Day( )

Returns the day of the week of a Date object, in local or universal time.


get[UTC]FullYear( )

Returns the year of the date in full four-digit form, in local or universal time.


get[UTC]Hours( )

Returns the hours field of a Date object, in local or universal time.


get[UTC]Milliseconds( )

Returns the milliseconds field of a Date object, in local or universal time.


get[UTC]Minutes( )

Returns the minutes field of a Date object, in local or universal time.


get[UTC]Month( )

Returns the month field of a Date object, in local or universal time.


get[UTC]Seconds( )

Returns the seconds field of a Date object, in local or universal time.


getTime( )

Returns the internal, millisecond representation of a Date object. Note that this value is independent of time zone, and therefore, there is not a separate getUTCTime( ) method.


getTimezoneOffset( )

Returns the difference, in minutes, between the local and UTC representations of this date. Note that the value returned depends on whether daylight saving time is or would be in effect at the specified date.


getYear( )

Returns the year field of a Date object. Deprecated in favor of getFullYear( ).


set[UTC]Date( )

Sets the day of the month field of the date, using local or universal time.


set[UTC]FullYear( )

Sets the year (and optionally month and day) field of the date, using local or universal time.


set[UTC]Hours( )

Sets the hour field (and optionally the minutes, seconds, and milliseconds fields) of the date, using local or universal time.


set[UTC]Milliseconds( )

Sets the milliseconds field of a date, using local or universal time.


set[UTC]Minutes( )

Sets the minutes field (and optionally the seconds and milliseconds fields) of a date, using local or universal time.


set[UTC]Month( )

Sets the month field (and optionally the day of the month) of a date, using local or universal time.


set[UTC]Seconds( )

Sets the seconds field (and optionally the milliseconds field) of a date, using local or universal time.


setTime( )

Sets the fields of a Date object using the millisecond format.


setYear( )

Sets the year field of a Date object. Deprecated in favor of setFullYear( ).


toDateString( )

Returns a string that represents the date portion of the date, expressed in the local time zone.


toGMTString( )

Converts a Date to a string, using the GMT time zone. Deprecated in favor of toUTCString( ).


toLocaleDateString( )

Returns a string that represents the date portion of the date, expressed in the local time zone, using the local date formatting conventions.


toLocaleString( )

Converts a Date to a string, using the local time zone and the local date formatting conventions.


toLocaleTimeString( )

Returns a string that represents the time portion of the date, expressed in the local time zone, using the local time formatting conventions.


toString( )

Converts a Date to a string using the local time zone.


toTimeString( )

Returns a string that represents the time portion of the date, expressed in the local time zone.


toUTCString( )

Converts a Date to a string, using universal time.


valueOf( )

Converts a Date to its internal millisecond format.

24.23.3. Static Methods

In addition to the many instance methods listed previously, the Date object also defines two static methods. These methods are invoked through the Date( ) constructor itself, not through individual Date objects:


Date.parse( )

Parses a string representation of a date and time and returns the internal millisecond representation of that date.


Date.UTC( )

Returns the millisecond representation of the specified UTC date and time.

24.23.4. Description

The Date object is a datatype built into the JavaScript language. Date objects are created with the new Date( ) syntax shown earlier.

Once a Date object is created, a number of methods allow you to operate on it. Most methods simply allow you to get and set the year, month, day, hour, minute, second, and millisecond fields of the object, using either local time or UTC (universal, or GMT) time. The toString( ) method and its variants convert dates to human-readable strings. getTime( ) and setTime( ) convert to and from the internal representation of the Date objectthe number of milliseconds since midnight (GMT) on January 1, 1970. In this standard millisecond format, a date and time are represented by a single integer, which makes date arithmetic particularly easy. The ECMAScript standard requires the Date object to be able to represent any date and time, to millisecond precision, within 100 million days before or after 1/1/1970. This is a range of plus or minus 273,785 years, so the JavaScript clock will not "roll over" until the year 275755.

24.23.5. Examples

Once you create a Date object, there are a variety of methods you can use to operate on it:

 d = new Date( );  // Get the current date and time document.write('Today is: " + d.toLocaleDateString( ) + '. ');  // Display date document.write('The time is: ' + d.toLocaleTimeString( ));      // Display time var dayOfWeek = d.getDay( );                                    // What weekday is it? var weekend = (dayOfWeek == 0) || (dayOfWeek == 6);            // Is it a weekend? 

Another common use of the Date object is to subtract the millisecond representations of the current time from some other time to determine the difference between the two times. The following client-side example shows two such uses:

 <script language="JavaScript"> today = new Date( );            // Make a note of today's date christmas = new Date( );        // Get a date with the current year christmas.setMonth(11);        // Set the month to December... christmas.setDate(25);         // and the day to the 25th // If Christmas hasn't already passed, compute the number of // milliseconds between now and Christmas, convert this // to a number of days and print a message if (today.getTime() < christmas.getTime( )) {     difference = christmas.getTime() - today.getTime( );     difference = Math.floor(difference / (1000 * 60 * 60 * 24));     document.write('Only ' + difference + ' days until Christmas!<p>'); } </script> // ... rest of HTML document here ... <script language="JavaScript"> // Here we use Date objects for timing // We divide by 1000 to convert milliseconds to seconds now = new Date( ); document.write('<p>It took ' +     (now.getTime()-today.getTime( ))/1000 +     'seconds to load this page.'); </script> 

24.23.6. See Also

 Date.parse( ), Date.UTC( ) 




JavaScript. The Definitive Guide
JavaScript: The Definitive Guide
ISBN: 0596101996
EAN: 2147483647
Year: 2004
Pages: 767

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net