Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

CFString Reference

Derived from
Framework
CoreFoundation/CoreFoundation.h
Declared in
CFBase.h
CFString.h
CFStringEncodingExt.h
Companion guides

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 Carbon and Cocoa programs. CFString is relevant for any Carbon application that uses strings. If your application supports (or is planning to support) Unicode, CFString is recommended. CFString creates immutable strings—use CFMutableString 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, CFStrings can be hashed using the CFHash function. Note, though, that hash values are not guaranteed to remain equal between releases of the operating system. In particular, hash values are different between Mac OS X v10.3 and v10.4. If you need to make a hash value persistent and consistent across different releases, you should use an alternate technique, such as SHA-1.

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 Interchangeable Data Types for more information on toll-free bridging.

Functions by Task

Creating a CFString

Searching Strings

Comparing Strings

Accessing Characters

Working With Encodings

Getting Numeric Values

Getting String Properties

String File System Representations

Getting Paragraph Bounds

Functions

CFShowStr

Prints the attributes of a string during debugging.

void CFShowStr (
   CFStringRef str
);

Parameters
str

The string whose attributes you want to print.

Discussion

Use this function to learn about specific attributes of a CFString object during debugging. These attributes include the following:

The information provided by this function is for debugging purposes only. The values of any of these attributes might change between different releases and on different platforms. Note in particular that this function does not show the contents of the string. If you want to display the contents of the string, use CFShow.

Special Considerations

You can use CFShowStr in one of two general ways. If your debugger supports function calls (such as gdb does), call CFShowStr in the debugger:

(gdb) call (void) CFShowStr(string)
Length 11
IsEightBit 1
HasLengthByte 1
HasNullByte 1
InlineContents 1
Allocator SystemDefault
Mutable 0
Contents 0x4e7c0

You can also incorporate calls to CFShowStr in a test version of your code to print descriptions of CFString objects to the console.

Availability
Declared In
CFString.h

CFSTR

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

CFStringRef CFSTR (
   const char *cStr
);

Parameters
cStr

A constant C string (that is, text enclosed in double-quotation marks) from which the string is to be created. The characters enclosed by the quotation marks must be ASCII characters, otherwise the behavior is undefined.

Return Value

An immutable string, or NULL if there was a problem creating the object. The returned object is a constant. You may retain and release it, similar to other immutable CFString objects, but are not required to do so—it will remain valid until the program terminates.

Discussion

The CFSTR macro is a convenient way to create CFString representations of constant compile-time strings.

A value returned by CFSTR has the following semantics:

Non-ASCII characters (that is, character codes greater than 127) are not supported. If you use them, the result is undefined. Even if using them works for you in testing, it might not work if the user selects a different language preference.

Note that when using this macro as an initializer, you must compile using the flag -fconstant-cfstrings (see Options Controlling C Dialect).

CFStringCompare

Compares one string with another string.

CFComparisonResult CFStringCompare (
   CFStringRef theString1,
   CFStringRef theString2,
   CFOptionFlags compareOptions
);

Parameters
theString1

The first string to use in the comparison.

theString2

The second string to use in the comparison.

compareOptions

Flags that select different types of comparisons, such as localized comparison, case-insensitive comparison, and non-literal comparison. If you want the default comparison behavior, pass 0. See “String Comparison Flags” for the available flags.

Return Value

A CFComparisonResult value that indicates whether theString1 is equal to, less than, or greater than theString2.

Discussion

You can affect how the comparison proceeds by specifying one or more option flags in compareOptions. Not all comparison options are currently implemented.

Availability
Declared In
CFString.h

CFStringCompareWithOptions

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

CFComparisonResult CFStringCompareWithOptions (
   CFStringRef theString1,
   CFStringRef theString2,
   CFRange rangeToCompare,
   CFOptionFlags compareOptions
);

Parameters
theString1

The first string to use in the comparison.

theString2

The second string to use in the comparison.

rangeToCompare

The range of characters in theString1 to be used in the comparison to theString2. To use the whole string, pass the range CFRangeMake(0, CFStringGetLength(theString1)) or use CFStringCompare. The specified range must not exceed the length of the string.

compareOptions

Flags that select different types of comparisons, such as localized comparison, case-insensitive comparison, and non-literal comparison. If you want the default comparison behavior, pass 0. See “String Comparison Flags” for the available flags.

Return Value

A CFComparisonResult value that indicates whether theString1 is equal to, less than, or greater than theString2.

Discussion

You can affect how the comparison proceeds by specifying one or more option flags in compareOptions.

If you want to compare one entire string with another string, use the CFStringCompare function.

Availability
Declared In
CFString.h

CFStringCompareWithOptionsAndLocale

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

CFComparisonResult CFStringCompareWithOptionsAndLocale (
   CFStringRef theString1,
   CFStringRef theString2,
   CFRange rangeToCompare,
   CFOptionFlags compareOptions,
   CFLocaleRef locale
);

Parameters
theString1

The first string to use in the comparison.

theString2

The second string to use in the comparison. The full range of this string is used.

rangeToCompare

The range of characters in theString1 to be used in the comparison to theString2. To use the whole string, pass the range CFRangeMake(0, CFStringGetLength(theString1)). The specified range must not exceed the bounds of the string.

compareOptions

Flags that select different types of comparisons, such as case-insensitive comparison and non-literal comparison. If you want the default comparison behavior, pass 0. See “String Comparison Flags” for the available flags. kCFCompareBackwards and kCFCompareAnchored are not applicable.

locale

The locale to use for the comparison. NULL specifies the canonical locale (the return value from CFLocaleGetSystem).

Return Value

A CFComparisonResult value that indicates whether theString1 is equal to, less than, or greater than theString2.

Availability
Declared In
CFString.h

CFStringConvertEncodingToIANACharSetName

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

CFStringRef CFStringConvertEncodingToIANACharSetName (
   CFStringEncoding encoding
);

Parameters
encoding

The Core Foundation string encoding to use.

Return Value

The name of the IANA “charset” that is the closest mapping to encoding. Returns NULL if the encoding is not recognized.

Discussion

The CFStringConvertIANACharSetNameToEncoding function is complementary to this function.

Availability
Declared In
CFString.h

CFStringConvertEncodingToNSStringEncoding

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

UInt32 CFStringConvertEncodingToNSStringEncoding (
   CFStringEncoding encoding
);

Parameters
encoding

The Core Foundation string encoding to use.

Return Value

The Cocoa encoding (of type NSStringEncoding) that is closest to the Core Foundation encoding encoding. The behavior is undefined if an invalid string encoding is passed.

Discussion

The CFStringConvertNSStringEncodingToEncoding function is complementary to this function.

Availability
Declared In
CFString.h

CFStringConvertEncodingToWindowsCodepage

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

UInt32 CFStringConvertEncodingToWindowsCodepage (
   CFStringEncoding encoding
);

Parameters
encoding

The Core Foundation string encoding to use.

Return Value

The Windows codepage value that is closest to the Core Foundation encoding encoding. The behavior is undefined if an invalid string encoding is passed.

Discussion

The CFStringConvertWindowsCodepageToEncoding function is complementary to this function.

Availability
Declared In
CFString.h

CFStringConvertIANACharSetNameToEncoding

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

CFStringEncoding CFStringConvertIANACharSetNameToEncoding (
   CFStringRef theString
);

Parameters
IANAName

The IANA “charset” name to use.

Return Value

The Core Foundation string encoding that is closest to the IANA “charset” IANAName. Returns the kCFStringEncodingInvalidId constant if the name is not recognized.

Discussion

The CFStringConvertEncodingToIANACharSetName function is complementary to this function.

Availability
Declared In
CFString.h

CFStringConvertNSStringEncodingToEncoding

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

CFStringEncoding CFStringConvertNSStringEncodingToEncoding (
   UInt32 encoding
);

Parameters
encoding

The Cocoa string encoding (of type NSStringEncoding) to use.

Return Value

The Core Foundation string encoding that is closest to the Cocoa string encoding encoding. Returns the kCFStringEncodingInvalidId constant if the mapping is not known.

Discussion

The CFStringConvertEncodingToNSStringEncoding function is complementary to this function.

Availability
Declared In
CFString.h

CFStringConvertWindowsCodepageToEncoding

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

CFStringEncoding CFStringConvertWindowsCodepageToEncoding (
   UInt32 codepage
);

Parameters
codepage

The Windows codepage identifier to use.

Return Value

The Core Foundation string encoding that is closest to the Windows codepage identifier codepage. Returns the kCFStringEncodingInvalidId constant if the mapping is not known.

Discussion

The CFStringConvertEncodingToWindowsCodepage function is complementary to this function.

Availability
Declared In
CFString.h

CFStringCreateArrayBySeparatingStrings

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

CFArrayRef CFStringCreateArrayBySeparatingStrings (
   CFAllocatorRef alloc,
   CFStringRef theString,
   CFStringRef separatorString
);

Parameters
alloc

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

theString

The string to be divided into substrings. The substrings should be separated by separatorString.

separatorString

A string containing the character or characters used to separate the substrings in theString.

Return Value

A new array that contains CFString objects that represent substrings of theString, or NULL if there was a problem creating the object. The order of elements in the array is identical to the order of the substrings in theString. If separatorString does not occur in theString, the result is an array containing theString. If separatorString is equal to theString, then the result is an array containing two empty strings. Ownership follows the Create Rule.

Discussion

This function provides a convenient way to convert units of data captured in a single string to a form (an array) suitable for iterative processing. One or more delimiter characters (or “separator string”) separates the substrings in the source string—these characters are frequently whitespace characters such as tabs and newlines (carriage returns). For example, you might have a file containing a localized list of place names with each name separated by a tab character. You could create a CFString object from this file and call this function on the string to obtain a CFArray object whose elements are these place names.

See also CFStringCreateByCombiningStrings.

Availability
Declared In
CFString.h

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.

CFArrayRef CFStringCreateArrayWithFindResults (
   CFAllocatorRef alloc,
   CFStringRef theString,
   CFStringRef stringToFind,
   CFRange rangeToSearch,
   CFOptionFlags compareOptions
);

Parameters
alloc

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

theString

The string in which to search for stringToFind.

stringToFind

The string to search for in theString.

rangeToSearch

The range of characters within theString to be searched. The specified range must not exceed the length of the string.

compareOptions

Flags that select different types of comparisons, such as localized comparison, case-insensitive comparison, and non-literal comparison. If you want the default comparison behavior, pass 0. See “String Comparison Flags” for the available flags.

Return Value

An array that contains pointers to CFRange structures identifying the character locations of stringToFind in theString. Returns NULL, if no matching substring is found in the source object, or if there was a problem creating the array. Ownership follows the Create Rule.

Availability
Declared In
CFString.h

CFStringCreateByCombiningStrings

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

CFStringRef CFStringCreateByCombiningStrings (
   CFAllocatorRef alloc,
   CFArrayRef theArray,
   CFStringRef separatorString
);

Parameters
alloc

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

theArray

An array of CFString objects to concatenate. This value should not be NULL.

separatorString

The string to insert between the substrings in the returned string. This value is commonly a whitespace character such as a tab or a newline (carriage return). If this value is not a valid CFString object, an assertion is raised.

Return Value

A string that contains a concatenation of the strings in theArray separated by separatorString. The order of the substrings in the string is identical to the order of the elements in theArray.

If theArray is empty, returns an empty CFString object; if theArray contains one CFString object, that object is returned (without the separator string). Returns NULL if there was a problem in creating the string. Ownership follows the Create Rule.

Discussion

See also CFStringCreateArrayBySeparatingStrings.

Availability
Declared In
CFString.h

CFStringCreateCopy

Creates an immutable copy of a string.

CFStringRef CFStringCreateCopy (
   CFAllocatorRef alloc,
   CFStringRef theString
);

Parameters
alloc

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

theString

The string to copy.

Return Value

An immutable string whose contents are identical to theString. Returns NULL if there was a problem copying the object. Ownership follows the Create Rule.

Discussion

The resulting object has the same Unicode contents as the original object, but it is always immutable. It might also have different storage characteristics, and hence might reply differently to functions such as CFStringGetCStringPtr. Also, if the specified allocator and the allocator of the original object are the same, and the string is already immutable, this function may simply increment the retention count without making a true copy. However, the resulting object is a true immutable copy, except the operation was a lot more efficient.

You should use this function in situations where a string is or could be mutable, and you need to take a snapshot of its current value. For example, you might decide to pass a copy of a string to a function that stores its current value in a list for later use.

Availability
Declared In
CFString.h

CFStringCreateExternalRepresentation

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

CFDataRef CFStringCreateExternalRepresentation (
   CFAllocatorRef alloc,
   CFStringRef theString,
   CFStringEncoding encoding,
   UInt8 lossByte
);

Parameters
alloc

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

theString

The string to convert to an external representation.

encoding

The string encoding to use for the external representation.

lossByte

The character value to assign to characters that cannot be converted to the requested encoding. Pass 0 if you want conversion to stop at the first such error; if this happens, the function returns NULL.

Return Value

A CFData object that stores the characters of the CFString object as an “external representation.” Returns NULL if no loss byte was specified and the function could not convert the characters to the specified encoding. Ownership follows the Create Rule.

Discussion

In the CFData object form, the string can be written to disk as a file or be sent out over a network. If the encoding of the characters in the data object is Unicode, the function may insert a BOM (byte-order marker) to indicate endianness. However, representations created with encoding constants kCFStringEncodingUTF16BE, kCFStringEncodingUTF16LE, kCFStringEncodingUTF32BE, and kCFStringEncodingUTF32LE do not include a BOM because the byte order is explicitly indicated by the letters “BE” (big-endian) and “LE” (little-endian).

This function allows the specification of a “loss byte” to represent characters that cannot be converted to the requested encoding.

When you create an external representation from a CFMutableString object, it loses this mutability characteristic when it is converted back to a CFString object.

The CFStringCreateFromExternalRepresentation function complements this function by creating a CFString object from an “external representation” CFData object.

Availability
Declared In
CFString.h

CFStringCreateFromExternalRepresentation

Creates a string from its “external representation.”

CFStringRef CFStringCreateFromExternalRepresentation (
   CFAllocatorRef alloc,
   CFDataRef data,
   CFStringEncoding encoding
);

Parameters
alloc

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

data

The CFData object containing bytes that hold the characters in the specified encoding.

encoding

The encoding to use when interpreting the bytes in the data argument.

Return Value

An immutable string containing the characters from data, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

In the CFData object form, the string can be written to disk as a file or be sent out over a network. If the encoding of the characters in the data object is Unicode, the function reads any BOM (byte order marker) and properly resolves endianness.

The CFStringCreateExternalRepresentation function complements this function by creating an “external representation” CFData object from a string.

Availability
Declared In
CFString.h

CFStringCreateWithBytes

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

CFStringRef CFStringCreateWithBytes (
   CFAllocatorRef alloc,
   const UInt8 *bytes,
   CFIndex numBytes,
   CFStringEncoding encoding,
   Boolean isExternalRepresentation
);

Parameters
alloc

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

bytes

A buffer containing characters in the encoding specified by encoding. The buffer must not contain a length byte (as in Pascal buffers) or any terminating NULL character (as in C buffers).

numBytes

The number of bytes in bytes.

encoding

The string encoding of the characters in the buffer.

isExternalRepresentation

true if the characters in the byte buffer are in an “external representation” format—that is, whether the buffer contains a BOM (byte order marker). This is usually the case for bytes that are read in from a text file or received over the network. Otherwise, pass false.

Return Value

An immutable string, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

This function handles character data in an “external representation” format by interpreting any BOM (byte order marker) character and performing any necessary byte swapping.

Availability
Declared In
CFString.h

CFStringCreateWithBytesNoCopy

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

CFStringRef CFStringCreateWithBytesNoCopy (
   CFAllocatorRef alloc,
   const UInt8 *bytes,
   CFIndex numBytes,
   CFStringEncoding encoding,
   Boolean isExternalRepresentation,
   CFAllocatorRef contentsDeallocator
);

Parameters
alloc

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

bytes

A buffer containing characters in the encoding specified by encoding. The buffer must not contain a length byte (as in Pascal buffers) or any terminating NULL character (as in C buffers).

numBytes

The number of bytes in bytes.

encoding

The character encoding of bytes.

isExternalRepresentation

true if the characters in the byte buffer are in an “external representation” format—that is, whether the buffer contains a BOM (byte order marker). This is usually the case for bytes that are read in from a text file or received over the network. Otherwise, pass false.

contentsDeallocator

The allocator to use to deallocate bytes when it is no longer needed. You can pass NULL or kCFAllocatorDefault to request the default allocator for this purpose. If the buffer does not need to be deallocated, or if you want to assume responsibility for deallocating the buffer (and not have the string deallocate it), pass kCFAllocatorNull.

Return Value

A new string whose contents are bytes. Ownership follows the Create Rule.

Discussion

This function takes an explicit length, and allows you to specify whether the data is an external format—that is, whether to pay attention to the BOM character (if any) and do byte swapping if necessary

Special Considerations

If an error occurs during the creation of the string, then bytes is not deallocated. In this case, the caller is responsible for freeing the buffer. This allows the caller to continue trying to create a string with the buffer, without having the buffer deallocated.

Availability
See Also
Declared In
CFString.h

CFStringCreateWithCharacters

Creates a string from a buffer of Unicode characters.

CFStringRef CFStringCreateWithCharacters (
   CFAllocatorRef alloc,
   const UniChar *chars,
   CFIndex numChars
);

Parameters
alloc

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

chars

The buffer of Unicode characters to copy into the new string.

numChars

The number of characters in the buffer pointed to by chars. Only this number of characters will be copied to internal storage.

Return Value

An immutable string containing chars, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

This function creates an immutable string from a client-supplied Unicode buffer. You must supply a count of the characters in the buffer. This function always copies the characters in the provided buffer into internal storage.

To save memory, this function might choose to store the characters internally in a 8-bit backing store. That is, just because a buffer of UniChar characters was used to initialize the object does not mean you will get back a non-NULL result from CFStringGetCharactersPtr.

Availability
Declared In
CFString.h

CFStringCreateWithCharactersNoCopy

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

CFStringRef CFStringCreateWithCharactersNoCopy (
   CFAllocatorRef alloc,
   const UniChar *chars,
   CFIndex numChars,
   CFAllocatorRef contentsDeallocator
);

Parameters
alloc

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

chars

The Unicode buffer that has been allocated and initialized with Unicode characters.

numChars

The number of characters in the buffer pointed to by chars. Only this number of characters will be copied to internal storage.

contentsDeallocator

The allocator to use to deallocate the external buffer when it is no longer needed. You can pass NULL or kCFAllocatorDefault to request the default allocator for this purpose. If the buffer does not need to be deallocated, or if you want to assume responsibility for deallocating the buffer (and not have the string deallocate it), pass kCFAllocatorNull.

Return Value

An immutable string containing chars, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

Unless the situation warrants otherwise, the returned object does not copy the external buffer to internal storage but instead uses the buffer as its backing store. However, you should never count on the object using the external buffer since it could copy the buffer to internal storage or might even dump the buffer altogether and use alternative means for storing the characters.

The function includes a contentsDeallocator parameter with which to specify an allocator to use for deallocating the external buffer when the string is deallocated. If you want to assume responsibility for deallocating this memory, specify kCFAllocatorNull for this parameter.

If at creation time CFString decides it can't use the buffer, and there is a contentsDeallocator, it will use this allocator to free the buffer at that time.

Special Considerations

If an error occurs during the creation of the string, then chars is not deallocated. In this case, the caller is responsible for freeing the buffer. This allows the caller to continue trying to create a string with the buffer, without having the buffer deallocated.

Availability
See Also
Declared In
CFString.h

CFStringCreateWithCString

Creates an immutable string from a C string.

CFStringRef CFStringCreateWithCString (
   CFAllocatorRef alloc,
   const char *cStr,
   CFStringEncoding encoding
);

Parameters
alloc

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

cStr

The NULL-terminated C string to be used to create the CFString object. The string must use an 8-bit encoding.

encoding

The encoding of the characters in the C string. The encoding must specify an 8-bit encoding.

Return Value

An immutable string containing cStr (after stripping off the NULL terminating character), or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

A C string is a string of 8-bit characters terminated with an 8-bit NULL. Unichar and Unichar32 are not considered C strings.

Availability
Declared In
CFString.h

CFStringCreateWithCStringNoCopy

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

CFStringRef CFStringCreateWithCStringNoCopy (
   CFAllocatorRef alloc,
   const char *cStr,
   CFStringEncoding encoding,
   CFAllocatorRef contentsDeallocator
);

Parameters
alloc

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

cStr

The NULL-terminated C string to be used to create the CFString object. The string must use an 8-bit encoding.

encoding

The encoding of the characters in the C string. The encoding must specify an 8-bit encoding.

contentsDeallocator

The CFAllocator object to use to deallocate the external string buffer when it is no longer needed. You can pass NULL or kCFAllocatorDefault to request the default allocator for this purpose. If the buffer does not need to be deallocated, or if you want to assume responsibility for deallocating the buffer (and not have the CFString object deallocate it), pass kCFAllocatorNull.

Return Value

An immutable string containing cStr (after stripping off the NULL terminating character), or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

A C string is a string of 8-bit characters terminated with an 8-bit NULL. Unichar and Unichar32 are not considered C strings.

Unless the situation warrants otherwise, the created object does not copy the external buffer to internal storage but instead uses the buffer as its backing store. However, you should never assume that the object is using the external buffer since the object might copy the buffer to internal storage or even dump the buffer altogether and store the characters in another way.

The function includes a contentsDeallocator parameter with which to specify an allocator to use for deallocating the external buffer when the CFString object is deallocated. If you want to assume responsibility for deallocating this memory, specify kCFAllocatorNull for this parameter.

If at creation time the CFString object decides it can't use the buffer, and the function specifies a contentsDeallocator allocator, it will use this allocator to free the buffer at that time.

Special Considerations

If an error occurs during the creation of the string, then cStr is not deallocated. In this case, the caller is responsible for freeing the buffer. This allows the caller to continue trying to create a string with the buffer, without having the buffer deallocated.

Availability
See Also
Declared In
CFString.h

CFStringCreateWithFileSystemRepresentation

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

CFStringRef CFStringCreateWithFileSystemRepresentation (
   CFAllocatorRef alloc,
   const char *buffer
);

Parameters
alloc

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

buffer

The C string that you want to convert.

Return Value

A string that represents buffer. The result is NULL if there was a problem in creating the string (possible if the conversion fails due to bytes in the buffer not being a valid sequence of bytes for the appropriate character encoding). Ownership follows the Create Rule.

Availability
Declared In
CFString.h

CFStringCreateWithFormat

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

CFStringRef CFStringCreateWithFormat (
   CFAllocatorRef alloc,
   CFDictionaryRef formatOptions,
   CFStringRef format,
   ...
);

Parameters
alloc

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

formatOptions

A CFDictionary object containing formatting options for the string (such as the thousand-separator character, which is dependent on locale). Currently, these options are an unimplemented feature.

format

The formatted string with printf-style specifiers. For information on supported specifiers, see String Format Specifiers.

...

Variable list of the values to be inserted in format.

Return Value

An immutable string, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Availability
Declared In
CFString.h

CFStringCreateWithFormatAndArguments

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

CFStringRef CFStringCreateWithFormatAndArguments (
   CFAllocatorRef alloc,
   CFDictionaryRef formatOptions,
   CFStringRef format,
   va_list arguments
);

Parameters
alloc

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

formatOptions

A CFDictionary object containing formatting options for the string (such as the thousand-separator character, which is dependent on locale). Currently, these options are an unimplemented feature.

format

The formatted string with printf-style specifiers. For information on supported specifiers, see String Format Specifiers.

arguments

The variable argument list of values to be inserted into the formatted string contained in format.

Return Value

An immutable string, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

The programming interface for variable argument lists (va_list, va_start, va_end, and so forth) is declared in the standard C header file stdarg.h.

Availability
Declared In
CFString.h

CFStringCreateWithPascalString

Creates an immutable CFString object from a Pascal string.

CFStringRef CFStringCreateWithPascalString (
   CFAllocatorRef alloc,
   ConstStr255Param pStr,
   CFStringEncoding encoding
);

Parameters
alloc

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

pStr

The Pascal string to be used to create the string.

encoding

The encoding of the characters in the Pascal string.

Return Value

An immutable string containing pStr, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

This function creates an immutable CFString objects from the character contents of a Pascal string (after stripping off the initial length byte).

Availability
Declared In
CFString.h

CFStringCreateWithPascalStringNoCopy

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

CFStringRef CFStringCreateWithPascalStringNoCopy (
   CFAllocatorRef alloc,
   ConstStr255Param pStr,
   CFStringEncoding encoding,
   CFAllocatorRef contentsDeallocator
);

Parameters
alloc

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

pStr

The Pascal string to be used to create the string.

encoding

The encoding of the characters in the Pascal string.

contentsDeallocator

The CFAllocator object to use to deallocate the external string buffer when it is no longer needed. Pass NULL or kCFAllocatorDefault to request the default allocator for this purpose. If the buffer does not need to be deallocated, or if you want to assume responsibility for deallocating the buffer (and not have the string deallocate it), pass kCFAllocatorNull.

Return Value

An immutable string containing pStr, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Discussion

This function creates an immutable CFString objects from the character contents of a Pascal string (after stripping off the initial length byte).

Unless the situation warrants otherwise, the created object does not copy the external buffer to internal storage but instead uses the buffer as its backing store. However, you should never assume that the object is using the external buffer since the object might copy the buffer to internal storage or even dump the buffer altogether and store the characters in another way.

The function includes a contentsDeallocator parameter with which to specify an allocator to use for deallocating the external buffer when the string is deallocated. If you want to assume responsibility for deallocating this memory, specify kCFAllocatorNull for this parameter.

If at creation time the string decides it can't use the buffer, and there is an allocator specified in the contentsDeallocator parameter, it will use this allocator to free the buffer at that time.

Special Considerations

If an error occurs during the creation of the string, then pStr is not deallocated. In this case, the caller is responsible for freeing the buffer. This allows the caller to continue trying to create a string with the buffer, without having the buffer deallocated.

Availability
See Also
Declared In
CFString.h

CFStringCreateWithSubstring

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

CFStringRef CFStringCreateWithSubstring (
   CFAllocatorRef alloc,
   CFStringRef str,
   CFRange range
);

Parameters
alloc

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

str

The string from which to create the new string.

range

The range of characters in str to copy. The specified range must not exceed the length of the string.

Return Value

An immutable string, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

Availability
Declared In
CFString.h

CFStringFind

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

CFRange CFStringFind (
   CFStringRef theString,
   CFStringRef stringToFind,
   CFOptionFlags compareOptions
);

Parameters
theString

The string in which to search for stringToFind.

stringToFind

The string to search for in theString.

compareOptions

Flags that select different types of comparisons, such as localized comparison, case-insensitive comparison, and non-literal comparison. If you want the default comparison behavior, pass 0. See “String Comparison Flags” for the available flags.

Return Value

The range of the located substring within theString. If a match is not located, the returned CFRange structure will have a location of kCFNotFound and a length of 0 (either of which is enough to indicate failure).

Discussion

This function is a convenience when you want to know if the entire range of characters represented by a string contains a particular substring. If you want to search only part of the characters of a string, use the CFStringFindWithOptions function. Both of these functions return upon finding the first occurrence of the substring, so if you want to find out about multiple occurrences, call the CFStringCreateArrayWithFindResults function.

Depending on the comparison-option flags specified, the length of the resulting range might be different than the length of the search string.

Availability
Declared In
CFString.h

CFStringFindCharacterFromSet