CFStringCreateMutableCopy

Header: CFString.h Carbon status: Supported

Creates a copy of a CFString object that can be modified.

CFMutableStringRef CFStringCreateMutableCopy (
    CFAllocatorRef alloc, 
    CFIndex maxLength, 
    CFStringRef theString
);
Parameter descriptions
alloc

Pass a reference to an allocator used for creating the object or pass NULL to request the default allocator.

maxLength

Pass an integer of type CFIndex to specify the maximum number of Unicode characters that can be stored by this mutable object. Pass zero if there should be no character limit. Note that initially the string still has the same length as the string argument; this parameter simply specifies what the maximum size is. CFString might try to optimize its internal storage by paying attention to this value.

theString

Pass a reference to the CFString object that is to be copied.

function result

A reference to a mutable CFString object that has the same contents as the original object. Returns NULL if there was a problem copying the object.

DISCUSSION

The CFStringCreateMutableCopy function creates a mutable CFString object from another mutable or immutable CFString object. The mutable object is identical to the original object except for (perhaps) the mutability attribute. You can add character data to this object with any of the CFStringAppend... functions, and you can insert, delete, replace, pad, and trim characters with the appropriate CFString functions. If the maxLength parameter is greater than zero, any attempt to add characters beyond this limit results in a run-time error.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later.


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