< Previous PageNext Page > Hide TOC

Date Formatters

This article describes how you use date formatters using Mac OS X v10.4 and later and iPhone OS. If you are using Mac OS X v10.3 or earlier, you should read “Date and Number Formatters on Mac OS X v10.0 to 10.3.”

Contents:

Behavior Modes
Formatter Styles
Parsing and Creating Strings
Format Strings

Behavior Modes

On Mac OS X desktop version 10.4 and later, instances of an NSDateFormatter can operate in two modes, 10.0 compatibility mode and 10.4 mode.

• In the v10.0 compatibility mode, NSDateFormatter operates as it did in Mac OS X from version 10.0 to 10.3, including the limitations and bugs—see “Date and Number Formatters on Mac OS X v10.0 to 10.3.”

• On Mac OS X v10.4 and later, the behavior of the NSDateFormatter class is based on CFDateFormatter, which is in turn based on the open-source ICU (International Components for Unicode) library. (NSDateFormatter and CFDateFormatter, however, are not toll-free bridged.)

The v10.4 behavior mode allows more configurability and better localization; you should use it for any new projects, and ideally upgrade any existing code that uses v10.0 behavior to use v10.4 behavior.

For backwards binary compatibility, the default behavior for NSDateFormatter on Mac OS X version 10.4 is the v10.0 behavior. On Mac OS X version 10.5 and later, however, the default is the v10.4 behavior. You can set the default behavior of all instances of NSDateFormatter to the v10.4 behavior by invoking the class method, setDefaultFormatterBehavior: with the argument NSDateFormatterBehavior10_4. You can also set the behavior for any instance individually by invoking setFormatterBehavior:.

You can set an application default (preference) to cause date formatters to be automatically converted to the new style. Set the NSMakeDateFormatters10_4 default to a Boolean YES/true value in the application's preferences. You must set the preference before any use is made of the NSDateFormatter class. Note that the default has two effects:

1. Date formatters you initialize with init adopt the v10.4 formatter behavior.

2. Date formatters that are unarchived from either non-keyed or keyed archives are converted to v10.4-style if the archived formatter has an un-customized format string at unarchive time.

The object type for date formatters that use the v10.0 behavior mode is NSCalendarDate, but for new-style formatters it is NSDate. If you want, you can configure a new style formatter to generate NSCalendarDate objects using setGeneratesCalendarDates:. You are encouraged, however, to switch to using NSDate for new style formatters.

The 10.4 methods do not do anything when invoked on a v10.0-style formatter, and return a generic return value when required to return something—you should therefore not invoke the new methods on a v10.0-style formatter. On a v10.4-style formatter, the old methods map approximately to one or more new methods or attributes, but you should use the new methods directly when possible.

Formatter Styles

There are many attributes you can get and set on a date formatter, including the date style, time style, locale, time zone, calendar, format string, the two-digit-year cross-over date, the default date which provides unspecified components, and there is also access to the various textual strings, like the month names. You are encouraged, however, not to change individual settings, but instead to use the NSDateFormatter style constants to specify pre-defined sets of attributes that determine how a formatted date is displayed—NSDateFormatterNoStyle, NSDateFormatterShortStyle, NSDateFormatterMediumStyle, NSDateFormatterLongStyle, or NSDateFormatterFullStyle. These are styles that the user can configure in the International preferences panel in System Preferences. If you specify your own format string, you lose user-configurability. The code sample below illustrates how you can set a date format using formatter styles.

// assume default behavior set for class using

// [NSDateFormatter setDefaultFormatterBehavior:NSDateFormatterBehavior10_4];

NSDateFormatter *dateFormatter =

        [[[NSDateFormatter alloc] init] autorelease];

[dateFormatter setDateStyle:NSDateFormatterMediumStyle];

[dateFormatter setTimeStyle:NSDateFormatterNoStyle];

NSDate *date =

        [NSDate dateWithTimeIntervalSinceReferenceDate:118800];

NSString *formattedDateString = [dateFormatter stringFromDate:date];

NSLog(@"formattedDateString for locale %@: %@",

        [[dateFormatter locale] localeIdentifier], formattedDateString);

// Output: formattedDateString for locale en_US: Jan 2, 2001

Parsing and Creating Strings

In addition to the methods inherited from NSFormatter, NSDateFormatter adds two convenience methods—stringFromDate: and dateFromString:—and a new method to parse a string—getObjectValue:forString:range:error:. These methods make it easier for you to use an NSDateFormatter object directly in code, and make it easier to format dates into strings more complex and more convenient ways than NSString formatting allows.

The getObjectValue:forString:range:error: method allows you to specify a subrange of the string to be parsed, and it returns the range of the string that was actually parsed (in the case of failure, it indicates where the failure occurred). It also returns an NSError object that can contain richer information than the failure string returned by the getObjectValue:forString:errorDescription: method inherited from NSFormatter.

Note that, since they work with general instances of NSFormatter, instances of NSCell only invoke the NSFormatter getObjectValue:forString:errorDescription: method on Mac OS X v10.4. For a v10.4-style date formatter, that method calls getObjectValue:forString:range:error:.

The v10.4-style date formatter’s lenient parsing mode is not as forgiving as the "natural language" parsing of NSDateFormatter when the allowsNaturalLanguage option is enabled in the formatter. This has advantages and disadvantages: users will have to be more careful and perhaps thorough when typing in dates, but they are more likely to find that the value they were trying to input was correctly set to the value they wanted rather than what the "natural language" parsing guessed they meant.

Format Strings

The format string uses the format patterns from the Unicode standard (this reference is to version tr35-6 for Mac OS X v10.5; for Mac OS X v10.4 use version tr35-4). (When the formatter is in v10.0 mode, you must use the old-style format strings, described in “Date Format String Syntax (Mac OS X Versions 10.0 to 10.3).”) Note with the Unicode format string format, you should enclose literal text in the format string inside single quotes ('), as illustrated in the following example:

NSDateFormatter *inputFormatter = [[NSDateFormatter alloc] init];

[inputFormatter setDateFormat:@"yyyy-MM-dd 'at' HH:mm"];

NSDate *formatterDate = [inputFormatter dateFromString:@"1999-07-11 at 10:30:03"];

NSDateFormatter *outputFormatter = [[NSDateFormatter alloc] init];

[outputFormatter setDateFormat:@"HH:mm 'on' EEEE MMMM d"];

NSString *newDateString = [outputFormatter stringFromDate:formatterDate];

NSLog(@"newDateString %@", newDateString);

// For US English, the output is:

// newDateString 10:30 on Sunday July 11

< Previous PageNext Page > Hide TOC