CFDateFormatter Reference

CFDateFormatter objects format the textual representations of CFDate and CFAbsoluteTime objects, and convert textual representations of dates and times into CFDate and CFAbsoluteTime objects. You can express the representation of dates and times very flexibly, for example “Thu 22 Dec 1994” is just as acceptable as “12/22/94.” You specify how strings are formatted and parsed by setting a format string and other properties of a CFDateFomatter object.

Return Value

A new date formatter, localized to the given locale, which will format dates to the given date and time styles. Returns NULL if there was a problem creating the object. Ownership follows the The Create Rule.

Discussion

You can use kCFDateFormatterNoStyle to suppress output for the date or time. The following code fragment illustrates the creation and use of a date formatter that only outputs the date information (memory management is omitted for clarity).

Parameters

Discussion

The format string may override other properties previously set using other functions. If this function is not called, the default value of the format string is derived from the date formatter’s date and time styles.

Parameters

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

formatter

The date formatter object to use to parse string.

string

The string that contains the date.

rangep

A reference to the range within the string specifying the substring to be parsed. If NULL, the whole string is parsed. Upon return, contains the range that defines the extent of the parse (may be less than the given range).

Return Value

A new date that represents string, or NULL if there was a problem creating the object. Ownership follows the The Create Rule.

Parameters

formatter

The date formatter object to use to parse string.

string

The string that contains the time to be parsed.

rangep

Reference to the range within the string specifying the substring to be parsed. If NULL, the whole string is parsed. On return, the range that defines the extent of the parse (may be less than the given range).

atp

An absolute time value, returned by reference, that represents string. Ownership follows the The Get Rule.

Return Value

A localized date format string representing the date format components given in template, arranged appropriately for the locale specified by locale. Ownership follows the The Create Rule.

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 CFLocaleCopyCurrent).

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

Constants

You use this constant to suppress output for the date or time (see CFDateFormatterCreate for more details).

Available in OS X v10.3 and later.

ShortStyle

kCFDateFormatterShortStyle

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

Available in OS X v10.3 and later.

MediumStyle

kCFDateFormatterMediumStyle

Specifies a medium style, typically with abbreviated text, such as “Nov 23, 1937”.

Available in OS X v10.3 and later.

LongStyle

kCFDateFormatterLongStyle

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

Available in OS X v10.3 and later.

FullStyle

kCFDateFormatterFullStyle

Specifies a full style with complete details, such as “Tuesday, April 12, 1952 AD” or “3:30:42pm PST”.

Available in OS X v10.3 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, for example if you are parsing an external data file which contains date information in a fixed format. There are several different “lengths” of the formats:

"long" era names, for example "Anno Domini" instead of "AD"

"very short" names for months and weekdays; for example, "F" instead of "Friday"

"standalone" names for months and weekdays (for some locales or languages, a month name displayed in isolation needs to be written differently than a month name within a displayed date)

Specifies the short standalone quarter symbols property, a CFArray of CFString objects.

Available in OS X v10.5 and later.

kCFDateFormatterGregorianStartDate

kCFDateFormatterGregorianStartDate

Specifies the Gregorian start date property, a CFDate object.

This is used to specify the start date for the Gregorian calendar switch from the Julian calendar. Different locales switched at different times. Normally you should just accept the locale's default date for the switch.

Available in OS X v10.5 and later.

kCFDateFormatterDoesRelativeDateFormattingKey

kCFDateFormatterDoesRelativeDateFormattingKey

Specifies the relative date formatting property, a CFBoolean object.

This is used to specify whether the receiver uses phrases such as “today” and “tomorrow” for the date component.

Available in OS X v10.6 and later.

Discussion

The values for these keys are all CFType objects. The specific types for each key are specified above.