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 othersinsertObject: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.

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

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

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