iOS Developer Library

Developer

CoreFoundation Framework Reference CFAttributedString Reference

Options
Deployment Target:

On This Page
Language:

CFAttributedString Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreFoundation

Objective-C

@import CoreFoundation;

Instances of CFAttributedString manage 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 Core Foundation provides the basic container functionality, while higher levels provide definitions for standard attributes, their values, and additional behaviors involving these. CFAttributedString represents an immutable string—use CFMutableAttributedStringRef to create and manage an attributed string that can be changed after it has been created.

CFAttributedString is not a “subclass” of CFString; that is, it does not respond to CFString function calls. CFAttributedString conceptually contains a CFString to which it applies attributes. This protects you from ambiguities caused by the semantic differences between simple and attributed string.

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 or NSAttributedString UIKit Additions Reference for standard attribute names.

CFAttributedString is “toll-free bridged” with its Foundation counterpart, NSAttributedString. 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 NSAttributedString * parameter, you can pass in a CFAttributedStringRef, and in a function where you see a CFAttributedStringRef parameter, you can pass in an NSAttributedString instance. This also applies to concrete subclasses of NSAttributedString. See Toll-Free Bridged Types for more information on toll-free bridging.

Functions

  • Creates an attributed string with specified string and attributes.

    Declaration

    Swift

    func CFAttributedStringCreate(_ alloc: CFAllocator!, _ str: CFString!, _ attributes: CFDictionary!) -> CFAttributedString!

    Objective-C

    CFAttributedStringRef CFAttributedStringCreate ( CFAllocatorRef alloc, CFStringRef str, CFDictionaryRef attributes );

    Parameters

    alloc

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

    str

    A string that specifies the characters to use in the new attributed string. This value is copied.

    attributes

    A dictionary that contains the attributes to apply to the new attributed string. This value is copied.

    Return Value

    An attributed string that contains the characters from str and the attributes specified by attributes. The result is NULL if there was a problem in creating the attributed string. Ownership follows the Create Rule.

    Discussion

    Note that both the string and the attributes dictionary are copied. The specified attributes are applied to the whole string. If you want to apply different attributes to different ranges of the string, you should use a mutable attributed string.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Creates an immutable copy of an attributed string.

    Declaration

    Swift

    func CFAttributedStringCreateCopy(_ alloc: CFAllocator!, _ aStr: CFAttributedString!) -> CFAttributedString!

    Objective-C

    CFAttributedStringRef CFAttributedStringCreateCopy ( CFAllocatorRef alloc, CFAttributedStringRef aStr );

    Parameters

    alloc

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

    aStr

    The attributed string to copy.

    Return Value

    An immutable attributed string with characters and attributes identical to those of aStr. Returns NULL if there was a problem copying the object. Ownership follows the Create Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Creates a sub-attributed string from the specified range.

    Declaration

    Swift

    func CFAttributedStringCreateWithSubstring(_ alloc: CFAllocator!, _ theString: CFAttributedString!, _ range: CFRange) -> CFAttributedString!

    Objective-C

    CFAttributedStringRef CFAttributedStringCreateWithSubstring ( CFAllocatorRef alloc, CFAttributedStringRef aStr, CFRange range );

    Parameters

    alloc

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

    theString

    The attributed string to copy.

    range

    The range of the attributed string to copy. range must not exceed the bounds of aStr.

    Return Value

    A new attributed string whose string and attributes are copied from the specified range of the supplied attributed string. Returns NULL if there was a problem copying the object. Ownership follows the Create Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the length of the attributed string in characters.

    Declaration

    Swift

    func CFAttributedStringGetLength(_ str: CFAttributedString!) -> CFIndex

    Objective-C

    CFIndex CFAttributedStringGetLength ( CFAttributedStringRef aStr );

    Parameters

    str

    The attributed string to examine.

    Return Value

    The length of the attributed string in characters; this is the same as CFStringGetLength(CFAttributedStringGetString(aStr)).

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the string for an attributed string.

    Declaration

    Swift

    func CFAttributedStringGetString(_ aStr: CFAttributedString!) -> CFString!

    Objective-C

    CFStringRef CFAttributedStringGetString ( CFAttributedStringRef aStr );

    Parameters

    aStr

    The attributed string to examine.

    Return Value

    An immutable string containing the characters from aStr, or NULL if there was a problem creating the object. Ownership follows the Get Rule.

    Discussion

    For performance reasons, the string returned will often be the backing store of the attributed string, and it might therefore change if the attributed string is edited. However, this is an implementation detail, and you should not rely on this behavior.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value of a given attribute of an attributed string at a specified location.

    Declaration

    Swift

    func CFAttributedStringGetAttribute(_ str: CFAttributedString!, _ loc: CFIndex, _ attrName: CFString!, _ effectiveRange: UnsafeMutablePointer<CFRange>) -> AnyObject!

    Objective-C

    CFTypeRef CFAttributedStringGetAttribute ( CFAttributedStringRef aStr, CFIndex loc, CFStringRef attrName, CFRange *effectiveRange );

    Parameters

    str

    The attributed string to examine.

    loc

    The location in str at which to determine the attributes. loc must not exceed the bounds of str.

    attrName

    The name of the attribute whose value you want to determine.

    effectiveRange

    If not NULL, upon return contains a range including loc over which exactly the same set of attributes apply as at loc.

    Return Value

    The value of the specified attribute at the specified location in str. Ownership follows the Get Rule.

    Discussion

    For performance reasons, a range returned in effectiveRange is not necessarily the maximal range. If you need the maximum range, you should use CFAttributedStringGetAttributeAndLongestEffectiveRange.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the attributes of an attributed string at a specified location.

    Declaration

    Swift

    func CFAttributedStringGetAttributes(_ str: CFAttributedString!, _ loc: CFIndex, _ effectiveRange: UnsafeMutablePointer<CFRange>) -> CFDictionary!

    Objective-C

    CFDictionaryRef CFAttributedStringGetAttributes ( CFAttributedStringRef aStr, CFIndex loc, CFRange *effectiveRange );

    Parameters

    str

    The attributed string to examine.

    loc

    The location in str at which to determine the attributes. loc must not exceed the bounds of str.

    effectiveRange

    If not NULL, upon return contains a range including loc over which exactly the same set of attributes apply as at loc.

    Return Value

    A dictionary that contains the attributes of str at the specified location. Ownership follows the Get Rule.

    Discussion

    For performance reasons, a range returned in effectiveRange is not necessarily the maximal range. If you need the maximum range, you should use CFAttributedStringGetAttributesAndLongestEffectiveRange.

    Note that the returned attribute dictionary might change in unpredictable ways if the attributed string is edited after this call. If you want to preserve the state of the dictionary, you should make an actual copy of it rather than just retaining it. In addition, you should make no assumptions about the relationship of the actual dictionary returned by this call and the dictionary originally used to set the attributes, other than the fact that the values stored in the dictionaries will be identical (that is, ==) to those originally specified.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the value of a given attribute of an attributed string at a specified location.

    Declaration

    Swift

    func CFAttributedStringGetAttributeAndLongestEffectiveRange(_ str: CFAttributedString!, _ loc: CFIndex, _ attrName: CFString!, _ inRange: CFRange, _ effectiveRange: UnsafeMutablePointer<CFRange>) -> AnyObject!

    Objective-C

    CFTypeRef CFAttributedStringGetAttributeAndLongestEffectiveRange ( CFAttributedStringRef aStr, CFIndex loc, CFStringRef attrName, CFRange inRange, CFRange *longestEffectiveRange );

    Parameters

    str

    The attributed string to examine.

    loc

    The location in str at which to determine the attributes. It is a programming error for loc to specify a location outside the bounds of str.

    attrName

    The name of the attribute whose value you want to determine.

    inRange

    The range in str within which you want to find the longest effective range of the attributes at loc. inRange must not exceed the bounds of str.

    effectiveRange

    If not NULL, upon return contains the maximal range within inRange over which the exact same set of attributes apply. The returned range is clipped to inRange.

    Return Value

    A dictionary that contains the attributes of str at the specified location. Ownership follows the Get Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the attributes of an attributed string at a specified location.

    Declaration

    Swift

    func CFAttributedStringGetAttributesAndLongestEffectiveRange(_ str: CFAttributedString!, _ loc: CFIndex, _ inRange: CFRange, _ effectiveRange: UnsafeMutablePointer<CFRange>) -> CFDictionary!

    Objective-C

    CFDictionaryRef CFAttributedStringGetAttributesAndLongestEffectiveRange ( CFAttributedStringRef aStr, CFIndex loc, CFRange inRange, CFRange *longestEffectiveRange );

    Parameters

    str

    The attributed string to examine.

    loc

    The location in str at which to determine the attributes. loc must not exceed the bounds of str.

    inRange

    The range in str within to find the longest effective range of the attributes at loc. inRange must not exceed the bounds of str.

    effectiveRange

    If not NULL, upon return contains the maximal range within inRange over which the exact same set of attributes apply. The returned range is clipped to inRange.

    Return Value

    A dictionary that contains the attributes of str at the specified location. Ownership follows the Get Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the type identifier for the CFAttributedString opaque type.

    Declaration

    Swift

    func CFAttributedStringGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFAttributedStringGetTypeID ( void );

    Return Value

    The type identifier for the CFAttributedString opaque type.

    Discussion

    CFMutableAttributedString objects have the same type identifier as CFAttributedString objects.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Data Types

  • A reference to a CFAttributedString object.

    Declaration

    Swift

    typealias CFAttributedStringRef = CFAttributedString

    Objective-C

    typedef const struct __CFAttributedString *CFAttributedStringRef;

    Discussion

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

    Values of type CFAttributedStringRef may refer to immutable or mutable strings, as CFMutableAttributedString objects respond to all functions intended for immutable CFAttributedString objects. Functions which accept CFAttributedStringRef values, and which need to hold on to the values immutably, should call CFAttributedStringCreateWithSubstring (instead of CFRetain) to do so.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.