---

NSMutableString Class Reference

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.

Tasks

Creating and Initializing a Mutable String

• + stringWithCapacity:
• – initWithCapacity:

Modifying a String

• – appendFormat:
• – appendString:
• – deleteCharactersInRange:
• – insertString:atIndex:
• – replaceCharactersInRange:withString:
• – replaceOccurrencesOfString:withString:options:range:
• – setString:

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 Mac OS X v10.0 and later.

Related Sample Code

• PDFKitLinker2
• QTRecorder

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.

Discussion

The appended string is formed using NSString's stringWithFormat: method with the arguments listed.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – appendString:

Related Sample Code

• CoreRecipes
• iSpend
• ThreadsImporter
• ThreadsImportMovie
• TimelineToTC

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 Mac OS X v10.0 and later.

See Also

• – appendFormat:

Related Sample Code

• CoreRecipes
• DockTile
• JavaSplashScreen
• SampleScannerApp
• TimelineToTC

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 Mac OS X v10.0 and later.

Related Sample Code

• NumberInput_IMKit_Sample

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 Mac OS X v10.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 Mac OS X v10.0 and later.

Related Sample Code

• Aperture Image Resizer
• CustomSave

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 Mac OS X v10.0 and later.

Related Sample Code

• LSMSmartCategorizer

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 Cocoa 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 Mac OS X v10.2 and later.

Related Sample Code

• CubePuzzle
• JavaSplashScreen
• NewsReader
• SpotlightAPI
• Video Hardware Info

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 Mac OS X v10.0 and later.

Related Sample Code

• NumberInput_IMKit_Sample
• PDFKitLinker2
• QTCoreVideo201
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

NSString.h

---