Dates

The topics are:

Script Date Values

Date values provide a way of manipulating dates and times. Dates can be best understood as internally represented by a number of milliseconds since 00:00:00 UTC, January 1, 1970. This number can be negative, thus expressing a date before 1970.

Note

For C/C++ programmers: Unlike dates manipulated by the the standard C library, date values are not limited to the range of 1970 to 2038, but span over approximately 285,616 years before and after 1970.

When Automatic Conversion to a Number , a date yields the number of milliseconds since 00:00:00 UTC, January 1, 1970.

Date Constructor

The date constructor has four distinct syntaxes:

Script Date Constructor

Syntax

Effect

new Date( )

Returns the date representing the current time.

new Date(milliseconds)

Returns the date representing 00:00:00 UTC, January 1, 1970, plus milliseconds milliseconds. The argument can be negative, thus expressing a date before 1970. If the argument cannot be converted to a number, the third constructor syntax is used.

Examples:

  new Date(0)-> a date representing 00:00:00 UTC, January 1, 1970.

  new Date(1000*60*60*24*20) -> a date representing twenty days after 00:00:00 UTC, January 1, 1970.

  new Date(-1000*60*60*24*20)-> a date representing twenty days before 00:00:00 UTC, January 1, 1970.

new Date(string)

Returns the date described by string, which must have the form:

  month/day/year hour:minute:second msecond

The date expressed in string is taken in local time.

Example:

  new Date("12/25/1932 14:35:12 820")-> a date representing December the 25th, 1932, at 2:35 PM plus 12 seconds and 820 milliseconds, local time.

new Date(year,
  month,
  [ , date
  [ , hours
  [ , minutes
  [ , seconds
  [ , mseconds ]]]]]]]] )

Returns a new date representing the given year, month, date, etc., taken in local time. The arguments are:

year: Any integer.

month: range 0-11 (0=January, 1=February, etc)

day: range 1-31, defaults to 1.

hours: range 0-23, defaults to 0.

minutes: range 0-59, defaults to 0.

seconds: range 0-59, defaults to 0.

mseconds: range 0-999, defaults to 0.

Example:

  new Date(1932, 11, 25, 14, 35, 12, 820)-> a date representing December the 25th, 1932, at 2:35 PM plus 12 seconds and 820 milliseconds, local time.

  new Date(1932, 11, 25)-> a date representing December the 25th, 1932, at 00:00, local time.

Date Methods

Dates have the following methods:

Script Date Methods

Syntax

Effect

date.getTime( )
date.setTime(milliseconds)

Returns (or sets) the number of milliseconds since 00:00:00 UTC, January 1, 1970.

Example: Suppose that the date d has been created with:

  d = new Date(3427)

Then:

  d.getTime()-> 3427

date.toLocaleString( )
date.toUTCString( )

Returns a string representing the date in local time (respectively in UTC.)

Example: Suppose that the date d has been created with:

  d = new Date("3/12/1997 12:45:00 0")

Then:

  d.toLocaleString()-> "03/12/1997 12:45:00 000"

  d.toUTCString()-> "03/12/1997 10:45:00 000", assuming a local time zone offset of +2 hours with respect to the Greenwich meridian.

date.getYear( )
date.setYear(year)

Returns (or sets) the year of date.

date.getMonth( )
date.setMonth(month)

Returns (or sets) the month of date.

date.getDate( )
date.setDate(day)

Returns (or sets) the day of date.

date.getHours( )
date.setHours(day)

Returns (or sets) the hour of date.

date.getMinutes( )
date.setMinutes(day)

Returns (or sets) the minute of date.

date.getSeconds( )
date.setSeconds(day)

Returns (or sets) the second of date.

date.getMilliseconds( )
date.setMilliseconds(day)

Returns (or sets) the millisecond of date.

date.toString( )

Returns the same value as date.toLocaleString()

Date Functions

The following functions manipulate dates:

Script Date Functions

Syntax

Effect

Date.UTC(string)

Same as new Date(string), but string is taken in UTC and the result is returned as a number rather than as a date object.

Date.parse(string)

Same as new Date(string), but the result is returned as a number rather than as a date object.

Date Operators

There are no specific operators for dealing with dates, but, since Numeric Operators automatically convert their arguments to numbers, these operators can be used to compute the time elapsed between two dates, to compare dates, or to add a given amount of time to a date. For example:

  date1 - date2-> the number of milliseconds elapsed between date1 and date2.

  date1 < date2-> true if date1 is before date2, false otherwise.

  new Date(date+10000)-> a date representing 10000 milliseconds after date.

The following program displays the number of milliseconds spent for executing the statement <do something>:

before = new Date()

<do something>

after = new Date()

writeln("Time for doing something: ", after-before, " milliseconds.")