---

NSMutableArray

Class at a Glance

An NSMutableArray stores a modifiable array of objects.

Principal Attributes

• A count of the number of objects in the array

• The list of objects contained in the array

Creation

NSMutableArray

Creates a mutable array.

Commonly Used Methods

insertObjectAtIndex

Inserts an object at a specified index.

removeObject

Removes all occurrences of an object.

removeObjectAtIndex

Removes the object at a given index.

replaceObjectAtIndex

Replaces the object at a given index.

Overview

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 inherited from NSArray.

NSMutableArray methods are conceptually based on these primitive methods:

• addObject

• insertObjectAtIndex

• removeLastObject

• removeObjectAtIndex

• replaceObjectAtIndex

The other methods in its interface 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.

Tasks

Constructors

• NSMutableArray

Adding and Replacing Objects

• addObject
• addObjectsFromArray
• insertObjectAtIndex
• insertObjectsAtIndexes
• replaceObjectAtIndex
• replaceObjectsAtIndexes
• replaceObjectsInRange
• setArray

Removing Objects

• filterUsingPredicate
• removeAllObjects
• removeIdenticalObject
• removeLastObject
• removeObject
• removeObjectAtIndex
• removeObjectsAtIndexes
• removeObjectsInArray
• removeObjectsInRange

Rearranging Objects

• sortUsingDescriptors
• sortUsingSelector

Instance Methods

addObject

Inserts anObject at the end of the receiver.

public void addObject(Object anObject)

Discussion

If anObject is null, an InvalidArgumentException is thrown.

See Also

• addObjectsFromArray
• removeObject
• setArray

addObjectsFromArray

Adds the objects contained in otherArray to the end of the receiver’s array of objects.

public void addObjectsFromArray(NSArray otherArray)

See Also

• setArray
• removeObject

filterUsingPredicate

public void filterUsingPredicate(NSPredicate predicate)

Discussion

Evaluates the predicate against the receiver’s content and leaves only objects that match.

Availability

• Available in Mac OS X v10.4 and later.

insertObjectAtIndex

Inserts anObject into the receiver at index.

public void insertObjectAtIndex(Object anObject, int index)

Discussion

If index is already occupied, the objects at index and beyond are shifted by adding 1 to their indices to make room. index cannot be greater than the number of elements in the array. This method throws an InvalidArgumentException if anObject is null and throws a RangeException 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 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 fact, 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 indices 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.

See Also

• removeObjectAtIndex

insertObjectsAtIndexes

Inserts the objects in objects into the receiver at the indexes specified by indexes.

public void insertObjectsAtIndexes(NSArray objects, NSIndexSet indexes)

Discussion

Each object in objects is inserted into the receiver in turn at the corresponding location specified in indexes after earlier insertions have been made.

The locations specified by indexes may only exceed the bounds of the receiver if one location specifies the count of the array or the count of the array after preceding insertions, and other locations exceeding the bounds do so in a contiguous fashion from that location.

Availability

• Available in Mac OS X version 10.4 and later.

See Also

• insertObjectAtIndex

removeAllObjects

Empties the receiver of all its elements.

public void removeAllObjects()

See Also

• removeObject
• removeLastObject
• removeObjectAtIndex
• removeIdenticalObject

removeIdenticalObject

This method has been deprecated.

public void removeIdenticalObject(Object anObject)

This method has been deprecated.

public void removeIdenticalObject(Object anObject, NSRange aRange)

See Also

• removeAllObjects
• removeLastObject
• removeObject
• removeObjectAtIndex

removeLastObject

Removes the object with the highest-valued index in the receiver.

public void removeLastObject()

Discussion

removeLastObject throws a RangeException if there are no objects in the receiver.

See Also

• removeAllObjects
• removeObject
• removeObjectAtIndex
• removeIdenticalObject

removeObject

Removes all occurrences of anObject throughout the receiver.

public void removeObject(Object anObject)

Discussion

This method uses indexOfObject to locate matches and then removes them by using removeObjectAtIndex. Thus, matches are determined on the basis of an object’s response to the equals message.

Removes all occurrences of anObject in the specified range, aRange, of the receiver.

public void removeObject(Object anObject, NSRange aRange)

Discussion

This method uses indexOfObject to locate matches and then removes them by using removeObjectAtIndex. Thus, matches are determined on the basis of an object’s response to the equals message.

See Also

• removeAllObjects
• removeLastObject
• removeObjectAtIndex
• removeIdenticalObject
• removeObjectsInArray

removeObjectAtIndex

Removes the object at index and moves all elements beyond index by subtracting 1 from their indices to fill the gap.

public void removeObjectAtIndex(int index)

Discussion

This method throws a RangeException if index is beyond the end of the receiver.

See Also

• insertObjectAtIndex
• removeAllObjects
• removeLastObject
• removeObject
• removeIdenticalObject

removeObjectsAtIndexes

Removes the objects at the specified indexes from the receiver.

public void removeObjectsAtIndexes(NSIndexSet indexes)

Discussion

This method is similar to removeObjectAtIndex, but allows you to efficiently remove multiple objects with a single operation. indexes specifies the locations of objects to be removed given the state of the receiver when the method is invoked.

The locations specified by indexes must lie within the bounds of the receiver.

Availability

• Available in Mac OS X version 10.4 and later.

See Also

• removeObjectAtIndex

removeObjectsInArray

This method is similar to removeObject, but allows you to efficiently remove large sets of objects with a single operation.

public void removeObjectsInArray(NSArray otherArray)

Discussion

It assumes that all elements in otherArray—which are the objects to be removed—respond to hash and equals.

See Also

• removeAllObjects
• removeIdenticalObject

removeObjectsInRange

Removes each of the objects within the specified range, aRange, in the receiver using removeObjectAtIndex.

public void removeObjectsInRange(NSRange aRange)

replaceObjectAtIndex

Replaces the object at index with anObject.

public void replaceObjectAtIndex(int index, Object anObject)

Discussion

This method throws an InvalidArgumentException if anObject is null and throws a RangeException if index is beyond the end of the receiver.

See Also

• insertObjectAtIndex
• removeObjectAtIndex

replaceObjectsAtIndexes

Replaces the objects in the receiver at the locations specified by indexes with the objects from objects.

public void replaceObjectsAtIndexes(NSIndexSet indexes, NSArray objects)

Discussion

The count of locations in indexes must equal the count of objects.

Availability

• Available in Mac OS X version 10.4 and later.

See Also

• insertObjectAtIndex
• removeObjectAtIndex
• replaceObjectAtIndex

replaceObjectsInRange

Replaces the objects in the receiver specified by aRange with the objects in otherArray specified by otherRange.

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

Discussion

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.

See Also

• insertObjectAtIndex
• removeObjectAtIndex
• replaceObjectAtIndex

setArray

Sets the receiver’s elements to those in otherArray.

public void setArray(NSArray otherArray)

Discussion

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. Finally, if there are more elements in otherArray than there are in the receiver, the additional items are then added.

See Also

• addObjectsFromArray
• insertObjectAtIndex

sortUsingDescriptors

Sorts the receiver as specified by sortDescriptors.

public void sortUsingDescriptors(NSArray sortDescriptors)

Discussion

See NSSortDescriptor for additional information.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• sortUsingSelector
• sortedArrayUsingDescriptors (NSArray)

sortUsingSelector

Sorts the receiver’s elements in ascending order, as determined by the comparison method specified by the selector selector.

public void sortUsingSelector(NSSelector selector)

Discussion

The selector message is sent to each object in the array and has as its single argument another object in the array. The selector method is used to compare two elements at a time and should return OrderedAscending if the receiver is smaller than the argument, OrderedDescending if the receiver is larger than the argument, and OrderedSame if they are equal.

See Also

• sortUsingDescriptors
• sortedArrayUsingSelector (NSArray)

---