Mac Developer Library

Developer

Foundation Framework Reference NSMutableArray Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableArray

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. More...

Inheritance


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.0 and later.
  • 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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    import Foundation

    Availability

    Available in OS X v10.4 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

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    See Also

    filteredArrayUsingPredicate: (NSArray)