< Previous PageNext Page >

Hide TOC

Manipulating Mutable String Objects

You can choose from a variety of string object functions to add to and modify the contents of mutable CFString objects. These functions, as one might expect, do not work on immutable CFString objects. If you want to change the contents of a CFString object, you must either start with a content-less mutable CFString object or make a mutable copy of an immutable CFString object. See “Creating Mutable String Objects” for information on creating objects of this kind.

Forms of Mutation

The functions that manipulate mutable CFString objects fall into several categories, described in the following sections.

Appending

You can append strings in a variety of formats to a mutable CFString object: other CFString objects (CFStringAppend), C and Pascal strings (CFStringAppendCString and CFStringAppendPascalString), Unicode characters (CFStringAppendCharacters), and formatted strings (CFStringAppendFormat and CFStringAppendFormatAndArguments).

Inserting, deleting, replacing

The functions CFStringInsert, CFStringDelete, and CFStringReplace perform the corresponding operations. These functions require you to specify a zero-based index into, or range of, the string to be modified.

Padding and trimming

The CFStringPad function extends or truncates a mutable CFString to a given length; if it extends the string, it pads with a specified character or characters. The CFStringTrim function trims a specific character from both sides of the string. For example, the call:

CFStringTrim(CFStringCreateMutableCopy(NULL, NULL, CFSTR("xxxabcx")), CFSTR("x"));

would result in the string “abc”. A related function, CFStringTrimWhitespace, does the same thing with whitespace characters, which include such characters as tabs and carriage returns.

Case operations

Three functions modify the case of a mutable string, making it all uppercase (CFStringUppercase), all lowercase (CFStringLowercase), or just the first character of each word in a string uppercase (CFStringCapitalize).

Code Examples

Listing 1 exemplifies several of the functions that manipulate mutable CFString objects:

Listing 1 Various operations on a mutable string

void mutableStringOperations() {

    CFMutableStringRef mstr;

    CFRange range;

    StringPtr pbuf;

    CFIndex length;

    mstr = CFStringCreateMutable(NULL, 0);

    CFStringAppend(mstr, CFSTR("Now is the time for all good men to come to the aid of their "));

    CFStringAppend(mstr, CFSTR("party."));

    CFShow(CFSTR("Mutable String 1 - Appended CFStrings"));

    CFShow(mstr);

    range = CFStringFind(mstr, CFSTR("good"), 0);

    if (range.length > 0) {

        CFStringReplace(mstr, range, CFSTR("bad"));

        CFShow(CFSTR("Mutable String 2 - Replaced substring"));

        CFShow(mstr);

    CFStringAppendPascalString(mstr, "\p Now is the time for a party.",

        kCFStringEncodingMacRoman);

    CFStringDelete(mstr, CFRangeMake(10, 20));

    CFShow(CFSTR("Mutable String 3 - Pascal string added, characters in middle deleted:"));

    CFShow(mstr);

    CFStringUppercase(mstr, NULL);

    CFShow(CFSTR("Mutable String 4 - Convert to uppercase:"));

    CFShow(mstr);

When compiled and run, this code generates the following output:

Mutable String 1 - Appended CFStrings

Now is the time for all good men to come to the aid of their party.

Mutable String 2 - Replaced substring

Now is the time for all bad men to come to the aid of their party.

Mutable String 3 - Pascal string added, characters in middle deleted:

Now is then to come to the aid of their party. Now is the time for a party.

Mutable String 4 - Convert to uppercase:

NOW IS THEN TO COME TO THE AID OF THEIR PARTY. NOW IS THE TIME FOR A PARTY.