Mac Developer Library

Developer

Foundation Framework Reference NSMutableString Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableString

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.

The NSMutableString class declares the programmatic interface to an object that manages a mutable string—that is, a string whose contents can be edited—that conceptually represents an array of Unicode characters. To construct and manage an immutable string—or a string that cannot be changed after it has been created—use an object of the NSString class.

The NSMutableString class adds one primitive method—replaceCharactersInRange:withString:—to the basic string-handling behavior inherited from NSString. All other methods that modify a string work through this method. For example, insertString:atIndex: simply replaces the characters in a range of 0 length, while deleteCharactersInRange: replaces the characters in a given range with no characters.

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

  • Returns an empty NSMutableString object with initial storage for a given number of characters.

    Declaration

    Objective-C

    + (NSMutableString *)stringWithCapacity:(NSUInteger)capacity

    Parameters

    capacity

    The number of characters the string is expected to initially contain.

    Return Value

    An empty NSMutableString object with initial storage for capacity characters.

    Discussion

    The number of characters indicated by capacity is simply a hint to increase the efficiency of data storage. The value does not limit the length of the string.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSMutableString object initialized with initial storage for a given number of characters,

    Declaration

    Swift

    init(capacity capacity: Int)

    Objective-C

    - (NSMutableString *)initWithCapacity:(NSUInteger)capacity

    Parameters

    capacity

    The number of characters the string is expected to initially contain.

    Return Value

    An initialized NSMutableString object with initial storage for capacity characters. The returned object might be different than the original receiver.

    Discussion

    The number of characters indicated by capacity is simply a hint to increase the efficiency of data storage. The value does not limit the length of the string.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Adds a constructed string to the receiver.

    Declaration

    Objective-C

    - (void)appendFormat:(NSString *)format, ...

    Parameters

    format

    A format string. See Formatting String Objects for more information. This value must not be nil.

    ...

    A comma-separated list of arguments to substitute into format.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func appendString(_ aString: String)

    Objective-C

    - (void)appendString:(NSString *)aString

    Parameters

    aString

    The string to append to the receiver. aString must not be nil

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Removes from the receiver the characters in a given range.

    Declaration

    Swift

    func deleteCharactersInRange(_ aRange: NSRange)

    Objective-C

    - (void)deleteCharactersInRange:(NSRange)aRange

    Parameters

    aRange

    The range of characters to delete. aRange must not exceed the bounds of the receiver.

    Discussion

    This method treats the length of the string as a valid range value that returns an empty string.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Inserts into the receiver the characters of a given string at a given location.

    Declaration

    Swift

    func insertString(_ aString: String, atIndex anIndex: Int)

    Objective-C

    - (void)insertString:(NSString *)aString atIndex:(NSUInteger)anIndex

    Parameters

    aString

    The string to insert into the receiver. aString must not be nil.

    anIndex

    The location at which aString is inserted. The location must not exceed the bounds of the receiver.

    Discussion

    The new characters begin at anIndex and the existing characters from anIndex to the end are shifted by the length of aString.

    This method treats the length of the string as a valid index value that returns an empty string.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Replaces the characters from aRange with those in aString.

    Declaration

    Swift

    func replaceCharactersInRange(_ aRange: NSRange, withString aString: String)

    Objective-C

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

    Parameters

    aRange

    The range of characters to replace. aRange must not exceed the bounds of the receiver.

    aString

    The string with which to replace the characters in aRange. aString must not be nil.

    Discussion

    This method treats the length of the string as a valid range value that returns an empty string.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Replaces all occurrences of a given string in a given range with another given string, returning the number of replacements.

    Declaration

    Swift

    func replaceOccurrencesOfString(_ target: String, withString replacement: String, options opts: NSStringCompareOptions, range searchRange: NSRange) -> Int

    Objective-C

    - (NSUInteger)replaceOccurrencesOfString:(NSString *)target withString:(NSString *)replacement options:(NSStringCompareOptions)opts range:(NSRange)searchRange

    Parameters

    target

    The string to replace.

    replacement

    The string with which to replace target.

    opts

    A mask specifying search options. See String Programming Guide for details.

    If opts is NSBackwardsSearch, the search is done from the end of the range. If opts is NSAnchoredSearch, only anchored (but potentially multiple) instances are replaced. NSLiteralSearch and NSCaseInsensitiveSearch also apply.

    searchRange

    The range of characters to replace. aRange must not exceed the bounds of the receiver. Specify searchRange as NSMakeRange(0, [receiver length]) to process the entire string.

    Return Value

    The number of replacements made.

    Discussion

    This method treats the length of the string as a valid range value that returns an empty string.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.2 and later.

  • Replaces the characters of the receiver with those in a given string.

    Declaration

    Swift

    func setString(_ aString: String)

    Objective-C

    - (void)setString:(NSString *)aString

    Parameters

    aString

    The string with which to replace the receiver's content. aString must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.