< Previous PageNext Page > Hide TOC

Converting Dates to Strings

The first section, “String Representations of NSDate Objects,” describes some formatting methods for NSDate. The last two sections, “The Calendar Format” and “String Representations of NSCalendarDate Objects,” describes methods for formatting NSCalendarDate.

String Representations of NSDate Objects

To represent your date object as an NSString object, use the description... methods. The simplest method, description, prints out the date in the format YYYY-MM-DD HH:MM:SS ±HHMM, where ±HHMM represents the time zone offset in hours and minutes from GMT. (Adding the offset to the specific time yields the equivalent GMT.) To have a specific locale dictionary affect the representation of your NSDate object, use descriptionWithLocale: instead of description. The following keys in the locale dictionary affect NSDate objects:

Note that NSDate’s implementation of the description method uses NSCalendarDate. NSCalendarDate does not model the transition from the Julian to the Gregorian calendar, so using NSDate’s description method yields inaccurate results for dates earlier than October 1582. If you need to describe dates earlier than the transition, you should use NSDateFormatter (as described in Data Formatting Programming Guide for Cocoa).

The Calendar Format

Each NSCalendarDate object has a calendar format associated with it. This format is a string that contains date-conversion specifiers that are very similar to those used in the standard C library function strftime(). NSCalendarDate interprets dates that are represented as strings conforming to this format. You can set the default format for an NSCalendarDate object at initialization time or using the setCalendarFormat: method. Several methods allow you to specify formats other than the one bound to the object.

The date conversion specifiers cover a range of date conventions:

Note that most of the formats that specify numeric values pad the width of the value with 0s (for example, %S represents 6 seconds as 06). You can suppress these 0s using a width specifier, just as you would with, for example, printf, as illustrated by the following example.

NSCalendarDate *date = [NSCalendarDate dateWithYear:2006 month:2 day:2

                                       hour:2 minute:2 second:2

                                       timeZone:nil];

[date setCalendarFormat:@"%m (%1m), %d (%1d), %I (%1I), %j (%1j), %S (%1S)"];

NSLog(@"date: %@", date);

// Output: date: 02 (2), 02 (2), 02 (2), 033 (33), 02 (2)

String Representations of NSCalendarDate Objects

NSCalendarDate provides several description... methods for representing dates as strings. These methods—description, descriptionWithLocale:, descriptionWithCalendarFormat:, and descriptionWithCalendarFormat:locale:—take an implicit or explicit calendar format. The user’s locale information affects the returned string. NSCalendarDate accesses the locale information as an NSDictionary object. If you use descriptionWithLocale: or descriptionWithCalendarFormat:locale:, you can specify a different locale dictionary. The following keys in the locale dictionary affect NSCalendarDate:

If you subclass NSCalendarDate and override description, you should also override descriptionWithLocale:. The stringWithFormat: method of NSString uses descriptionWithLocale: instead of description when you use the %@ conversion specifier to print an NSCalendarDate. That is, this message:

[NSString stringWithFormat:@"The current date and time are %@",

        [MyNSCalendarDateSubclass date]]

invokes descriptionWithLocale:.

< Previous PageNext Page > Hide TOC