CFStringCreateWithCStringNoCopyHeader: CFString.h

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
);
alloc

Pass a reference to an allocator to be used to create the CFString object or pass NULL to request the default allocator.

cStr

Pass a pointer to a NULL-terminated C string to be used to create the CFString object.

encoding

Pass an enum constant of type CFStringEncoding that specifes the encoding of the characters in the C string.

contentsDeallocator

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

function result

A reference to an immutable CFString object or NULL if there was a problem creating the object.

DISCUSSION

The CFStringCreateWithCStringNoCopy function creates an immutable CFString objects from the character contents of a C string (after stripping off the NULL terminating character).

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.


© 1999 Apple Computer, Inc. — (Last Updated 9/15/99)