NSMutableString Class Reference

Inherits from
NSString : NSObject
Conforms to
NSCopying (NSString)
NSMutableCopying (NSString)
NSSecureCoding (NSString)
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
String Programming Guide
Declared in
NSString.h
Related sample code

Overview

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.

Tasks

Creating and Initializing a Mutable String

Modifying a String

Class Methods

stringWithCapacity:

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

+ (id)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.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

Instance Methods

appendFormat:

Adds a constructed string to the receiver.

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

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

Important: Raises an NSInvalidArgumentException if format is nil.

...

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

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
NSString.h

appendString:

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

- (void)appendString:(NSString *)aString
Parameters
aString

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

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
NSString.h

deleteCharactersInRange:

Removes from the receiver the characters in a given range.

- (void)deleteCharactersInRange:(NSRange)aRange
Parameters
aRange

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

Important: Raises an NSRangeException if any part of aRange lies beyond the end of the string.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

initWithCapacity:

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

- (id)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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

insertString:atIndex:

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

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

Important: Raises an NSRangeException if anIndex lies beyond the end of the string.

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

replaceCharactersInRange:withString:

Replaces the characters from aRange with those in aString.

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

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

Important: Raises an NSRangeException if any part of aRange lies beyond the end 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.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h

replaceOccurrencesOfString:withString:options:range:

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

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

The string to replace.

Important: Raises an NSInvalidArgumentException if target is nil.

replacement

The string with which to replace target.

Important: Raises an NSInvalidArgumentException if replacement is nil.

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.

Important: Raises an NSRangeException if any part of searchRange lies beyond the end of the receiver.

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.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSString.h

setString:

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

- (void)setString:(NSString *)aString
Parameters
aString

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

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSString.h


© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-03-06)

Did this document help you? Yes It's good, but... Not helpful...