Developer Documentation
PATH  Mac OS X Documentation > Foundation Reference: Java


[Previous] [Class List] [Next]

NSMutableArray


Inherits from: NSArray : NSObject
Package: com.apple.yellow.foundation

Class at a Glance


An NSMutableArray stores a modifiable array of objects.

Principal Attributes


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.

Primitive Methods


removeLastObject




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

NSMutableArray methods are conceptually based on these three 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.


Method Types


Constructors
NSMutableArray
Adding and replacing objects
addObject
addObjectsFromArray
insertObjectAtIndex
replaceObjectAtIndex
replaceObjectsInRange
setArray
Removing objects
removeAllObjects
removeLastObject
removeObject
removeObjectAtIndex
removeIdenticalObject
removeObjectsInArray
removeObjectsInRange

Constructors


NSMutableArray

public NSMutableArray()

Creates an empty array.

public NSMutableArray(Object anObject)

Creates an array containing the single element anObject.

public NSMutableArray(Object[] objects)

Creates an array containing objects.

public NSMutableArray(NSArray anArray)

Creates an array containing the objects in anArray.



Instance Methods



addObject

public void addObject (Object anObject)

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

See Also: removeObjectaddObjectsFromArray, setArray



addObjectsFromArray

public void addObjectsFromArray (NSArray otherArray)

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

See Also: removeObjectsetArray



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 NSInvalidArgumentException if anObject is null and throws an NSRangeException 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, 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.

See Also: removeObjectAtIndex



removeAllObjects

public void removeAllObjects()

Empties the receiver of all its elements.

See Also: removeObjectremoveIdenticalObjectremoveLastObject, removeObjectAtIndex


removeIdenticalObject

public void removeIdenticalObject (Object anObject)

Removes all occurrences of anObject throughout the array. These methods use the indexOfIdenticalObject method to locate matches and then removes them by using removeObjectAtIndex. Thus, this method uses the equals method to determine a match.

public void removeIdenticalObject (Object anObject, NSRange aRange)

Removes all occurrences of anObject in the specified range of the array. These methods use the indexOfIdenticalObject method to locate matches and then removes them by using removeObjectAtIndex. Thus, this method uses the equals method to determine a match.

See Also: removeObjectremoveAllObjects, removeLastObject, removeObjectAtIndex


removeLastObject

public void removeLastObject()

Removes the object with the highest-valued index in the array. removeLastObject throws an NSRangeException if there are no objects in the array.

See Also: removeObjectremoveIdenticalObjectremoveAllObjects, removeObjectAtIndex


removeObject

public void removeObject (Object anObject)

Removes all occurrences of anObject throughout the array. 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.

public void removeObject (Object anObject, NSRange aRange)

Removes all occurrences of anObject in the specified range of the array. 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: removeObjectIdenticalTo:removeAllObjects, removeLastObject, removeObjectAtIndex, removeObjectsInArray


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 an NSRangeException if index is beyond the end of the array.

See Also: removeObjectremoveIdenticalObjectinsertObjectAtIndex, removeAllObjects, removeLastObject



removeObjectsInArray

public void removeObjectsInArray (NSArray otherArray)

This method is similar to removeObject, but allows you to efficiently remove large sets of objects with a single operation. It assumes that all elements in otherArray-which are the objects to be removed-respond to hash and equals.

This method does not distribute and therefore should be used sparingly.

See Also: removeIdenticalObjectremoveAllObjects



removeObjectsInRange

public void removeObjectsInRange (NSRange aRange)

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



replaceObjectAtIndex

public void replaceObjectAtIndex (int index, Object anObject)

Replaces the object at index with anObject. This method throws an NSInvalidArgumentException if anObject is null and throws an NSRangeException if index is beyond the end of the array.

See Also: insertObjectAtIndex, removeObjectAtIndex



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.

See Also: insertObjectAtIndex, removeObjectAtIndex



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

See Also: addObjectsFromArray, insertObjectAtIndex




[Previous] [Next]