NSMutableArray

Inherits from:
NSArray

Package:
com.webobjects.foundation

Class Description

The NSMutableArray defines the programmatic interface for managing collections of objects called arrays. It adds insertion and deletion operations to the basic array-handling behavior inherited from its superclass, NSArray.

Table 0-7 describes the NSMutableArray methods that provide the basis for all NSMutableArray's other methods; that is, all other methods are implemented in terms of these. If you create a subclass of NSMutableArray, you need only ensure that these base methods work properly. Having done so, you can be sure that all your subclass's inherited methods operate properly.

**Table 0-7 NSMutableArray's Base API**
Method	Description
addObject	Adds an object to the array.
addObjects	Adds multiple objects to the array.
insertObjectAtIndex	Inserts an object into the array at a specified index.
removeAllObjects	Empties the receiver of all its elements.
removeObjectAtIndex	Removes the object at a specified index from the array.
`replaceObjectAtIndex(Object, int)`	Replaces the object at a specified index with another object.
setArray	Sets an array's elements to the ones in another array.
sortUsingComparator	Sorts the elements of the array.

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

Method Types

Creating mutable arrays

NSMutableArray
immutableClone
clone

Adding and replacing objects

addObject
addObjects
addObjectsFromArray
insertObjectAtIndex
replaceObjectAtIndex
replaceObjectsInRange
setArray

Removing objects

removeAllObjects
removeIdenticalObject
removeLastObject
removeObject
removeObjectAtIndex
removeObjects
removeObjectsInArray
removeObjectsInRange

Rearranging objects

sortUsingComparator

Constructors

NSMutableArray

public NSMutableArray()

Creates an empty mutable array.

public NSMutableArray(int capacity)

Creates an empty mutable array with enough allocated memory to hold the number of objects specified by capacity, a number greater than 0. NSMutableArrays expand as needed, so capacity simply establishes the object's initial capacity.

public NSMutableArray(NSArray anArray)

Creates a mutable array containing the objects in anArray.

public NSMutableArray(Object anObject)

Creates a mutable array containing the single element anObject.

public NSMutableArray(Object[] objects)

Creates a mutable array containing objects.

public NSMutableArray( Object[] objects, NSRange aRange)

Creates a mutable array containing the objects from objects in the range specified by aRange. After an immutable array has been initialized in this way, it can't be modified.

public NSMutableArray( java.util.Vector aVector, NSRange aRange, boolean checkForNull)

Creates a mutable array containing the objects from aVector in the range specified by aRange. The checkForNull argument controls the method's behavior when it encounters a null value in the vector: if checkForNull is true, the null value is simply ignored. If checkForNull is false, the method raises an IllegalArgumentException.

Instance Methods

addObject

public void addObject(Object anObject)

Inserts anObject at the end of the receiver. If anObject is null, an IllegalArgumentException is thrown.

addObjects

public void addObjects(Object[] otherArray)

Adds the objects contained in otherArray to the end of the receiver's array of objects. If any of the objects in otherArray are null, an IllegalArgumentException is thrown.

addObjectsFromArray

public void addObjectsFromArray(NSArray anArray)

Adds the objects contained in anArray to the end of the receiver's array of objects.

clone

public Object clone()

Creates a clone of the receiver. NSMutableArray's implementation simply creates a new NSMutableArray with the objects in the receiver.

immutableClone

public NSArray immutableClone()

Returns a copy of the receiver as an immutable NSArray.

insertObjectAtIndex

public void insertObjectAtIndex( Object anObject, int index)

Inserts anObject into the receiver at index. If index is already occupied, the objects at index and beyond are shifted down one slot to make room. index cannot be greater than the number of elements in the array. This method throws an IllegalArgumentException if anObject is null or if index is greater than the number of elements in the array.

Note that NSArrays are not like C arrays. That is, even though you might specify a size when you create an array, the specified size is regarded as a hint; the actual size of the array is still 0. Because of this, you can only insert new objects in ascending order-with no gaps. Once you add two objects, the array's size is 2, so you can add objects at indexes 0, 1, or 2. Index 3 is illegal and out of bounds; if you try to add an object at index 3 (when the size of the array is 2), NSMutableArray throws an exception.

mutableClone

public NSMutableArray mutableClone()

Description forthcoming.

removeAllObjects

public void removeAllObjects()

Empties the receiver of all its elements.

removeIdenticalObject

public void removeIdenticalObject(Object anObject)

public void removeIdenticalObject( Object anObject, NSRange aRange)

Removes all occurrences of anObject throughout the array; or if aRange provided, removes all occurrences of anObject in the specified range. These methods use the indexOfIdenticalObject method to locate matches and remove them by using removeObjectAtIndex. Throws an IllegalArgumentException if anObject is null or if aRange is out of bounds.

removeLastObject

public void removeLastObject()

Removes the receiver's element with the highest-valued index. Throws an IllegalArgumentException if there are no objects in the array.

removeObject

public void removeObject(Object anObject)

public void removeObject( Object anObject, NSRange aRange)

Removes all occurrences of anObject throughout the array; or if aRange provided, removes all occurrences of anObject in the specified range. These methods use the indexOfObject method to locate matches and remove them by using removeObjectAtIndex. Thus, matches are determined on the basis of an object's response to the equals message. Throws an IllegalArgumentException if anObject is null or if aRange is out of bounds.

removeObjectAtIndex

public void removeObjectAtIndex(int index)

Removes the object at index and moves all elements beyond index up one slot to fill the gap. This method throws a IllegalArgumentException if the array is empty or if index is beyond the end of the array.

removeObjects

public void removeObjects(Object[] objects)

This method is similar to removeObject, but allows you to efficiently remove the set of objects in objects with a single operation.

removeObjectsInArray

public void removeObjectsInArray(NSArray otherArray)

This method is similar to removeObject, but allows you to efficiently remove the set of objects in otherArray with a single operation.

removeObjectsInRange

public void removeObjectsInRange(NSRange aRange)

Removes each of the objects within the specified range in the receiver using removeObjectAtIndex. Throws an IllegalArgumentException if aRange is out of bounds.

replaceObjectAtIndex

public void replaceObjectAtIndex( Object anObject, int index)

Replaces the object at index with anObject. This method throws an IllegalArgumentException if anObject is null or if index is beyond the end of the array.

public void replaceObjectAtIndex( int index, Object anObject)

This method is deprecated. Use replaceObjectAtIndex(Object, int) instead.

replaceObjectsInRange

public void replaceObjectsInRange( NSRange aRange, NSArray otherArray, NSRange otherRange)

Replaces the objects in the receiver specified by aRange with the objects in otherArray specified by otherRange. aRange and otherRange don't have to be equal; if aRange is greater than otherRange, the extra objects in the receiver are removed. If otherRange is greater than aRange, the extra objects from otherArray are inserted into the receiver.

setArray

public void setArray(NSArray otherArray)

Sets the receiver's elements to those in otherArray. Shortens the receiver, if necessary, so that it contains no more than the number of elements in otherArray. Replaces existing elements in the receiver with the elements in otherArray. If there are more elements in otherArray than there are in the receiver, the additional items are added.

sortUsingComparator

public void sortUsingComparator(NSComparator aComparator) throws NSComparator.ComparisonException

Sorts the receiver's elements, as determined by aComparator. Throws an NSComparator.Exception if aComparator is null.

See Also: sortedArrayUsingComparator (NSArray)