---

NSMutableStringReference

Overview

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

An immutable string is implemented as an array of Unicode characters (in other words, as a text string). The NSMutableStringReference class adds one primitive method—replaceCharactersInRange—to the basic string-handling behavior inherited from NSStringReference. All other methods that modify a string work through this method. For example, insertStringAtIndex simply replaces the characters in a range of 0 length, while deleteCharactersInRange replaces the characters in a given range with no characters.

The Application Kit also uses NSParagraphStyle and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes.

Tasks

Constructors

• NSMutableStringReference

Modifying a String

• appendString
• deleteCharactersInRange
• insertStringAtIndex
• replaceCharactersInRange
• replaceOccurrencesOfString
• setString

Instance Methods

appendString

Adds the characters of aString to the end of the receiver.

public void appendString(String aString)

Discussion

aString may not be null.

Adds the characters of aStringReference to the end of the receiver.

public void appendString(NSStringReference aStringReference)

Discussion

aStringReference may not be null.

deleteCharactersInRange

Removes the characters in aRange from the receiver.

public void deleteCharactersInRange(NSRange aRange)

Discussion

Throws a RangeException if any part of aRange lies beyond the end of the string. This method treats the length of the string as a valid range value that returns an empty string.

insertStringAtIndex

Inserts the characters of aString into the receiver, so the new characters begin at anIndex and the existing characters from anIndex to the end are shifted by the length of aString.

public void insertStringAtIndex(String aString, int anIndex)

Discussion

aString may not be null. Throws a RangeException if anIndex lies beyond the end of the string. This method treats the length of the string as a valid index value that returns an empty string.

Inserts the characters of aStringReference into the receiver, so the new characters begin at anIndex and the existing characters from anIndex to the end are shifted by the length of aStringReference.

public void insertStringAtIndex(NSStringReference aStringReference, int anIndex)

Discussion

aStringReference may not be null. Throws a RangeException if anIndex lies beyond the end of the string.

replaceCharactersInRange

Replaces the characters from aRange with those in aString.

public void replaceCharactersInRange(NSRange aRange, String aString)

Discussion

aString may not be null. Throws a RangeException if any part of aRange lies beyond the end of the receiver. This method treats the length of the string as a valid range value that returns an empty string.

Replaces the characters from aRange with those in aStringReference.

public void replaceCharactersInRange(NSRange aRange, NSStringReference aStringReference)

Discussion

aStringReference may not be null. Throws a RangeException if any part of aRange lies beyond the end of the receiver. This method treats the length of the string as a valid range value that returns an empty string.

replaceOccurrencesOfString

This method replaces all occurrences of target with replacement, in the specified searchRange of the receiver.

public void replaceOccurrencesOfString(String target, String replacement, int opts, NSRange searchRange)

Discussion

Throws an InvalidArgumentException if any of the arguments are null. Throws a RangeException if any part of searchRange lies beyond the end of the receiver. This method treats the length of the string as a valid range value that returns an empty string. If opts is BackwardsSearch, the search is done from the end of the range. If opts is AnchoredSearch, only anchored (but potentially multiple) instances are replaced. LiteralSearch and CaseInsensitiveSearch also apply. Specify searchRange as new NSRange(0, receiver.length()) to process the entire string.

Availability

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

setString

Replaces the characters of the receiver with those in aString.

public void setString(String aString)

Discussion

aString may not be null.

Replaces the characters of the receiver with those in aStringReference.

public void setString(NSStringReference aStringReference)

Discussion

aStringReference may not be null.

---