Mac 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. More...

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.0 and later.
  • Initializes and returns an NSDateFormatter instance that uses the OS X v10.0 formatting behavior and the given date format string in its conversions.

    Declaration

    Objective-C

    - (id)initWithDateFormat:(NSString *)format allowNaturalLanguage:(BOOL)flag

    Parameters

    format

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

    flag

    A flag that specifies whether the receiver should process dates entered as expressions in the vernacular (for example, "tomorrow")—YEStrue means that it should.

    Return Value

    An initialized NSDateFormatter instance that uses format in its conversions and that uses the OS X v10.0 formatting behavior.

    Discussion

    NSDateFormatter attempts natural-language processing only after it fails to interpret an entered string according to format. Natural-language processing supports only a limited set of colloquial phrases, primarily in English. It may give unexpected results, and its use is strongly discouraged.

    The following example creates a date formatter with the format string (for example) “Mar 15 1994” and then associates the formatter with the cells of a form (contactsForm):

    • NSDateFormatter *dateFormat = [[NSDateFormatter alloc]
    • initWithDateFormat:@"%b %d %Y" allowNaturalLanguage:NO];
    • [[contactsForm cells] makeObjectsPerformSelector:@selector(setFormatter:)
    • withObject:dateFormat];

    Special Considerations

    You cannot use this method to initialize a formatter with the OS X v10.4 formatting behavior, you must use init.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.9.

  • 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.6 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • dateStyle dateStyle Property

    The date style of the receiver.

    Declaration

    Swift

    var dateStyle: NSDateFormatterStyle

    Objective-C

    @property NSDateFormatterStyle dateStyle

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • timeStyle timeStyle Property

    The time style of the receiver.

    Declaration

    Swift

    var timeStyle: NSDateFormatterStyle

    Objective-C

    @property NSDateFormatterStyle timeStyle

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • calendar calendar Property

    The calendar for the receiver.

    Declaration

    Swift

    @NSCopying var calendar: NSCalendar!

    Objective-C

    @property(copy) NSCalendar *calendar

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • locale locale Property

    The locale for the receiver.

    Declaration

    Swift

    @NSCopying var locale: NSLocale!

    Objective-C

    @property(copy) NSLocale *locale

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    - (BOOL)allowsNaturalLanguage

    Return Value

    YEStrue if the receiver attempts to process dates entered as a vernacular string (“today,” “next week,” “dinner time,” and so on), otherwise NOfalse.

    Discussion

    Natural-language processing supports only a limited set of colloquial phrases, primarily in English. It may give unexpected results, and its use is strongly discouraged.

    Special Considerations

    This method is for use with formatters using NSDateFormatterBehavior10_0 behavior.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.9.

  • 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

    import Foundation

    Availability

    Available in OS X v10.10 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

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • AMSymbol AMSymbol Property

    The AM symbol for the receiver.

    Declaration

    Swift

    var AMSymbol: String!

    Objective-C

    @property(copy) NSString *AMSymbol

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.5 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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.5 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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 OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Constants that specify the behavior NSDateFormatter should exhibit.

    Declaration

    Swift

    enum NSDateFormatterBehavior : UInt { case BehaviorDefault case Behavior10_0 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 OS X v10.4 and later.

    • Behavior10_0

      NSDateFormatterBehavior10_0

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

      Available in OS X v10.4 and later.

    • Behavior10_4

      NSDateFormatterBehavior10_4

      Specifies formatting behavior equivalent for OS X v10.4.

      Available in OS X v10.4 and later.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.