---

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.

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 Cocoa 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 Interchangeable Data 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

• CFAttributedStringCreateMutableCopy
• CFAttributedStringCreateMutable

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
);

Parameters

str

A mutable attributed string that is to be edited.

Discussion

Defers internal consistency-checking and coalescing for a mutable attributed string. You must balance a call to this function with a corresponding CFAttributedStringEndEditing.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

CFAttributedStringCreateMutable

Creates a mutable attributed string.

CFMutableAttributedStringRef CFAttributedStringCreateMutable (
   CFAllocatorRef alloc,
   CFIndex maxLength
);

Parameters

alloc

An allocator to be used to allocate memory for the new attributed string. Pass NULL or kCFAllocatorDefault to use the current default allocator.

maxLength

The limit on the length of the returned attributed string; exceeding this size during any subsequent editing operation is a programming error. Pass 0 to specify no limit.

Return Value

A new mutable attributed string. Ownership follows the Create Rule.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

CFAttributedStringCreateMutableCopy

Creates a mutable copy of an attributed string.

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

Parameters

alloc

The allocator to be used to allocate memory for the new attributed string. Pass NULL or kCFAllocatorDefault to use the current default allocator.

maxLength

The limit on the length of the returned attributed string; exceeding this size during any subsequent editing operation is a programming error. Pass 0 to specify no limit.

aStr

The attributed string to copy.

Return Value

A mutable copy of aStr. Ownership follows the Create Rule.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

CFAttributedStringEndEditing

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

void CFAttributedStringEndEditing (
   CFMutableAttributedStringRef aStr
);

Parameters

str

A mutable attributed string, following a call to CFAttributedStringBeginEditing.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

CFAttributedStringGetMutableString

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

CFMutableStringRef CFAttributedStringGetMutableString (
   CFMutableAttributedStringRef aStr
);

Parameters

str

The mutable attributed string from which to retrieve the string.

Return Value

The string for the specified attributed string as a mutable string.

Discussion

This function allows you to edit the character contents of the attributed string as if it were a CFMutableString. Attributes corresponding to the edited range are appropriately modified. If, as a result of the edit, new characters are introduced into the string, they inherit the attributes of the first replaced character from range. If no existing characters are replaced by the edit, the new characters inherit the attributes of the character preceding range if it has any, otherwise of the character following range. If the initial string is empty, the attributes for the new characters are also empty.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

CFAttributedStringRemoveAttribute

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

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

Parameters

str

The mutable attributed string to modify.

range

The range of aStr from which to remove the specified attribute. range must not exceed the bounds of aStr.

attrName

The name of the attribute to remove.

Discussion

It is not an error of the specified attribute does not exist over the given range.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

CFAttributedStringReplaceAttributedString

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

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

Parameters

aStr

The mutable attributed string to modify.

range

The range of aStr to be modified. range must not specify characters outside the bounds of aStr.

replacement

The attributed string to replace the contents of aStr in range.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

CFAttributedStringReplaceString

Modifies the string of an attributed string.

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

Parameters

aStr

The mutable attributed string to modify.

range

The range of aStr to be modified. range must not specify characters outside the bounds of aStr.

replacement

The string to replace the existing string in range.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

CFAttributedStringSetAttribute

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

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

Parameters

aStr

The mutable attributed string to modify.

range

The range of aStr over to which the new attributes apply. range must not exceed the bounds of aStr.

attrName

The name of the attribute whose value to set.

value

The value of the attribute attrName to apply over range. This value may not be NULL. If you want to remove an attribute, use CFAttributedStringRemoveAttribute.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

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
);

Parameters

aStr

The mutable attributed string to modify.

range

The range of aStr over to which the new attributes apply. range must not exceed the bounds of aStr.

replacement

A dictionary that contains key-value pairs that specify the new attributes to apply to range. The keys must be CFString objects, and the corresponding values must be CFType objects.

clearOtherAttributes

If false, existing attributes (that aren’t being replaced) are left alone; otherwise they are cleared.

Discussion

Note that after this call, if it is mutable, changes to replacement will not affect the contents of the attributed string.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

Data Types

CFMutableAttributedStringRef

A reference to a CFMutableAttributedString object.

typedef struct __CFAttributedString *CFMutableAttributedStringRef;

Discussion

The CFMutableAttributedStringRef type refers to a mutable object that combines a CFString object with a collection of attributes that specify how the characters in the string should be displayed. CFMutableAttributedString is an opaque type that defines the characteristics and behavior of CFMutableAttributedString objects.

CFMutableAttributedString objects also respond to all functions intended for immutable CFAttributedString objects.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CFAttributedString.h

---