Manipulate time and date values with JavaScript's Date object

Working with dates
It is simple to get going with time and date values in JavaScript. It begins with creating an instance of the Date object:

var d = new Date();

This returns an instance of the Date object in the variable d using the current date and time. The Date object includes numerous methods and properties for accessing and manipulating its value. The following list includes methods for accessing date values:

• getDate(): Returns the day of the month.
• getDay(): Returns the day of the week. The week begins with Sunday (0 - 6).
• getFullYear(): Returns the four-digit year.
• getMonth(): Returns the month.
• getYear(): Returns the two-digit year.
• getUTCDate(): Returns the day of the month according to the Coordinated Universal Time (UTC).
• getUTCMonth(): Returns the month according to the UTC (0 - 11).
• getUTCFullYear(): Returns the four-digit year according to the UTC.

Note: Wikipedia defines UTC as a high-precision atomic time standard which approximately tracks Universal Time (UT).

An important note regarding JavaScript and dates is it uses the number of milliseconds from midnight January 1, 1970 to store dates. This is called the epoch, and any dates and times before this date are not allowed.

Using the methods in the previous list is simple and straightforward as Listing A illustrates. One thing you will notice is the month and weekday values begin with zero, so you'll need to add one to them to display their actual values. You could easily use an array to display the actual day of the week's name. Listing B includes the JavaScript.

You are not restricted to working with the current date. The Date object may be initialized with a value passed to it, like this:

var d = new Date("date value");

Using this approach, we could alter the previous example to use a specific date. Listing C presents a simple way to discover the day of the week for a given value. The code produces the following output:

Today is: Wednesday 4/15/1979

UTC is: Wednesday 4/15/1979

Actually, there are four approaches to creating a Date object instance:

var d = new Date();
var d = new Date('July 4, 1976');
var d = new Date(7, 4, 1976);
var d = new Date(7, 4, 1976, 12,00,00);

We've covered the first two (notice that apostrophes or parentheses may be used). The final two use individual integer parameters using the following format (the time is optional):

var d = new Date(month, day,
 year, hour, minutes, seconds);

Another way to populate a Date object is by way of the setDate method. It provides a way to reset a Date object's value or initialize it, but it requires an actual JavaScript Date object:

Var d1 = new Date();
var d2 = new Date("7/4/1976");

d1.setDate(d2.getDate());

There are more set methods for populating the various properties of the Date object, but let's cover time before discussing them.

Working with time
Along with the date components, the Date object stores time information as well. The following methods provide access to a Date object's time information:

• getHours(): Returns the hour portion of the time.
• getMinutes(): Returns the minutes portion of the time.
• getSeconds(): Returns the seconds portion of the time.
• getMilliseconds(): Returns the milliseconds portion of the time.
• getTime(): Returns the number of milliseconds since midnight January 1, 1970.
• getTimezoneOffset(): Returns the difference in minutes between local time and Greenwich Mean Time (GMT).
• getUTCHours(): Returns the hour portion of the time according to UTC.
• getUTCMinutes(): Returns the minutes portion of the time according to UTC.
• getUTCSeconds(): Returns the seconds portion of the time according to UTC.
• getUTCMilliseconds(): Returns the milliseconds portion of the time according to UTC.

As previously demonstrated, you can initialize a Date object by passing in the hours, minutes, and seconds, but the milliseconds property is set via the setMilliseconds method. This JavaScript displays the current time:

<script language="javascript">var d = new Date();
document.write(d.getHours() +
 ":" + d.getMinutes() + ":" + d.getSeconds() +
":" + d.getMilliseconds());
document.write(d.getTime());
</script>

It displays the following output:

12:36:33:41

1146760593041

The second value is a bit odd since it displays the number of milliseconds since January 1, 1970 to the value stored in the referenced Date object. It comes in handy when finding the difference between two values. As with date values, a setTime method is available as well:

Var dt1 = new Date();
var dt2 = new Date(1970, 4, 15);

dt1.setTime(dt2.getTime());

Setting properties
Like the setTime, setDate, and setMilliseconds methods, there are methods to populate all portions of a Date object. This includes the following:

• setFullYear
• setHours
• setMinutes
• setMilliseconds
• setMonth
• setSeconds
• setUTCFullYear
• setUTCMonth
• setUTCHours
• setUTCSeconds
• setUTCMilliseconds

These methods allow you to easily reset a date property by passing in its new value. It's good to be able to work with and display dates, but there will be times when you need to perform calculations with dates and so forth.

Finding the difference between two values
The easiest arithmetic is subtracting or adding two numbers (you may disagree), so finding the difference between two JavaScript date values is simple. You just find the difference and it returns the difference as a number. The result will be a date value in milliseconds, so you'll have to perform division to get the necessary value type (days, months, minutes, hours, etc.).

The following JavaScript calculates the number of days until a specific date. It subtracts the two date values (via getTime) and divides the result by the number of milliseconds in a day (86400000) to present the result in day:

<script type="text/javascript">
var d1 = new Date();
var d2 = new Date(2006, 6, 7);
var day = 1000*60*60*24;
var diff = Math.ceil
((d2.getTime()-d1.getTime())/(day));
document.write("Days until vacation: " + diff);

</script>

Date arithmetic
The various properties of a Date value may be increased or decreased by adding or subtracting the necessary values via the appropriate property. For example, if you want to increase the value by one month, you would add one to the month property. The example in Listing D displays difference values for yesterday and tomorrow for the previous script. The following output is displayed:

Days until vacation: 50
Tomorrow it will be 49 days until vacation.

Yesterday, it was 51 days until vacation.

The time has come
Working with date and time values has its quirks that vary by platform, and Web development is no different. The JavaScript Data object provides an easy way to work with date and time values, but there are things to remember like the numbering of weekdays and months and formatting of some methods. They are not hard to remember once you are accustomed to its approach. A good thing to remember is the accuracy of date or time depends on the accuracy of the clock on the computer from which the page is being viewed.

Tony Patton began his professional career as an application developer earning Java, VB, Lotus, and XML certifications to bolster his knowledge.