CFString

Overview

CFString provides a suite of efficient string-manipulation and string-conversion functions. It offers seamless Unicode support and facilitates the sharing of data between Cocoa and C-based programs. CFString objects are immutable—use CFMutableStringRef to create and manage a string that can be changed after it has been created.

CFString has two primitive functions, CFStringGetLength and CFStringGetCharacterAtIndex, that provide the basis for all other functions in its interface. The CFStringGetLength function returns the total number (in terms of UTF-16 code pairs) of characters in the string. The CFStringGetCharacterAtIndex function gives access to each character in the string by index, with index values starting at 0.

CFString provides functions for finding and comparing strings. It also provides functions for reading numeric values from strings, for combining strings in various ways, and for converting a string to different forms (such as encoding and case changes). A number of functions, for example CFStringFindWithOptions, allow you to specify a range over which to operate within a string. The specified range must not exceed the length of the string. Debugging options may help you to catch any errors that arise if a range does exceed a string’s length.

Like other Core Foundation types, you can hash CFStrings using the CFHash function. You should never, though, store a hash value outside of your application and expect it to be useful if you read it back in later (hash values may change between different releases of the operating system).

CFString is “toll-free bridged” with its Cocoa Foundation counterpart, NSString. 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 NSString * parameter, you can pass in a CFStringRef, and in a function where you see a CFStringRef parameter, you can pass in an NSString instance. This also applies to concrete subclasses of NSString. See Toll-Free Bridged Types for more information on toll-free bridging.

Topics

Creating a CFString

CFSTR

Creates an immutable string from a constant compile-time string.

CFStringCreateArrayBySeparatingStrings

Creates an array of CFString objects from a single CFString object.

CFStringCreateByCombiningStrings

Creates a single string from the individual CFString objects that comprise the elements of an array.

CFStringCreateCopy

Creates an immutable copy of a string.

CFStringCreateFromExternalRepresentation

Creates a string from its “external representation.”

CFStringCreateWithBytes

Creates a string from a buffer containing characters in a specified encoding.

CFStringCreateWithBytesNoCopy

Creates a string from a buffer, containing characters in a specified encoding, that might serve as the backing store for the new string.

CFStringCreateWithCharacters

Creates a string from a buffer of Unicode characters.

CFStringCreateWithCharactersNoCopy

Creates a string from a buffer of Unicode characters that might serve as the backing store for the object.

CFStringCreateWithCString

Creates an immutable string from a C string.

CFStringCreateWithCStringNoCopy

Creates a CFString object from an external C string buffer that might serve as the backing store for the object.

CFStringCreateWithFormat

Creates an immutable string from a formatted string and a variable number of arguments.

CFStringCreateWithFormatAndArguments

Creates an immutable string from a formatted string and a variable number of arguments (specified in a parameter of type va_list).

CFStringCreateWithPascalString

Creates an immutable CFString object from a Pascal string.

CFStringCreateWithPascalStringNoCopy

Creates a CFString object from an external Pascal string buffer that might serve as the backing store for the object.

CFStringCreateWithSubstring

Creates an immutable string from a segment (substring) of an existing string.

Searching Strings

CFStringCreateArrayWithFindResults

Searches a string for multiple occurrences of a substring and creates an array of ranges identifying the locations of these substrings within the target string.

CFStringFind

Searches for a substring within a string and, if it is found, yields the range of the substring within the object's characters.

CFStringFindCharacterFromSet

Query the range of the first character contained in the specified character set.

CFStringFindWithOptions

Searches for a substring within a range of the characters represented by a string and, if the substring is found, returns its range within the object's characters.

CFStringFindWithOptionsAndLocale

Returns a Boolean value that indicates whether a given string was found in a given source string.

CFStringGetLineBounds

Given a range of characters in a string, obtains the line bounds—that is, the indexes of the first character and the final characters of the lines containing the range.

Comparing Strings

CFStringCompare

Compares one string with another string.

CFStringCompareWithOptions

Compares a range of the characters in one string with that of another string.

CFStringCompareWithOptionsAndLocale

Compares a range of the characters in one string with another string using a given locale.

CFStringHasPrefix

Determines if the character data of a string begin with a specified sequence of characters.

CFStringHasSuffix

Determines if a string ends with a specified sequence of characters.

Accessing Characters

CFStringCreateExternalRepresentation

Creates an “external representation” of a CFString object, that is, a CFData object.

CFStringGetBytes

Fetches a range of the characters from a string into a byte buffer after converting the characters to a specified encoding.

CFStringGetCharacterAtIndex

Returns the Unicode character at a specified location in a string.

CFStringGetCharacters

Copies a range of the Unicode characters from a string to a user-provided buffer.

CFStringGetCharactersPtr

Quickly obtains a pointer to the contents of a string as a buffer of Unicode characters.

CFStringGetCharacterFromInlineBuffer

Returns the Unicode character at a specific location in an in-line buffer.

CFStringGetCString

Copies the character contents of a string to a local C string buffer after converting the characters to a given encoding.

CFStringGetCStringPtr

Quickly obtains a pointer to a C-string buffer containing the characters of a string in a given encoding.

CFStringGetLength

Returns the number (in terms of UTF-16 code pairs) of Unicode characters in a string.

CFStringGetPascalString

Copies the character contents of a CFString object to a local Pascal string buffer after converting the characters to a requested encoding.

CFStringGetPascalStringPtr

Quickly obtains a pointer to a Pascal buffer containing the characters of a string in a given encoding.

CFStringGetRangeOfComposedCharactersAtIndex

Returns the range of the composed character sequence at a specified index.

CFStringInitInlineBuffer

Initializes an in-line buffer to use for efficient access of a CFString object's characters.

Working With Hyphenation

CFStringGetHyphenationLocationBeforeIndex

Retrieve the first potential hyphenation location found before the specified location.

CFStringIsHyphenationAvailableForLocale

Returns a Boolean value that indicates whether hyphenation data is available.

Working With Encodings

CFStringConvertEncodingToIANACharSetName

Returns the name of the IANA registry “charset” that is the closest mapping to a specified string encoding.

CFStringConvertEncodingToNSStringEncoding

Returns the Cocoa encoding constant that maps most closely to a given Core Foundation encoding constant.

CFStringConvertEncodingToWindowsCodepage

Returns the Windows codepage identifier that maps most closely to a given Core Foundation encoding constant.

CFStringConvertIANACharSetNameToEncoding

Returns the Core Foundation encoding constant that is the closest mapping to a given IANA registry “charset” name.

CFStringConvertNSStringEncodingToEncoding

Returns the Core Foundation encoding constant that is the closest mapping to a given Cocoa encoding.

CFStringConvertWindowsCodepageToEncoding

Returns the Core Foundation encoding constant that is the closest mapping to a given Windows codepage identifier.

CFStringGetFastestEncoding

Returns for a CFString object the character encoding that requires the least conversion time.

CFStringGetListOfAvailableEncodings

Returns a pointer to a list of string encodings supported by the current system.

CFStringGetMaximumSizeForEncoding

Returns the maximum number of bytes a string of a specified length (in Unicode characters) will take up if encoded in a specified encoding.

CFStringGetMostCompatibleMacStringEncoding

Returns the most compatible Mac OS script value for the given input encoding.

CFStringGetNameOfEncoding

Returns the canonical name of a specified string encoding.

CFStringGetSmallestEncoding

Returns the smallest encoding on the current system for the character contents of a string.

CFStringGetSystemEncoding

Returns the default encoding used by the operating system when it creates strings.

CFStringIsEncodingAvailable

Determines whether a given Core Foundation string encoding is available on the current system.

Getting Numeric Values

CFStringGetDoubleValue

Returns the primary double value represented by a string.

CFStringGetIntValue

Returns the integer value represented by a string.

Getting String Properties

CFShowStr

Prints the attributes of a string during debugging.

CFStringGetTypeID

Returns the type identifier for the CFString opaque type.

String File System Representations

CFStringCreateWithFileSystemRepresentation

Creates a CFString from a zero-terminated POSIX file system representation.

CFStringGetFileSystemRepresentation

Extracts the contents of a string as a NULL-terminated 8-bit string appropriate for passing to POSIX APIs.

CFStringGetMaximumSizeOfFileSystemRepresentation

Determines the upper bound on the number of bytes required to hold the file system representation of the string.

Getting Paragraph Bounds

CFStringGetParagraphBounds

Given a range of characters in a string, obtains the paragraph bounds—that is, the indexes of the first character and the final characters of the paragraph(s) containing the range.

Managing Surrogates

CFStringGetLongCharacterForSurrogatePair

Returns a UTF-32 character that corresponds to a given pair of UTF-16 surrogate characters.

CFStringGetSurrogatePairForLongCharacter

Maps a given UTF-32 character to a pair of UTF-16 surrogate characters.

CFStringIsSurrogateHighCharacter

Returns a Boolean value that indicates whether a given character is a high character in a surrogate pair.

CFStringIsSurrogateLowCharacter

Returns a Boolean value that indicates whether a given character is a low character in a surrogate pair.

Data Types

CFStringEncoding

An integer type for constants used to specify supported string encodings in various CFString functions.

CFStringEncodings

Index type for constants used to specify external string encodings.

CFStringCompareFlags

A CFOptionFlags type for specifying options for string comparison .

CFStringInlineBuffer

Defines the buffer and related fields used for in-line buffer access of characters in CFString objects.

CFStringRef

A reference to a CFString object.

Constants

String Comparison Flags

Flags that specify how string comparisons are performed.

CFStringBuiltInEncodings

Encodings that are built-in on all platforms on which macOS runs.

Invalid String Encoding Flag

Special value returned from functions to indicate a string encoding that is not supported or recognized by CFString.

External String Encodings

CFStringEncoding constants for encodings that may be supported by CFString.

See Also

Opaque Types

CFFileDescriptor

The CFFileDescriptor provides an opaque type to monitor file descriptors for read and write activity via CFRunLoop.

CFStringTokenizer

CFStringTokenizer allows you to tokenize strings into words, sentences or paragraphs in a language-neutral way. It supports languages such as Japanese and Chinese that do not delimit words by spaces, as well as de-compounding German compounds. You can obtain Latin transcription for tokens. It also provides language identification API.