Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

NSDateFormatter on Mac OS X 10.4

The NSDateFormatter class is significantly enhanced in Mac OS X v10.4. The new implementation 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. To ensure backwards binary compatibility, the default behavior for NSDateFormatter in Mac OS X v10.4 is the v10.0 behavior.

Contents:

Default Behavior
Formatter Styles
Parsing and Creating Strings
Format Strings

Default Behavior

On Mac OS X version 10.4, instances of an NSDateFormatter can operate in two modes. 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 “Creating and Using Formatters Programmatically (Mac OS X 10.0 to 10.3).” The new v10.4 behavior mode allows more configurability and better localization. For backwards binary compatibility, the default behavior for NSDateFormatter in Mac OS X version 10.4 is the v10.0 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 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 still 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 new methods in v10.4 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 new attributes one can get and set on a v10.4-style 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 in Mac OS X v10.4. For a v10.4-style date formatter, that method calls getObjectValue:forString:range:error:.

The difference you may notice with a new v10.4-style date formatter is that the 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 biggest change in a v10.4-style formatter is the format of the format string. The "%A %B %y" style described in “Date Format String Syntax (Mac OS X Versions 10.0 to 10.3)” has been replaced with the format string from the Unicode standard (this reference is to version tr35-6; formatters 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. Note with the Unicode format string format, you should enclose literal text in the format string inside single quotes (').

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice