Class

NSDate​Formatter

Instances of NSDate​Formatter create string representations of NSDate objects, and convert textual representations of dates and times into NSDate objects. For user-visible representations of dates and times, NSDate​Formatter provides a variety of localized presets and configuration options. For fixed format representations of dates and times, you can specify a custom format string.

Overview

When working with date representations in ISO 8601 format, use NSISO8601Date​Formatter instead.

To represent an interval between two NSDate objects, use NSDate​Interval​Formatter instead.

To represent a quantity of time specified by an NSDate​Components object, use NSDate​Components​Formatter instead.

Working With User-Visible Representations of Dates and Times

When displaying a date to a user, you set the date​Style and time​Style properties of the date formatter according to your particular needs. For example, if you want to show the month, day, and year without showing the time, you would set the date​Style property to NSDate​Formatter​Long​Style and the time​Style property to NSDate​Formatter​No​Style. Conversely, if you want to show only the time, you would set the date​Style property to NSDate​Formatter​No​Style and the time​Style property to NSDate​Formatter​Short​Style. Based on the values of the date​Style and time​Style properties, NSDate​Formatter provides a representation of a specified date that is appropriate for a given locale.

NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
dateFormatter.dateStyle = NSDateFormatterMediumStyle;
dateFormatter.timeStyle = NSDateFormatterNoStyle;
 
NSDate *date = [NSDate dateWithTimeIntervalSinceReferenceDate:118800];
 
// US English Locale (en_US)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US"];
NSLog(@"%@", [dateFormatter stringFromDate:date]); // Jan 2, 2001
 
// French Locale (fr_FR)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"fr_FR"];
NSLog(@"%@", [dateFormatter stringFromDate:date]); // 2 janv. 2001
 
// Japanese Locale (ja_JP)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"ja_JP"];
NSLog(@"%@", [dateFormatter stringFromDate:date]); // 2001/01/02

If you need to define a format that cannot be achieved using the predefined styles, you can use the set​Localized​Date​Format​From​Template:​ to specify a localized date format from a template.

NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
NSDate *date = [NSDate dateWithTimeIntervalSinceReferenceDate:410220000];
 
// US English Locale (en_US)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US"];
[dateFormatter setLocalizedDateFormatFromTemplate:@“MMMMd”]; // set template after setting locale
NSLog(@"%@", [dateFormatter stringFromDate:date]); // December 31
 
// British English Locale (en_GB)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_GB"];
[dateFormatter setLocalizedDateFormatFromTemplate:@“MMMMd”]; // set template after setting locale
NSLog(@"%@", [dateFormatter stringFromDate:date]); // 31 December

Working With Fixed Format Date Representations

When working with fixed format dates, such as RFC 3339, you set the date​Format property to specify a format string. For most fixed formats, you should also set the locale property to a POSIX locale ("en_US_POSIX"), and set the time​Zone property to UTC.

RFC3339DateFormatter = [[NSDateFormatter alloc] init];
RFC3339DateFormatter.locale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
RFC3339DateFormatter.dateFormat = @"yyyy-MM-dd'T'HH:mm:ssZZZZZ";
RFC3339DateFormatter.timeZone = [NSTimeZone timeZoneForSecondsFromGMT:0];
 
/* 39 minutes and 57 seconds after the 16th hour of December 19th, 1996 with an offset of -08:00 from UTC (Pacific Standard Time) */
NSString *string = @"1996-12-19T16:39:57-08:00";
NSDate *date = [RFC3339DateFormatter dateFromString:string];

For more information, see Technical Q&A QA1480 “NSDateFormatter and Internet Dates”.

Thread Safety

On iOS 7 and later NSDate​Formatter is thread safe.

In macOS 10.9 and later NSDate​Formatter is thread safe so long as you are using the modern behavior in a 64-bit app.

On earlier versions of the operating system, or when using the legacy formatter behavior or running in 32-bit in macOS, NSDate​Formatter is not thread safe, and you therefore must not mutate a date formatter simultaneously from multiple threads.

Symbols

Converting Objects

- date​From​String:​​

Returns a date representation of a given string interpreted using the receiver’s current settings.

- string​From​Date:​​

Returns a string representation of a given date formatted using the receiver’s current settings.

+ localized​String​From​Date:​​date​Style:​​time​Style:​​

Returns a string representation of a given date, formatted for the current locale using the specified date and time styles.

- get​Object​Value:​​for​String:​​range:​​error:​​

Returns by reference a date representation of a given string and the range of the string used, and returns a Boolean value that indicates whether the string could be parsed.

generates​Calendar​Dates

You should not use this property.

Managing Formats and Styles

date​Style

The date style of the receiver.

time​Style

The time style of the receiver.

date​Format

The date format string used by the receiver.

- set​Localized​Date​Format​From​Template:​​

Sets the date format from a template using the specified locale for the receiver.

+ date​Format​From​Template:​​options:​​locale:​​

Returns a localized date format string representing the given date format components arranged appropriately for the specified locale.

Managing Attributes

calendar

The calendar for the receiver.

default​Date

The default date for the receiver.

locale

The locale for the receiver.

time​Zone

The time zone for the receiver.

two​Digit​Start​Date

The earliest date that can be denoted by a two-digit year specifier.

gregorian​Start​Date

The start date of the Gregorian calendar for the receiver.

Managing Behavior Version

formatter​Behavior

The formatter behavior for the receiver.

default​Formatter​Behavior

Returns the default formatting behavior for instances of the class.

Managing Natural Language Support

- allows​Natural​Language

Returns a Boolean value that indicates whether the receiver attempts to process dates entered as a vernacular string.

Deprecated
lenient

A Boolean value that indicates whether the receiver uses heuristics when parsing a string.

does​Relative​Date​Formatting

A Boolean value that indicates whether the receiver uses phrases such as “today” and “tomorrow” for the date component.

Managing AM and PM Symbols

AMSymbol

The AM symbol for the receiver.

PMSymbol

The PM symbol for the receiver.

Managing Weekday Symbols

weekday​Symbols

The array of weekday symbols for the receiver.

short​Weekday​Symbols

The array of short weekday symbols for the receiver.

very​Short​Weekday​Symbols

The array of very short weekday symbols for the receiver.

standalone​Weekday​Symbols

The array of standalone weekday symbols for the receiver.

short​Standalone​Weekday​Symbols

The array of short standalone weekday symbols for the receiver.

very​Short​Standalone​Weekday​Symbols

The array of very short standalone weekday symbols for the receiver.

Managing Month Symbols

month​Symbols

The month symbols for the receiver.

short​Month​Symbols

The array of short month symbols for the receiver.

very​Short​Month​Symbols

The very short month symbols for the receiver.

standalone​Month​Symbols

The standalone month symbols for the receiver.

short​Standalone​Month​Symbols

The short standalone month symbols for the receiver.

very​Short​Standalone​Month​Symbols

The very short month symbols for the receiver.

Managing Quarter Symbols

quarter​Symbols

The quarter symbols for the receiver.

short​Quarter​Symbols

The short quarter symbols for the receiver.

standalone​Quarter​Symbols

The standalone quarter symbols for the receiver.

short​Standalone​Quarter​Symbols

The short standalone quarter symbols for the receiver.

Managing Era Symbols

era​Symbols

The era symbols for the receiver.

long​Era​Symbols

The long era symbols for the receiver

Deprecated Initializers

- init​With​Date​Format:​​allow​Natural​Language:​​

Initializes and returns an NSDate​Formatter instance that uses the OS X 10.0 formatting behavior and the given date format string in its conversions.

Deprecated

Constants

NSDate​Formatter​Style

The following constants specify predefined format styles for dates and times.

NSDate​Formatter​Behavior

Constants that specify the behavior NSDate​Formatter should exhibit.

Instance Properties

Relationships

Inherits From