JavaScript’s Date object, half explained

This one is for the JavaScript newbies (myself included) :-).

For a full description and explanation of the Date object and what it does check the Core JavaScript 1.5 Reference. What I’m going to tell you here is only one way in which it works.

The Date object takes up to seven parameters:*

new Date(year_number, month_number, day_number,
hour_number, minute_number, second_number, millisecond_number)

When parameters are passed to the Date object, it returns a date string. When no parameters are passed, it returns a date string of the current time.

All of the above parameters are integers. The last four parameters deal specifically with time. We’re going to focus on the first three.

Something to remember about numeric representations of months in JavaScript: months are expressed using numbers 0 (January) through 11 (December).

So document.write(new Date(2006,11,1)) would return Fri Dec 01 2006 00:00:00 GMT-0500 (EST).

Now here’s where things get interesting. Months are represented as 0 through 11, right? So what happens when we change 11 to 12?

Well document.write(new Date(2006,12,1)) gives us Mon Jan 01 2007 00:00:00 GMT-0500 (EST). It may help to think of it as the thirteenth month.

Days work similarly. Any positive integer that’s outside of the valid date range for that month and year will spill over into next month. For example document.write(new Date(2006,11,32)) also gives us Mon Jan 01 2007 00:00:00 GMT-0500 (EST).**

You can then extract values from this new date using the ‘get’ or ‘set’ methods (i.e. getMonth(), getFullYear(), setDate() etc.).

Below is a (super simple) function that will determine if a given year is a leap year.

function isLeapYear(yearInQuestion){
 	var isThisALeapYear = new Date(yearInQuestion,1,29);
 	var isTheMonthFebruary = isThisALeapYear.getMonth();

 	var currentYear = new Date();

 	if( yearInQuestion < currentYear.getFullYear()){
 		var verb = 'was';
 	  } else if(yearInQuestion == currentYear.getFullYear()){
 	  	var verb = 'is';
 	  } else {
 		var verb = 'will be';
 	}

 	if(isTheMonthFebruary == 1){
 		document.write(yearInQuestion +' '+verb +' a leap year.');
 	  } else {
 		document.write(yearInQuestion +' '+verb+' not a leap year.');
 	}
}

In years that are leap years, February will have 29 days, so the value of isTheMonthFebruary will be 1. But in non-leap years, the 29th day will interpreted as March 1st. The value of isTheMonthFebruary will be 2.

Or try the following function which returns the number of days in a given month for the current year.

function getDaysInMonth(monthInQuestion){
	var currentYear = new Date().getFullYear();

        // 1 is just to give us a starting date.
	var daysInMonth = new Date(currentYear,monthInQuestion,1);

        // We set i = 28 because every month has at least 28 days, but less than 32.
	for(i = 28; i < 32; i++){
	        // changes the value of the day number parameter above to be equal to i
		daysInMonth.setDate(i);

                /*
                If the month number from the new, reset date does not equal
                the monthInQuestion, end the script. Otherwise return the value of i
                */

		if(daysInMonth.getMonth() != monthInQuestion){
			break;
		   } else {
			returnOfi = i;
		}
	} 

	document.write(returnOfi);
}

(*Date strings or milliseconds since January 1, 1970 are also acceptable. Millisecond is a new parameter in JavaScript 1.5 and above. Versions equal to or below 1.3 do not accept a millisecond parameter.)

(**Hours, minutes, seconds, and milliseconds work the same way. 25 hours will be 1 a.m. the following day.)