- Inherits from:
- NSArray : NSObject
- Conforms to:
- NSCoding
- (NSArray)
- NSCopying (NSArray)
- NSMutableCopying (NSArray)
- NSObject (NSObject)
Declared in:
- Foundation/NSArray.h
An NSMutableArray stores a modifiable array of objects.
+ arrayWithCapacity: | An empty array with enough allocated memory to hold a specified number of objects |
- 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. |
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:
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];
- 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:
+ (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:
- (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:
- (void)addObjectsFromArray:(NSArray
*)otherArray
Adds the objects contained in otherArray to the end of the receiver's array of objects.
See Also: - setArray:, - removeObject:
- (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:
- (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:
- (void)removeAllObjects
Empties the receiver of all its elements. Each removed object is sent a release message.
See Also: - removeObject:, - removeLastObject, - removeObjectAtIndex:, - removeObjectIdenticalTo:
- (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:
- (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:
- (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:
- (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:
- (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:
- (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:
- (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:
- (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:
- (void)removeObjectsInRange:(NSRange)aRange
Removes each of the objects within the specified range in the receiver using removeObjectAtIndex:.
- (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:
- (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:
- (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:
- (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:
- (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)
- (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)