iOS Developer Library

Developer

Core Foundation Framework Reference CFMutableAttributedString Reference

Options
Deployment Target:

On This Page
Language:

CFMutableAttributedString Reference

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 and NSAttributedString UIKit Additions Reference on iOS.

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

Data Types

  • A reference to a CFMutableAttributedString object.

    Declaration

    Swift

    class CFMutableAttributedString { }

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.