Introduction to date and time

This page describes the basics of date and time scripting and explains the millennium problem.

The problem with date and time scripting is that the human calendar is not very logical (to put it mildly). Therefore we have to write large scripts to accurately perform our calculations and to give user friendly output afterwards. All this is made more difficult by the millennium problem. Fortunately there is a simple solution for this problem.

Date and time scripting uses the date and time according to the system the browser is on. If this system time is wrong, there's nothing you can do about it and all scripts in this section will give wrong output.

First I describe Epoch Time, followed by the Date object and its methods, then I continue with the Millennium problem and its solution.

Epoch Time

First of all you need to know the concept Epoch Time. It is the basis of date and time calculation on computers.

Epoch Time is the time elapsed since 1 January 1970 00:00:00. This is usually expressed in seconds, but browsers use milliseconds.

This way of dating will end somewhere in 2038 because then the 32 bits number used for keeping track of the time passes its maximum. What happens then to date and time calculations is anyone's guess. Probably a 64 bits number will be installed as its successor somewhere before 2038. This will allow us to go on with date and time calculations for the next 292 billion years or so, comfortably longer than the human race (or, indeed, the universe) will exist.

The Date Object

To access a date and create user friendly output, you need to create a Date object that contains a certain date. For each Date object, JavaScript creates several methods that we can use to extract useful data, like the day of the month, the time in seconds, minutes and hours etc. The main trouble is calculating the year. (I'll treat this in detail below.)

To create a Date object, do

var thisdate = new Date();

If you don't fill in anything between the brackets (), the browser takes the current date (system date of the computer the browser is on) and puts this in thisdate.

The current date is .

Since this output is browser dependent and not particularly user friendly, we need to start using the methods that JavaScript has prepared for us. For instance, do

thisdate.getMinutes()

to get the minutes of the current date: (I list these methods below).

To take any other date than the current one, fill in something between the brackets (), like:

var thisdate = new Date(document.lastModified);

This takes the string document.lastModified (last modification date of the document) and converts it to a Date object so we can start reading out things in the way described above.

Methods of the Date object

Each Date object has methods that you can use to read out certain details and make the output more user friendly or to construe your own dates.

• getSomething()
• setSomething()
• UTC()
• toGMTString() and toLocaleString()
• Date.parse()
• Date.getTimetzoneOffset()

getSomething()

The basic syntax for getting information about the date is thisDate.getSomething(). You can get the following information:

For a practical example of these methods, see the date and time script.

setSomething()

If you want to construe your own date, you'll have to use the methods setSeconds(), setMinutes() etc. These methods exactly match the get methods listed above, except that you say set instead of get.

So if you want to set the date to 1 January 1999, do:

var thisDate = new Date();
thisDate.setYear(1999);
thisDate.setMonth(0);
thisDate.setDate(1);

and thisDate contains the date 1 January 1999 00:00:00.

I use both the setSomething() methods and the UTC method in the week number script.

UTC()

The UTC() method converts a comma-separated list of values to milliseconds since 01/01/1970 00:00:00. The syntax is

date.UTC(year,month,date,hours,minutes,seconds);

toGMTString() and toLocaleString()

There are two methods that have to do with time zones. Both convert a date to a string:

• toGMTString() converts the date to a GMT date (Greenwich, UK).
• toLocaleString() converts the date to the local time zone set in the system time of the computer.

Note that the result of one of these functions is a string, not a Date object. Unfortunately you cannot make the string a Date object again, if you do

var theDate = new Date();		// create Date object with the current date;
var temp = theDate.toGMTString();	// convert date to a GMT string;
var theSecondDate = new Date(temp);	// convert string to a Date object

theSecondDate once again holds the same date as theDate. Very, very annoying.

Date.parse()

The Date.parse() method is for reading in strings like October, 4 2000 07:04:11 and translating them to a Date object. To set a date like this, do

var today = new Date();
today.setTime(Date.parse('October, 4 2000 07:04:11'));

Now you can use the usual methods on today. Note that the syntax of this string is very strict:

'MonthName, DayNr Year Hrs:Min:Sec'

Some things I discovered while playing with this method:

• If you use only two numbers for the year (99 instead of 1999) everything will go well for dates before 2000, but both Netscape and Explorer get terribly confused when the year is 2000 or larger.
• Dates before 1970 are forbidden
• If you give too many hours (27:04:11, for instance), Explorer will get confused but Netscape will go to the next day (Oct., 5 2000 03:04:11).
• Too many minutes or seconds will confuse both browsers.

I need to do more research on this method.

getTimezoneOffset()

The Date.getTimezoneOffset() method gives the difference between the local timezone on the computer and GMT in minutes.

I use this method in the Internet Beat script.

The millennium problem

The millennium problem is well known: the writers of older programs didn't really know what to do about the new century. Netscape devised a complex solution that even Netscape itself doesn't completely follow.

When using the method date.getYear(), the Netscape system doesn't give the full year but uses an abbreviated version of the year. In this system, 1997 becomes 97 and 2000 is represented by 100.

Microsoft did not entirely agree: before 2000 Explorer did the same as Netscape, but now that 2000 has come Explorer 4 and 5 give 2000 as the Year.

Just to keep you on your toes, Netscape 3 (and only 3) follows Explorer. As to the minor browsers: they all follow the orginial Netscape system, except for WebTV.

To make the matter even more complex, date.getYear() is deprecated nowadays and you should use date.getFullYear(), which, in turn, is not supported by the older browsers. If it works, however, it should always give the full year, ie. 2000 instead of 100.

Your browser gives the following years with these two methods:

Finally, Netscape has one grave bug in the implementation of document.lastModified. I have found out that if you use getYear() on this date, Netscape gives 0 instead of 100 and if you use getFullYear() you get 1900 instead of 2000.

Calculating the full year

Fortunately there is a simple solution to this extremely complex problem. Since it is supported by all browsers, always use getYear(). Divide the outcome by 100 and take the modulus, so that now we have a number from 0 to 99. If this number is smaller than 38, add 2000, if it's larger add 1900. This always gives the correct year.

So always use the function below when you have to calculate a year:

function takeYear(theDate) {
	x = theDate.getYear();
	var y = x % 100;
	y += (y < 38) ? 2000 : 1900;
	return y;
}

(Why 38? Because Epoch Time will end in 2038. You can also use (y > 69) ? 1900: 2000; because in the Epoch Time system no date can be before 1970).

Send the Date object to the function, like

var today = new Date();
Year = takeYear(today);

Now Year contains the right year and we have succesfully solved the millennium problem.