Class

NSMutableArray

A dynamic ordered collection of objects.

Declaration

@interface NSMutableArray<__covariant ObjectType> : NSArray

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 is “toll-free bridged” with its Core Foundation counterpart, CFMutableArrayRef. See Toll-Free Bridging for more information.

Accessing Values Using Subscripting

In addition to the provided instance methods, such as replaceObjectAtIndex:withObject:, you can access NSArray values by their indexes using subscripting.

mutableArray[3] = @"someValue";

Subclassing Notes

There is typically little reason to subclass NSMutableArray. The class does well what it is designed to do—maintain a mutable, ordered collection of objects. But there are situations where a custom NSArray object might come in handy. Here are a few possibilities:

  • Changing how NSMutableArray stores the elements of its collection. You might do this for performance reasons or for better compatibility with legacy code.

  • Acquiring more information about what is happening to the collection (for example, statistics gathering).

Methods to Override

NSMutableArray defines five primitive methods:

In a subclass, you must override all these methods. You must also override the primitive methods of the NSArray class.

Topics

Creating and Initializing a Mutable Array

+ arrayWithCapacity:

Creates and returns an NSMutableArray object with enough allocated memory to initially hold a given number of objects.

+ arrayWithContentsOfFile:

Creates and returns a mutable array containing the contents of the file specified by the given path.

+ arrayWithContentsOfURL:

Creates and returns a mutable array containing the contents specified by a given URL.

- init

Initializes a newly allocated array.

- initWithCapacity:

Returns an array, initialized with enough memory to initially hold a given number of objects.

- initWithContentsOfFile:

Initializes a newly allocated mutable array with the contents of the file specified by a given path

- initWithContentsOfURL:

Initialized a newly allocated mutable array with the contents of the location specified by a given URL.

Adding Objects

- addObject:

Inserts a given object at the end of the array.

- addObjectsFromArray:

Adds the objects contained in another given array to the end of the receiving array’s content.

- insertObject:atIndex:

Inserts a given object into the array’s contents at a given index.

- insertObjects:atIndexes:

Inserts the objects in the provided array into the receiving array at the specified indexes.

Removing Objects

- removeAllObjects

Empties the array of all its elements.

- removeLastObject

Removes the object with the highest-valued index in the array

- removeObject:

Removes all occurrences in the array of a given object.

- removeObject:inRange:

Removes all occurrences within a specified range in the array of a given object.

- removeObjectAtIndex:

Removes the object at index .

- removeObjectsAtIndexes:

Removes the objects at the specified indexes from the array.

- removeObjectIdenticalTo:

Removes all occurrences of a given object in the array.

- removeObjectIdenticalTo:inRange:

Removes all occurrences of anObject within the specified range in the array.

- removeObjectsFromIndices:numIndices:

Removes the specified number of objects from the array, beginning at the specified index.

Deprecated
- removeObjectsInArray:

Removes from the receiving array the objects in another given array.

- removeObjectsInRange:

Removes from the array each of the objects within a given range.

Replacing Objects

- replaceObjectAtIndex:withObject:

Replaces the object at index with anObject.

- setObject:atIndexedSubscript:

Replaces the object at the index with the new object, possibly adding the object.

- replaceObjectsAtIndexes:withObjects:

Replaces the objects in the receiving array at locations specified with the objects from a given array.

- replaceObjectsInRange:withObjectsFromArray:range:

Replaces the objects in the receiving array specified by one given range with the objects in another array specified by another range.

- replaceObjectsInRange:withObjectsFromArray:

Replaces the objects in the receiving array specified by a given range with all of the objects from a given array.

- setArray:

Sets the receiving array’s elements to those in another given array.

Filtering Content

- filterUsingPredicate:

Evaluates a given predicate against the array’s content and leaves only objects that match.

Rearranging Content

- exchangeObjectAtIndex:withObjectAtIndex:

Exchanges the objects in the array at given indexes.

- sortUsingDescriptors:

Sorts the receiver using a given array of sort descriptors.

- sortUsingComparator:

Sorts the receiver in ascending order using the comparison method specified by a given NSComparator block.

- sortWithOptions:usingComparator:

Sorts the receiver in ascending order using the specified options and the comparison method specified by a given NSComparator block.

- sortUsingFunction:context:

Sorts the receiver in ascending order as defined by the comparison function compare.

- sortUsingSelector:

Sorts the receiver in ascending order, as determined by the comparison method specified by a given selector.

Initializers

Relationships

Inherits From

See Also

Basic Collections

NSArray

A static ordered collection of objects.

NSDictionary

A static collection of objects associated with unique keys.

NSMutableDictionary

A dynamic collection of objects associated with unique keys.

NSSet

A static unordered collection of unique objects.

NSMutableSet

A dynamic unordered collection of unique objects.