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

NSMutableArray 

Inherits From:	NSArray : NSObject

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

Declared In:	Foundation/NSArray.h 

Class Description

The NSMutableArray class declares the programmatic interface to objects that manage a modifiable array of objects. This class adds insertion and deletion operations to the basic array-handling behavior it inherits from NSArray. 

The array operations that NSMutableArray declares are conceptually based on these three methods:

addObject:
replaceObjectAtIndex:withObject:
removeLastObject

The other methods in its interface provide convenient ways of inserting an object into a specific slot in the array and of removing an object based on its identity or position in the array.

When an object is removed from a mutable array it receives a release message, which can cause it to be deallocated. Note that if your program keeps a reference to such an object, the reference may become invalid unless you remember to send the object a retain message before it's removed from the array. For example, the third statement below could result in a run-time error, except for the retain message in the first statement:

id anObject = [[anArray objectAtIndex:0] retain];
[anArray removeObjectAtIndex:0];
[anObject someMessage];

Implementing Subclasses of NSMutableArray

Although conceptually the interface to the NSMutableArray class is based on the three methods listed above, for performance reasons two othersÐinsertObject:atIndex: and removeObjectAtIndex:Ðalso directly access the object's data. These two methods could be implemented using the methods listed above but in doing so would incur unnecessary overhead from the retain and release messages that objects would receive as they are shifted to accommodate the insertion or deletion of an element. Thus, if you create a subclass of NSMutableArray, you should override all five primitive methods so that the other methods in NSMutableArray's interface work properly.

Creating and Initializing an NSMutableArray

+ (id)allocWithZone:(NSZone *)zone	Creates and returns an uninitialized NSMutableArray in zone.

+ (id)arrayWithCapacity:(unsigned int)aNumItems	Creates and returns an NSMutableArray, giving it enough allocated memory to hold numItems objects.

- (id)initWithCapacity:(unsigned int)aNumItems	Initializes a newly allocated NSMutableArray, giving it enough memory to hold numItems objects.

Adding Objects	

- (void)addObject:(id)anObject	Inserts anObject at the end of the array. Raises NSInvalidArgumentException if anObject is nil.

- (void)addObjectsFromArray:(NSArray *)anotherArray
	Adds the objects contained in anotherArray to the end of the receiver's array.

- (void)insertObject:(id)anObject atIndex:(unsigned int)index
	Inserts anObject into the array at index. Raises
		NSInvalidArgumentException if anObject is nil. Raises NSRangeException if index is outside of the bounds of the array.	

Removing Objects

- (void)removeAllObjects	Empties the array of all its elements.

- (void)removeLastObject	Removes the last object in the array and sends it a release message. Raises NSRangeException if there are no objects in the array.

- (void)removeObject:(id)anObject	Removes all occurrences of anObject. isEqual: is used to test for anObject.

- (void)removeObjectAtIndex:(unsigned int)index	Removes the object at index and moves all elements beyond index up one slot to fill the gap. Raises NSRangeException if index is outside of the bounds of the array.	

- (void)removeObjectIdenticalTo:(id)anObject	Removes all elements having the same id as anObject.

- (void)removeObjectsFromIndices:(unsigned int*)indices	
numIndices:(unsigned int)count	Removes objects at the positions specified in the indices array, which has count elements. Raises NSRangeException if any of the indices is outside of the bounds of the array. This method is provided for efficiency reasons; it will not work if the receiver is a proxy to an array in another process.

- (void)removeObjectsInArray:(NSArray *)otherArray
	Removes from the receiver the objects found in otherArray.

Replacing Objects

- (void)replaceObjectAtIndex:(unsigned int)index	Replaces the object at index with anObject. Raises
 withObject:(id)anObject		NSInvalidArgumentException if anObject is nil. Raises NSRangeException if index is not within the bounds of the array.

- (void)setArray:(NSArray *)otherArray	Sets the contents of the receiver to the elements in otherArray

Sorting Elements

- (void)sortUsingFunction:(int (*)(id element1, id element2,void *userData))comparator
context:(void *)context	Sorts the receiver's elements in ascending order as defined by the comparison function comparator. context is passed as the function's third argument.

- (void)sortUsingSelector:(SEL)comparator	Sorts the receiver's elements in ascending order as defined by the comparison method comparator.