Class

NSArray

NSArray and its subclass NSMutableArray manage ordered collections of objects called arrays. NSArray creates static arrays, and NSMutableArray creates dynamic arrays. You can use arrays when you need an ordered collection of objects.

Overview

NSArray is “toll-free bridged” with its Core Foundation counterpart, CFArray. See Toll-Free Bridging for more information on toll-free bridging.

Creating NSArray Objects Using Dictionary Literals

In addition to the provided initializers, such as initWithObjects:, you can create an NSArray object using an array literal.

let array: NSArray = [someObject, "Hello, World!", 42]

In Objective-C, the compiler generates code that makes an underlying call to the arrayWithObjects:count: method.

id objects[] = { someObject, @"Hello, World!", @42 };
NSUInteger count = sizeof(objects) / sizeof(id);
NSArray *array = [NSArray arrayWithObjects:objects
                                     count:count];

You should not terminate the list of objects with nil when using this literal syntax, and in fact nil is an invalid value. For more information about object literals in Objective-C, see Working with Objects in Programming with Objective-C.

In Swift, the NSArray class conforms to the ArrayLiteralConvertible protocol, which allows it to be initialized with array literals. For more information about object literals in Swift, see Literal Expression in The Swift Programming Language (Swift 3).

Accessing Values Using Subscripting

In addition to the provided instance methods, such as object(at:), you can access NSArray values by their indexes using subscripting.

let value = array[3]

Subclassing Notes

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

  • Changing how NSArray 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

Any subclass of NSArray must override the primitive instance methods count and object(at:). These methods must operate on the backing store that you provide for the elements of the collection. For this backing store you can use a static array, a standard NSArray object, or some other data type or mechanism. You may also choose to override, partially or fully, any other NSArray method for which you want to provide an alternative implementation.

You might want to implement an initializer for your subclass that is suited to the backing store that the subclass is managing. If you do, your initializer must invoke one of the designated initializers of the NSArray class, either init() or init(objects:count:). The NSArray class adopts the NSCopying, NSMutableCopying, and NSCoding protocols; custom subclasses of NSArray should override the methods in these protocols as necessary.

Remember that NSArray is the public interface for a class cluster and what this entails for your subclass. You must provide the storage for your subclass and implement the primitive methods that directly act on that storage.

Alternatives to Subclassing

Before making a custom subclass of NSArray, investigate NSPointerArray and the corresponding Core Foundation type, CFArray. Because NSArray and CFArray are “toll-free bridged,” you can substitute a CFArray object for a NSArray object in your code (with appropriate casting). Although they are corresponding types, CFArray and NSArray do not have identical interfaces or implementations, and you can sometimes do things with CFArray that you cannot easily do with NSArray. For example, CFArray provides a set of callbacks, some of which are for implementing custom retain-release behavior. If you specify NULL implementations for these callbacks, you can easily get a non-retaining array.

If the behavior you want to add supplements that of the existing class, you could write a category on NSArray. Keep in mind, however, that this category will be in effect for all instances of NSArray that you use, and this might have unintended consequences. Alternatively, you could use composition to achieve the desired behavior.

Symbols

Creating an Array

init(object: Any)

Creates and returns an array containing a given object.

Initializing an Array

init()

Initializes a newly allocated array.

init(array: [Any])

Initializes a newly allocated array by placing in it the objects contained in a given array.

init(array: [Any], copyItems: Bool)

Initializes a newly allocated array using anArray as the source of data objects for the array.

init?(contentsOfFile: String)

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

init?(contentsOf: URL)

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

init(objects: UnsafePointer<AnyObject>!, count: Int)

Initializes a newly allocated array to include a given number of objects from a given C array.

Querying an Array

func contains(Any)

Returns a Boolean value that indicates whether a given object is present in the array.

var count: Int

The number of objects in the array.

var firstObject: Any?

The first object in the array.

var lastObject: Any?

The last object in the array.

func object(at: Int)

Returns the object located at the specified index.

subscript(Int)

Returns the object at the specified index.

func objects(at: IndexSet)

Returns an array containing the objects in the array at the indexes specified by a given index set.

func objectEnumerator()

Returns an enumerator object that lets you access each object in the array.

func reverseObjectEnumerator()

Returns an enumerator object that lets you access each object in the array, in reverse order.

Finding Objects in an Array

func index(of: Any)

Returns the lowest index whose corresponding array value is equal to a given object.

func index(of: Any, in: NSRange)

Returns the lowest index within a specified range whose corresponding array value is equal to a given object .

func indexOfObjectIdentical(to: Any)

Returns the lowest index whose corresponding array value is identical to a given object.

func indexOfObjectIdentical(to: Any, in: NSRange)

Returns the lowest index within a specified range whose corresponding array value is equal to a given object .

func indexOfObject(passingTest: (Any, Int, UnsafeMutablePointer<ObjCBool>) -> Bool)

Returns the index of the first object in the array that passes a test in a given block.

func indexOfObject(options: NSEnumerationOptions = [], passingTest: (Any, Int, UnsafeMutablePointer<ObjCBool>) -> Bool)

Returns the index of an object in the array that passes a test in a given block for a given set of enumeration options.

func indexOfObject(at: IndexSet, options: NSEnumerationOptions = [], passingTest: (Any, Int, UnsafeMutablePointer<ObjCBool>) -> Bool)

Returns the index, from a given set of indexes, of the first object in the array that passes a test in a given block for a given set of enumeration options.

func indexesOfObjects(passingTest: (Any, Int, UnsafeMutablePointer<ObjCBool>) -> Bool)

Returns the indexes of objects in the array that pass a test in a given block.

func indexesOfObjects(options: NSEnumerationOptions = [], passingTest: (Any, Int, UnsafeMutablePointer<ObjCBool>) -> Bool)

Returns the indexes of objects in the array that pass a test in a given block for a given set of enumeration options.

func indexesOfObjects(at: IndexSet, options: NSEnumerationOptions = [], passingTest: (Any, Int, UnsafeMutablePointer<ObjCBool>) -> Bool)

Returns the indexes, from a given set of indexes, of objects in the array that pass a test in a given block for a given set of enumeration options.

func index(of: Any, inSortedRange: NSRange, options: NSBinarySearchingOptions = [], usingComparator: (Any, Any) -> ComparisonResult)

Returns the index, within a specified range, of an object compared with elements in the array using a given NSComparator block.

Sending Messages to Elements

func enumerateObjects((Any, Int, UnsafeMutablePointer<ObjCBool>) -> Void)

Executes a given block using each object in the array, starting with the first object and continuing through the array to the last object.

Comparing Arrays

func firstObjectCommon(with: [Any])

Returns the first object contained in the receiving array that’s equal to an object in another given array.

func isEqual(to: [Any])

Compares the receiving array to another array.

Deriving New Arrays

func adding(Any)

Returns a new array that is a copy of the receiving array with a given object added to the end.

func addingObjects(from: [Any])

Returns a new array that is a copy of the receiving array with the objects contained in another array added to the end.

func filtered(using: NSPredicate)

Evaluates a given predicate against each object in the receiving array and returns a new array containing the objects for which the predicate returns true.

func subarray(with: NSRange)

Returns a new array containing the receiving array’s elements that fall within the limits specified by a given range.

Sorting

var sortedArrayHint: Data

Analyzes the array and returns a “hint” that speeds the sorting of the array when the hint is supplied to sortedArray(_:context:hint:).

func sortedArray((Any, Any, UnsafeMutableRawPointer?) -> Int, context: UnsafeMutableRawPointer?)

Returns a new array that lists the receiving array’s elements in ascending order as defined by the comparison function comparator.

func sortedArray((Any, Any, UnsafeMutableRawPointer?) -> Int, context: UnsafeMutableRawPointer?, hint: Data?)

Returns a new array that lists the receiving array’s elements in ascending order as defined by the comparison function comparator.

func sortedArray(using: [NSSortDescriptor])

Returns a copy of the receiving array sorted as specified by a given array of sort descriptors.

func sortedArray(using: Selector)

Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given selector.

func sortedArray(comparator: (Any, Any) -> ComparisonResult)

Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given NSComparator block.

func sortedArray(options: NSSortOptions = [], usingComparator: (Any, Any) -> ComparisonResult)

Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given NSComparator block.

Working with String Elements

func componentsJoined(by: String)

Constructs and returns an NSString object that is the result of interposing a given separator between the elements of the array.

Creating a Description

var description: String

A string that represents the contents of the array, formatted as a property list.

func description(withLocale: Any?)

Returns a string that represents the contents of the array, formatted as a property list.

func description(withLocale: Any?, indent: Int)

Returns a string that represents the contents of the array, formatted as a property list.

Storing Arrays

func write(toFile: String, atomically: Bool)

Writes the contents of the array to a file at a given path.

func write(to: URL, atomically: Bool)

Writes the contents of the array to the location specified by a given URL.

Collecting Paths

func pathsMatchingExtensions([String])

Returns an array containing all the pathname elements in the receiving array that have filename extensions from a given array.

Key-Value Coding

func setValue(Any?, forKey: String)

Invokes setValue(_:forKey:) on each of the array's items using the specified value and key.

func value(forKey: String)

Returns an array containing the results of invoking value(forKey:) using key on each of the array's objects.

Randomly Shuffling an Array

func shuffled()

Returns a new array that lists this array’s elements in a random order.

func shuffled(using: GKRandomSource)

Returns a new array that lists this array’s elements in a random order, using the specified random source.

Constants

Initializers

init(array: NSArray)

Initializes a newly allocated array by placing in it the objects contained in a given array.

init(arrayLiteral: Any...)

Create an instance initialized with elements.

init(objects: Any...)

Instance Properties

Instance Methods

func makeIterator()

Return an iterator over the elements of this sequence.