iOS Developer Library

Developer

Foundation Framework Reference NSMutableAttributedString Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableAttributedString

The NSMutableAttributedString class declares additional methods for mutating the content of an attributed string. You can add and remove characters (raw strings) and attributes separately or together as attributed strings. See the class description for NSAttributedString for more information about attributed strings.

NSMutableAttributedString adds two primitive methods to those of NSAttributedString. These primitive methods provide the basis for all the other methods in its class. The primitive replaceCharactersInRange:withString: method replaces a range of characters with those from a string, leaving all attribute information outside that range intact. The primitive setAttributes:range: method sets attributes and values for a given range of characters, replacing any previous attributes and values for that range.

In OS X, AppKit also uses NSParagraphStyle and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes.

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

NSMutableAttributedString is “toll-free bridged” with its Core Foundation counterpart, CFMutableAttributedStringRef. See Toll-Free Bridging for more information.

  • The character contents of the receiver as an NSMutableString object.

    Declaration

    Swift

    var mutableString: NSMutableString { get }

    Objective-C

    @property(readonly, retain) NSMutableString *mutableString

    Return Value

    The mutable string object.

    Discussion

    The receiver tracks changes to this string and keeps its attribute mappings up to date.

    Availability

    Available in iOS 3.2 and later.

  • Overridden by subclasses to buffer or optimize a series of changes to the receiver’s characters or attributes, until it receives a matching endEditing message, upon which it can consolidate changes and notify any observers that it has changed.

    Declaration

    Swift

    func beginEditing()

    Objective-C

    - (void)beginEditing

    Discussion

    You can nest pairs of beginEditing and endEditing messages.

    Availability

    Available in iOS 3.2 and later.

  • Overridden by subclasses to consolidate changes made since a previous beginEditing message and to notify any observers of the changes.

    Declaration

    Swift

    func endEditing()

    Objective-C

    - (void)endEditing

    Discussion

    The NSMutableAttributedString implementation does nothing. NSTextStorage, for example, overrides this method to invoke fixAttributesInRange: and to inform its NSLayoutManager objects that they need to re-lay the text.

    Availability

    Available in iOS 3.2 and later.

    See Also

    – processEditing (NSTextStorage)

  • Cleans up font, paragraph style, and attachment attributes within the given range.

    Declaration

    Swift

    func fixAttributesInRange(_ range: NSRange)

    Objective-C

    - (void)fixAttributesInRange:(NSRange)range

    Parameters

    range

    The character range within which to fix attributes. Raises an NSRangeException if any part of range lies beyond the end of the receiver’s characters.

    Discussion

    Removes attachment attributes assigned to characters other than NSAttachmentCharacter, assigns default fonts to characters with illegal fonts for their scripts and otherwise corrects font attribute assignments, and assigns the first paragraph style attribute value in each paragraph to all characters of the paragraph.

    This method extends the range as needed to cover the last paragraph partially contained.

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

    NSTextStorage subclasses that return YEStrue from the fixesAttributesLazily method should avoid directly calling fixAttributesInRange: or else bracket such calls with beginEditing and endEditing messages.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Sets the contents of the receiver from the stream at data.

    Declaration

    Swift

    func readFromData(_ data: NSData, options opts: [String : AnyObject], documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>) throws

    Objective-C

    - (BOOL)readFromData:(NSData *)data options:(NSDictionary<NSString *,id> *)opts documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)dict error:(NSError * _Nullable *)error

    Parameters

    data

    The data object providing text data.

    opts

    Keys specifying the types of documents and other document import options. For a list of possible values, see “Option keys for importing documents” in NSAttributedString Class Reference

    dict

    On return, the dictionary (if provided) contains keys representing various document-wide attributes. For a list of possible values, see “Document Attributes” in NSAttributedString Class Reference.

    error

    Upon return, if an error occurs, contains an NSError object that describes the problem. If you are not interested in possible errors, pass in NULL.

    Return Value

    YEStrue if the attributed string is created successfully; otherwise NOfalse.

    Discussion

    opts can contain one of the values described in the Constants section of NSAttributedString Application Kit Additions Reference ("Option keys for importing documents").

    On return, the documentAttributes dictionary (if provided) contains the various keys described in the Constants section of NSAttributedString Application Kit Additions Reference. If unsuccessful, returns NO , after setting error to point to an NSError object that encapsulates the reason why the attributed string object could not be created.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Sets the contents of attributed string to the contents of the specified file.

    Declaration

    Swift

    func readFromURL(_ url: NSURL, options opts: [String : AnyObject], documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>) throws

    Objective-C

    - (BOOL)readFromURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)opts documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)dict error:(NSError * _Nullable *)error

    Parameters

    url

    The URL of the file to read.

    opts

    The option keys for importing the document. For a list of possible values, see “Option keys for importing documents” in NSAttributedString Class Reference.

    dict

    On return, contains the document attributes. For a list of possible values, see “Document Attributes” in NSAttributedString Class Reference.

    error

    Upon return, if an error occurs, contains an NSError object that describes the problem. If you are not interested in possible errors, pass in NULL.

    Return Value

    YEStrue if the attributed string is created successfully or NOfalse if it was not.

    Discussion

    Filter services can be used to convert the contents of the URL into a format recognized by Cocoa.

    For RTF formatted files, the contents of the file are appended to the previous string instead of replacing the previous string. Therefore, when using this method with existing content it's best to clear the content away explicitly.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 9.0 and later.