Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

CFDateFormatter Reference

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 CFDateFormatter object. The format of the format string itself is defined by Unicode Technical Standard #35.

The CFDateFormatter opaque type is available in Mac OS X v10.3 and later.

Functions by Task

Creating a Date Formatter

• CFDateFormatterCreate

Configuring a Date Formatter

• CFDateFormatterSetFormat
• CFDateFormatterSetProperty

Parsing Strings

• CFDateFormatterCreateDateFromString
• CFDateFormatterGetAbsoluteTimeFromString

Creating Strings From Data

• CFDateFormatterCreateStringWithAbsoluteTime
• CFDateFormatterCreateStringWithDate

Getting Information About a Date Formatter

• CFDateFormatterCopyProperty
• CFDateFormatterGetDateStyle
• CFDateFormatterGetFormat
• CFDateFormatterGetLocale
• CFDateFormatterGetTimeStyle

Getting the CFDateFormatter Type ID

• CFDateFormatterGetTypeID

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

CFDateFormatterGetTypeID

Returns the type identifier for CFDateFormatter.

CFTypeID CFDateFormatterGetTypeID (
   void
);

Return Value

The type identifier for the CFDateFormatter opaque type.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared In

Data Types

CFDateFormatterRef

A reference to a CFDateFormatter object.

typedef struct __CFDateFormatter *CFDateFormatterRef;

Availability

• Available in Mac OS X v10.3 and later.

Declared In

CFDateFormatterStyle

Data type for predefined date and time format styles.

typedef CFIndex CFDateFormatterStyle;

Discussion

For possible values, see “Date Formatter Styles.”

Availability

• Available in Mac OS X v10.3 and later.

Declared In

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 Mac OS X v10.3 and later.

Declared in CFDateFormatter.h

kCFDateFormatterShortStyle

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

Available in Mac OS X v10.3 and later.

Declared in CFDateFormatter.h

kCFDateFormatterMediumStyle

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

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

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;

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 Mac OS X v10.3 and later.

Declared in CFDateFormatter.h

kCFDateFormatterTimeZone

Specifies the time zone property, a CFTimeZone object.

Available in Mac OS X v10.3 and later.

Declared in CFDateFormatter.h

kCFDateFormatterCalendarName

Specifies the calendar name, a CFString object.

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

Available in Mac OS X v10.3 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 Mac OS X v10.3 and later.

Declared in CFDateFormatter.h

kCFDateFormatterTwoDigitStartDate

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

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterDefaultDate

Specifies the default date property, a CFDate object.

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterCalendar

Specifies the calendar property, a CFCalendar object.

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterEraSymbols

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

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterMonthSymbols

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

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterShortMonthSymbols

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

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterWeekdaySymbols

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

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterShortWeekdaySymbols

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

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterAMSymbol

Specifies the AM symbol property, a CFString object.

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterPMSymbol

Specifies the PM symbol property, a CFString object.

Available in Mac OS X v10.4 and later.

Declared in CFDateFormatter.h

kCFDateFormatterLongEraSymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterVeryShortMonthSymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterStandaloneMonthSymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterShortStandaloneMonthSymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterVeryShortStandaloneMonthSymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterVeryShortWeekdaySymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterStandaloneWeekdaySymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterShortStandaloneWeekdaySymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterVeryShortStandaloneWeekdaySymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterQuarterSymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterShortQuarterSymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterStandaloneQuarterSymbols

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

Available in Mac OS X v10.5 and later.

Declared in CFDateFormatter.h

kCFDateFormatterShortStandaloneQuarterSymbols

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

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

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 Mac OS X v10.3 and later.

Declared in CFLocale.h

Declared In

Next Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice