iOS Developer Library

Developer

Foundation Framework Reference NSDateFormatter Class Reference

Options
Deployment Target:

On This Page
Language:

NSDateFormatter

Instances of NSDateFormatter create string representations of NSDate objects, and convert textual representations of dates and times into NSDate objects. You can express the representation of dates and times flexibly using pre-set format styles or custom format strings.

Date formats for user-visible strings should be configured using the styles configured by the user—use dateStyle, timeStyle, and appropriate style constants (defined in NSDateFormatterStyle) to choose between them.

  • NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
  • dateFormatter.timeStyle = NSDateFormatterNoStyle;
  • dateFormatter.dateStyle:NSDateFormatterMediumStyle;
  • NSDate *date = [NSDate dateWithTimeIntervalSinceReferenceDate:118800];
  • NSLocale *usLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US"];
  • [dateFormatter setLocale:usLocale];
  • NSLog(@"Date for locale %@: %@",
  • [[dateFormatter locale] localeIdentifier], [dateFormatter stringFromDate:date]);
  • // Output:
  • // Date for locale en_US: Jan 2, 2001
  • NSLocale *frLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"fr_FR"];
  • [dateFormatter setLocale:frLocale];
  • NSLog(@"Date for locale %@: %@",
  • [[dateFormatter locale] localeIdentifier], [dateFormatter stringFromDate:date]);
  • // Output:
  • // Date for locale fr_FR: 2 janv. 2001

If for some reason you need to define a format that was not specified by the user at the system level, you can set individual attributes such as the locale, time zone, calendar, format string, and various textual strings like the month names.

Note that although setting a format string (dateFormat) in principle specifies an exact format, in practice it may nevertheless also be overridden by a user’s preferences—see Data Formatting Guide for more details.

Formatter Behaviors and OS Versions

OS X v10.4 introduced the modern behavior for NSDateFormatter. See Data Formatting Guide for a full description of the old and new behaviors.

In OS X v10.5 and later, NSDateFormatter defaults to the modern behavior. If necessary, you can set the default class behavior using setDefaultFormatterBehavior:, or you can set the behavior for an instance using formatterBehavior.

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later.
  • Returns a date representation of a given string interpreted using the receiver’s current settings.

    Declaration

    Swift

    func dateFromString(_ string: String) -> NSDate?

    Objective-C

    - (NSDate *)dateFromString:(NSString *)string

    Parameters

    string

    The string to parse.

    Return Value

    A date representation of string interpreted using the receiver’s current settings. If dateFromString: can not parse the string, returns nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func stringFromDate(_ date: NSDate) -> String

    Objective-C

    - (NSString *)stringFromDate:(NSDate *)date

    Parameters

    date

    The date to format.

    Return Value

    A string representation of date formatted using the receiver’s current settings.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func localizedStringFromDate(_ date: NSDate, dateStyle dateStyle: NSDateFormatterStyle, timeStyle timeStyle: NSDateFormatterStyle) -> String

    Objective-C

    + (NSString *)localizedStringFromDate:(NSDate *)date dateStyle:(NSDateFormatterStyle)dateStyle timeStyle:(NSDateFormatterStyle)timeStyle

    Parameters

    date

    A date.

    dateStyle

    A format style for the date. For possible values, see NSDateFormatterStyle.

    timeStyle

    A format style for the time. For possible values, see NSDateFormatterStyle.

    Return Value

    A localized string representation of date using the specified date and time styles

    Discussion

    This method uses a date formatter configured with the current default settings. The returned string is the same as if you configured and used a date formatter as shown in the following example:

    • NSDateFormatter *formatter = [[NSDateFormatter alloc] init];
    • formatter.formatterBehavior = NSDateFormatterBehavior10_4;
    • [formatter.dateStyle = dateStyle;
    • [formatter.timeStyle = timeStyle;
    • NSString *result = [formatter stringForObjectValue:date];

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • 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.

    Declaration

    Swift

    func getObjectValue(_ obj: AutoreleasingUnsafeMutablePointer<AnyObject?>, forString string: String, range rangep: UnsafeMutablePointer<NSRange>, error error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)getObjectValue:(out id *)obj forString:(NSString *)string range:(inout NSRange *)rangep error:(out NSError **)error

    Parameters

    obj

    If the receiver is able to parse string, upon return contains a date representation of string.

    string

    The string to parse.

    rangep

    If the receiver is able to parse string, upon return contains the range of string used to create the date.

    error

    If the receiver is unable to create a date by parsing string, upon return contains an NSError object that describes the problem.

    Return Value

    YEStrue if the receiver can create a date by parsing string, otherwise NOfalse.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • You should not use this property.

    Declaration

    Swift

    var generatesCalendarDates: Bool

    Objective-C

    @property BOOL generatesCalendarDates

    Discussion

    YEStrue if the receiver generates calendar dates, otherwise NOfalse.

    NSCalendarDate is no longer supported; you should not use this method.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The date format string used by the receiver.

    Declaration

    Swift

    var dateFormat: String!

    Objective-C

    @property(copy) NSString *dateFormat

    Discussion

    See Data Formatting Guide for a list of the conversion specifiers permitted in date format strings.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • dateStyle dateStyle Property

    The date style of the receiver.

    Declaration

    Swift

    var dateStyle: NSDateFormatterStyle

    Objective-C

    @property NSDateFormatterStyle dateStyle

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • timeStyle timeStyle Property

    The time style of the receiver.

    Declaration

    Swift

    var timeStyle: NSDateFormatterStyle

    Objective-C

    @property NSDateFormatterStyle timeStyle

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func dateFormatFromTemplate(_ template: String, options opts: Int, locale locale: NSLocale?) -> String?

    Objective-C

    + (NSString *)dateFormatFromTemplate:(NSString *)template options:(NSUInteger)opts locale:(NSLocale *)locale

    Parameters

    template

    A string containing date format patterns (such as “MM” or “h”).

    For full details, see Date and Time Programming Guide.

    opts

    No options are currently defined—pass 0.

    locale

    The locale for which the template is required.

    Return Value

    A localized date format string representing the date format components given in template, arranged appropriately for the locale specified by locale.

    The returned string may not contain exactly those components given in template, but may—for example—have locale-specific adjustments applied.

    Discussion

    Different locales have different conventions for the ordering of date components. You use this method to get an appropriate format string for a given set of components for a specified locale (typically you use the current locale—see currentLocale).

    The following example shows the difference between the date formats for British and American English:

    • NSLocale *usLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US"];
    • NSLocale *gbLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_GB"];
    • NSString *dateFormat;
    • NSString *dateComponents = @"yMMMMd";
    • dateFormat = [NSDateFormatter dateFormatFromTemplate:dateComponents options:0 locale:usLocale];
    • NSLog(@"Date format for %@: %@",
    • [usLocale displayNameForKey:NSLocaleIdentifier value:[usLocale localeIdentifier]], dateFormat);
    • dateFormat = [NSDateFormatter dateFormatFromTemplate:dateComponents options:0 locale:gbLocale];
    • NSLog(@"Date format for %@: %@",
    • [gbLocale displayNameForKey:NSLocaleIdentifier value:[gbLocale localeIdentifier]], dateFormat);
    • // Output:
    • // Date format for English (United States): MMMM d, y
    • // Date format for English (United Kingdom): d MMMM y

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • calendar calendar Property

    The calendar for the receiver.

    Declaration

    Swift

    @NSCopying var calendar: NSCalendar!

    Objective-C

    @property(copy) NSCalendar *calendar

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The default date for the receiver.

    Declaration

    Swift

    @NSCopying var defaultDate: NSDate?

    Objective-C

    @property(copy) NSDate *defaultDate

    Discussion

    The default default date is nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • locale locale Property

    The locale for the receiver.

    Declaration

    Swift

    @NSCopying var locale: NSLocale!

    Objective-C

    @property(copy) NSLocale *locale

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • timeZone timeZone Property

    The time zone for the receiver.

    Declaration

    Swift

    @NSCopying var timeZone: NSTimeZone!

    Objective-C

    @property(copy) NSTimeZone *timeZone

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    @NSCopying var twoDigitStartDate: NSDate!

    Objective-C

    @property(copy) NSDate *twoDigitStartDate

    Discussion

    If the two-digit start date is set to January 6, 1976, then “January 1, 76” is interpreted as New Year's Day in 2076, whereas “February 14, 76” is interpreted as Valentine's Day in 1976.

    The default date is December 31, 1949.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The start date of the Gregorian calendar for the receiver.

    Declaration

    Swift

    @NSCopying var gregorianStartDate: NSDate!

    Objective-C

    @property(copy) NSDate *gregorianStartDate

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • lenient lenient Property

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

    Declaration

    Swift

    var lenient: Bool

    Objective-C

    @property(getter=isLenient) BOOL lenient

    Discussion

    YEStrue if the receiver has been set to use heuristics when parsing a string to guess at the date which is intended, otherwise NOfalse.

    If a formatter is set to be lenient, when parsing a string it uses heuristics to guess at the date which is intended. As with any guessing, it may get the result date wrong (that is, a date other than that which was intended).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var doesRelativeDateFormatting: Bool

    Objective-C

    @property BOOL doesRelativeDateFormatting

    Discussion

    YEStrue if the receiver uses relative date formatting, otherwise NOfalse.

    If a date formatter uses relative date formatting, where possible it replaces the date component of its output with a phrase—such as “today” or “tomorrow”—that indicates a relative date. The available phrases depend on the locale for the date formatter; whereas, for dates in the future, English may only allow “tomorrow,” French may allow “the day after the day after tomorrow,” as illustrated in the following example.

    • NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
    • dateFormatter.timeStyle = NSDateFormatterNoStyle;
    • dateFormatter.dateStyle = NSDateFormatterMediumStyle;
    • NSLocale *frLocale = [[NSLocale alloc] initWithLocaleIdentifier:@"fr_FR"];
    • dateFormatter.locale = frLocale;
    • dateFormatter.doesRelativeDateFormatting = YES;
    • NSDate *date = [NSDate dateWithTimeIntervalSinceNow:60*60*24*3];
    • NSString *dateString = [dateFormatter stringFromDate:date];
    • NSLog(@"dateString: %@", dateString);
    • // Output
    • // dateString: après-après-demain

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.

  • AMSymbol AMSymbol Property

    The AM symbol for the receiver.

    Declaration

    Swift

    var AMSymbol: String!

    Objective-C

    @property(copy) NSString *AMSymbol

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – PMSymbol

  • PMSymbol PMSymbol Property

    The PM symbol for the receiver.

    Declaration

    Swift

    var PMSymbol: String!

    Objective-C

    @property(copy) NSString *PMSymbol

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – AMSymbol

  • The array of weekday symbols for the receiver.

    Declaration

    Swift

    var weekdaySymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *weekdaySymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The array of short weekday symbols for the receiver.

    Declaration

    Swift

    var shortWeekdaySymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *shortWeekdaySymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var veryShortWeekdaySymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *veryShortWeekdaySymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The array of standalone weekday symbols for the receiver.

    Declaration

    Swift

    var standaloneWeekdaySymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *standaloneWeekdaySymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var shortStandaloneWeekdaySymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *shortStandaloneWeekdaySymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var veryShortStandaloneWeekdaySymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *veryShortStandaloneWeekdaySymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The month symbols for the receiver.

    Declaration

    Swift

    var monthSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *monthSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The array of short month symbols for the receiver.

    Declaration

    Swift

    var shortMonthSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *shortMonthSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The very short month symbols for the receiver.

    Declaration

    Swift

    var veryShortMonthSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *veryShortMonthSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The standalone month symbols for the receiver.

    Declaration

    Swift

    var standaloneMonthSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *standaloneMonthSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The short standalone month symbols for the receiver.

    Declaration

    Swift

    var shortStandaloneMonthSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *shortStandaloneMonthSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The very short month symbols for the receiver.

    Declaration

    Swift

    var veryShortStandaloneMonthSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *veryShortStandaloneMonthSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The quarter symbols for the receiver.

    Declaration

    Swift

    var quarterSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *quarterSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The short quarter symbols for the receiver.

    Declaration

    Swift

    var shortQuarterSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *shortQuarterSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The standalone quarter symbols for the receiver.

    Declaration

    Swift

    var standaloneQuarterSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *standaloneQuarterSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The short standalone quarter symbols for the receiver.

    Declaration

    Swift

    var shortStandaloneQuarterSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *shortStandaloneQuarterSymbols

    Discussion

    The symbols are NSString objects.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The era symbols for the receiver.

    Declaration

    Swift

    var eraSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *eraSymbols

    Discussion

    An array containing NSString objects representing the era symbols for the receiver (for example, {“B.C.E.”, “C.E.”}).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The long era symbols for the receiver

    Declaration

    Swift

    var longEraSymbols: [AnyObject]!

    Objective-C

    @property(copy) NSArray *longEraSymbols

    Discussion

    An array containing NSString objects representing the era symbols for the receiver (for example, {“Before Common Era”, “Common Era”}).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

Data Types

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

    Declaration

    Swift

    enum NSDateFormatterStyle : UInt { case NoStyle case ShortStyle case MediumStyle case LongStyle case FullStyle }

    Objective-C

    typedef enum { NSDateFormatterNoStyle = kCFDateFormatterNoStyle, NSDateFormatterShortStyle = kCFDateFormatterShortStyle, NSDateFormatterMediumStyle = kCFDateFormatterMediumStyle, NSDateFormatterLongStyle = kCFDateFormatterLongStyle, NSDateFormatterFullStyle = kCFDateFormatterFullStyle } NSDateFormatterStyle;

    Constants

    • NoStyle

      NSDateFormatterNoStyle

      Specifies no style.

      Equal to kCFDateFormatterNoStyle.

      Available in iOS 2.0 and later.

    • ShortStyle

      NSDateFormatterShortStyle

      Specifies a short style, typically numeric only, such as “11/23/37” or “3:30 PM”.

      Equal to kCFDateFormatterShortStyle.

      Available in iOS 2.0 and later.

    • MediumStyle

      NSDateFormatterMediumStyle

      Specifies a medium style, typically with abbreviated text, such as “Nov 23, 1937” or “3:30:32 PM”.

      Equal to kCFDateFormatterMediumStyle.

      Available in iOS 2.0 and later.

    • LongStyle

      NSDateFormatterLongStyle

      Specifies a long style, typically with full text, such as “November 23, 1937” or “3:30:32 PM PST”.

      Equal to kCFDateFormatterLongStyle.

      Available in iOS 2.0 and later.

    • FullStyle

      NSDateFormatterFullStyle

      Specifies a full style with complete details, such as “Tuesday, April 12, 1952 AD” or “3:30:42 PM Pacific Standard Time”.

      Equal to kCFDateFormatterFullStyle.

      Available in iOS 2.0 and later.

    Discussion

    The format for these date and time styles is not exact because they depend on the locale, user preference settings, and the operating system version. Do not use these constants if you want an exact format.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Constants that specify the behavior NSDateFormatter should exhibit.

    Declaration

    Swift

    enum NSDateFormatterBehavior : UInt { case BehaviorDefault case Behavior10_4 }

    Objective-C

    typedef enum { NSDateFormatterBehaviorDefault = 0, NSDateFormatterBehavior10_0 = 1000, NSDateFormatterBehavior10_4 = 1040, } NSDateFormatterBehavior;

    Constants

    • BehaviorDefault

      NSDateFormatterBehaviorDefault

      Specifies default formatting behavior.

      Available in iOS 2.0 and later.

    • NSDateFormatterBehavior10_0

      NSDateFormatterBehavior10_0

      Specifies formatting behavior equivalent to that in OS X v10.0.

      Available in iOS 2.0 through iOS 2.1.

    • Behavior10_4

      NSDateFormatterBehavior10_4

      Specifies formatting behavior equivalent for OS X v10.4.

      Available in iOS 2.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.