Welcome to Getting to Know Cocoa , I’m Saul Mora. On each installment of Getting to Know Cocoa, we’ll peek inside the Developer docs and introduce a class, Framework, function or feature.

In this edition of Gettin to Know Cocoa, we’ll be talking about NSDate and NSDateFormatter.

The first thing you need to understand about NSDate is that instances are immutable. That is, once they have been initialized, you cannot change the value of that one instance. If oyu need to add or subtract a time interval from an instance, you will be returned with a new instance of an NSDate object. Also, remember that NSDate calculations such as adding time are done with NSTimeIntervals, which are seconds typed as floats.

NSDate is toll free bridged with CFDate, it’s Core Foundation counterpart. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSDate * parameter, you can pass a CFDateRef, and in a function where you see a CFDateRef parameter, you can pass an NSDate instance (you cast one type to the other to suppress compiler warnings).

To create an NSDate, you have a couple of options. First, you can create a date that reflects the date and time that code is run. Simply call [NSDate date]. To create a date representing a particular time interval, you can use [NSDate dateWithTimeIntervalSinceReferenceDate:]. The reference date is 12:00am January 1, 2001. Also available is [NSDate dateWIthTimeIntervaleSince1970:], which is 12:00am January 1, 1970. You can specify negative time intervals to get NSDates prior to the reference date.

You can add a time interval to a date instance, but the method to do so has changed in iOS 4.0. Use dateByAddingTimeInterval: rather than the deprecated addTimeInterval: method. I am reminded by @pliky on twitter that XCode won’t tell you what’s deprecated in the type ahead prompts.

Sometimes, you’ll want to parse dates from strings, and for that you’ll need to use NSDateFormatter’s dateFromString: method. You can also print out a custom formatted string using the stringFromDate: method. NSDateFormatters follow the unicode standard formatting strings, and I highly recommend that you at least keep a bookmark handy. I’ll include that in the episode notes.

You can also listen for a system wide notification, NSSystemClockDidChangeNotification to make sure your app is aware of when the system time changes. And, if you’re curious, you can also see what the value NSTimeIntervalSince1970 is….it’s 978307200.0…which is the number of seconds between from Jan1 1970 to Jan12001.

You can also compare dates using the compare: method. From this method, you can check the NSComparisonResult return value against NSOrderedSame, NSOrderedDescending or NSOrderedAscending to find out the order of a date. However, if you just want to know which date is later than another, you can use the laterDate: method to get the date that is the later for two dates. There is also an earlierDate: method that will return…the earlierDate…

On the mac, you have access to a couple other creation methods, namely: [NSDate dateWithNaturalLanguageString:] and dateWithString: . The former will let you put in something like “last Tuesday at dinner” or “3pm december 31”. You can also specify a custom dictionary that will help translate other words. However, this method is primarly based on english words, and it’s use is dicouraged in the docs. The dateWithString method lets you specify a date format in the creation method. Usually in iOS apps, I have to create an NSDate category that does this, and you have it for free in the MacOS APIs.

As always, I encourage you to take a few minutes and check out the docs in detail for yourself.

Rate