Mac Developer Library

Developer

Foundation Framework Reference NSMutableArray Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableArray

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in OS X v10.0 and later.

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.

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.

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

    Declaration

    Objective-C

    + (instancetype)arrayWithCapacity:(NSUInteger)numItems

    Parameters

    numItems

    The initial capacity of the new array.

    Return Value

    A new NSMutableArray object with enough allocated memory to hold numItems objects.

    Discussion

    Mutable arrays expand as needed; numItems simply establishes the object’s initial capacity.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    + (NSMutableArray *)arrayWithContentsOfFile:(NSString *)aPath

    Parameters

    aPath

    The path to a file containing a string representation of a mutable array produced by the writeToFile:atomically: method.

    Return Value

    A mutable array containing the contents of the file specified aPath. Returns nil if the file can’t be opened or if the contents of the file can’t be parsed into a mutable array.

    Discussion

    The mutable array representation in the file identified by aPath must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionaray objects). For more details, see Property List Programming Guide. The objects contained by this array are immutable even if the array is mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Objective-C

    + (NSMutableArray *)arrayWithContentsOfURL:(NSURL *)aURL

    Parameters

    aURL

    The location of the file containing a string representation of a mutable array produced by the writeToURL:atomically: method.

    Return Value

    A mutable array containing the contents specified by aURL. Returns nil if the location can’t be opened or if the contents of the location can’t be parsed into a mutable array.

    Discussion

    The array representation at the location identified by aURL must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionaray objects). The objects contained by this array are immutable even if the array is mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.10 and later.

  • init() - init Designated Initializer

    Initializes a newly allocated array.

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    Return Value

    An array.

    Discussion

    This method is a designated initializer.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.9 and later.

  • init(capacity:) - initWithCapacity: Designated Initializer

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

    Declaration

    Swift

    init(capacity numItems: Int)

    Objective-C

    - (instancetype)initWithCapacity:(NSUInteger)numItems

    Parameters

    numItems

    The initial capacity of the new array.

    Return Value

    An array initialized with enough memory to hold numItems objects. The returned object might be different than the original receiver.

    Discussion

    Mutable arrays expand as needed; numItems simply establishes the object’s initial capacity.

    This method is a designated initializer.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    convenience init?(contentsOfFile aPath: String)

    Objective-C

    - (NSMutableArray *)initWithContentsOfFile:(NSString *)aPath

    Parameters

    aPath

    The path to a file containing a representation of a mutable array produced by writeToFile:atomically: method.

    Return Value

    A mutable array initialized to contain the contents of the file specified by aPath or nil if the file can’t be opened or the contents of the file can’t be parsed into a mutable array. The returned object must be different than the original receiver.

    Discussion

    The mutable array representation in the file identified by aPath must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionaray objects). The objects contained by this array are immutable even if the array is mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    convenience init?(contentsOfURL aURL: NSURL)

    Objective-C

    - (NSMutableArray *)initWithContentsOfURL:(NSURL *)aURL

    Parameters

    aURL

    The location od a file containing a string representaion of a mutable array produced by writeToURL:atomically: method.

    Return Value

    A mutable array initialized to contain the contents specified by aURL. Returns nil if the location can’t be opened or if the contents of the location can’t be parsed into a mutable array. The returned objects must be different than the original receiver.

    Discussion

    The array representation at the location identified by aURL must contain only property list objects (NSString, NSData,NSDate, NSNumber, NSArray, or NSDictionaray objects). The objects contained by this array are immutable, even if the array is mutable.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.10 and later.

  • Inserts a given object at the end of the array.

    Declaration

    Swift

    func addObject(_ anObject: AnyObject)

    Objective-C

    - (void)addObject:(id)anObject

    Parameters

    anObject

    The object to add to the end of the array’s content. This value must not be nil.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func addObjectsFromArray(_ otherArray: [AnyObject])

    Objective-C

    - (void)addObjectsFromArray:(NSArray *)otherArray

    Parameters

    otherArray

    An array of objects to add to the end of the receiving array’s content.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func insertObject(_ anObject: AnyObject, atIndex index: Int)

    Objective-C

    - (void)insertObject:(id)anObject atIndex:(NSUInteger)index

    Parameters

    anObject

    The object to add to the array's content. This value must not be nil.

    index

    The index in the array at which to insert anObject. This value must not be greater than the count of elements in the array.

    Discussion

    If index is already occupied, the objects at index and beyond are shifted by adding 1 to their indices to make room.

    Note that NSArray objects 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. This means that you cannot insert an object at an index greater than the current count of an array. For example, if an array contains two objects, its size is 2, so you can add objects at indices 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.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func insertObjects(_ objects: [AnyObject], atIndexes indexes: NSIndexSet)

    Objective-C

    - (void)insertObjects:(NSArray *)objects atIndexes:(NSIndexSet *)indexes

    Parameters

    objects

    An array of objects to insert into the receiving array.

    indexes

    The indexes at which the objects in objects should be inserted. The count of locations in indexes must equal the count of objects. For more details, see the Discussion.

    Discussion

    Each object in objects is inserted into the receiving array in turn at the corresponding location specified in indexes after earlier insertions have been made. The implementation is conceptually similar to that illustrated in the following example.

    • - void insertObjects:(NSArray *)additions atIndexes:(NSIndexSet *)indexes
    • {
    • NSUInteger currentIndex = [indexes firstIndex];
    • NSUInteger i, count = [indexes count];
    • for (i = 0; i < count; i++)
    • {
    • [self insertObject:[additions objectAtIndex:i] atIndex:currentIndex];
    • currentIndex = [indexes indexGreaterThanIndex:currentIndex];
    • }
    • }

    The resulting behavior is illustrated by the following example.

    • NSMutableArray *array = [NSMutableArray arrayWithObjects: @"one", @"two", @"three", @"four", nil];
    • NSArray *newAdditions = [NSArray arrayWithObjects: @"a", @"b", nil];
    • NSMutableIndexSet *indexes = [NSMutableIndexSet indexSetWithIndex:1];
    • [indexes addIndex:3];
    • [array insertObjects:newAdditions atIndexes:indexes];
    • NSLog(@"array: %@", array);
    • // Output: array: (one, a, two, b, three, four)

    The locations specified by indexes may therefore only exceed the bounds of the receiving array if one location specifies the count of the array or the count of the array after preceding insertions, and other locations exceeding the bounds do so in a contiguous fashion from that location, as illustrated in the following examples.

    In this example, both new objects are appended to the end of the array.

    • NSMutableArray *array = [NSMutableArray arrayWithObjects: @"one", @"two", @"three", @"four", nil];
    • NSArray *newAdditions = [NSArray arrayWithObjects: @"a", @"b", nil];
    • NSMutableIndexSet *indexes = [NSMutableIndexSet indexSetWithIndex:5];
    • [indexes addIndex:4];
    • [array insertObjects:newAdditions atIndexes:indexes];
    • NSLog(@"array: %@", array);
    • // Output: array: (one, two, three, four, a, b)

    If you replace [indexes addIndex:4] with [indexes addIndex:6] (so that the indexes are 5 and 6), then the application will fail with an out of bounds exception.

    In this example, two objects are added into the middle of the array, and another at the current end of the array (index 4) which means that it is third from the end of the modified array.

    • NSMutableArray *array = [NSMutableArray arrayWithObjects: @"one", @"two", @"three", @"four", nil];
    • NSArray *newAdditions = [NSArray arrayWithObjects: @"a", @"b", @"c", nil];
    • NSMutableIndexSet *indexes = [NSMutableIndexSet indexSetWithIndex:1];
    • [indexes addIndex:2];
    • [indexes addIndex:4];
    • [array insertObjects:newAdditions atIndexes:indexes];
    • NSLog(@"array: %@", array);
    • // Output: array: (one, a, b, two, c, three, four)

    If you replace [indexes addIndex:4] with [indexes addIndex:6] (so that the indexes are 1, 2, and 6), then the output is (one, a, b, two, three, four, c).

    If objects or indexes is nil this method will raise an exception.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Empties the array of all its elements.

    Declaration

    Swift

    func removeAllObjects()

    Objective-C

    - (void)removeAllObjects

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeLastObject()

    Objective-C

    - (void)removeLastObject

    Discussion

    removeLastObject raises an exception NSRangeException if there are no objects in the array.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Removes all occurrences in the array of a given object.

    Declaration

    Swift

    func removeObject(_ anObject: AnyObject)

    Objective-C

    - (void)removeObject:(id)anObject

    Parameters

    anObject

    The object to remove from the array.

    Discussion

    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. If the array does not contain anObject, the method has no effect (although it does incur the overhead of searching the contents).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeObject(_ anObject: AnyObject, inRange aRange: NSRange)

    Objective-C

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

    Parameters

    anObject

    The object to be removed from the array’s content.

    aRange

    The range from which to remove anObject.

    Discussion

    Matches are determined on the basis of an object’s response to the isEqual: message. If the array does not contain anObject within aRange, the method has no effect (although it does incur the overhead of searching the contents).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Removes the object at index .

    Declaration

    Swift

    func removeObjectAtIndex(_ index: Int)

    Objective-C

    - (void)removeObjectAtIndex:(NSUInteger)index

    Parameters

    index

    The index from which to remove the object in the array. The value must not exceed the bounds of the array.

    Discussion

    To fill the gap, all elements beyond index are moved by subtracting 1 from their index.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Removes the objects at the specified indexes from the array.

    Declaration

    Swift

    func removeObjectsAtIndexes(_ indexes: NSIndexSet)

    Objective-C

    - (void)removeObjectsAtIndexes:(NSIndexSet *)indexes

    Parameters

    indexes

    The indexes of the objects to remove from the array. The locations specified by indexes must lie within the bounds of the array.

    Discussion

    This method is similar to removeObjectAtIndex:, but allows you to efficiently remove multiple objects with a single operation. indexes specifies the locations of objects to be removed given the state of the array when the method is invoked, as illustrated in the following example:

    • NSMutableArray *array = [NSMutableArray arrayWithObjects: @"one", @"a", @"two", @"b", @"three", @"four", nil];
    • NSMutableIndexSet *indexes = [NSMutableIndexSet indexSetWithIndex:1];
    • [indexes addIndex:3];
    • [array removeObjectsAtIndexes:indexes];
    • NSLog(@"array: %@", array);
    • // Output: array: (one, two, three, four)

    If indexes is nil, this method raises an exception.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Removes all occurrences of a given object in the array.

    Declaration

    Swift

    func removeObjectIdenticalTo(_ anObject: AnyObject)

    Objective-C

    - (void)removeObjectIdenticalTo:(id)anObject

    Parameters

    anObject

    The object to remove from the array.

    Discussion

    This method uses the indexOfObjectIdenticalTo: method to locate matches and then removes them by using removeObjectAtIndex:. Thus, matches are determined using object addresses. If the array does not contain anObject, the method has no effect (although it does incur the overhead of searching the contents).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeObjectIdenticalTo(_ anObject: AnyObject, inRange aRange: NSRange)

    Objective-C

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

    Parameters

    anObject

    The object to remove from the array within aRange.

    aRange

    The range in the array from which to remove anObject.

    Discussion

    This method uses the indexOfObjectIdenticalTo: method to locate matches and then removes them by using removeObjectAtIndex:. Thus, matches are determined using object addresses. If the array does not contain anObject within aRange, the method has no effect (although it does incur the overhead of searching the contents).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Deprecation Statement

    Instead ofusing this method, use removeObjectsAtIndexes: instead.

    Declaration

    Objective-C

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

    Parameters

    indices

    A C array of the indices of the objects to remove from the receiving array.

    count

    The number of objects to remove from the receiving array.

    Discussion

    This method is similar to removeObjectAtIndex:, but it allows you to efficiently remove multiple objects with a single operation. 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.

    Special Considerations

    This deprecated method uses a C array of indices. The removeObjectsAtIndexes: method uses an NSIndexSet which provides a more efficient way of indexing into an array.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Swift

    func removeObjectsInArray(_ otherArray: [AnyObject])

    Objective-C

    - (void)removeObjectsInArray:(NSArray *)otherArray

    Parameters

    otherArray

    An array containing the objects to be removed from the receiving array.

    Discussion

    This method is similar to removeObject:, but it allows you to efficiently remove large sets of objects with a single operation. If the receiving array does not contain objects in otherArray, the method has no effect (although it does incur the overhead of searching the contents).

    This method assumes that all elements in otherArray respond to hash and isEqual:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func removeObjectsInRange(_ aRange: NSRange)

    Objective-C

    - (void)removeObjectsInRange:(NSRange)aRange

    Parameters

    aRange

    The range of the objects to be removed from the array.

    Discussion

    The objects are removed using removeObjectAtIndex:.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func filterUsingPredicate(_ predicate: NSPredicate)

    Objective-C

    - (void)filterUsingPredicate:(NSPredicate *)predicate

    Parameters

    predicate

    The predicate to evaluate against the array’s elements.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    See Also

    filteredArrayUsingPredicate: (NSArray)