Up

# NSDateFormatter class reference

### Authors

Richard Frith-Macdonald (`richard@brainstorm.co.uk`)

Copyright: (C) 1998 Free Software Foundation, Inc.

# Software documentation for the NSDateFormatter class

## NSDateFormatter : NSFormatter

> Declared in:
>   Foundation/NSDateFormatter.h

> Conforms to:
>   NSCoding
>   NSCopying

Availability: MacOS-X 10.0.0

Class for generating text representations of NSDate s and NSCalendarDate s, and for converting strings into instances of these objects. Note that NSDate and NSCalendarDate do contain some string conversion methods, but using this class provides more control over conversion.

See the NSFormatter documentation for description of the basic methods for formatting and parsing that are available.

The basic format of a format string uses "%" codes to represent components of the date. Thus, for example, `@"%b %d, %Y"` specifies strings similar to "June 18, 1991". The full list of codes is as follows:

%%
  a '%' character
%a
  abbreviated weekday name
%A
  full weekday name
%b
  abbreviated month name
%B
  full month name
%c
  shorthand for "%X %x", the locale format for date and time
%d
  day of the month as a decimal number (01-31)
%e
  same as %d but does not print the leading 0 for days 1 through 9 (unlike strftime() , does not print a leading space)
%F
  milliseconds as a decimal number (000-999)
%H
  hour based on a 24-hour clock as a decimal number (00-23)
%I
  hour based on a 12-hour clock as a decimal number (01-12)
%j
  day of the year as a decimal number (001-366)
%m
  month as a decimal number (01-12)
%M
  minute as a decimal number (00-59)
%p
  AM/PM designation for the locale
%S
  second as a decimal number (00-59)
%w
  weekday as a decimal number (0-6), where Sunday is 0
%x
  date using the date representation for the locale, including the time zone (produces different results from strftime())
%X
  time using the time representation for the locale (produces different results from strftime())
%y
  year without century (00-99)
%Y
  year with century (such as 1990)
%Z
  time zone name (such as Pacific Daylight Time; produces different results from strftime())
%z
  time zone offset in hours and minutes from GMT (HHMM)

Instance Variables
Method summary

- +dateFormatFromTemplate:options:locale:
- +defaultFormatterBehavior
- +localizedStringFromDate:dateStyle:timeStyle:
- +setDefaultFormatterBehavior:
- -AMSymbol
- -PMSymbol
- -allowsNaturalLanguage
- -calendar
- -dateFormat
- -dateFromString:
- -dateStyle
- -defaultDate
- -doesRelativeDateFormatting
- -eraSymbols
- -formatterBehavior
- -generatesCalendarDates
- -getObjectValue:forString:range:error:
- -gregorianStartDate
- -initWithDateFormat:allowNaturalLanguage:
- -isLenient
- -locale
- -longEraSymbols
- -monthSymbols
- -quarterSymbols
- -setAMSymbol:
- -setCalendar:
- -setDateFormat:
- -setDateStyle:
- -setDefaultDate:
- -setDoesRelativeDateFormatting:
- -setEraSymbols:
- -setFormatterBehavior:
- -setGeneratesCalendarDates:
- -setGregorianStartDate:
- -setLenient:
- -setLocale:
- -setLongEraSymbols:
- -setMonthSymbols:
- -setPMSymbol:
- -setQuarterSymbols:
- -setShortMonthSymbols:
- -setShortQuarterSymbols:
- -setShortStandaloneMonthSymbols:
- -setShortStandaloneQuarterSymbols:
- -setShortStandaloneWeekdaySymbols:
- -setShortWeekdaySymbols:
- -setStandaloneMonthSymbols:
- -setStandaloneQuarterSymbols:
- -setStandaloneWeekdaySymbols:
- -setTimeStyle:
- -setTimeZone:
- -setTwoDigitStartDate:
- -setVeryShortMonthSymbols:
- -setVeryShortStandaloneMonthSymbols:
- -setVeryShortStandaloneWeekdaySymbols:
- -setVeryShortWeekdaySymbols:
- -setWeekdaySymbols:
- -shortMonthSymbols
- -shortQuarterSymbols
- -shortStandaloneMonthSymbols
- -shortStandaloneQuarterSymbols
- -shortStandaloneWeekdaySymbols
- -shortWeekdaySymbols
- -standaloneMonthSymbols
- -standaloneQuarterSymbols
- -standaloneWeekdaySymbols
- -stringFromDate:
- -timeStyle
- -timeZone
- -twoDigitStartDate
- -veryShortMonthSymbols
- -veryShortStandaloneMonthSymbols
- -veryShortStandaloneWeekdaySymbols
- -veryShortWeekdaySymbols
- -weekdaySymbols

### dateFormatFromTemplate: options: locale:

+ (NSString*) dateFormatFromTemplate: (NSString*)aTemplate options: (NSUInteger)opts locale: (NSLocale*)locale;
Availability: MacOS-X 10.6.0
Description forthcoming.

### defaultFormatterBehavior

+ (NSDateFormatterBehavior) defaultFormatterBehavior;
Availability: MacOS-X 10.4.0
Description forthcoming.

### localizedStringFromDate: dateStyle: timeStyle:

+ (NSString*) localizedStringFromDate: (NSDate*)date dateStyle: (NSDateFormatterStyle)dateStyle timeStyle: (NSDateFormatterStyle)timeStyle;
Availability: MacOS-X 10.6.0
Description forthcoming.

### setDefaultFormatterBehavior:

+ (void) setDefaultFormatterBehavior: (NSDateFormatterBehavior)behavior;
Availability: MacOS-X 10.4.0
Description forthcoming.

### AMSymbol

- (NSString*) AMSymbol;
Availability: MacOS-X 10.4.0
Description forthcoming.

### PMSymbol

- (NSString*) PMSymbol;
Availability: MacOS-X 10.4.0
Description forthcoming.

### allowsNaturalLanguage

- (BOOL) allowsNaturalLanguage;
Availability: MacOS-X 10.0.0
Returns whether initialized to support natural language formatting. If `YES`, string-to-object conversion will attempt to process strings as natural language dates, such as "yesterday", or "first Tuesday of next month" if straight format-based conversion fails.

### calendar

- (NSCalendar*) calendar;
Availability: MacOS-X 10.4.0
Description forthcoming.

### dateFormat

- (NSString*) dateFormat;
Availability: MacOS-X 10.0.0
Returns format string initialized with, specifying how dates are formatted, for object-to-string conversion, and how they are parsed, for string-to-object conversion. For example, `@"%b %d, %Y"` specifies strings similar to "June 18, 1991".

### dateFromString:

- (NSDate*) dateFromString: (NSString*)string;
Availability: MacOS-X 10.4.0
Description forthcoming.

### dateStyle

- (NSDateFormatterStyle) dateStyle;
Availability: MacOS-X 10.4.0
Description forthcoming.

### defaultDate

- (NSDate*) defaultDate;
Availability: MacOS-X 10.4.0
Description forthcoming.

### doesRelativeDateFormatting

- (BOOL) doesRelativeDateFormatting;
Availability: MacOS-X 10.6.0
Description forthcoming.

### eraSymbols

- (NSArray*) eraSymbols;
Availability: MacOS-X 10.4.0
Description forthcoming.

### formatterBehavior

- (NSDateFormatterBehavior) formatterBehavior;
Availability: MacOS-X 10.4.0
Description forthcoming.

### generatesCalendarDates

- (BOOL) generatesCalendarDates;
Availability: MacOS-X 10.4.0
Description forthcoming.

### getObjectValue: forString: range: error:

- (BOOL) getObjectValue: (out id*)obj forString: (NSString*)string range: (inout NSRange*)range error: (out NSError**)error;
Availability: MacOS-X 10.4.0
Description forthcoming.

### gregorianStartDate

- (NSDate*) gregorianStartDate;
Availability: MacOS-X 10.5.0
Description forthcoming.

### initWithDateFormat: allowNaturalLanguage:

- (id) initWithDateFormat: (NSString*)format allowNaturalLanguage: (BOOL)flag;
Availability: MacOS-X 10.0.0
Initialize with given specifier string format. See class description for how to specify a format string. If flag is `YES`, string-to-object conversion will attempt to process strings as natural language dates, such as "yesterday", or "first Tuesday of next month" if straight format-based conversion fails.

### isLenient

- (BOOL) isLenient;
Availability: MacOS-X 10.4.0
Description forthcoming.

### locale

- (NSLocale*) locale;
Availability: MacOS-X 10.4.0
Description forthcoming.

### longEraSymbols

- (NSArray*) longEraSymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### monthSymbols

- (NSArray*) monthSymbols;
Availability: MacOS-X 10.4.0
Description forthcoming.

### quarterSymbols

- (NSArray*) quarterSymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setAMSymbol:

- (void) setAMSymbol: (NSString*)string;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setCalendar:

- (void) setCalendar: (NSCalendar*)calendar;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setDateFormat:

- (void) setDateFormat: (NSString*)string;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setDateStyle:

- (void) setDateStyle: (NSDateFormatterStyle)style;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setDefaultDate:

- (void) setDefaultDate: (NSDate*)date;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setDoesRelativeDateFormatting:

- (void) setDoesRelativeDateFormatting: (BOOL)flag;
Availability: MacOS-X 10.6.0
Description forthcoming.

### setEraSymbols:

- (void) setEraSymbols: (NSArray*)array;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setFormatterBehavior:

- (void) setFormatterBehavior: (NSDateFormatterBehavior)behavior;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setGeneratesCalendarDates:

- (void) setGeneratesCalendarDates: (BOOL)flag;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setGregorianStartDate:

- (void) setGregorianStartDate: (NSDate*)date;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setLenient:

- (void) setLenient: (BOOL)flag;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setLocale:

- (void) setLocale: (NSLocale*)locale;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setLongEraSymbols:

- (void) setLongEraSymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setMonthSymbols:

- (void) setMonthSymbols: (NSArray*)array;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setPMSymbol:

- (void) setPMSymbol: (NSString*)string;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setQuarterSymbols:

- (void) setQuarterSymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setShortMonthSymbols:

- (void) setShortMonthSymbols: (NSArray*)array;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setShortQuarterSymbols:

- (void) setShortQuarterSymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setShortStandaloneMonthSymbols:

- (void) setShortStandaloneMonthSymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setShortStandaloneQuarterSymbols:

- (void) setShortStandaloneQuarterSymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setShortStandaloneWeekdaySymbols:

- (void) setShortStandaloneWeekdaySymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setShortWeekdaySymbols:

- (void) setShortWeekdaySymbols: (NSArray*)array;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setStandaloneMonthSymbols:

- (void) setStandaloneMonthSymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setStandaloneQuarterSymbols:

- (void) setStandaloneQuarterSymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setStandaloneWeekdaySymbols:

- (void) setStandaloneWeekdaySymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setTimeStyle:

- (void) setTimeStyle: (NSDateFormatterStyle)style;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setTimeZone:

- (void) setTimeZone: (NSTimeZone*)tz;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setTwoDigitStartDate:

- (void) setTwoDigitStartDate: (NSDate*)date;
Availability: MacOS-X 10.4.0
Description forthcoming.

### setVeryShortMonthSymbols:

- (void) setVeryShortMonthSymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setVeryShortStandaloneMonthSymbols:

- (void) setVeryShortStandaloneMonthSymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setVeryShortStandaloneWeekdaySymbols:

- (void) setVeryShortStandaloneWeekdaySymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setVeryShortWeekdaySymbols:

- (void) setVeryShortWeekdaySymbols: (NSArray*)array;
Availability: MacOS-X 10.5.0
Description forthcoming.

### setWeekdaySymbols:

- (void) setWeekdaySymbols: (NSArray*)array;
Availability: MacOS-X 10.4.0
Description forthcoming.

### shortMonthSymbols

- (NSArray*) shortMonthSymbols;
Availability: MacOS-X 10.4.0
Description forthcoming.

### shortQuarterSymbols

- (NSArray*) shortQuarterSymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### shortStandaloneMonthSymbols

- (NSArray*) shortStandaloneMonthSymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### shortStandaloneQuarterSymbols

- (NSArray*) shortStandaloneQuarterSymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### shortStandaloneWeekdaySymbols

- (NSArray*) shortStandaloneWeekdaySymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### shortWeekdaySymbols

- (NSArray*) shortWeekdaySymbols;
Availability: MacOS-X 10.4.0
Description forthcoming.

### standaloneMonthSymbols

- (NSArray*) standaloneMonthSymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### standaloneQuarterSymbols

- (NSArray*) standaloneQuarterSymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### standaloneWeekdaySymbols

- (NSArray*) standaloneWeekdaySymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### stringFromDate:

- (NSString*) stringFromDate: (NSDate*)date;
Availability: MacOS-X 10.4.0
Description forthcoming.

### timeStyle

- (NSDateFormatterStyle) timeStyle;
Availability: MacOS-X 10.4.0
Description forthcoming.

### timeZone

- (NSTimeZone*) timeZone;
Availability: MacOS-X 10.4.0
Description forthcoming.

### twoDigitStartDate

- (NSDate*) twoDigitStartDate;
Availability: MacOS-X 10.4.0
Description forthcoming.

### veryShortMonthSymbols

- (NSArray*) veryShortMonthSymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### veryShortStandaloneMonthSymbols

- (NSArray*) veryShortStandaloneMonthSymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### veryShortStandaloneWeekdaySymbols

- (NSArray*) veryShortStandaloneWeekdaySymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### veryShortWeekdaySymbols

- (NSArray*) veryShortWeekdaySymbols;
Availability: MacOS-X 10.5.0
Description forthcoming.

### weekdaySymbols

- (NSArray*) weekdaySymbols;
Availability: MacOS-X 10.4.0
Description forthcoming.

## Instance Variables for NSDateFormatter Class

### _allowsNaturalLanguage

@protected BOOL _allowsNaturalLanguage;
Availability: MacOS-X 10.0.0
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _dateFormat

@protected NSString* _dateFormat;
Availability: MacOS-X 10.0.0
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

Up