CFMutableAttributedString Reference

Overview

Instances of CFMutableAttributedString manage mutable character strings and associated sets of attributes (for example, font and kerning information) that apply to individual characters or ranges of characters in the string. CFAttributedString as defined in CoreFoundation provides the basic container functionality, while higher levels provide definitions for standard attributes, their values, and additional behaviors involving these. CFMutableAttributedString represents a mutable string—use CFAttributedString to create and manage an attributed string that cannot be changed after it has been created.

CFMutableAttributedString is not a “subclass” of CFMutableString; that is, it does not respond to CFMutableString (or CFString) function calls. CFAttributedString conceptually contains a CFMutableString to which it applies attributes. This protects you from ambiguities caused by the semantic differences between simple and attributed string. Functions defined for CFAttributedString can be applied to a CFMutableAttributedString object.

Attributes are identified by key/value pairs stored in CFDictionary objects. Keys must be CFString objects, while the corresponding values are CFType objects of an appropriate type. See the attribute constants in NSAttributedString Application Kit Additions Reference for standard attribute names on OS X.

When you modify the contents of a mutable attributed string, it may have to do a lot of work to ensure it is internally consistent, and to coalesce runs of identical attributes. You can call CFAttributedStringBeginEditing and CFAttributedStringEndEditing around a set of related mutation calls that don’t require the string to be in consistent state in between, and thereby reduce the amount of work necessary. These calls can be nested.

CFMutableAttributedString is “toll-free bridged” with its Foundation counterpart, NSMutableAttributedString. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSMutableAttributedString * parameter, you can pass in an object of type CFMutableAttributedStringRef, and in a function where you see a CFMutableAttributedStringRef parameter, you can pass in an NSMutableAttributedString instance. See “Toll-Free Bridged Types” for more information on toll-free bridging.

There is not always a 1:1 mapping between NSMutableAttributedString’s methods and CFMutableAttributedString's functions. For example, to perform an operation equivalent to NSMutableAttributedString’s appendAttributedString: method on a CFMutableAttributedString object, you can use CFAttributedStringReplaceAttributedString and specify CFRangeMake(CFAttributedStringGetLength(attrStr), 0) as the range. Alternatively you can cast the CFMutableAttributedString object to an NSMutableAttributedString object and send the appendAttributedString: message.

Functions by Task

Creating a CFMutableAttributedString

• CFAttributedStringCreateMutable
• CFAttributedStringCreateMutableCopy

Modifying a CFMutableAttributedString

• CFAttributedStringBeginEditing
• CFAttributedStringEndEditing
• CFAttributedStringGetMutableString
• CFAttributedStringRemoveAttribute
• CFAttributedStringReplaceString
• CFAttributedStringReplaceAttributedString
• CFAttributedStringSetAttribute
• CFAttributedStringSetAttributes

Functions

CFAttributedStringBeginEditing

Defers internal consistency-checking and coalescing for a mutable attributed string.

void CFAttributedStringBeginEditing (
   CFMutableAttributedStringRef aStr
);

CFAttributedStringCreateMutable

Creates a mutable attributed string.

CFMutableAttributedStringRef CFAttributedStringCreateMutable (
   CFAllocatorRef alloc,
   CFIndex maxLength
);

CFAttributedStringCreateMutableCopy

Creates a mutable copy of an attributed string.

CFMutableAttributedStringRef CFAttributedStringCreateMutableCopy (
   CFAllocatorRef alloc,
   CFIndex maxLength,
   CFAttributedStringRef aStr
);

CFAttributedStringEndEditing

Re-enables internal consistency-checking and coalescing for a mutable attributed string.

void CFAttributedStringEndEditing (
   CFMutableAttributedStringRef aStr
);

CFAttributedStringGetMutableString

Gets as a mutable string the string for an attributed string.

CFMutableStringRef CFAttributedStringGetMutableString (
   CFMutableAttributedStringRef aStr
);

CFAttributedStringRemoveAttribute

Removes the value of a single attribute over a specified range.

void CFAttributedStringRemoveAttribute (
   CFMutableAttributedStringRef aStr,
   CFRange range,
   CFStringRef attrName
);

CFAttributedStringReplaceAttributedString

Replaces the attributed substring over a range with another attributed string.

void CFAttributedStringReplaceAttributedString (
   CFMutableAttributedStringRef aStr,
   CFRange range,
   CFAttributedStringRef replacement
);

CFAttributedStringReplaceString

Modifies the string of an attributed string.

void CFAttributedStringReplaceString (
   CFMutableAttributedStringRef aStr,
   CFRange range,
   CFStringRef replacement
);

CFAttributedStringSetAttribute

Sets the value of a single attribute over the specified range.

void CFAttributedStringSetAttribute (
   CFMutableAttributedStringRef aStr,
   CFRange range,
   CFStringRef attrName,
   CFTypeRef value
);

CFAttributedStringSetAttributes

Sets the value of attributes of a mutable attributed string over a specified range.

void CFAttributedStringSetAttributes (
   CFMutableAttributedStringRef aStr,
   CFRange range,
   CFDictionaryRef replacement,
   Boolean clearOtherAttributes
);

Data Types

CFMutableAttributedStringRef

A reference to a CFMutableAttributedString object.

typedef struct __CFAttributedString *CFMutableAttributedStringRef;