ECMA-262 Core: JavaScript Date and Time





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








Introduction And Review

All programming languages must deal with dates and times. Some programming languages give date and time a unique data type (data base languages, HTML, Visual Basic, etc.). ECMAScript provides the Date class as opposed to a data type. The Date class provides date format flexibilities and numerous methods for setting and manipulating both date and time.

The purpose of this document is to present how date and time is handled in ECMAScript. The different formats will be detailed and explained. Definitions are provided. And date and time usage with ECMAScript is provided.

We address date and time from an object viewpoint at a page entitled "The Date Class". This separate page talks about constructors, properties, inheritance and methods.


Date and Time Terms You Need to Know

At the bottom of this document we have defined the following terms. Take the link if you wish.


Be Advised


Date and Time Formats


The Internal ECMAScript Date

A Date object contains a number indicating a particular instant in time to within a millisecond. For ECMAScript to work with the internal date, it needs the following framework:

The internal time for: (Fri Feb 16 20:12:40 PST 2007) is 1,171,685,560,000 milliseconds.
The internal time for: (Fri Feb 16 20:19:38 PST 2007) is 1,171,685,978,000 milliseconds.

Does the internal time (milliseconds) reflect the current date and time of the UTC time zone or the current date and time of the time zone of your computer clock?? Stated another way, has the internal date already been adjusted for your time zone or is it UTC time?? The internal date is the universal time of the UTC time zone at that point in time you instantiated the date object. The date methods (other than the UTC versions) will all adjust the internal date to arrive at local current date. They do this by applying the time zone offset to the internal date.


Date Parts and Time Parts

The internal date can be retrieved using a number of Date object methods. Here we show the date and time parts with there range of values, formats and the appropriate method for the part.


Date and Time Parts Available from a given Date Object
Part Range of Values Format and Comments Method
Footnotes:
Composite N/A Fri Feb 16 18:24:10 PST 2007
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
toString()
Composite N/A Sat, 17 Feb 2007 02:24:10 UTC
DOW, DD MON CCYY hh:mm:ss TZD
toUTCString()
Year + or - 273972.6 years
from starting point
four-digit year getYear()
Month 0 to 11 two-digit month, where:
0 = January
·······
11 = December
getMonth()
Day of
Month
1 to 31 two-digit day getDate()
Day of
Week
0 to 6 where: 0 = Sunday
1 = Monday
2 = Tuesday
3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday
getDay()
Hour 0 to 23 0 = midnight
23 = 11 pm
getHours()
Minute 0 to 59 60 minutes in an hour getMinutes()
Second 0 to 59 60 seconds in a minute getSeconds()
MilliSecond 0 to 999 a fraction of a second getMilliseconds()



Date.parse() and It's String Argument

The Date.parse() method is a static method. Meaning it is invoked through the class as opposed to a non-static method that is invoked via an object. The Date.parse() method takes a string argument (a date or date part) and returns the milliseconds equivalent that represents the internal date. The purpose of this topic is to explain the options and format of the string that serves as an argument to this class method.

An effective way of dealing with this topic is to inspect what the toString() method returns. Recall it returns a string that represents the date parts. It takes the internal date in milliseconds and transforms it into a string of date parts.

mydate.toString();

The string returned by the toString method has this format: 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

The class method Date.parse() in effect performs the opposite of toString. Date.parse() will take a string for its argument and return the internal date in milliseconds. If the string passed into Date.parse() can not be converted to a date, the method will return NaN. The following table gives some variations on the Date.parse() argument options.

The string format of the date used within the following examples is:
Sat Feb 17 14:39:07 PST 2007
This date has an internal date of: 1171751947000


Specifying the String Argument for Date.parse
Date Part Date.parse() Milliseconds
Returned
Comments About The Argument
Footnotes:
Composite Date.parse("Sat Feb 17 14:39:07 PST 2007") 1171751947000 All date and time parts in a format as returned by toString().
CCYY Date.parse("2007") NaN CCYY by itself does not work.
MON
DD
CCYY
Date.parse("Feb 17 2007") 1171699200000 Month, day and Year work. This is the midnight time (0) for the day.
DOW
MON
DD
CCYY
Date.parse("Sat Feb 17 2007") 1171699200000 Adding day of week has no effect.
DD
MON
CCYY
Date.parse("17 Feb 2007") 1171699200000 Changing order has no effect.
CCYY
MON
DD
Date.parse("2007 Feb 17") 1171699200000 All combos seem to work.
MON
DD
CCYY
TZD
Date.parse("Feb 17 2007 PST") 1171699200000 Adding time zone designator has no effect.
MON
DD
CCYY
hh
Date.parse("Feb 17 2007 14") NaN Adding the hour without appropriate punctuation returns NaN.
MON
DD
CCYY
hh:
Date.parse("Feb 17 2007 14:") 1171749600000 Adding the hour with appropriate punctuation works.
MON
DD
CCYY
hh:mm
Date.parse("Feb 17 2007 14:39") 1171751940000 Adding the minute works.
MON
DD
CCYY
hh:mm:ss
Date.parse("Feb 17 2007 14:39:07") 1171751947000 Adding the second works.
MM/DD/CCYY Date.parse("02/17/2007") 1171699200000 Most implementations will also accept the MM/DD/CCYY format.

In the above example, we were able to approach the true internal date millisecond value. Understand that all internal dates are represented to the 1/1000 of a second. When you instantiated a date object, the internal date will reflect the fractional second supplied by your computer clock. We cannot recreate an internal date with Date.parse() to the exact value of another internal date that was created based on the computer clock.



Date.UTC() and It's Arguments

The Date.UTC() method is another static method. The Date.UTC() method's argument takes a series of numbers (date parts) that are separated by commas and returns the milliseconds equivalent that represents the internal date. The date parts must be in a predefined sequence. All date parts are optional except for the first two (year and month).

The date parts making up the argument are:
year, (four digit)
month, (0 thru 11) where 0 = January
day, (Day of Month) values 1 - 31
hours, (military) values 0 - 23
minutes, values 0 - 59
second, values 0 - 59
milliseconds values 0 - 999

The class method Date.UTC() in effect performs the opposite of the toUTCString method. Date.UTC() will take its argument and return milliseconds. If the argument passed into Date.UTC() can not be converted to a date, the method will return NaN. The following table gives some variations on the Date.UTC() argument options.

The format of the date used within the following examples is:
Sun, 18 Feb 2007 23:57:08 UTC
This date has an internal date of: 1171843028375



Specifying the Arguments for Date.UTC
Date Part Date.UTC() Milliseconds
Returned
Comments About The Argument
Footnotes: In the above examples, we were able to recreate the internal date down to a millisecond value. The Date.UTC() method allows accuracy to the 1/1000 of a second.
Composite Date.UTC(2007, 1, 18, 23, 57, 08, 375) 1171843028375 All date and time parts in a predefined sequence separated by commas.
year Date.UTC(2007) NaN The stand alone year may work in some implementations.
year
month
Date.UTC(2007, 1) 1170288000000 The internal date for the midnight Feb. 1, 2007.
year
month
day
Date.UTC(2007, 1, 18) 1171756800000 The internal date for the midnight Feb. 18, 2007.
year
month
day
hours
Date.UTC(2007, 1, 18, 23) 1171839600000 The internal date for Feb. 18, 2007, 23rd hour.
year
month
day
hours
minutes
Date.UTC(2007, 1, 18, 23, 57) 1171843020000 The internal date for Feb. 18, 2007, 23:57.
year
month
day
hours
minutes
seconds
Date.UTC(2007, 1, 18, 23, 57, 08) 1171843028000 The internal date for Feb. 18, 2007, 23:57:08.
year
month
day
hours
minutes
seconds
ms
Date.UTC(2007, 1, 18, 23, 57, 08, 375) 1171843028375 The internal date for Feb. 18, 2007, 23:57:08:375.



Creating Dates


Current Date and Time

var myDate = new Date( ); //an empty argument to the constructor gives current date and time

UTC Start Date

var myDate = new Date(0); //an incremental number of zero gives Jan 1, 1970 at exactly midnight

A Specific Date Using the Constructor with a String Argument

var myDate = new Date("Sat Feb 17 14:39:07 PST 2007"); //the string argument to the constructor s/b a format option as we illustrated with the Date.parse argument above

A Specific Date with the Help From Date.Parse()

var myDate = new Date(Date.parse("March 5, 2007")); //Date.parse supplies the milliseconds increment to the Date constructor

A Specific Date Using the Constructor with comma separated date parts

var myDate = new Date(2007, 1, 18, 23, 57, 08, 375); //the argument to the constructor s/b a format option as we illustrated with the Date.UTC argument above

A Specific Date with the Help From Date.UTC()

var myDate = new Date(Date.UTC(2007, 1, 18, 23, 57, 08, 375)); //Date.UTC supplies the milliseconds increment to the Date constructor

Definitions

The following date and time definitions are grouped here for your convenience. These definitions are also repeated in our glossary. The linking on this page will link to the following definition versions. The linking from the remainder of the site will link to the glossary.

• Current Time:
In computer jargon, this is the date and time currently registered in the computer clock. Most of us are working on a client machine that is running many applications. The applications that run on the client (like your browser) will reflect the clients clock time. However, your client may interface to applications that are running on the server or mainframe. These applications will reflect the date and time from the server or mainframe.
 
• GMT:
Greenwich Mean Time is an older standard of precision time setting based on a solar reading from the Greenwich meridian. It is still correctly referred to as a time zone in the United Kingdom but GMT was replaced as the international time reference by Coordinated Universal Time.
 
• Local Time:
This is the date and time of the time zone of your current location and hopefully, is currently registered in the computer clock of your machine.
 
• Military Time:
Military time is a method of representing a time of day by designating the hour of the day with a range of 0 through 23. Military time eliminates the need for the AM/PM designator.
 
• Universal Time:
Universal time is the current time at Greenwich England. Universal time is based on UTC.
 
• UTC:
Coordinated Universal Time is a high-precision atomic time standard. Time zones around the world are expressed as positive or negative offsets from UTC. UTC is the current term for what was commonly referred to as Greenwich Meridian Time (GMT). Zero (0) hours UTC is midnight in Greenwich England, which lies on the zero longitudinal meridian. Universal time is the current time at Greenwich England. Universal time is based on a 24 hour clock.
 
• Y2K:
The Year 2000 problem pertained to software and firmware that would fail with the advent of the year 2000. The potential problems were many, but the jest of the matter pertained to the year rollover from 1999 to 2000. Many date routines handled only a two digit date (the century code was not part of the routine). So you might have year 99 rollover to 00 where the century 19 was fixed. Therefore, when year 1999 rolls over, it becomes 1900.


Top            

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