CFLocale Reference

Overview

Unicode operations such as collation and text boundary determination can be affected by the conventions of a particular language or region. CFLocale objects specify language-specific or region-specific information for locale-sensitive operations.

The CFLocale opaque type provides support for obtaining available locales, obtaining localized locale names, and converting among locale data formats. Locale identifiers in OS X follow the IETF’s BCP 47. CFLocale never uses Script Manager codes (except for the legacy support provided by CFLocaleCreateCanonicalLocaleIdentifierFromScriptManagerCodes)—the Script Manager and all its concepts are deprecated.

For more information on locale identifiers and the use of CFLocale, see Locales Programming Guide. It is also useful to read the ICU’s User Guide for the Locale Class.

CFLocale is “toll-free bridged” with its Cocoa Foundation counterpart, NSLocale. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSLocale * parameter, you can pass in a CFLocaleRef, and in a function where you see a CFLocaleRef parameter, you can pass in an NSLocale instance. See “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating a Locale

• CFLocaleCopyCurrent
• CFLocaleCreate
• CFLocaleCreateCopy
• CFLocaleGetSystem

Getting System Locale Information

• CFLocaleCopyAvailableLocaleIdentifiers

Getting ISO Information

• CFLocaleCopyISOCountryCodes
• CFLocaleCopyISOLanguageCodes
• CFLocaleCopyISOCurrencyCodes
• CFLocaleCopyCommonISOCurrencyCodes

Language Preferences

• CFLocaleCopyPreferredLanguages

Getting Information About a Locale

• CFLocaleCopyDisplayNameForPropertyValue
• CFLocaleGetValue
• CFLocaleGetIdentifier

Getting and Creating Locale Identifiers

• CFLocaleCreateCanonicalLocaleIdentifierFromScriptManagerCodes
• CFLocaleCreateCanonicalLanguageIdentifierFromString
• CFLocaleCreateCanonicalLocaleIdentifierFromString
• CFLocaleCreateComponentsFromLocaleIdentifier
• CFLocaleCreateLocaleIdentifierFromComponents
• CFLocaleCreateLocaleIdentifierFromWindowsLocaleCode
• CFLocaleGetWindowsLocaleCodeFromLocaleIdentifier

Getting Line and Character Direction for a Language

• CFLocaleGetLanguageCharacterDirection
• CFLocaleGetLanguageLineDirection

Getting the CFLocale Type ID

• CFLocaleGetTypeID

Functions

CFLocaleCopyAvailableLocaleIdentifiers

Returns an array of CFString objects that represents all locales for which locale data is available.

CFArrayRef CFLocaleCopyAvailableLocaleIdentifiers (
   void
);

CFLocaleCopyCommonISOCurrencyCodes

Returns an array of strings that represents ISO currency codes for currencies in common use.

CFArrayRef CFLocaleCopyCommonISOCurrencyCodes (
   void
);

CFLocaleCopyCurrent

Returns a copy of the logical locale for the current user.

CFLocaleRef CFLocaleCopyCurrent (
   void
);

CFLocaleCopyDisplayNameForPropertyValue

Returns the display name for the given value.

CFStringRef CFLocaleCopyDisplayNameForPropertyValue (
   CFLocaleRef displayLocale,
   CFStringRef key,
   CFStringRef value
);

CFLocaleCopyISOCountryCodes

Returns an array of CFString objects that represents all known legal ISO country codes.

CFArrayRef CFLocaleCopyISOCountryCodes (
   void
);

CFLocaleCopyISOCurrencyCodes

Returns an array of CFString objects that represents all known legal ISO currency codes.

CFArrayRef CFLocaleCopyISOCurrencyCodes (
   void
);

CFLocaleCopyISOLanguageCodes

Returns an array of CFString objects that represents all known legal ISO language codes.

CFArrayRef CFLocaleCopyISOLanguageCodes (
   void
);

CFLocaleCopyPreferredLanguages

Returns the array of canonicalized locale IDs that the user prefers.

CFArrayRef CFLocaleCopyPreferredLanguages (
   void
);

CFLocaleCreate

Creates a locale for the given arbitrary locale identifier.

CFLocaleRef CFLocaleCreate (
   CFAllocatorRef allocator,
   CFStringRef localeIdentifier
);

CFLocaleCreateCanonicalLanguageIdentifierFromString

Returns a canonical language identifier by mapping an arbitrary locale identification string to the canonical identifier

CFStringRef CFLocaleCreateCanonicalLanguageIdentifierFromString (
   CFAllocatorRef allocator,
   CFStringRef localeIdentifier
);

CFLocaleCreateCanonicalLocaleIdentifierFromScriptManagerCodes

Returns a canonical locale identifier from given language and region codes.

CFStringRef CFLocaleCreateCanonicalLocaleIdentifierFromScriptManagerCodes (
   CFAllocatorRef allocator,
   LangCode lcode,
   RegionCode rcode
);

CFLocaleCreateCanonicalLocaleIdentifierFromString

Returns a canonical locale identifier by mapping an arbitrary locale identification string to the canonical identifier.

CFStringRef CFLocaleCreateCanonicalLocaleIdentifierFromString (
   CFAllocatorRef allocator,
   CFStringRef localeIdentifier
);

CFLocaleCreateComponentsFromLocaleIdentifier

Returns a dictionary containing the result from parsing a locale ID consisting of language, script, country, variant, and keyword/value pairs.

CFDictionaryRef CFLocaleCreateComponentsFromLocaleIdentifier (
   CFAllocatorRef allocator,
   CFStringRef localeID
);

CFLocaleCreateCopy

Returns a copy of a locale.

CFLocaleRef CFLocaleCreateCopy (
   CFAllocatorRef allocator,
   CFLocaleRef locale
);

CFLocaleCreateLocaleIdentifierFromComponents

Returns a locale identifier consisting of language, script, country, variant, and keyword/value pairs derived from a dictionary containing the source information.

CFStringRef CFLocaleCreateLocaleIdentifierFromComponents (
   CFAllocatorRef allocator,
   CFDictionaryRef dictionary
);

CFLocaleCreateLocaleIdentifierFromWindowsLocaleCode

Returns a locale identifier from a Windows locale code.

CFStringRef CFLocaleCreateLocaleIdentifierFromWindowsLocaleCode (
   CFAllocatorRef allocator,
   uint32_t lcid
);

CFLocaleGetIdentifier

Returns the given locale's identifier.

CFStringRef CFLocaleGetIdentifier (
   CFLocaleRef locale
);

CFLocaleGetLanguageCharacterDirection

Returns the character direction for the specified ISO language code.

CFLocaleLanguageDirection CFLocaleGetLanguageCharacterDirection (
   CFStringRef isoLangCode
);

CFLocaleGetLanguageLineDirection

Returns the line direction for the specified ISO language code.

CFLocaleLanguageDirection CFLocaleGetLanguageLineDirection (
   CFStringRef isoLangCode
);

CFLocaleGetSystem

Returns the root, canonical locale.

CFLocaleRef CFLocaleGetSystem (
   void
);

CFLocaleGetTypeID

Returns the type identifier for the CFLocale opaque type.

CFTypeID CFLocaleGetTypeID (
   void
);

CFLocaleGetValue

Returns the corresponding value for the given key of a locale’s key-value pair.

CFTypeRef CFLocaleGetValue (
   CFLocaleRef locale,
   CFStringRef key
);

CFLocaleGetWindowsLocaleCodeFromLocaleIdentifier

Returns a Windows locale code from the locale identifier.

uint32_t CFLocaleGetWindowsLocaleCodeFromLocaleIdentifier (
   CFStringRef localeIdentifier
);

Data Types

CFLocaleRef

A reference to a CFLocale object.

typedef const struct __CFLocale *CFLocaleRef;

Constants

CFLocaleLanguageDirection

These constants describe the text direction for a language. They are returned by the functions CFLocaleGetLanguageCharacterDirection and CFLocaleGetLanguageLineDirection.

typedef enum : CFIndex {
   kCFLocaleLanguageDirectionUnknown = 0,
   kCFLocaleLanguageDirectionLeftToRight = 1,
   kCFLocaleLanguageDirectionRightToLeft = 2,
   kCFLocaleLanguageDirectionTopToBottom = 3,
   kCFLocaleLanguageDirectionBottomToTop = 4
} CFLocaleLanguageDirection;

Constants

kCFLocaleLanguageDirectionUnknown

The direction of the language is unknown.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFLocaleLanguageDirectionLeftToRight

The language direction is from left to right.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFLocaleLanguageDirectionRightToLeft

The language direction is from right to left.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFLocaleLanguageDirectionTopToBottom

The language direction is from top to bottom.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFLocaleLanguageDirectionBottomToTop

The language direction is from bottom to top.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

Locale Property Keys

Predefined locale keys used to get property values.

const CFStringRef kCFLocaleIdentifier;
const CFStringRef kCFLocaleLanguageCode;
const CFStringRef kCFLocaleCountryCode;
const CFStringRef kCFLocaleScriptCode;
const CFStringRef kCFLocaleVariantCode;
   
const CFStringRef kCFLocaleExemplarCharacterSet;
const CFStringRef kCFLocaleCalendarIdentifier;
const CFStringRef kCFLocaleCalendar;
const CFStringRef kCFLocaleCollationIdentifier;
const CFStringRef kCFLocaleUsesMetricSystem;
const CFStringRef kCFLocaleMeasurementSystem;
const CFStringRef kCFLocaleDecimalSeparator;
const CFStringRef kCFLocaleGroupingSeparator;
const CFStringRef kCFLocaleCurrencySymbol;
const CFStringRef kCFLocaleCurrencyCode;
const CFStringRef kCFLocaleCollatorIdentifier;
const CFStringRef kCFLocaleQuotationBeginDelimiterKey;
const CFStringRef kCFLocaleQuotationEndDelimiterKey;
const CFStringRef kCFLocaleAlternateQuotationBeginDelimiterKey;
const CFStringRef kCFLocaleAlternateQuotationEndDelimiterKey;

Constants

kCFLocaleIdentifier

Specifies locale identifier.

The corresponding value is a CFString containing the POSIX locale identifier as used by ICU, such as “ja_JP”. If you have a variant locale or a different currency or calendar, it can be as complex as “en_US_POSIX@calendar=japanese;currency=EUR” or “az_Cyrl_AZ@calendar=buddhist;currency=JPY”.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleLanguageCode

Specifies the locale language code.

The corresponding value is a CFString containing an ISO 639-x/IETF BCP 47 language identifier, such as “ja”.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleCountryCode

Specifies the locale country code.

The corresponding value is a CFString containing an ISO county code, such as “JP”.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleScriptCode

Specifies the locale script code.

The corresponding value is a CFString containing a Unicode script tag (strictly, an ISO 15924 script tag). Usually this is empty (it is for “ja_JP”). It may be present for locales where a script must be specified, for example “uz-Latn-UZ” vs. “uz-Cyrl-UZ” for Uzbek in Latin vs. Cyrillic (in the first case the script code is “Latn”, and in the second it is “Cyrl”).

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleVariantCode

Specifies the locale variant code.

The corresponding value is a CFString containing the variant name. The variant code is arbitrary and application-specific. ICU adds “_EURO” to its locale designations for locales that support the Euro currency. For “en_US_POSIX” the variant is “POSIX”, and for “hy_AM_REVISED” it is “REVISED”.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleExemplarCharacterSet

Specifies the locale character set.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleCalendarIdentifier

Specifies the locale calendar identifier.

The corresponding value is a CFString containing the calendar identifier (for possible values, see “Locale Calendar Identifiers”).

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleCalendar

Specifies the locale calendar.

The corresponding value is a CFCalendar object.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleCollationIdentifier

Specifies the locale collation identifier.

The corresponding value is a collation.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleUsesMetricSystem

Specifies the whether the locale uses the metric system.

The corresponding value is a CFBoolean.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleMeasurementSystem

Specifies the measurement system used.

The corresponding value is a CFString object, for example “Metric” or “U.S.”.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleDecimalSeparator

Specifies the decimal point string.

The corresponding value is a CFString object, for example “.” or “,”.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleGroupingSeparator

Specifies the separator string between groups of digits.

The corresponding value is a CFString object, for example “,” or “.”.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleCurrencySymbol

Specifies the currency symbol.

The corresponding value is a CFString object, for example “$” or “£”.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleCurrencyCode

Specifies the locale currency code.

The corresponding value is a CFString object, for example “USD” or “GBP”.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFLocaleCollatorIdentifier

Specifies the collation identifier for the locale.

The corresponding value is a CFString object. If unknown, nil is returned.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFLocaleQuotationBeginDelimiterKey

Specifies the the begin quotation symbol associated with the locale.

The corresponding value is a CFString object.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFLocaleQuotationEndDelimiterKey

Specifies the end quotation symbol associated with the locale.

The corresponding value is a CFString object.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFLocaleAlternateQuotationBeginDelimiterKey

Specifies the alternating begin quotation symbol associated with the locale. In some locales, when quotations are nested, the quotation characters alternate. Thus, NSLocaleQuotationBeginDelimiterKey, then NSLocaleAlternateQuotationBeginDelimiterKey, and so on.

The corresponding value is a CFString object.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFLocaleAlternateQuotationEndDelimiterKey

Specifies the alternating end quotation symbol associated with the locale. In some locales, when quotations are nested, the quotation characters alternate. Thus, NSLocaleQuotationEndDelimiterKey, then NSLocaleAlternateQuotationEndDelimiterKey, and so on.

The corresponding value is a CFString object.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

Locale Calendar Identifiers

Predefined locale keys used to get calendar values—values for kCFLocaleCalendarIdentifier.

const CFStringRef kCFGregorianCalendar;
const CFStringRef kCFBuddhistCalendar;
const CFStringRef kCFChineseCalendar;
const CFStringRef kCFHebrewCalendar;
const CFStringRef kCFIslamicCalendar;
const CFStringRef kCFIslamicCivilCalendar;
const CFStringRef kCFJapaneseCalendar;
const CFStringRef kCFRepublicOfChinaCalendar;
const CFStringRef kCFPersianCalendar;
const CFStringRef kCFIndianCalendar;
const CFStringRef kCFISO8601Calendar;

Constants

kCFGregorianCalendar

Specifies the Gregorian calendar.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFBuddhistCalendar

Specifies the Buddhist calendar.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFChineseCalendar

Specifies the Chinese calendar.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFHebrewCalendar

Specifies the Hebrew calendar.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFIslamicCalendar

Specifies the Islamic calendar.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFIslamicCivilCalendar

Specifies the Islamic Civil calendar.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFJapaneseCalendar

Specifies the Japanese calendar.

Available in iOS 2.0 and later.

Declared in CFLocale.h.

kCFRepublicOfChinaCalendar

Specifies the calendar for the Republic of China.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFPersianCalendar

Specifies the Persian calendar.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFIndianCalendar

Specifies the Indian calendar.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

kCFISO8601Calendar

Specifies the ISO 8601 calendar.

Available in iOS 4.0 and later.

Declared in CFLocale.h.

Locale Change Notification

Identifier for notification sent if the current locale changes.

const CFStringRef kCFLocaleCurrentLocaleDidChangeNotification

Constants

kCFLocaleCurrentLocaleDidChangeNotification

Identifier for the notification sent if the current locale changes.

This is a local notification posted when the user changes locale information in the System Preferences panel. Keep in mind that there is no order in how notifications are delivered to observers; frameworks or other parts of your code may also be observing this notification to take their own actions, and these may not have occurred at the time you receive the notification.

There is no object or user info for this notification.

Available in iOS 2.0 and later.

Declared in CFLocale.h.