PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSMutableArray


Inherits from:
NSArray : NSObject
Conforms to:
NSCoding
(NSArray)
NSCopying (NSArray)
NSMutableCopying (NSArray)
NSObject (NSObject)
Declared in:
Foundation/NSArray.h



Class at a Glance


An NSMutableArray stores a modifiable array of objects.

Principal Attributes


Creation



+ arrayWithCapacity: An empty array with enough allocated memory to hold a specified number of objects

Commonly Used Methods



- insertObject:atIndex: Inserts an object at a specified index.
- removeObject: Removes all occurrences of an object.
- removeObjectAtIndex: Removes the object at a given index.
- replaceObjectAtIndex:withObject: Replaces the object at a given index.


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 primitive methods:

addObject:
insertObject:atIndex:
removeLastObject
removeObjectAtIndex:
replaceObjectAtIndex:withObject:

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.

When an object is removed from a mutable array, it receives a release message. If there are no further references to the object, the object is deallocated. Note that if your program keeps a reference to such an object, the reference will become invalid unless you remember to send the object a retain message before it's removed from the array. For example, if anObject isn't retained before removing it from the array, the third statement below could result in a run-time error:

id anObject = [[anArray objectAtIndex:0] retain];
[anArray removeObjectAtIndex:0];
[anObject someMessage];




Method Types


Creating an NSMutableArray
+ arrayWithCapacity:
- initWithCapacity:
Adding and replacing objects
- addObject:
- addObjectsFromArray:
- insertObject:atIndex:
- replaceObjectAtIndex:withObject:
- replaceObjectsInRange:withObjectsFromArray:
- replaceObjectsInRange:withObjectsFromArray:range:
- setArray:
Removing objects
- removeAllObjects
- removeLastObject
- removeObject:
- removeObject:inRange:
- removeObjectAtIndex:
- removeObjectIdenticalTo:
- removeObjectIdenticalTo:inRange:
- removeObjectsFromIndices:numIndices:
- removeObjectsInArray:
- removeObjectsInRange:
Rearranging objects
- sortUsingFunction:context:
- sortUsingSelector:


Class Methods



arrayWithCapacity:

+ (id)arrayWithCapacity:(unsigned)numItems

Creates and returns an NSMutableArray, giving it enough allocated memory to hold numItems objects. NSMutableArrays expand as needed, so numItems simply establishes the object's initial capacity.

See Also: - initWithCapacity:




Instance Methods



addObject:

- (void)addObject:(id)anObject

Inserts anObject at the end of the receiver. The object receives a retain message as it's added to the array. If anObject is nil, an NSInvalidArgumentException is raised.

See Also: - addObjectsFromArray:, - removeObject:, - setArray:



addObjectsFromArray:

- (void)addObjectsFromArray:(NSArray *)otherArray

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

See Also: - setArray:, - removeObject:



initWithCapacity:

- (id)initWithCapacity:(unsigned)numItems

Initializes a newly allocated array, giving it enough memory to hold numItems objects. Mutable arrays expand as needed, so numItems simply establishes the object's initial capacity. Returns self.

See Also: + arrayWithCapacity:



insertObject:atIndex:

- (void)insertObject:(id)anObject atIndex:(unsigned)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. anObject receives a retain message as it's added to the array. This method raises an NSInvalidArgumentException if anObject is nil and raises 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 raises an exception.

See Also: - removeObjectAtIndex:



removeAllObjects

- (void)removeAllObjects

Empties the receiver of all its elements. Each removed object is sent a release message.

See Also: - removeObject:, - removeLastObject, - removeObjectAtIndex:, - removeObjectIdenticalTo:



removeLastObject

- (void)removeLastObject

Removes the object with the highest-valued index in the array and sends it a release message. removeLastObject raises an NSRangeException if there are no objects in the array.

See Also: - removeAllObjects, - removeObject:, - removeObjectAtIndex:, - removeObjectIdenticalTo:



removeObject:

- (void)removeObject:(id)anObject

Removes all occurrences of anObject in 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 isEqual: message.

See Also: - removeAllObjects, - removeLastObject, - removeObjectAtIndex:, - removeObjectIdenticalTo:, - removeObjectsInArray:



removeObject:inRange:

- (void)removeObject:(id)anObject inRange:(NSRange)aRange

Removes all occurrences of anObject within the specified range in the array. Matches are determined on the basis of an object's response to the isEqual: message.

See Also: - removeAllObjects, - removeLastObject, - removeObjectAtIndex:, - removeObjectIdenticalTo:, - removeObjectsInArray:



removeObjectAtIndex:

- (void)removeObjectAtIndex:(unsigned)index

Removes the object at index and moves all elements beyond index up one slot to fill the gap. The removed object receives a release message. This method raises an NSRangeException if index is beyond the end of the array.

See Also: - insertObject:atIndex:, - removeAllObjects, - removeLastObject, - removeObject:, - removeObjectIdenticalTo:, - removeObjectsFromIndices:numIndices:



removeObjectIdenticalTo:

- (void)removeObjectIdenticalTo:(id)anObject

Removes all occurrences of anObject in the array. This method uses the indexOfObjectIdenticalTo: method to locate matches and then removes them by using removeObjectAtIndex:. Thus, matches are determined using object addresses.

See Also: - removeAllObjects, - removeLastObject, - removeObject:, - removeObjectAtIndex:



removeObjectIdenticalTo:inRange:

- (void)removeObjectIdenticalTo:(id)anObject inRange:(NSRange)aRange

Removes all occurrences of anObject within the specified range in the array. Matches are determined using object addresses.

See Also: - removeAllObjects, - removeLastObject, - removeObject:, - removeObjectAtIndex:



removeObjectsFromIndices:numIndices:

- (void)removeObjectsFromIndices:(unsigned *)indices numIndices:(unsigned)count

This method is similar to removeObjectAtIndex:, but allows you to efficiently remove multiple objects with a single operation. count indicates the number of objects to be removed, while indices points to the first in a list of indexes. Note that if you sort the list of indexes in ascending order, you will improve the speed of this operation.

This method cannot be sent to a remote object with Distributed Objects.

See Also: - initWithCapacity:, - removeObjectAtIndex:, - removeObject:inRange:



removeObjectsInArray:

- (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 isEqual:.

See Also: - removeAllObjects, - removeObjectIdenticalTo:



removeObjectsInRange:

- (void)removeObjectsInRange:(NSRange)aRange

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



replaceObjectAtIndex:withObject:

- (void)replaceObjectAtIndex:(unsigned)index withObject:(id)anObject

Replaces the object at index with anObject. anObject receives a retain message as it's added to the array, and the previous object at index receives a release message. This method raises an NSInvalidArgumentException if anObject is nil and raises an NSRangeException if index is beyond the end of the array.

See Also: - insertObject:atIndex:, - removeObjectAtIndex:



replaceObjectsInRange:withObjectsFromArray:

- (void)replaceObjectsInRange:(NSRange)aRange withObjectsFromArray:(NSArray *)otherArray

Replaces the objects in the receiver specified by aRange with all of the objects from otherArray. If otherArray has fewer objects than are specified by aRange, the extra objects in the receiver are removed. If otherArray has more objects than are specified by aRange, the extra objects from otherArray are inserted into the receiver.

See Also: - insertObject:atIndex:, - removeObjectAtIndex:, - replaceObjectAtIndex:withObject:



replaceObjectsInRange:withObjectsFromArray:range:

- (void)replaceObjectsInRange:(NSRange)aRange withObjectsFromArray:(NSArray *)otherArray range:(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: - insertObject:atIndex:, - removeObjectAtIndex:, - replaceObjectAtIndex:withObject:



setArray:

- (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, releasing those objects that are being replaced and retaining those objects that are replacing them. Finally, if there are more elements in otherArray than there are in the receiver, the additional items are then added (and retain is sent to each object as it is added to the receiver).

See Also: - addObjectsFromArray:, - insertObject:atIndex:



sortUsingFunction:context:

- (void)sortUsingFunction:(int (*)(id, id, void *))compare context:(void *)context

Sorts the receiver's elements in ascending order as defined by the comparison function compare. The comparison function is used to compare two elements at a time and should return NSOrderedAscending if the first element is smaller than the second, NSOrderedDescending if the first element is larger than the second, and NSOrderedSame if the elements are equal. Each time the comparison function is called, it's passed context as its third argument. This allows the comparison to be based on some outside parameter, such as whether character sorting is case-sensitive or case-insensitive.

See Also: - sortUsingSelector:, - sortedArrayUsingFunction:context: (NSArray)



sortUsingSelector:

- (void)sortUsingSelector:(SEL)comparator

Sorts the receiver's elements in ascending order, as determined by the comparison method specified by the selector comparator. The comparator message is sent to each object in the array, and has as its single argument another object in the array. The comparator method is used to compare two elements at a time and should return NSOrderedAscending if the receiver is smaller than the argument, NSOrderedDescending if the receiver is larger than the argument, and NSOrderedSame if they are equal.

See Also: - sortUsingFunction:context:, - sortedArrayUsingSelector: (NSArray)




Table of Contents