|ReleasedLast Release||Apr 2016|
Maintained by Peter Hosey.
Obligatory relevant xkcd:
Add the source files to your project.
Create an ISO 8601 date formatter, then call
[formatter dateFromString:myString]. The method will return either an NSDate or
There are a total of six parser methods. The one that contains the actual parser is
-[ISO8601DateFormatter dateComponentsFromString:timeZone:range:]. The other five are based on this one.
outTimeZone” parameter, when not set to
NULL, is a pointer to an
NSTimeZone *variable. If the string specified a time zone, you'll receive the time zone object in that variable. If the string didn't specify a time zone, you'll receive
outRange” parameter, when not set to
NULL, is a pointer to
NSRange storage. You will receive the range of the parsed substring in that storage.
Create an ISO 8601 date formatter, then call
[formatter stringFromDate:myDate]. The method will return a string.
The formatter has several properties that control its behavior:
UPDATE from the year 2013: Conversion from the old make-based test monsters to modern OCUnit-based tests is underway. Contributions of new and old test cases will be greatly appreciated.
'make test' will perform all tests. If you want to perform only some tests:
Type 'make parser-test'. make will build the test program (testparser), then invoke testparser.sh.py to generate testparser.sh. Then make will invoke testparser.sh, which will invoke the test program with various dates.
If you don't want to use my tests, 'make testparser' will create the test program without running it. You can then invoke testparser yourself with any date you want to. If it doesn't give you the result you expected, contact me, making sure to provide me with both the input and the output.
Type 'make unparser-test'. make will build the test programs, then invoke testunparser.sh. This shell script invokes each test program for -01-01 of every year from 1991 to 2010, writing the output to a file, and then runs diff -qs between that file (testunparser.out) and a file (testunparser-expected.out) containing known correct output. diff should report that the files are identical.
Three test programs are included: unparse-date, unparse-weekdate, and unparse-ordinal date. If you don't want to use my tests, you can make these test programs separately. Each takes a date specified by ISO 8601 (parsed with my own ISO 8601 parser), and outputs a string that should represent the same date.
This version is 0.7. Changes from 0.6:
stringFromObjectValue:now logs to the Console when you hand it a value that isn't an NSDate. Check your Console output after upgrading—you might have had a bug all this time without knowing! 4e05978
nil. 3c12abc 4980ee6
stringFromObjectValue:to behave as NSFormatter's documentation says it should. 3846f80 9754438
ISO8601DefaultTimeSeparatorCharacteris now declared as
const. I hope none of you were relying on changing that. db9877c
Changes in 0.6 from 0.5:
description) and input (
Changes in 0.5 from 0.4:
Changes in 0.4 from 0.3:
Changes in 0.3 from 0.2:
%Mwhen creating the time strings. Oops.
ISO8601DateStringWithTime:the wrong way around. Oops again.
Changes in 0.2 from 0.1:
Whitespace before a date, and anything after a date, is ignored. Thus, " T23 and all's well" is a valid date for the purpose of this method. (Yes, T23 is a valid ISO 8601 date. It means 23:00:00, or 11 PM.)
All of the frills of ISO 8601 are supported, except for extended dates (years longer than 4 digits). Specifically, you can use week-based dates (2006-W2 for the second week of 2006), ordinal dates (2006-365 for December 31), decimal minutes (11:30.5 == 11:30:30), and decimal seconds (11:30:10.5). All methods of specifying a time zone are supported.
ISO 8601 leaves quite a bit up to the parties exchanging dates. I hope I've chosen reasonable defaults. For example (note that I'm writing this on 2006-02-24):
When a date is parsed that has a year but no century, this implementation adds the current century.
The implementation is tolerant of out-of-range numbers. For example, "2005-13-40T24:62:89" == 1:02 AM on 2006-02-10. Notice that the month (13 > 12), date (40 > 31), hour (24 > 23), minute (62 > 59), and second (89 > 59) are all out-of-range.
As mentioned above, there is a "strict" mode that enforces sanity checks. In particular, the date must be the entire contents of the string, and numbers are range-checked. If you have any suggestions on how to make this mode more strict, please file an enhancement request in the Issues section.
I use Rick McCarty's algorithm for converting calendar dates to week dates, slightly tweaked.
This method won't extract a date from just anywhere in a string, only immediately after the start of the string (or any leading whitespace). There are two solutions: either require you to invoke the parser on a string that is only an ISO 8601 date, with nothing before or after (bad for parsing purposes), or make the parser able to find an ISO 8601 date as a substring. I won't do the first one, and barring a patch, I probably won't do the second one either.
Date ranges (also specified by ISO 8601) are not supported; this method will only return one date. To handle ranges would require at least one more method.
There is no method to analyze a date string and tell you what was found in it (year, month, week, day, ordinal day, etc.). Feel free to submit a patch.
This code is copyright 2006–2013 Peter Hosey. It is under the BSD license; see LICENSE.txt for the full text of the license.