ISO 8601 date formatter

An NSFormatter subclass to convert an ISO 8601 string to an NSDate and back


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.7 — 2013-10-09

0.6 — 2011-11-05

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.

Objective-C source code and test programs, with Xcode project, in a zip archive.
MD5 hash: bf8194cbdf42c4e988a9cbb0217f3fd9
SHA-1 hash: eeac6f2a873ba6c94448e271064787d1a7124881
Objective-C source code and test programs, with Makefile, in a zip archive.
MD5 hash: ee5e0d014aa43556f0cd51d9304de492
SHA-1 hash: 3f1228d71f3375c038805850ee468688d65d49a4

MD5 and SHA1 signatures for 0.6 and later were created using EasyHash.

SHA1 signatures for versions through 0.5 were created using the sha1sum(1) utility from GNU coreutils.


If you want to contribute bug-fixes or enhancements to the ISO 8601 date formatter, the easiest way to do that is to clone the Git repository on GitHub. See GitHub's help page on this topic.

This project used to be hosted in a Mercurial repository. The old Mercurial repository will never again be updated! It is frozen forever at 0.6. If you want to follow changes or contribute changes yourself, follow and/or clone the Git repo.

Thanks to Jonathan Wight for converting the old Mercurial repo to Git.

I provide the ISO 8601 date f,ormatter under a BSD license. For more information, see the file named LICENSE.txt that comes with it.

Valid XHTML 1.0! Valid CSS!