It is quite common to have to display time information in your app, be it the current time, news feed’s creation date, scheduled meeting time or birthday reminders. However, not all of them are displayed the same way and may require different formatting. To do that with Objective-C for iPhone apps, NSDateFormatter is what we need.
In most cases, you’d just need to use the default styles defined in NSDateFormatterStyle.
NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init]; [dateFormatter setDateStyle:NSDateFormatterMediumStyle]; [dateFormatter setTimeStyle:NSDateFormatterShortStyle]; NSLog(@"%@", [dateFormatter stringFromDate:[NSDate date]]); [dateFormatter release]; // Output: Dec 2, 2008 3:58 PM
But at times, you’d prefer to set your own time format, and that’s where it starts to get tricky.
It is actually quite simple, all you have to do is to create a format string to tell NSDateFormatter how to format your time string.
: [dateFormatter setDateFormat:@"hh:mm:ss"] : // Output: 03:58:27
The problem is, the official documentation from apple doesn’t really tell you what specifiers are available to format your string. Even worse, it doesn’t conform to the ISO 8601 standard! What a bummer! And after a bit of searching on the net and still come up short, I have decided to just hack a little bit of code together to dump a list of specifiers and their results.
(EDIT: Apparently, there is now a link to the Unicode Date Field Symbol Table that Apple follows, even though my test shows that it still doesn’t conform 100% to the standard. Thanks Benjamin and Adam for finding it.)
a: AM/PM A: 0~86399999 (Millisecond of Day) c/cc: 1~7 (Day of Week) ccc: Sun/Mon/Tue/Wed/Thu/Fri/Sat cccc: Sunday/Monday/Tuesday/Wednesday/Thursday/Friday/Saturday d: 1~31 (0 padded Day of Month) D: 1~366 (0 padded Day of Year) e: 1~7 (0 padded Day of Week) E~EEE: Sun/Mon/Tue/Wed/Thu/Fri/Sat EEEE: Sunday/Monday/Tuesday/Wednesday/Thursday/Friday/Saturday F: 1~5 (0 padded Week of Month, first day of week = Monday) g: Julian Day Number (number of days since 4713 BC January 1) G~GGG: BC/AD (Era Designator Abbreviated) GGGG: Before Christ/Anno Domini h: 1~12 (0 padded Hour (12hr)) H: 0~23 (0 padded Hour (24hr)) k: 1~24 (0 padded Hour (24hr) K: 0~11 (0 padded Hour (12hr)) L/LL: 1~12 (0 padded Month) LLL: Jan/Feb/Mar/Apr/May/Jun/Jul/Aug/Sep/Oct/Nov/Dec LLLL: January/February/March/April/May/June/July/August/September/October/November/December m: 0~59 (0 padded Minute) M/MM: 1~12 (0 padded Month) MMM: Jan/Feb/Mar/Apr/May/Jun/Jul/Aug/Sep/Oct/Nov/Dec MMMM: January/February/March/April/May/June/July/August/September/October/November/December q/qq: 1~4 (0 padded Quarter) qqq: Q1/Q2/Q3/Q4 qqqq: 1st quarter/2nd quarter/3rd quarter/4th quarter Q/QQ: 1~4 (0 padded Quarter) QQQ: Q1/Q2/Q3/Q4 QQQQ: 1st quarter/2nd quarter/3rd quarter/4th quarter s: 0~59 (0 padded Second) S: (rounded Sub-Second) u: (0 padded Year) v~vvv: (General GMT Timezone Abbreviation) vvvv: (General GMT Timezone Name) w: 1~53 (0 padded Week of Year, 1st day of week = Sunday, NB: 1st week of year starts from the last Sunday of last year) W: 1~5 (0 padded Week of Month, 1st day of week = Sunday) y/yyyy: (Full Year) yy/yyy: (2 Digits Year) Y/YYYY: (Full Year, starting from the Sunday of the 1st week of year) YY/YYY: (2 Digits Year, starting from the Sunday of the 1st week of year) z~zzz: (Specific GMT Timezone Abbreviation) zzzz: (Specific GMT Timezone Name) Z: +0000 (RFC 822 Timezone)
(Letters not listed here did not return any result.)
Basically, you put the above letters together in a NSString to tell NSDateFormatter what to display.
In most cases, you can concatenate a letter together a number of times, and you will get a 0 padded version of it up to the number of letters you have concatenated (eg: @”ssssss” => @”000059″). In other cases, the longer concatenated version will give a different result (eg: @”M” => @”12″, @”MMMM” => @”December”).
Also, some of the different letters seem to be giving out the same results (eg. the q’s & the Q’s), while others have subtle differences (eg. the v’s & the z’s). One of the silly one is the uppercase Y’s, where the year jumps ahead at the end of the year, so unless you really want that, it’s better to just stick with the lowercase y’s.
You can grab the sample code here: DateFormat
NSDateFormatter formatting at Under The Bridge
January 29th, 2009 at 1:02 am
[...] Ever wonder just what you could put in NSDateFormatter format strings? Enough to actually go to the trouble of actually dumping specifiers and results? Nah, us neither. But somebody did, and here’s what they found: [...]
Benjamin Ragheb
February 17th, 2009 at 1:47 am
It uses the Unicode format, and the documentation links to the spec:
http://unicode.org/reports/tr35/tr35-6.html#Date_Format_Patterns
You seriously couldn’t find it?
Adam Knight
March 24th, 2009 at 11:24 am
Actually, Apple does document the codes. They say in the “Data Formatting Programming Guide for Cocoa” that the 10.4-style date formatters, when used in 10.5 and iPhone, use Unicode standard tr35-6 (http://unicode.org/reports/tr35/tr35-6.html#Date_Format_Patterns) markers.
At the bottom of: http://developer.apple.com/documentation/Cocoa/Conceptual/DataFormatting/Articles/dfDateFormatting10_4.html
But thanks for the lead, it’s not easy to find in the docs. I had to find your page and then full-text search the docs for “EEEE” to find the reference, and then I found it because it was an example!
Johnny
April 22nd, 2009 at 4:21 am
Thanks Benjamin and Adam for the heads up.
My guess is that Apple might have updated that page to include the links, as I have referenced that page in my post as well… either that or I have over looked their welly hidden links ^_^. Either way, I still blame Apple for not making it more clear.
After taking a look at the Unicode Standard code page, it seems that Apple’s implementation still doesn’t quite 100% follow the standard. But I guess it’s close enough and the minor discrepancies don’t among to much.
A Little More on NSDateFormatter « David J. Hinson’s Logorrhea
June 11th, 2009 at 12:36 am
[...] I ran across this blog post that does a good job of consolidating format strings for NSDateFormatter in one place. I thought [...]
LukeChampetierDeRibes
January 21st, 2010 at 2:20 pm
Hello,
I am Luke, soon 37 ,
I am a professor and teach sciences at university
regards,
Luke, ingenieur
Jay S. Cox
February 14th, 2010 at 6:33 pm
Hello! Nice and interesting site, glad to see you on my cialis professional review Hope to see you soon.
besslialliarm
March 5th, 2010 at 4:28 am
The response to national disaster is great but it’s a real shame that so many people take advantage of the negative situations.
I mean everytime there is an earthquake, a flood, an oil spill – there’s always a group of heartless people who rip off tax payers.
This is in response to reading that 4 of Oprah Winfreys “angels” got busted ripping off the system. Shame on them!
http://www.cbsnews.com/blogs/2009/08/19/crimesider/entry5251471.shtml
kamagman123
April 15th, 2010 at 3:39 pm
Learn more about Kamagra Oral Jelly
Date Formatting in Objective-C | Boydlee's Blog
May 9th, 2010 at 5:10 am
[...] http://www.stepcase.com/blog/2008/12/02/format-string-for-the-iphone-nsdateformatter/ Post Published: 09 May 2010 Author: admin Found in section: iPhone [...]
NSDateFormatter formatting strings reference | deanoj
May 9th, 2010 at 6:50 am
[...] formatting strings. Sourced from this blog post. a: AM/PM A: 0~86399999 (Millisecond of Day) c/cc: 1~7 (Day of Week) ccc: [...]
iPhone – Display Date and Time Using NSDateFormatter « Eureka!
June 16th, 2010 at 10:04 am
[...] The above examples are found in Unicode Technical Standard #35. But it is found that Apple is not 100% conform to the standard. More examples can be found at Format String for the iPhone NSDateFormatter. [...]
eddy
July 22nd, 2010 at 4:29 pm
I ran across a weird timezone at the end the date string that I could not format. Instead of the standard -0500 it has a colon in it -05:00
2010-12-07T10:11:00-05:00
Any suggestions?