Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights
Inherits From: NSArray : NSObject
Conforms To: NSCoding, NSCopying, NSMutableCopying (NSArray)
Declared In: Foundation/NSArray.h
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:
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];
Implementing Subclasses of NSMutableArray
Although conceptually the interface to the NSMutableArray class is based on the
three methods listed above, for performance reasons two
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
- - (id)initWithCapacity:(unsigned int)aNumItems Initializes a
newly allocated NSMutableArray, giving it enough memory to hold numItems
- - (void)addObject:(id)anObject Inserts anObject at the end
of the array. Raises NSInvalidArgumentException if anObject is
- - (void)addObjectsFromArray:(NSArray *)anotherArray
Adds the objects contained in anotherArray to the end of the
- - (void)insertObject:(id)anObject atIndex:(unsigned
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
- - (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
- - (void)sortUsingFunction:(int (*)(id element1, id
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