Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSMutableString 

Inherits From:	NSString : NSObject

Conforms To:	NSCoding, NSCopying, NSMutableCopying (NSString)
NSObject (NSObject)

Declared In:	Foundation/NSString.h 

Class Description

NSMutableString (and NSString) declare the programmatic interface for objects that create and managemutable representation-independent character strings. For a more general overview of string classes, see the description of NSString. 

NSMutableString (and NSString) are abstract classes for string manipulation. NSMutableString declares the interface to objects that inherit all the capabilities of NSString objects, but in addition allow for modification of the string data. NSString and NSMutableString provide factory methods that return autoreleased instances of unspecified subclasses of strings.

You can instantiate an NSMutableString object by sending any of the stringWith¼ methods to the NSMutableString class object. This set of methods also includes localizedStringWithFormat:. A newly allocated NSMutableString object can also be initialized using the initWithCapacity: method, to set the string to a specified capacity.

Creating Temporary Strings 

+ (NSMutableString *)localizedStringWithFormat:(NSString *)format,...
	Returns a string created by using format as a printf() style format string, and the following arguments as values to be substituted into the format string. The user's default locale is used for format information.

+ (NSMutableString *)stringWithCString:(const char *)zeroTerminatedBytes
	Returns a mutable string containing the characters in zeroTerminatedBytes, which must be null-terminated. The zeroTerminatedBytes string should contain bytes in the default C string encoding.

+ (NSMutableString *)stringWithCString:(const char *)bytes
length:(unsigned int)length	Returns a mutable string containing length characters made from bytes. This method doesn't stop at a null byte. bytes should contain bytes in the default C string encoding.

+ (NSMutableString *)stringWithCapacity:(unsigned int)capacity
	Returns an empty mutable string, using capacity as a hint for how much initial storage to reserve.

+ (NSMutableString *)stringWithCharacters:(const unichar *)characters	
length:(unsigned int)length	Returns a mutable string containing characters. The first length characters are copied into the string. This method doesn't stop at a null character.

+ (NSMutableString *)stringWithContentsOfFile:(NSString *)path	
	Returns a string containing the contents of the file specified by path. This method attempts to determine the encoding for the file. The string is assumed to be in Unicode encoding, but if the encoding is determined not to be Unicode, the default C string encoding is used instead.

+ (NSMutableString *)stringWithFormat:(NSString *)format,...
	Returns a mutable string created by using format as a printf() style format string, and the subsequent arguments as values to be substituted into the format string.

Initializing a Mutable String

- initWithCapacity:(unsigned int)capacity	Initializes a newly allocated mutable string object, giving it enough allocated memory to hold capacity characters.

Modifying a String

- (void)appendFormat:(NSString *)format,...	Adds a constructed string to the receiver. The new characters are created by using format as a printf() style format string, and the following arguments as values to be substituted into the format string. Invokes replaceCharactersInRange:withString: as part of its implementation.

- (void)appendString:(NSString *)aString	Adds the characters of aString to end of the receiver. Invokes replaceCharactersInRange:withString: as part of its implementation.

- (void)deleteCharactersInRange:(NSRange)range
	Removes from the receiver the characters in range. This method raises an NSStringBoundsError exception if any part of range lies beyond the end of the string. Invokes replaceCharactersInRange:withString: as part of its implementation.

- (void)insertString:(NSString *)aString	Inserts the characters of aString into the receiver, such that
atIndex:(unsigned)index	 	the new characters begin at index and the existing character from index to the end are shifted by the length of aString. This method raises an NSStringBoundsError exception if index lies beyond the end of the string. Invokes replaceCharactersInRange:withString: as part of its implementation.

- (void)replaceCharactersInRange:(NSRange)aRange
withString:(NSString *)aString	Inserts the characters of aString into the receiver, such that they replace the characters in aRange. This method raises an NSStringBoundsError exception if any part of aRange lies beyond the end of the string.

- (void)setString:(NSString *)aString	Replaces the characters of the receiver with those in aString.