A formatter that converts between dates and their textual representations.
SDKs
- iOS 2.0+
- macOS 10.0+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Foundation
Declaration
@interface NSDateFormatter : NSFormatter
Overview
Instances of NSDate 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 provides a variety of localized presets and configuration options. For fixed format representations of dates and times, you can specify a custom format string.
When working with date representations in ISO 8601 format, use NSISO8601Date instead.
To represent an interval between two NSDate objects, use NSDate instead.
To represent a quantity of time specified by an NSDate object, use NSDate instead.
Working With User-Visible Representations of Dates and Times
When displaying a date to a user, you set the date and time 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 property to NSDate and the time property to NSDate. Conversely, if you want to show only the time, you would set the date property to NSDate and the time property to NSDate. Based on the values of the date and time properties, NSDate 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 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 property to specify a format string. For most fixed formats, you should also set the locale property to a POSIX locale ("en), and set the time 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 is thread safe.
In macOS 10.9 and later NSDate 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 is not thread safe, and you therefore must not mutate a date formatter simultaneously from multiple threads.