CFStringCreateArrayBySeparatingStringsHeader: CFString.h

Creates an array of CFString objects from a single CFString object.

CFArrayRef CFStringCreateArrayBySeparatingStrings (
    CFAllocatorRef alloc, 
    CFStringRef theString, 
    CFStringRef separatorString
);
alloc

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

theString

Pass a reference to the CFString object containing the substrings which are to become the CFString elements of the created array. The substrings should be separated by one or more delimiter characters (separatorString).

separatorString

Pass a reference to a CFString object containing the character or characters used to separate the substrings in theString. Whitespace characters such as tabs and newlines (carriage returns) are commonly used as separator strings.

function result

A reference to a CFArray object that contains CFString objects that represent substrings of the original CFString object. The result is NULL if there was a problem creating the object.

DISCUSSION

The CFStringCreateArrayBySeparatingStrings function creates an array containing CFString objects, each of which represents a substring of some source CFString object. The function is a convenience for converting units of data captured in a single string to a form (that is, an array) suitable for iterative processing. One or more delimiter characters (or "separator string") separates the substrings in the source string; these characters can be such things 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.

For example, might have a localized list of place names with each name separated by a tab character. You could create a CFString object from this list and call the CFStringCreateArrayBySeparatingStrings function on the object to obtain a CFArray object whose elements are these place names.

If the separator string does not occur in the string, the result is a CFArray containing the original string. If the separator string is the same as the string, then the result is a CFArray containing two empty strings.

The CFStringCreateByCombiningStrings function is complementary in that it creates a single CFString object from a CFArray object whose elements are CFString objects.


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