CFStringCreateMutableWithExternalCharactersNoCopyHeader: CFString.h

Creates a mutable CFString object whose Unicode character buffer is controlled externally.

CFMutableStringRef CFStringCreateMutableWithExternalCharactersNoCopy (
    CFAllocatorRef alloc, 
    UniChar *chars, 
    CFIndex numChars, 
    CFIndex capacity, 
    CFAllocatorRef externalCharactersAllocator
);
alloc

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

chars

Pass a pointer to a Unicode character buffer. Before calling, create this buffer on the stack or heap and optionally initialize it with Unicode character data. Upon return, the created CFString object keeps its own copy of the pointer to this buffer. You may pass in NULL if there is no initial buffer being provided.

numChars

Pass an integer specifying the number of characters initially in the Unicode buffer pointed to by chars.

capacity

Pass an integer that specifies the capacity of the external buffer (chars); that is, the maximum number of Unicode characters that can be stored. This value should be zero if no initial buffer is being provided.

externalCharactersAllocator

Pass a reference to an allocator object to be used for reallocating the external buffer when editing takes place and for deallocating the buffer when the CFString object is deallocated. If the default allocator is suitable for these purposes, pass NULL. If you do not want the created CFString object to reallocate or deallocate memory for the buffer (that is, you assume responsibility for these things yourself), pass kCFAllocatorNull.

function result

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

DISCUSSION

The CFStringCreateMutableWithExternalCharactersNoCopy function permits you to create a mutable CFString object whose backing store is an external Unicode character buffer—that is, a buffer that you control (or can control) entirely. This function allows you to take advantage of the features of String Services, particularly the mutability functions that add and modify character data. But at the same time you can directly add, delete, modify, and examine the characters in the buffer. You can even replace the buffer entirely. If, however, you directly modify or replace the character buffer, you should inform the CFString object of this change with the CFStringSetExternalCharactersNoCopy function.

If you mutate the character contents with the CFString functions, and the buffer needs to be enlarged, the CFString object calsl the allocation callbacks specified for the allocator externalCharactersAllocator.

This function should be used in special circumstances where you want to create a CFString wrapper around an existing, potentially large UniChar buffer you own. Using this function causes the CFString object to forgo some of its internal optimizations, so it should be avoided in general use. That is, if you want to create a CFString object from a small UniChar buffer, and you don't need to continue owning the buffer, use one of the other creation functions (for instance CFStringCreateWithCharacters) instead.


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