< Previous PageNext Page >

Hide TOC

Creating and Using CFDateFormatter Objects

Date formatters format the textual representation of date objects and convert textual representations of dates and times into date objects. You create date formatter objects by specifying a locale (typically the user's current locale) and a time style, you can also specify a custom format string.

Creating Date Formatters

You create a date formatter using the function CFDateFormatterCreate. You specify a locale for the format, and styles for the date and time parts of the format. You use CFDateFormatterCreateStringWithDate to convert a date to a textual representation.

CFDateFormatter defines several date and time format styles—short, medium, long, and full. It also defines a "none" style that you can use to suppress output of a component. The use of styles is illustrated in “Using Date Format Styles.” The date and time styles do not specify an exact format—they depend on the locale, the user preference settings, and the operating system version. If you want an exact format, use the CFDateFormatterSetFormat function to change the format strings, as shown in “Using Date Format Strings.”

Using Date Format Styles

The following code sample creates a date formatter that provides a full representation of a date using the kCFDateFormatterLongStyle style.

CFDateRef date = CFDateCreate(NULL, 123456);

CFLocaleRef currentLocale = CFLocaleCopyCurrent();

CFDateFormatterRef dateFormatter = CFDateFormatterCreate

        (NULL, currentLocale, kCFDateFormatterLongStyle, kCFDateFormatterLongStyle);

CFStringRef formattedString = CFDateFormatterCreateStringWithDate

        (NULL, dateFormatter, date);

CFShow(formattedString);

// Memory management

CFRelease(date);

CFRelease(currentLocale);

CFRelease(dateFormatter);

CFRelease(formattedString);

// Output (for en_US locale): January 2, 2001 2:17:36 AM PST

The following example shows the use of kCFDateFormatterNoStyle to suppress output of the time component.

CFDateRef date = CFDateCreate(NULL, 123456);

CFLocaleRef currentLocale = CFLocaleCopyCurrent();

CFDateFormatterRef dateFormatter = CFDateFormatterCreate

        (NULL, currentLocale, kCFDateFormatterShortStyle, kCFDateFormatterNoStyle);

CFStringRef formattedString = CFDateFormatterCreateStringWithDate

        (NULL, dateFormatter, date);

CFShow(formattedString);

// Memory management

CFRelease(date);

CFRelease(currentLocale);

CFRelease(dateFormatter);

CFRelease(formattedString);

// Output (for en_US locale): 1/2/01

The code sample shown in Listing 1 formats a date value using different styles as a comparison. For the purposes of illustration, the sample specifies a particular locale.

Listing 1 Comparing date format styles

CFDateRef date = CFDateCreate(NULL, 123456);

CFStringRef enUSLocaleIdentifier = CFSTR("en_US");

CFLocaleRef enUSLocale = CFLocaleCreate(NULL, enUSLocaleIdentifier);

// Create different date formatters

CFDateFormatterRef shortFormatter = CFDateFormatterCreate

        (NULL, enUSLocale, kCFDateFormatterShortStyle, kCFDateFormatterShortStyle);

CFDateFormatterRef mediumFormatter = CFDateFormatterCreate

        (NULL, enUSLocale, kCFDateFormatterMediumStyle, kCFDateFormatterMediumStyle);

CFDateFormatterRef longFormatter = CFDateFormatterCreate

        (NULL, enUSLocale, kCFDateFormatterLongStyle, kCFDateFormatterLongStyle);

CFDateFormatterRef fullFormatter = CFDateFormatterCreate

        (NULL, enUSLocale, kCFDateFormatterFullStyle, kCFDateFormatterFullStyle);

// Create formatted strings

CFStringRef shortString = CFDateFormatterCreateStringWithDate

        (NULL, shortFormatter, date);

CFStringRef mediumString = CFDateFormatterCreateStringWithDate

        (NULL, mediumFormatter, date);

CFStringRef longString = CFDateFormatterCreateStringWithDate

        (NULL, longFormatter, date);

CFStringRef fullString = CFDateFormatterCreateStringWithDate

        (NULL, fullFormatter, date);

fprintf(stdout, "Short formatted date = %s\n",

        CFStringGetCStringPtr(shortString, CFStringGetSystemEncoding()));

fprintf(stdout, "Medium date = %s\n",

        CFStringGetCStringPtr(mediumString, CFStringGetSystemEncoding()));

fprintf(stdout, "Long formatted date = %s\n",

        CFStringGetCStringPtr(longString, CFStringGetSystemEncoding()));

fprintf(stdout, "Full formatted date = %s\n\n",

        CFStringGetCStringPtr(fullString, CFStringGetSystemEncoding()));

// Memory management

CFRelease(date);

CFRelease(enUSLocale);

CFRelease(shortFormatter);

CFRelease(mediumFormatter);

CFRelease(longFormatter);

CFRelease(fullFormatter);

CFRelease(shortString);

CFRelease(mediumString);

CFRelease(longString);

CFRelease(fullString);

// Output

Short formatted date = 1/2/01 2:17 AM

Medium date = Jan 2, 2001 2:17:36 AM

Long formatted date = January 2, 2001 2:17:36 AM PST

Full formatted date = Tuesday, January 2, 2001 2:17:36 AM PST

Using Date Format Strings

Typically, you are encouraged to use the predefined styles that are localized by the system. If you want to specify an exact format, however, use the CFDateFormatterSetFormat function to set the date format string directly. The syntax of the format string conforms to date format strings used by the Unicode standard (this reference is to version tr35-6; formatters for Mac OS X v10.4 use version tr35-4), as illustrated in the following example.

CFLocaleRef currentLocale = CFLocaleCopyCurrent();

CFDateRef date = CFDateCreate(NULL, 123456);

CFDateFormatterRef customDateFormatter = CFDateFormatterCreate

        (NULL, currentLocale, kCFDateFormatterNoStyle, kCFDateFormatterNoStyle);

CFStringRef customDateFormat = CFSTR("yyyy-MM-dd*HH:mm");

CFDateFormatterSetFormat(customDateFormatter, customDateFormat);

CFStringRef customFormattedDateString = CFDateFormatterCreateStringWithDate

        (NULL, customDateFormatter, date);

CFShow(customFormattedDateString);

// Memory management

CFRelease(currentLocale);

CFRelease(date);

CFRelease(customDateFormatter);

CFRelease(customFormattedDateString);

// Output: 2001-01-02*02:17