ADC Home > Reference Library > Reference > Cocoa > Data Management > NSAttributedString Class Reference >

Next Page > Hide TOC

NSAttributedString Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSAttributedString.h
Related sample code

Overview

NSAttributedString objects manage character strings and associated sets of attributes (for example, font and kerning) that apply to individual characters or ranges of characters in the string. An association of characters and their attributes is called an attributed string. The cluster’s two public classes, NSAttributedString and NSMutableAttributedString, declare the programmatic interface for read-only attributed strings and modifiable attributed strings, respectively. The Foundation framework defines only the basic functionality for attributed strings; additional methods supporting RTF, graphics attributes, and drawing attributed strings are described in NSAttributedString Additions, found in the Application Kit. The Application Kit also uses a subclass of NSMutableAttributedString, called NSTextStorage, to provide the storage for the Application Kit’s extended text-handling system.

The Application Kit also uses NSParagraphStyle and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes.

An attributed string identifies attributes by name, storing a value under the name in an NSDictionary object. Standard attribute keys are described in the “Constants” section of NSAttributedString Application Kit Additions Reference. You can also assign any attribute name/value pair you wish to a range of characters—it is up to your application to interpret custom attributes (see Attributed Strings Programming Guide).

Note that the default font for NSAttributedString objects is Helvetica 12-point, which differs from the Mac OS X system font Lucida Grande, so you may wish to create the string with non-default attributes suitable for your application using, for example, initWithString:attributes:.

Be aware that isEqual: comparison among NSAttributedString objects compares for exact equality, including not only literal character-by-character string equality but also equality of all attributes, which is not likely to be achieved in the case of many attributes such as attachments, lists, and tables, for example.

Adopted Protocols

NSCoding
NSCopying
NSMutableCopying

Tasks

Creating an NSAttributedString Object

Retrieving Character Information

Retrieving Attribute Information

Comparing Attributed Strings

Extracting a Substring

Instance Methods

attribute:atIndex:effectiveRange:

Returns the value for an attribute with a given name of the character at a given index, and by reference the range over which the attribute applies.

- (id)attribute:(NSString *)attributeName atIndex:(NSUInteger)index effectiveRange:(NSRangePointer)aRange

Parameters
attributeName

The name of an attribute.

index

The index for which to return attributes. This value must not exceed the bounds of the receiver.

aRange

If non-NULL:

  • If the named attribute exists at index, upon return aRange contains a range over which the named attribute’s value applies.

  • If the named attribute does not exist at index, upon return aRange contains the range over which the attribute does not exist.

The range isn’t necessarily the maximum range covered by attributeName, and its extent is implementation-dependent. If you need the maximum range, use attribute:atIndex:longestEffectiveRange:inRange:. If you don't need this value, pass NULL.

Return Value

The value for the attribute named attributeName of the character at index index, or nil if there is no such attribute.

Discussion

Raises an NSRangeException if index lies beyond the end of the receiver’s characters.

Availability
See Also
Related Sample Code
Declared In
NSAttributedString.h

attribute:atIndex:longestEffectiveRange:inRange:

Returns the value for the attribute with a given name of the character at a given index, and by reference the range over which the attribute applies.

- (id)attribute:(NSString *)attributeName atIndex:(NSUInteger)index longestEffectiveRange:(NSRangePointer)aRange inRange:(NSRange)rangeLimit

Parameters
attributeName

The name of an attribute.

index

The index at which to test for attributeName.

aRange

If non-NULL:

  • If the named attribute exists at index, upon return aRange contains the full range over which the value of the named attribute is the same as that at index, clipped to rangeLimit.

  • If the named attribute does not exist at index, upon return aRange contains the full range over which the attribute does not exist, clipped to rangeLimit.

If you don't need this value, pass NULL.

rangeLimit

The range over which to search for continuous presence of attributeName. This value must not exceed the bounds of the receiver.

Return Value

The value for the attribute named attributeName of the character at index, or nil if there is no such attribute.

Discussion

Raises an NSRangeException if index or any part of rangeLimit lies beyond the end of the receiver’s characters.

If you don’t need the longest effective range, it’s far more efficient to use the attribute:atIndex:effectiveRange: method to retrieve the attribute value.

Availability
See Also
Declared In
NSAttributedString.h

attributedSubstringFromRange:

Returns an NSAttributedString object consisting of the characters and attributes within a given range in the receiver.

- (NSAttributedString *)attributedSubstringFromRange:(NSRange)aRange

Parameters
aRange

The range from which to create a new attributed string. aRange must lie within the bounds of the receiver.

Return Value

An NSAttributedString object consisting of the characters and attributes within aRange in the receiver.

Discussion

Raises an NSRangeException if any part of aRange lies beyond the end of the receiver’s characters. This method treats the length of the string as a valid range value that returns an empty string.

Availability
Declared In
NSAttributedString.h

attributesAtIndex:effectiveRange:

Returns the attributes for the character at a given index.

- (NSDictionary *)attributesAtIndex:(NSUInteger)index effectiveRange:(NSRangePointer)aRange

Parameters
index

The index for which to return attributes. This value must lie within the bounds of the receiver.

aRange

Upon return, the range over which the attributes and values are the same as those at index. This range isn’t necessarily the maximum range covered, and its extent is implementation-dependent. If you need the maximum range, use attributesAtIndex:longestEffectiveRange:inRange:. If you don't need this value, pass NULL.

Return Value

The attributes for the character at index.

Discussion

Raises an NSRangeException if index lies beyond the end of the receiver’s characters.

Availability
See Also
Declared In
NSAttributedString.h

attributesAtIndex:longestEffectiveRange:inRange:

Returns the attributes for the character at a given index, and by reference the range over which the attributes apply.

- (NSDictionary *)attributesAtIndex:(NSUInteger)index longestEffectiveRange:(NSRangePointer)aRange inRange:(NSRange)rangeLimit

Parameters
index

The index for which to return attributes. This value must not exceed the bounds of the receiver.

aRange

If non-NULL, upon return contains the maximum range over which the attributes and values are the same as those at index, clipped to rangeLimit.

rangeLimit

The range over which to search for continuous presence of the attributes at index. This value must not exceed the bounds of the receiver.

Discussion

Raises an NSRangeException if index or any part of rangeLimit lies beyond the end of the receiver’s characters.

If you don’t need the range information, it’s far more efficient to use the attributesAtIndex:effectiveRange: method to retrieve the attribute value.

Availability
See Also
Declared In
NSAttributedString.h

initWithAttributedString:

Returns an NSAttributedString object initialized with the characters and attributes of another given attributed string.

- (id)initWithAttributedString:(NSAttributedString *)attributedString

Parameters
attributedString

An attributed string.

Return Value

An NSAttributedString object initialized with the characters and attributes of attributedString. The returned object might be different than the original receiver.

Availability
See Also
Related Sample Code
Declared In
NSAttributedString.h

initWithString:

Returns an NSAttributedString object initialized with the characters of a given string and no attribute information.

- (id)initWithString:(NSString *)aString

Parameters
aString

The characters for the new object.

Return Value

An NSAttributedString object initialized with the characters of aString and no attribute information The returned object might be different than the original receiver.

Availability
See Also
Declared In
NSAttributedString.h

initWithString:attributes:

Returns an NSAttributedString object initialized with a given string and attributes.

- (id)initWithString:(NSString *)aString attributes:(NSDictionary *)attributes

Parameters
aString

The string for the new attributed string.

attributes

The attributes for the new attributed string. You can assign to a range of characters any attribute name/value pairs you wish, in addition to the standard attributes described in the “Constants” section of NSAttributedString Application Kit Additions Reference.

Discussion

Returns an NSAttributedString object initialized with the characters of aString and the attributes of attributes. The returned object might be different from the original receiver.

Availability
See Also
Related Sample Code
Declared In
NSAttributedString.h

isEqualToAttributedString:

Returns a Boolean value that indicates whether the receiver is equal to another given attributed string.

- (BOOL)isEqualToAttributedString:(NSAttributedString *)otherString

Parameters
otherString

The attributed string with which to compare the receiver.

Return Value

YES if the receiver is equal to otherString, otherwise NO.

Discussion

Attributed strings must match in both characters and attributes to be equal.

Availability
Declared In
NSAttributedString.h

length

Returns the length of the receiver’s string object.

- (NSUInteger)length

Availability
See Also
Related Sample Code
Declared In
NSAttributedString.h

string

Returns the character contents of the receiver as an NSString object.

- (NSString *)string

Return Value

The character contents of the receiver as an NSString object.

Discussion

This method doesn’t strip out attachment characters; use NSText's string method to extract just the linguistically significant characters.

For performance reasons, this method returns the current backing store of the attributed string object. If you want to maintain a snapshot of this as you manipulate the returned string, you should make a copy of the appropriate substring.

This primitive method must guarantee efficient access to an attributed string’s characters; subclasses should implement it to execute in O(1) time.

Availability
Related Sample Code
Declared In
NSAttributedString.h

Constants

Standard attribute keys are described in the “Constants” section of NSAttributedString Application Kit Additions Reference.



Next Page > Hide TOC

© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.