A Roundup of Popular JavaScript Date Parsing Libraries: XDate

Welcome to the third installment in a series on Date Parsing JavaScript libraries. The idea to look for libraries specializing in dates came to me while writing an article on Date Parsing using JavaScript and Regular Expressions. I was delighted to find that there were a lot of them out there. Having said that, not all are equally well suited for my particular need, which is to parse dates from a block of text. In part one, I talked about the outstanding Moment.js library. Part 2 focused on the equally popular Datejs. We will now turn our attention to the XDate library.

A Little History

All of the XDate’s functionality for parsing, formatting and manipulating dates is contained within one small (7.2k) file. It was originally released by by Adam Shaw in October of 2011, who planned to integrate it into a project called FullCalendar. XDate acts a as a wrapper to the native JS object and is safe to include with other libraries. It follows the same method names and naming conventions as the native Date in order to minimize developers’ learning curve.

Although MomentJS has since eclipsed XDate in popularity, XDate remains an important alternative. Being powerful while still conforming to the familiar native Date API that many developers already understand is no doubt a contributing factor. Other noteworthy features include method chaining support as well as handy methods for retrieving date values, adding/subtracting dates, calculating differences, and producing output in multiple formats. There are also several methods for working with UTC values.

The latest version, 0.8, was released on Mar 30th, 2013. The library is dual-licensed under MIT or GPL and is available from Shaw’s website.

A Quick Overview

As mentioned above, the XDate wrapper object possesses many of the same methods as the native JS Date, but with some differences. For instance, the XDate’s toString() method accepts a standard Unicode (Locale Data Markup Language (LDML)) input format parameter string, whereas the the Date object does not:

var d = new XDate(2012, 5, 8);
d.toString("'the month is' MMMM"); // "the month is June"

var thanksgiving = new XDate(2011, 10, 24);
var christmas = new XDate(2011, 11, 25);
thanksgiving.diffDays(christmas); // 31
christmas.diffDays(thanksgiving); // -31

XDate also provides some additional methods, such as the always useful diffDays() and diffYears:

var thanksgiving = new XDate(2011, 10, 24);
var christmas = new XDate(2011, 11, 25);
thanksgiving.diffDays(christmas); // 31
christmas.diffDays(thanksgiving); // -31

var jan2011 = new XDate(2011, 0, 1);
var jul2012 = new XDate(2012, 6, 1);
jan2011.diffYears(jul2012); // 1.5

Many of XDate’s methods return a reference to the same XDate objects allowing you to “chain” method calls together. In the estimation of many coders, chaining makes for more concise code.

var d1 = new XDate();
var d2 = d1.clone()
          .setUTCMode(true)
            .setDate(1)
              .addMonths(1)
                .addYears(2);

Parsing Capability

Unfortunately, XDate only supports date-strings in ISO8601 (the preferred format) or IETF format. For example:

• 2011-09-05 (ISO8601)
• 2011-09-05T12:30:00 (IETF)
• 2011-09-05T12:30:00-07:00 (IETF)
• 2011-09-05T12:30:00Z (IETF)

Extending the Parser

You can extend the parser by appending your parsing functions to the XDate.parsers array. Here’s a parser for MySQL datetime strings:

XDate.parsers.push(function(str) {
  // Split timestamp into [ Y, M, D, h, m, s ]
  var parts = str.split(/[- :]/);

  // Apply each element to the Date function
  return new XDate(parts[0], parts[1]-1, parts[2], parts[3], parts[4], parts[5]);
}); 

//now you can call the XDate wrapper like so:
var d = new XDate("2010-06-09 13:12:01");

Parsing a date from a larger string is not much more difficult; it merely requires using a RegEx to extract the date first. Once again, here’s the code to add a parser for my doctor’s appointment test string. It’s not terribly different from the above function other than that extra initial step:

XDate.parsers.push(function(str) {
  var dateString = str.match(/d{4}/d{2}/d{2}s+d{2}:d{2}/);
  
  // Split dateString into [ Y, M, D, h, m ]
  var parts = dateString.split(new RegExp('[/ :]'));

  // Apply each element to the Date function
  return new XDate(parts[0], parts[1]-1, parts[2], parts[3], parts[4]);
}); 

var stringToParse = "You have a doctor's appointment on 2012/03/13 16:00.  Please show up on time.";
var dt            = XDate.parse(stringToParse);
console.log(dt);  //prints Tue Mar 13 2012 17:00:00 GMT-0400 (Eastern Daylight Time) 

Conclusion

The XDate library is quite good if you don’t mind writing your own parsing code. So far, the only library that worked right out of the box to parse dates from a block of text is Moment.js. Both XDate and Datejs are more limited in what kind of string(s) they will accept as a parameter. If you know of a good date parsing library, please do email me at the address below. I’d love to hear from you!