CFDateFormatter Reference

Derived from	CFType Reference
Framework	CoreFoundation/CoreFoundation.h
Companion guide	Data Formatting Guide for Core Foundation
Declared in	CFDateFormatter.h CFLocale.h

Overview

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.

The format of the format string itself is defined by Unicode Technical Standard #35; the version of the standard used varies with release of the operating system, and is described in “Introduction to Data Formatting Programming Guide For Cocoa”.

Functions by Task

Creating a Date Formatter

Configuring a Date Formatter

Parsing Strings

Creating Strings From Data

Getting Information About a Date Formatter

Getting the CFDateFormatter Type ID

Functions

CFDateFormatterCopyProperty

Returns a copy of a date formatter’s value for a given key.

CFTypeRef CFDateFormatterCopyProperty (
   CFDateFormatterRef formatter,
   CFStringRef key
);

Parameters

formatter: The date formatter to examine.
key: The property key for the value to obtain. See “Date Formatter Property Keys” for a description of possible values for this parameter.

Return Value

A CFType object that is a copy of the property value for key, or NULL if there is no value specified for key. Ownership follows the Create Rule.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterCreate

Creates a new CFDateFormatter object, localized to the given locale, which will format dates to the given date and time styles.

CFDateFormatterRef CFDateFormatterCreate (
   CFAllocatorRef allocator,
   CFLocaleRef locale,
   CFDateFormatterStyle dateStyle,
   CFDateFormatterStyle timeStyle
);

Parameters

alloc: The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
locale: The locale to use for localization. If NULL uses the default system local. Use CFLocaleCopyCurrent to specify the locale of the current user.
dateStyle: The date style to use when formatting dates. See “Date Formatter Styles” for possible values.
timeStyle: The time style to use when formatting times. See “Date Formatter Styles” for possible values.

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

CFLocaleRef locale = CFLocaleCreate(kCFAllocatorDefault, CFSTR("en_GB"));

CFDateFormatterRef formatter = CFDateFormatterCreate(

        kCFAllocatorDefault, locale, kCFDateFormatterMediumStyle, kCFDateFormatterNoStyle);

CFDateRef date = CFDateCreate(kCFAllocatorDefault, 123456);

CFStringRef dateAsString = CFDateFormatterCreateStringWithDate (

        kCFAllocatorDefault, formatter, date);

CFShow(dateAsString);

// outputs "2 Jan 2001"

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterCreateDateFormatFromTemplate

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

CFStringRef CFDateFormatterCreateDateFormatFromTemplate (
   CFAllocatorRef allocator,
   CFStringRef template,
   CFOptionFlags options,
   CFLocaleRef locale
);

Parameters

allocator

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

template

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

For full details, see Unicode Technical Standard #35.

options

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. Ownership follows 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:

CFStringRef dateComponents = CFSTR("yMMMMd");

CFLocaleRef usLocale = CFLocaleCreate(NULL, CFSTR("en_US"));

CFStringRef usDateFormatString =

    CFDateFormatterCreateDateFormatFromTemplate(NULL, dateComponents, 0, usLocale);

// Date format for English (United States): MMMM d, y

CFLocaleRef gbLocale = CFLocaleCreate(NULL, CFSTR("en_GB"));

CFStringRef gbDateFormatString =

    CFDateFormatterCreateDateFormatFromTemplate(NULL, dateComponents, 0, gbLocale);

// Date format for English (United Kingdom): d MMMM y

Availability

Available in iOS 4.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterCreateDateFromString

Returns a date object representing a given string.

CFDateRef CFDateFormatterCreateDateFromString (
   CFAllocatorRef allocator,
   CFDateFormatterRef formatter,
   CFStringRef string,
   CFRange *rangep
);

Parameters

alloc: 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 Create Rule.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterCreateStringWithAbsoluteTime

Returns a string representation of the given absolute time using the specified date formatter.

CFStringRef CFDateFormatterCreateStringWithAbsoluteTime (
   CFAllocatorRef allocator,
   CFDateFormatterRef formatter,
   CFAbsoluteTime at
);

Parameters

alloc: 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 that specifies the format of the returned string.
at: The absolute time for which to generate a string representation.

Return Value

A new string that represents at in the specified format. Returns NULL if there was a problem creating the object. Ownership follows the Create Rule.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterCreateStringWithDate

Returns a string representation of the given date using the specified date formatter.

CFStringRef CFDateFormatterCreateStringWithDate (
   CFAllocatorRef allocator,
   CFDateFormatterRef formatter,
   CFDateRef date
);

Parameters

alloc: 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 that specifies the format of the returned string.
date: The date object for which to create a string representation.

Return Value

A new string that represents date in the specified format. Returns NULL if there was a problem creating the object. Ownership follows the Create Rule.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterGetAbsoluteTimeFromString

Returns an absolute time object representing a given string.

Boolean CFDateFormatterGetAbsoluteTimeFromString (
   CFDateFormatterRef formatter,
   CFStringRef string,
   CFRange *rangep,
   CFAbsoluteTime *atp
);

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 Get Rule.

Return Value

true if the string was parsed successfully, otherwise false.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterGetDateStyle

Returns the date style used to create the given date formatter object.

CFDateFormatterStyle CFDateFormatterGetDateStyle (
   CFDateFormatterRef formatter
);

Parameters

formatter: The date formatter to examine.

Return Value

The date style used to create formatter.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterGetFormat

Returns a format string for the given date formatter object.

CFStringRef CFDateFormatterGetFormat (
   CFDateFormatterRef formatter
);

Parameters

formatter: The date formatter to examine.

Return Value

The format string for formatter as was specified by calling the CFDateFormatterSetFormat function, or derived from the date formatter’s date or time styles. Ownership follows the Get Rule.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterGetLocale

Returns the locale object used to create the given date formatter object.

CFLocaleRef CFDateFormatterGetLocale (
   CFDateFormatterRef formatter
);

Parameters

formatter: The date formatter object to examine.

Return Value

The locale object used to create formatter. Ownership follows the Get Rule.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterGetTimeStyle

Returns the time style used to create the given date formatter object.

CFDateFormatterStyle CFDateFormatterGetTimeStyle (
   CFDateFormatterRef formatter
);

Parameters

formatter: The date formatter to examine.

Return Value

The time style used to create formatter.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterGetTypeID

Returns the type identifier for CFDateFormatter.

CFTypeID CFDateFormatterGetTypeID (
   void
);

Return Value

The type identifier for the CFDateFormatter opaque type.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterSetFormat

Sets the format string of the given date formatter to the specified value.

void CFDateFormatterSetFormat (
   CFDateFormatterRef formatter,
   CFStringRef formatString
);

Parameters

formatter: The date formatter to modify.
formatString: The format string for formatter. The syntax of this string is defined by Unicode Technical Standard #35..

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.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterSetProperty

Sets a date formatter property using a key-value pair.

void CFDateFormatterSetProperty (
   CFDateFormatterRef formatter,
   CFStringRef key,
   CFTypeRef value
);

Parameters

formatter: The date formatter to modify.
key: The name of the property to set. See “Date Formatter Property Keys” for a description of possible values for this parameter.
value: The value for key. This should be a CFType object corresponding to the specified key.

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

Data Types

CFDateFormatterRef

A reference to a CFDateFormatter object.

typedef struct __CFDateFormatter *CFDateFormatterRef;

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

CFDateFormatterStyle

Data type for predefined date and time format styles.

typedef CFIndex CFDateFormatterStyle;

Discussion

For possible values, see “Date Formatter Styles.”

Availability

Available in iOS 2.0 and later.

Declared In

CFDateFormatter.h

Constants

Date Formatter Styles

Predefined date and time format styles.

enum {
   kCFDateFormatterNoStyle = 0,
   kCFDateFormatterShortStyle = 1,
   kCFDateFormatterMediumStyle = 2,
   kCFDateFormatterLongStyle = 3,
   kCFDateFormatterFullStyle = 4
};

Constants

kCFDateFormatterNoStyle

Specifies no output.

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterShortStyle

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterMediumStyle

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterLongStyle

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterFullStyle

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

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)
names of quarters; for example, "Q2" for a short quarter name

Declared In

CFDateFormatter.h

Date Formatter Property Keys

Keys used in key-value pairs to discover and specify the value of date formatter properties—used in conjunction with CFDateFormatterCopyProperty and CFDateFormatterSetProperty.

const CFStringRef kCFDateFormatterIsLenient;
const CFStringRef kCFDateFormatterTimeZone;
const CFStringRef kCFDateFormatterCalendarName;
const CFStringRef kCFDateFormatterDefaultFormat;
   
const CFStringRef kCFDateFormatterTwoDigitStartDate;
const CFStringRef kCFDateFormatterDefaultDate;
const CFStringRef kCFDateFormatterCalendar;
const CFStringRef kCFDateFormatterEraSymbols;
const CFStringRef kCFDateFormatterMonthSymbols;
const CFStringRef kCFDateFormatterShortMonthSymbols;
const CFStringRef kCFDateFormatterWeekdaySymbols;
const CFStringRef kCFDateFormatterShortWeekdaySymbols;
const CFStringRef kCFDateFormatterAMSymbol;
const CFStringRef kCFDateFormatterPMSymbol;
   
const CFStringRef kCFDateFormatterLongEraSymbols;
const CFStringRef kCFDateFormatterVeryShortMonthSymbols;
const CFStringRef kCFDateFormatterStandaloneMonthSymbols;
const CFStringRef kCFDateFormatterShortStandaloneMonthSymbols;
const CFStringRef kCFDateFormatterVeryShortStandaloneMonthSymbols;
const CFStringRef kCFDateFormatterVeryShortWeekdaySymbols;
const CFStringRef kCFDateFormatterStandaloneWeekdaySymbols;
const CFStringRef kCFDateFormatterShortStandaloneWeekdaySymbols;
const CFStringRef kCFDateFormatterVeryShortStandaloneWeekdaySymbols;
const CFStringRef kCFDateFormatterQuarterSymbols;
const CFStringRef kCFDateFormatterShortQuarterSymbols;
const CFStringRef kCFDateFormatterStandaloneQuarterSymbols;
const CFStringRef kCFDateFormatterShortStandaloneQuarterSymbols;
const CFStringRef kCFDateFormatterGregorianStartDate;
const CFStringRef kCFDateFormatterDoesRelativeDateFormattingKey;

Constants

kCFDateFormatterIsLenient

Specifies the lenient property, a CFBoolean object where a true value indicates that the parsing of strings into date or absolute time values will be fuzzy.

The formatter will use heuristics to guess at the date which is intended by the string. As with any guessing, it may get the result date wrong (that is, a date other than that which was intended).

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterTimeZone

Specifies the time zone property, a CFTimeZone object.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterCalendarName

Specifies the calendar name, a CFString object.

With OS X version 10.3, kCFGregorianCalendar is the only possible value. With OS X version 10.4, kCFGregorianCalendar and other calendar names are specified by CFLocale.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterDefaultFormat

The original format string for the formatter (given the date & time style and locale specified at creation).

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterTwoDigitStartDate

Specifies the property representing the date from which two-digit years start, a CFDate object.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterDefaultDate

Specifies the default date property, a CFDate object.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterCalendar

Specifies the calendar property, a CFCalendar object.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterEraSymbols

Specifies the era symbols property, a CFArray of CFString objects.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterMonthSymbols

Specifies the month symbols property, a CFArray of CFString objects.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterShortMonthSymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterWeekdaySymbols

Specifies the weekday symbols property, a CFArray of CFString objects.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterShortWeekdaySymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterAMSymbol

Specifies the AM symbol property, a CFString object.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterPMSymbol

Specifies the PM symbol property, a CFString object.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterLongEraSymbols

Specifies the long era symbols property, a CFArray of CFString objects.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterVeryShortMonthSymbols

Specifies the very short month symbols property, a CFArray of CFString objects.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterStandaloneMonthSymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterShortStandaloneMonthSymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterVeryShortStandaloneMonthSymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterVeryShortWeekdaySymbols

Specifies the very short weekday symbols property, a CFArray of CFString objects.

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterStandaloneWeekdaySymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterShortStandaloneWeekdaySymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterVeryShortStandaloneWeekdaySymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterQuarterSymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterShortQuarterSymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterStandaloneQuarterSymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

kCFDateFormatterShortStandaloneQuarterSymbols

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

Available in iOS 2.0 and later.

Declared in CFDateFormatter.h.

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 iOS 2.0 and later.

Declared in CFDateFormatter.h.

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 iOS 4.0 and later.

Declared in CFDateFormatter.h.

Discussion

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

Declared In

CFDateFormatter.h

Calendar Names

Calendar names used by CFDateFormatter.

const CFStringRef kCFGregorianCalendar;

Constants

kCFGregorianCalendar

The name of the calendar currently supported by the kCFDateFormatterCalendarName property.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

Declared In

CFDateFormatter.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.