CFStringCreateWithCharactersNoCopy

Header: CFString.h Carbon status: Supported

Creates a CFString object 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
);
Parameter descriptions
alloc

Pass a reference to an allocator object to use to create the object or pass NULL to request the default allocator.

chars

Pass a pointer to a Unicode buffer that you have allocated and initialized with Unicode characters.

numChars

Pass an integer specifying the number of characters in the buffer pointed to by chars. Only this number of characters will be copied to internal storage.

contentsDeallocator

Pass a reference to the allocator to use to deallocate the external 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 CFStringCreateWithCharactersNoCopy function creates an immutable CFString object from a buffer of Unicode characters. 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 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 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 decides it can't use the buffer, and there is a contentsDeallocator, it will use this allocator to free the buffer at that time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later.


© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)