Class: NSAttributedString

Inherits:
NSObject show all

Overview

An NSAttributedString object manages 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.

Direct Known Subclasses

NSMutableAttributedString

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Instance Method Details

- (Object) attribute(attributeName, atIndex:index, effectiveRange:aRange)

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. Raises an NSRangeException if index lies beyond the end of the receiver’s characters.For information about where to find the attribute keys for the returned dictionary, see the overview section of this document.

Parameters:

  • attributeName (String) —

    The name of an attribute.

  • index (Integer) —

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

  • aRange (NSRangePointer) —

    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.

Returns:

  • (Object) —

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

- (Object) attribute(attributeName, atIndex:index, longestEffectiveRange:aRange, inRange:rangeLimit)

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. 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.For information about where to find the attribute keys for the returned dictionary, see the overview section of this document.

Parameters:

  • attributeName (String) —

    The name of an attribute.

  • index (Integer) —

    The index at which to test for attributeName.

  • aRange (NSRangePointer) —

    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 (NSRange) —

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

Returns:

  • (Object) —

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

- (NSAttributedString) attributedSubstringFromRange(aRange)

Returns an NSAttributedString object consisting of the characters and attributes within a given range in the receiver. 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.

Parameters:

  • aRange (NSRange) —

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

Returns:

- (Hash) attributesAtIndex(index, effectiveRange:aRange)

Returns the attributes for the character at a given index. Raises an NSRangeException if index lies beyond the end of the receiver’s characters.For information about where to find the attribute keys for the returned dictionary, see the overview section of this document.

Parameters:

  • index (Integer) —

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

  • aRange (NSRangePointer) —

    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.

Returns:

  • (Hash) —

    The attributes for the character at index.

- (Hash) attributesAtIndex(index, longestEffectiveRange:aRange, inRange:rangeLimit)

Returns the attributes for the character at a given index, and by reference the range over which the attributes apply. 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.For information about where to find the attribute keys for the returned dictionary, see the overview section of this document.

Parameters:

  • index (Integer) —

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

  • aRange (NSRangePointer) —

    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 (NSRange) —

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

Returns:

- (Object) enumerateAttribute(attrName, inRange:enumerationRange, options:opts, usingBlock:block)

Executes the Block for the specified attribute run in the specified range. If this method is sent to an instance of NSMutableAttributedString, mutation (deletion, addition, or change) is allowed, as long as it is within the range provided to the block; after a mutation, the enumeration continues with the range immediately following the processed range, after the length of the processed range is adjusted for the mutation. (The enumerator basically assumes any change in length occurs in the specified range.) For example, if block is called with a range starting at location N, and the block deletes all the characters in the supplied range, the next call will also pass N as the index of the range.

Parameters:

  • attrName —

    The name of an attribute.

  • enumerationRange —

    If non-NULL, contains the maximum range over which the attributes and values are enumerated, clipped to enumerationRange.

  • opts —

    The options used by the enumeration. The values can be combined using C-bitwise OR. The values are described in “NSAttributedStringEnumerationOptions.”

  • block —

    The Block to apply to ranges of the attribute in the attributed string.The Block takes three arguments:valueThe attrName value.rangeAn NSRange indicating the run of the attribute.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

  • value —

    The attrName value.

  • range —

    An NSRange indicating the run of the attribute.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

- (Object) enumerateAttributesInRange(enumerationRange, options:opts, usingBlock:block)

Executes the Block for each attribute in the range. If this method is sent to an instance of NSMutableAttributedString, mutation (deletion, addition, or change) is allowed, as long as it is within the range provided to the block; after a mutation, the enumeration continues with the range immediately following the processed range, after the length of the processed range is adjusted for the mutation. (The enumerator basically assumes any change in length occurs in the specified range.) For example, if block is called with a range starting at location N, and the block deletes all the characters in the supplied range, the next call will also pass N as the index of the range.

Parameters:

  • enumerationRange —

    If non-NULL, contains the maximum range over which the attributes and values are enumerated, clipped to enumerationRange.

  • opts —

    The options used by the enumeration. The values can be combined using C-bitwise OR. The values are described in “NSAttributedStringEnumerationOptions.”

  • block —

    The Block to apply to ranges of the attribute in the attributed string.The Block takes three arguments:attrsAn NSDictionary that contains the attributes for the range.rangeAn NSRange indicating the run of the attribute.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

  • attrs —

    An NSDictionary that contains the attributes for the range.

  • range —

    An NSRange indicating the run of the attribute.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

- (Object) initWithAttributedString(attributedString)

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

Parameters:

Returns:

  • (Object) —

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

- (Object) initWithString(aString)

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

Parameters:

  • aString (String) —

    The characters for the new object.

Returns:

  • (Object) —

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

- (Object) initWithString(aString, attributes:attributes)

Returns an NSAttributedString object initialized with a given string and attributes. 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.

Parameters:

  • aString (String) —

    The string for the new attributed string.

  • attributes (Hash) —

    The attributes for the new attributed string. For information about where to find the attribute keys you can include in this dictionary, see the overview section of this document.

Returns:

- (Boolean) isEqualToAttributedString(otherString)

Returns a Boolean value that indicates whether the receiver is equal to another given attributed string. Attributed strings must match in both characters and attributes to be equal.

Parameters:

  • otherString (NSAttributedString) —

    The attributed string with which to compare the receiver.

Returns:

  • (Boolean) —

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

- (Integer) length

Returns the length of the receiver’s string object.

Returns:

- (String) string

Returns the character contents of the receiver as an NSString object. This method doesn’t strip out attachment 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.

Returns:

  • (String) —

    The character contents of the receiver as an NSString object.