CFStringPadHeader: CFString.h

Enlarges the string represented by a CFString object, padding it with specified characters, or truncates the string.

void CFStringPad (
    CFMutableStringRef theString, 
    CFStringRef padString, 
    CFIndex length, 
    CFIndex indexIntoPad
);
theString

Pass a reference to a mutable CFString object to be padded or truncated. The function raises an assertion if the referenced CFString object is not mutable

padString

Pass a reference to the CFString object containing the characters to fill the extended character buffer with. If you are truncating the string represented by the object, this parameter is ignored (pass NULL).

length

Pass an integer specifying the new length of the string represented by the mutable CFString object (theString). If this length is greater than the current length, padding takes place; if it is lesser, truncation takes place.

indexIntoPad

Pass an integer specifying the index of the character in the pad string (padString) to begin padding with. If you are truncating the string represented by the object, this parameter is ignored.

DISCUSSION

The CFStringPad function has two purposes. It either enlarges the character buffer of a mutable CFString object to a given length, padding the added length with a given character or characters, or it truncates the character buffer to a smaller size. The key parameter for this behavior is the length parameter; if it is greater than the current length of the represented string, padding takes place, and if it less than that length, truncation occurs.

For example, say you have a mutable CFString (aMutStr) containing the characters "abcdef". The call

CFStringPad(aMutStr,  CFSTR(". "), 12, 1);

results in aMutStr containing "abcdef . . .". However, the following call

CFStringPad(aMutStr,  NULL, 3, 0);

results in aMutStr containing "abc".


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