CFStringCreateByCombiningStringsHeader: CFString.h

Creates a single CFString object from the individual CFString objects that comprise the elements of a CFArray object.

CFStringRef CFStringCreateByCombiningStrings (
    CFAllocatorRef alloc, 
    CFArrayRef theArray, 
    CFStringRef separatorString
);
alloc

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

theArray

Pass a reference to a CFArray object whose elements are CFString objects whose characters you want to concatenate in the created CFString object. If the array is empty an empty CFString object is returned; if the array has one CFString element, that object is returned (without separator character). The array should not be NULL.

separatorString

Pass a reference to a CFString object that contains the character or characters to insert between the substrings in the created CFString object. If the reference is not to a valid Core Foundation object, an assertion is raised.

function result

A reference to a CFString object that contains a concatenation of the the strings in the array along with the separator strings. The result is NULL if there was a problem in creating the CFString object.

DISCUSSION

The CFStringCreateByCombiningStrings function creates a single CFString object from the CFString elements of an array. The string represented by the created object is a concatenation of the strings represented in the CFArray object; the separator string (specified in separatorString) is inserted between each substring. The separator string is commonly characters such as tabs and newlines (carriage returns). The order of elements in the array is identical to the order of the substrings in the source CFString object.

The CFStringCreateArrayBySeparatingStrings function is complementary in that it creates a CFArray object whose elements are substrings in a separator-string delimited CFString object.


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