PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSAttributedString


Inherits from:
NSObject
Conforms to:
NSCoding
NSCopying
NSMutableCopying
NSObject (NSObject)
Declared in:
Foundation/NSAttributedString.h




Class Description


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 Kit defines only the basic functionality for attributed strings; the remainder of the classes' interfaces is actually defined by 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.

NSAttributedString is not a subclass of NSString. It contains a string object to which it applies attributes. This protects users of attributed strings from ambiguities caused by the semantic differences between simple and attributed string. For example, equality can't be simply defined between an NSString and an attributed string.

Because of the nature of class clusters, attributed string objects are not actual instances of the NSAttributedString or NSMutableAttributedString classes, but are instances of one of their private concrete subclasses. Although an attributed string object's class is private, its interface is public, as declared by these abstract superclasses, NSAttributedString and NSMutableAttributedString. The attributed string classes adopt the NSCopying and NSMutableCopying protocols, making it convenient to convert an attributed string from one type to the other.

You create an NSAttributedString object by using one of the initWithString:, initWithString:attributes:, or initWithAttributedString: methods. These methods initialize an attributed string with data you provide. The Application Kit also provides methods for creating attributed strings from RTF data.

An attributed string provides basic access to its contents with the string and attributesAtIndex:effectiveRange: methods, which yield characters and attributes, respectively. These two primitive methods are used by the other access methods to retrieve attributes individually by name, by functional group (font or ruler attributes, for example), and so on.

The attribute values assigned to an attributed string become the property of that string, and shouldn't be modified in any way by other objects. Doing so can render inconsistent the attributed string's internal state. Always use NSMutableAttributedString's setAttributes:range: and related methods to change attribute values.

For more information on using attributed strings, see the Application Kit's specification for this class cluster.

The NSAttributedString class declares the programmatic interface to an object that manages an immutable attributed string. NSAttributedString's two primitive methods provide the basis for all the other methods in the class. The primitive string method returns the NSString object to which attributes are applied. The primitive attributesAtIndex:effectiveRange: method returns an NSDictionary containing the attribute names and values for characters around a specified index.




Adopted Protocols


NSCoding
- encodeWithCoder:
- initWithCoder:
NSCopying
- copyWithZone:
NSMutableCopying
- mutableCopyWithZone:


Method Types


Creating an NSAttributedString
- initWithString:
- initWithAttributedString:
- initWithString:attributes:
Retrieving character information
- string
- length
Retrieving attribute information
- attributesAtIndex:effectiveRange:
- attributesAtIndex:longestEffectiveRange:inRange:
- attribute:atIndex:effectiveRange:
- attribute:atIndex:longestEffectiveRange:inRange:
Comparing attributed strings
- isEqualToAttributedString:
Extracting a substring
- attributedSubstringFromRange:


Instance Methods



attribute:atIndex:effectiveRange:

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

Returns the value for the attribute named attributeName of the character at index, or nil if there is no such attribute. If the named attribute exists at index and aRange is non-nil, it's filled with a range over which the named attribute's value applies. If the named attribute doesn't exist at index and aRange is non-nil, aRange is filled instead with the range over which the attribute doesn't exist. This 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:.

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

See Also: - attributesAtIndex:effectiveRange:



attribute:atIndex:longestEffectiveRange:inRange:

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

Returns the value for the attribute named attributeName of the character at index, or nil if there is no such attribute. If the named attribute exists at index and aRange is non-nil, it's filled with 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 doesn't exist at index and aRange is non-nil, aRange is filled instead with the full range over which the attribute doesn't exist, clipped to rangeLimit.

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.

See Also: - attributesAtIndex:longestEffectiveRange:inRange:



attributedSubstringFromRange:

- (NSAttributedString *)attributedSubstringFromRange:(NSRange)aRange

Returns an NSAttributedString object consisting of the characters and attributes within aRange in the receiver. Raises an NSRangeException if any part of aRange lies beyond the end of the receiver's characters.

attributesAtIndex:effectiveRange:

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

Returns the attributes for the character at index. If aRange is non-nil it's filled with the range over which the attributes and values apply. This range isn't necessarily the maximum range covered, and its extent is implementation-dependent. If you need the maximum range, use attributesAtIndex:effectiveRange:.

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

See Also: - attribute:atIndex:effectiveRange:



attributesAtIndex:longestEffectiveRange:inRange:

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

Returns the attributes for the character at index. If aRange is non-nil, it's filled with the maximum range over which the attributes and values are the same as those at index, clipped to rangeLimit.

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.

See Also: - attribute:atIndex:longestEffectiveRange:inRange:



initWithAttributedString:

- (id)initWithAttributedString:(NSAttributedString *)attributedString

Initializes a newly allocated NSAttributedString object with the characters and attributes of attributedString. Returns self.

See Also: - initWithRTF:documentAttributes: (NSAttributedString Additions in the Application Kit)



initWithString:

- (id)initWithString:(NSString *)aString

Initializes a newly allocated NSAttributedString object with the characters of aString and no attribute information. Returns self.

See Also: - initWithRTF:documentAttributes: (NSAttributedString Additions in the Application Kit)



initWithString:attributes:

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

Initializes a newly allocated NSAttributedString object with the characters of aString and the attributes of attributes. Returns self.

See Also: - initWithRTF:documentAttributes: (NSAttributedString Additions in the Application Kit)



isEqualToAttributedString:

- (BOOL)isEqualToAttributedString:(NSAttributedString *)otherString

Returns YES if the receiver is equal to otherString. Attributed strings must match in both characters and attributes to be equal.

length

- (unsigned)length

Returns the length of the receiver's string object.

See Also: - length (NSString), - size (NSAttributedString Additions in the Application Kit)



string

- (NSString *)string

Returns the character contents of the receiver as an NSString object. This method doesn't strip out attachment characters; use NSText's string method to extract just the linguistically significant characters.

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




Table of Contents