Class

NSDateFormatter

Instances of NSDateFormatter 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, NSDateFormatter 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 NSISO8601DateFormatter instead.

To represent an interval between two NSDate objects, use NSDateIntervalFormatter instead.

To represent a quantity of time specified by an NSDateComponents object, use NSDateComponentsFormatter instead.

Working With User-Visible Representations of Dates and Times

When displaying a date to a user, you set the dateStyle and timeStyle 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 dateStyle property to NSDateFormatterLongStyle and the timeStyle property to NSDateFormatterNoStyle. Conversely, if you want to show only the time, you would set the dateStyle property to NSDateFormatterNoStyle and the timeStyle property to NSDateFormatterShortStyle. Based on the values of the dateStyle and timeStyle properties, NSDateFormatter 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 setLocalizedDateFormatFromTemplate: 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 dateFormat 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 timeZone 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 NSDateFormatter is thread safe.

In macOS 10.9 and later NSDateFormatter 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, NSDateFormatter is not thread safe, and you therefore must not mutate a date formatter simultaneously from multiple threads.

Symbols

Initializing a Date Formatter

- initWithDateFormat:allowNaturalLanguage:

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

Deprecated

Converting Objects

- dateFromString:

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

- stringFromDate:

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

+ localizedStringFromDate:dateStyle:timeStyle:

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

- getObjectValue:forString: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.

generatesCalendarDates

You should not use this property.

Managing Formats and Styles

dateStyle

The date style of the receiver.

timeStyle

The time style of the receiver.

dateFormat

The date format string used by the receiver.

- setLocalizedDateFormatFromTemplate:

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

+ dateFormatFromTemplate: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.

defaultDate

The default date for the receiver.

locale

The locale for the receiver.

timeZone

The time zone for the receiver.

twoDigitStartDate

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

gregorianStartDate

The start date of the Gregorian calendar for the receiver.

Managing Behavior Version

formatterBehavior

The formatter behavior for the receiver.

Managing Natural Language Support

- allowsNaturalLanguage

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.

doesRelativeDateFormatting

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

weekdaySymbols

The array of weekday symbols for the receiver.

shortWeekdaySymbols

The array of short weekday symbols for the receiver.

veryShortWeekdaySymbols

The array of very short weekday symbols for the receiver.

standaloneWeekdaySymbols

The array of standalone weekday symbols for the receiver.

shortStandaloneWeekdaySymbols

The array of short standalone weekday symbols for the receiver.

veryShortStandaloneWeekdaySymbols

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

Managing Month Symbols

monthSymbols

The month symbols for the receiver.

shortMonthSymbols

The array of short month symbols for the receiver.

veryShortMonthSymbols

The very short month symbols for the receiver.

standaloneMonthSymbols

The standalone month symbols for the receiver.

shortStandaloneMonthSymbols

The short standalone month symbols for the receiver.

veryShortStandaloneMonthSymbols

The very short month symbols for the receiver.

Managing Quarter Symbols

quarterSymbols

The quarter symbols for the receiver.

shortQuarterSymbols

The short quarter symbols for the receiver.

standaloneQuarterSymbols

The standalone quarter symbols for the receiver.

shortStandaloneQuarterSymbols

The short standalone quarter symbols for the receiver.

Managing Era Symbols

eraSymbols

The era symbols for the receiver.

longEraSymbols

The long era symbols for the receiver

Constants

NSDateFormatterStyle

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

NSDateFormatterBehavior

Constants that specify the behavior NSDateFormatter should exhibit.

Instance Properties

Relationships

Inherits From