A scenic diversion on the road to understanding JavaScript when you're a C# programmer.

In this episode, we'll look at dates in JavaScript.

Dates are implemented in JavaScript by the Date() constructor function, which acts like a class. You can new up a Date object in much the same way as you new up a DateTime object in C#. For instance, here's how to create a date that's equal to the date I wrote this post (Mon, Apr 27, 2009):

var today = new Date(2009, 3, 27);
console.log(today.toDateString); // outputs Mon Apr 27 2009

If you look at this code a little more carefully, you'll notice that I used 3 for the month and not 4. Yes, this is gotcha number 1: the date library in JavaScript uses zero-based month numbers. The days numbers are one-based, as you'd imagine: it's just the months that are zero-based. This is, to put it mildly, confusing.

Date objects you create are of type object. Their prototype is the Date() constructor. This prototype implements several nice methods you can use to manipulate dates, of which we've already seen one (toDateString()):

var today = new Date(2009, 3, 27);
console.log(today.getDay()); // outputs 1 (the day of the week of the date)
console.log(today.getDate()); // outputs 27 
console.log(today.getMonth()); // outputs 3
console.log(today.getYear()); // outputs 109 (the years since 1900)
console.log(today.getFullYear()); // outputs 2009
console.log(today.toDateString()); // outputs "Mon Apr 27 2009"
console.log(today.toLocaleDateString()); // outputs "Monday, April 27, 2009"
console.log(today.toUTCString()); // outputs "Mon, 27 Apr 2009 06:00:00 GMT"

There are a couple of points to note here. First, the getDay() method returns the day of the week as an integer, with Sunday as 0, Monday as 1, and so on. This can be a little confusing for C# developers, because the equivalent in .NET is the DayOfWeek property. The .NET Day property, on the other hand, is the equivalent of JavaScript's getDate() method. Note that the month is returned as a zero-based value again.

The getYear() method I include for completeness only, since different browsers implement it in different ways (despite the ECMAScript standard being very explicit about what it should do). As you can see, Firefox returns the number of years since 1900 (that's what the standard says too), however IE7 and 8 return the full year value (that is, 2009 in this example). So, I'd advise you to avoid it completely and use getFullYear() instead.

The various "toString" methods return the date in various string representations. The results are very similar between Firefox and IE here, although I'd note that toUTCString() in Firefox uses the confusing GMT suffix, whereas IE uses the more correct UTC. (There is a similar method, fully deprecated in 1999 when the ECMA standard was released, called toGMTString(). This is set equal to toUTCString(), so they do the same thing, but you might see the older version in old code.) All in all, I'd say don't depend on the output of these "toString" methods: as the standard states: "The contents of the string are implementation-dependent", but note that they would use the browser's locale (that is, the OS's locale) for the various day and month names.

As you may have guessed from the last method there, date objects also contain a time portion, that is they are DateTimes in the .NET vernacular. To create a date object with a time part you would use an overloaded constructor call:

var today = new Date(2009, 3, 27, 15, 24, 23, 300);
console.log(today.getHours()); // outputs 15
console.log(today.getMinutes()); // outputs 24
console.log(today.getSeconds()); // outputs 23
console.log(today.getMilliseconds()); // outputs 300

If you need the date/time value for right now, the equivalent of DateTime.Now, you'd use the Date constructor with no parameters:

var today = new Date();
console.log(today.toLocaleDateString()); // outputs "Monday, April 27, 2009"
console.log(today.toLocaleTimeString()); // outputs "8:14:38 PM"

There are also a set of methods that deal with setting the various parts of a date/time object: the year, the month, and so on (in essence, the same names as the getters but with "set" instead), but there are no methods that deal with date computations, such as adding a number of days to a date and so on. There is an open source library out there called Datejs which uses a "fluent" API (that is, you can write things like: Date.today().add(3).days();), but there's nothing particularly geared to C# developers used to DateTime who are coding in JavaScript. We'll take a look at that next time.

Another warning before I close this post: although Date() is a constructor function, you can actually use it as an ordinary function:

var nowAsString = Date();
console.log(nowAsString); // outputs the current date/time as a string

No matter what parameters you pass in the call, it'll ignore them and return a string representing the current date and time. Pretty useless, and it's dead confusing to boot (is it a constructor or isn't it?). My advice is don't use Date() in this way.