Creates a CFString object from an external C string buffer that might serve as the backing store for the object.
- iOS 2.0+
- macOS 10.0+
- Mac Catalyst 13.0+Beta
- tvOS 9.0+
- watchOS 2.0+
- Core Foundation
The allocator to use to allocate memory for the new string. Pass
kto use the current default allocator.
NULL-terminated C string to be used to create the CFString object. The string must use an 8-bit encoding.
The encoding of the characters in the C string. The encoding must specify an 8-bit encoding.
The CFAllocator object to use to deallocate the external string buffer when it is no longer needed. You can pass
kto 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
An immutable string containing
c (after stripping off the
NULL terminating character), or
NULL if there was a problem creating the object. Ownership follows the The Create Rule.
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
contents 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
k for this parameter.
If at creation time the CFString object decides it can't use the buffer, and the function specifies a
contents allocator, it will use this allocator to free the buffer at that time.
If an error occurs during the creation of the string, then
c 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.