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

Instance Methods

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.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software