Mac 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Replaces the characters in the given range with the characters of the given string.

    Declaration

    Swift

    func replaceCharactersInRange(_ range: NSRange, withString str: String)

    Objective-C

    - (void)replaceCharactersInRange:(NSRange)aRange withString:(NSString *)aString

    Parameters

    aRange

    A range specifying the characters to replace.

    aString

    A string specifying the characters to replace those in aRange.

    Discussion

    The new characters inherit the attributes of the first replaced character from aRange. Where the length of aRange is 0, the new characters inherit the attributes of the character preceding aRange if it has any, otherwise of the character following aRange.

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Deletes the characters in the given range along with their associated attributes.

    Declaration

    Swift

    func deleteCharactersInRange(_ range: NSRange)

    Objective-C

    - (void)deleteCharactersInRange:(NSRange)aRange

    Parameters

    aRange

    A range specifying the characters to delete.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Adds the characters and attributes of a given attributed string to the end of the receiver.

    Declaration

    Swift

    func appendAttributedString(_ attrString: NSAttributedString)

    Objective-C

    - (void)appendAttributedString:(NSAttributedString *)attributedString

    Parameters

    attributedString

    The string whose characters and attributes are added.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Inserts the characters and attributes of the given attributed string into the receiver at the given index.

    Declaration

    Swift

    func insertAttributedString(_ attrString: NSAttributedString, atIndex loc: Int)

    Objective-C

    - (void)insertAttributedString:(NSAttributedString *)attributedString atIndex:(NSUInteger)index

    Parameters

    attributedString

    The string whose characters and attributes are inserted.

    index

    The index at which the characters and attributes are inserted.

    Discussion

    The new characters and attributes begin at the given index and the existing characters and attributes from the index to the end of the receiver are shifted by the length of the attributed string. Raises an NSRangeException if index lies beyond the end of the receiver’s characters.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Replaces the characters and attributes in a given range with the characters and attributes of the given attributed string.

    Declaration

    Swift

    func replaceCharactersInRange(_ range: NSRange, withAttributedString attrString: NSAttributedString)

    Objective-C

    - (void)replaceCharactersInRange:(NSRange)aRange withAttributedString:(NSAttributedString *)attributedString

    Parameters

    aRange

    The range of characters and attributes replaced.

    attributedString

    The attributed string whose characters and attributes replace those in the specified range.

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Replaces the receiver’s entire contents with the characters and attributes of the given attributed string.

    Declaration

    Swift

    func setAttributedString(_ attrString: NSAttributedString)

    Objective-C

    - (void)setAttributedString:(NSAttributedString *)attributedString

    Parameters

    attributedString

    The attributed string whose characters and attributes replace those in the receiver.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 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.

    Availability

    Available in OS X v10.0 and later.

  • Cleans up attachment attributes in aRange, removing all attachment attributes assigned to characters other than NSAttachmentCharacter.

    Declaration

    Swift

    func fixAttachmentAttributeInRange(_ range: NSRange)

    Objective-C

    - (void)fixAttachmentAttributeInRange:(NSRange)aRange

    Parameters

    aRange

    The range of characters.

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

  • Fixes the font attribute in aRange, assigning default fonts to characters with illegal fonts for their scripts and otherwise correcting font attribute assignments.

    Declaration

    Swift

    func fixFontAttributeInRange(_ range: NSRange)

    Objective-C

    - (void)fixFontAttributeInRange:(NSRange)aRange

    Parameters

    aRange

    The range of characters.

    Discussion

    For example, Kanji characters assigned a Latin font are reassigned an appropriate Kanji font. Raises an NSRangeException if any part of aRange lies beyond the end of the receiver’s characters.

    Availability

    Available in OS X v10.0 and later.

  • Fixes the paragraph style attributes in aRange, assigning the first paragraph style attribute value in each paragraph to all characters of the paragraph.

    Declaration

    Swift

    func fixParagraphStyleAttributeInRange(_ range: NSRange)

    Objective-C

    - (void)fixParagraphStyleAttributeInRange:(NSRange)aRange

    Parameters

    aRange

    The range of characters.

    Discussion

    This method extends the range as needed to cover the last paragraph partially contained. A paragraph is delimited by any of these characters, the longest possible sequence being preferred to any shorter:

    • U+000D (\r or CR)

    • U+000A (\n or LF)

    • U+2029 (Unicode paragraph separator) \r\n, in that order (also known as CRLF)

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

    Availability

    Available in OS X v10.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?>, error error: ()) 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.

    Availability

    Available in OS X v10.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?>, error error: ()) 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.

    Availability

    Available in OS X v10.11 and later.