CFStringCreateCopy |
||||
Header: | CFString.h | Carbon status: | Supported | |
Creates a copy of a CFString object.
CFStringRef CFStringCreateCopy ( CFAllocatorRef alloc, CFStringRef theString );
Pass a reference to an allocator object or pass NULL to request the default allocator.
Pass a reference to the CFString object to be copied.
A reference to a CFString object whose contents are identical to the original except that it is immutable (if the original was mutable). The result is NULL if there was a problem copying the object.
The CFStringCreateCopy function creates a copy of a CFString object. 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. To the caller, however, the resulting object is a true immutable copy, except the operation was a lot more efficient.
You should use the CFStringCreateCopy function when you pass a CFString into a function and the function needs to hold on to that object's value (and not that particular "instance" of the object). The CFStringCreateCopy function assures that a true, immutable copy is made for that function's own use as efficiently as possible.
Supported in Carbon. Available in Carbon 1.0.2 and later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)