Inherits from: NSFormatter : NSObject
Conforms to: NSObject
(NSObject)
NSCoding (NSObject)
NSCopying (NSObject)
Declared in: Foundation/NSDateFormatter.h
Instances of NSDateFormatter format the textual representation of cells that contain NSDates (including NSCalendarDates), and convert textual representations of dates and times into NSDates. You can express the representation of dates and times very flexibly: "Thu 22 Dec 1994" is just as acceptable as "12/22/94". With natural-language processing for dates enabled, users can also express dates colloquially, such as "today," "day after tomorrow," and "a month from today."
To use an NSDateFormatter, allocate an instance of it and
initialize it with initWithDateFormat:allowNaturalLanguage:.
In the first argument use strftime
-style
conversion specifiers to compose the format string for textual representation.
(For more information on these specifiers, see the see the description
of NSCalendarDate's dateWithCalendarFormat:timeZone: method.) Then
use NSCell's setFormatter: method to associate
the NSDateFormatter object with a cell. The value of a cell (NSCell)
is represented by an object, typically an NSDate object in this
case. When this value needs to be displayed or edited, the cell
passes its object to the NSDateFormatter instance, which returns
the formatted string. When the user enters a string, or when one
is programmatically written in a cell (using setStringValue:),
the cell obtains the equivalent NSDate object from the NSDateFormatter.
NSControl provides delegation methods that permit you to validate cell contents and to handle errors in formatting. See the specification of the NSFormatter class for details.
When a cell with a NSDateFormatter is copied, the new cell
retains the NSDateFormatter object instead of copying it. You remove
an NSDateFormatter from a cell by specifying nil
as
the argument of setFormatter:.
Instances of NSDateFormatter are immutable.
You must specify a format whenever you create a NSDateFormatter. This format is a string that contains specifiers that are very similar to those used in the standard C library function strftime(). When NSDateFormatter converts a date to a string, it uses this format.
Some NSCalendar methods, including setCalendarFormat: and many initialization methods, also expect format strings made from these specifiers.
The date conversion specifiers cover a range of date conventions:
Specifier | Description |
%% |
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 |
%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 |
%X |
time using the time representation for the locale |
%y |
year without century (00-99) |
%Y |
year with century (such as 1990) |
%Z |
time zone abbreviation (such as PDT) |
%z |
time zone offset in hours and minutes from GMT (HHMM) |
- Initializing an NSDateFormatter
- - initWithDateFormat:allowNaturalLanguage:
- Determining attributes
- - allowsNaturalLanguage
- - dateFormat
- (BOOL)allowsNaturalLanguage
Returns YES
if
the NSDateFormatter attempts to process dates entered as a vernacular
string ("today," "day before yesterday," and so on). Returns NO
if
the NSDateFormatter does not do any natural-language processing
of these date expressions.
- (NSString *)dateFormat
Returns the date format string used by an NSDateFormatter object. See The Calendar Format for a list of the conversion specifiers permitted in date format strings.
- (id)initWithDateFormat:(NSString
*)format
allowNaturalLanguage:(BOOL)flag
Initializes and returns an NSDateFormatter
instance that uses the date format in its conversions. See the description
of NSCalendarDate's dateWithCalendarFormat:timeZone: for
a list of conversion specifiers permitted in date format strings.
Set flag to YES
if
you want the NSDateFormatter to process dates entered as expressions
in the vernacular (for example, "tomorrow"); NSDateFormatter
attempts natural-language processing only after it fails to interpret
an entered string according to format. The following example creates
a date formatter with the format string (as 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] makeObjectsPerform:@selector(setFormatter:) withObject:dateFormat]