ISO 8601 date formatter

Description

ISO 8601 provides a standard unambiguous format (several, actually) for dates and times. Unfortunately, NSDateFormatter alone does not completely support ISO 8601; in particular, it does not support week dates or ordinal dates.

This came to my attention when I began writing a patch for Vienna to add support for the ttl element of RSS 2.0 and the updatePeriod, updateFrequency, and updateBase elements of RDF Site Summary 1.0's Syndication module (which it borrowed from Open Content Syndication). The latter prescribes a YYYY-MM-DDTHH:MM format for dates. Somehow, I got it into my head that it prescribed ISO 8601 format for dates (as opposed to only the YYYY-MM-DDTHH:MM format), which would have meant that NSDateFormatter wouldn't work.

So, that's why I wrote this parser. I won't need it for Vienna, since RSS 1.0 doesn't actually prescribe ISO 8601 format by name (simply one version of it, which should be perfectly doable with plain Cocoa date-formatting techniques). Adium, however, does use ISO 8601 format in its log format, and so this parser/unparser is being used in Adium X 1.0 and later.

Version history

0.6 — 2011-11-05

When not set to strict parsing, allow a space before the time-zone specification, for greater compatibility with NSDate output (description) and input (dateWithString:). 27603efc8a77
Bug fix: We no longer try to format the formatter. 83415de9f527
Bug fix: Hours are now zero-padded correctly (#4). a5608e189ebe af0c6b397428
Fixed many various compiler warnings. Some fixes contributed by Sparks. 8be3d6f7c6f2 78ae31de2170 68dc351e9fdb e7ea87db8621 873f499ae6db
Now 75 times faster. 6a023812bd2b 05dc35d6b505 3b2225e0ce8c d59720ad015a 10f526956963 297b8dae4095 796be11aa596 cadf0f0c8199 61d2959c6921
iOS users can now tell the ISO 8601 date formatter class to drop its caches (which you should do when you receive a memory warning). 2bb1725914b1
Added a couple of command-line options to the calendar-format-unparser test tool. c644aadb2b14
The parser test tool now displays parsed dates in GMT rather than the local time zone. 788c1455ecb1
Added a test tool to test unparsing with the time included. a89a9a8b3d61
You can now “make analysis” to run the Clang Static Analyzer on the date formatter. b3dd33841f42
The test tools are now built using Clang. 0723d3aa6596

Earlier versions

Version 0.5 was a major rewrite of much of the code, especially the unparser. Previous versions were category additions to NSCalendarDate (which is now deprecated). It's all now a single subclass of NSFormatter, and the implementation now uses NSCalendar and friends instead of the “strongly discouraged” NSCalendarDate. This means that version 0.5 and later require Mac OS X 10.4 or later. However, I have not tested it on Tiger; if it is broken on Tiger, I welcome your patch to fix it.

Version 0.4 added the ability to specify a custom time separator character instead of ':'. This works on both the parsing and unparsing directions.

Version 0.3 fixed some bugs found by Colin Barrett.

In version 0.2, I added an unparser. Now you can go back and forth between NSCalendarDate and NSString.

Mercurial repository

If you want to contribute bug-fixes or enhancements to the ISO 8601 parser and unparser, the easiest way to do that is to clone the Mercurial repository on Bitbucket. To do this, type this command into a terminal:

hg clone https://bitbucket.org/boredzo/iso-8601-parser-unparser

I provide the ISO 8601 parser and unparser under a BSD license. For more information, see the file named LICENSE.txt that comes with it.