Function

CFStringCreateWithCharacters

Creates a string from a buffer of Unicode characters.

Declaration

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 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.

See Also

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.

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.