CFMutableAttributedString Reference

Derived from
Framework
CoreFoundation/CoreFoundation.h
Declared in
CFAttributedString.h
Companion guides

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 AppKit 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

Modifying a CFMutableAttributedString

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 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 new attributed string. The string starts empty and can grow to this length (it can be shorter).

Pass 0 to specify that the maximum length is not limited. The value must not be negative.

Return Value

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

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
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 new attributed string. The string starts empty and can grow to this length (it can be shorter).

Pass 0 to specify that the maximum length is not limited. If non-0, maxLength must be greater than or equal to the length of aStr.

aStr

The attributed string to copy.

Return Value

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

Availability
  • Available in 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 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 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 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 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 OS X v10.4 and later.
Related Sample Code
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 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 OS X v10.4 and later.
Related Sample Code
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 OS X v10.4 and later.
Declared In
CFAttributedString.h