# NSArray A static ordered collection of objects. ``` class NSArray ``` ## Overview You can use this type in Swift instead of an constant in cases that require reference semantics. `NSArray` and its subclass [`NSMutableArray`](/documentation/Foundation/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. `NSArray` is “toll-free bridged” with its Core Foundation counterpart, . See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging. ### Creating NSArray Objects Using Array Literals In addition to the provided initializers, such as [`initWithObjects:`](/documentation/Foundation/NSArray/initWithObjects:), you can create an `NSArray` object using an *array literal*. ```objc NSArray *array = @[someObject, @"Hello, World!", @42]; ``` In Objective-C, the compiler generates code that makes an underlying call to the [`init(objects:count:)`](/documentation/Foundation/NSArray/init(objects:count:)-7dct1) method. ```objc 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](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/WorkingwithObjects/WorkingwithObjects.html#//apple_ref/doc/uid/TP40011210-CH4) in [Programming with Objective-C](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html#//apple_ref/doc/uid/TP40011210). 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](https://developer.apple.com/library/archive/documentation/Swift/Conceptual/Swift_Programming_Language/Expressions.html#//apple_ref/doc/uid/TP40014097-CH32-ID390) in [The Swift Programming Language (Swift 4.1)](https://developer.apple.com/library/archive/documentation/Swift/Conceptual/Swift_Programming_Language/index.html#//apple_ref/doc/uid/TP40014097). ### Accessing Values Using Subscripting In addition to the provided instance methods, such as [`object(at:)`](/documentation/Foundation/NSArray/object(at:)), you can access `NSArray` values by their indexes using *subscripting*. ```objc id 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`](/documentation/Foundation/NSArray/count) and [`object(at:)`](/documentation/Foundation/NSArray/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()`](/documentation/Foundation/NSArray/init()) or [`init(objects:count:)`](/documentation/Foundation/NSArray/init(objects:count:)-5odxv). The `NSArray` class adopts the [`NSCopying`](/documentation/Foundation/NSCopying), [`NSMutableCopying`](/documentation/Foundation/NSMutableCopying), and [`NSCoding`](/documentation/Foundation/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`](/documentation/Foundation/NSPointerArray) and the corresponding Core Foundation type, . 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. ## Topics ### Creating an Array [`array`](/documentation/Foundation/NSArray/array) Creates and returns an empty array. [`arrayWithArray:`](/documentation/Foundation/NSArray/arrayWithArray:) Creates and returns an array containing the objects in another given array. [`arrayWithContentsOfFile:`](/documentation/Foundation/NSArray/arrayWithContentsOfFile:) Creates and returns an array containing the contents of the file specified by a given path. [`init(object:)`](/documentation/Foundation/NSArray/init(object:)) Creates and returns an array containing a given object. [`arrayWithObjects:`](/documentation/Foundation/NSArray/arrayWithObjects:) Creates and returns an array containing the objects in the argument list. [`init(objects:count:)`](/documentation/Foundation/NSArray/init(objects:count:)-7dct1) Creates and returns an array that includes a given number of objects from a given C array. ### Initializing an Array [`init()`](/documentation/Foundation/NSArray/init()) Initializes a newly allocated array. [`init(array:)`](/documentation/Foundation/NSArray/init(array:)-o72h) Initializes a newly allocated array by placing in it the objects contained in a given array. [`init(array:copyItems:)`](/documentation/Foundation/NSArray/init(array:copyItems:)) Initializes a newly allocated array using `anArray` as the source of data objects for the array. [`init(contentsOfFile:)`](/documentation/Foundation/NSArray/init(contentsOfFile:)) Initializes a newly allocated array with the contents of the file specified by a given path. [`initWithObjects:`](/documentation/Foundation/NSArray/initWithObjects:) Initializes a newly allocated array by placing in it the objects in the argument list. [`init(objects:count:)`](/documentation/Foundation/NSArray/init(objects:count:)-5odxv) Initializes a newly allocated array to include a given number of objects from a given C array. ### Querying an Array [`contains(_:)`](/documentation/Foundation/NSArray/contains(_:)) Returns a Boolean value that indicates whether a given object is present in the array. [`count`](/documentation/Foundation/NSArray/count) The number of objects in the array. [`getObjects:`](/documentation/Foundation/NSArray/getObjects:) Copies all the objects contained in the array to `aBuffer`. [`getObjects:range:`](/documentation/Foundation/NSArray/getObjects:range:) Copies references to objects contained in the array that fall within the specified range to `aBuffer`. [`firstObject`](/documentation/Foundation/NSArray/firstObject) The first object in the array. [`lastObject`](/documentation/Foundation/NSArray/lastObject) The last object in the array. [`object(at:)`](/documentation/Foundation/NSArray/object(at:)) Returns the object located at the specified index. [`subscript(_:)`](/documentation/Foundation/NSArray/subscript(_:)) Returns the object at the specified index. [`objects(at:)`](/documentation/Foundation/NSArray/objects(at:)) Returns an array containing the objects in the array at the indexes specified by a given index set. [`objectEnumerator()`](/documentation/Foundation/NSArray/objectEnumerator()) Returns an enumerator object that lets you access each object in the array. [`reverseObjectEnumerator()`](/documentation/Foundation/NSArray/reverseObjectEnumerator()) Returns an enumerator object that lets you access each object in the array, in reverse order. ### Finding Objects in an Array [`index(of:)`](/documentation/Foundation/NSArray/index(of:)) Returns the lowest index whose corresponding array value is equal to a given object. [`index(of:in:)`](/documentation/Foundation/NSArray/index(of:in:)) Returns the lowest index within a specified range whose corresponding array value is equal to a given object . [`indexOfObjectIdentical(to:)`](/documentation/Foundation/NSArray/indexOfObjectIdentical(to:)) Returns the lowest index whose corresponding array value is identical to a given object. [`indexOfObjectIdentical(to:in:)`](/documentation/Foundation/NSArray/indexOfObjectIdentical(to:in:)) Returns the lowest index within a specified range whose corresponding array value is equal to a given object . [`indexOfObject(passingTest:)`](/documentation/Foundation/NSArray/indexOfObject(passingTest:)) Returns the index of the first object in the array that passes a test in a given block. [`indexOfObject(options:passingTest:)`](/documentation/Foundation/NSArray/indexOfObject(options:passingTest:)) Returns the index of an object in the array that passes a test in a given block for a given set of enumeration options. [`indexOfObject(at:options:passingTest:)`](/documentation/Foundation/NSArray/indexOfObject(at:options:passingTest:)) 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. [`indexesOfObjects(passingTest:)`](/documentation/Foundation/NSArray/indexesOfObjects(passingTest:)) Returns the indexes of objects in the array that pass a test in a given block. [`indexesOfObjects(options:passingTest:)`](/documentation/Foundation/NSArray/indexesOfObjects(options:passingTest:)) Returns the indexes of objects in the array that pass a test in a given block for a given set of enumeration options. [`indexesOfObjects(at:options:passingTest:)`](/documentation/Foundation/NSArray/indexesOfObjects(at:options:passingTest:)) 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. [`index(of:inSortedRange:options:usingComparator:)`](/documentation/Foundation/NSArray/index(of:inSortedRange:options:usingComparator:)) 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 [`makeObjectsPerformSelector:`](/documentation/Foundation/NSArray/makeObjectsPerformSelector:) Sends to each object in the array the message identified by a given selector, starting with the first object and continuing through the array to the last object. [`makeObjectsPerformSelector:withObject:`](/documentation/Foundation/NSArray/makeObjectsPerformSelector:withObject:) Sends the `aSelector` message to each object in the array, starting with the first object and continuing through the array to the last object. [`enumerateObjects(_:)`](/documentation/Foundation/NSArray/enumerateObjects(_:)) Executes a given closure or block using each object in the array, starting with the first object and continuing through the array to the last object. [`enumerateObjects(options:using:)`](/documentation/Foundation/NSArray/enumerateObjects(options:using:)) Executes a given closure or block using each object in the array with the specified options. [`enumerateObjects(at:options:using:)`](/documentation/Foundation/NSArray/enumerateObjects(at:options:using:)) Executes a given block using the objects in the array at the specified indexes. ### Comparing Arrays [`firstObjectCommon(with:)`](/documentation/Foundation/NSArray/firstObjectCommon(with:)) Returns the first object contained in the receiving array that’s equal to an object in another given array. [`isEqual(to:)`](/documentation/Foundation/NSArray/isEqual(to:)) Compares the receiving array to another array. ### Deriving New Arrays [`adding(_:)`](/documentation/Foundation/NSArray/adding(_:)) Returns a new array that is a copy of the receiving array with a given object added to the end. [`addingObjects(from:)`](/documentation/Foundation/NSArray/addingObjects(from:)) Returns a new array that is a copy of the receiving array with the objects contained in another array added to the end. [`filtered(using:)`](/documentation/Foundation/NSArray/filtered(using:)) 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. [`subarray(with:)`](/documentation/Foundation/NSArray/subarray(with:)) Returns a new array containing the receiving array’s elements that fall within the limits specified by a given range. ### Sorting [`sortedArrayHint`](/documentation/Foundation/NSArray/sortedArrayHint) Analyzes the array and returns a “hint” that speeds the sorting of the array when the hint is supplied to [`sortedArray(_:context:hint:)`](/documentation/Foundation/NSArray/sortedArray(_:context:hint:)). [`sortedArray(_:context:)`](/documentation/Foundation/NSArray/sortedArray(_:context:)) Returns a new array that lists the receiving array’s elements in ascending order as defined by the comparison function `comparator`. [`sortedArray(_:context:hint:)`](/documentation/Foundation/NSArray/sortedArray(_:context:hint:)) Returns a new array that lists the receiving array’s elements in ascending order as defined by the comparison function `comparator`. [`sortedArray(using:)`](/documentation/Foundation/NSArray/sortedArray(using:)-82wi1) Returns a copy of the receiving array sorted as specified by a given array of sort descriptors. [`sortedArray(using:)`](/documentation/Foundation/NSArray/sortedArray(using:)-9nhh9) Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given selector. [`sortedArray(comparator:)`](/documentation/Foundation/NSArray/sortedArray(comparator:)) 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. [`sortedArray(options:usingComparator:)`](/documentation/Foundation/NSArray/sortedArray(options:usingComparator:)) 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. [`Comparator`](/documentation/Foundation/Comparator) Defines the signature for a block object used for comparison operations. ### Working with String Elements [`componentsJoined(by:)`](/documentation/Foundation/NSArray/componentsJoined(by:)) Constructs and returns an `NSString` object that is the result of interposing a given separator between the elements of the array. ### Creating a Description [`description`](/documentation/Foundation/NSArray/description) A string that represents the contents of the array, formatted as a property list. [`description(withLocale:)`](/documentation/Foundation/NSArray/description(withLocale:)) Returns a string that represents the contents of the array, formatted as a property list. [`description(withLocale:indent:)`](/documentation/Foundation/NSArray/description(withLocale:indent:)) Returns a string that represents the contents of the array, formatted as a property list. ### Storing Arrays [`write(toFile:atomically:)`](/documentation/Foundation/NSArray/write(toFile:atomically:)) Writes the contents of the array to a file at a given path. [`write(to:atomically:)`](/documentation/Foundation/NSArray/write(to:atomically:)) Writes the contents of the array to the location specified by a given URL. ### Collecting Paths [`pathsMatchingExtensions(_:)`](/documentation/Foundation/NSArray/pathsMatchingExtensions(_:)) Returns an array containing all the pathname elements in the receiving array that have filename extensions from a given array. ### Key-Value Observing [`addObserver(_:forKeyPath:options:context:)`](/documentation/Foundation/NSArray/addObserver(_:forKeyPath:options:context:)) Raises an exception. [`removeObserver(_:forKeyPath:)`](/documentation/Foundation/NSArray/removeObserver(_:forKeyPath:)) Raises an exception. [`removeObserver(_:forKeyPath:context:)`](/documentation/Foundation/NSArray/removeObserver(_:forKeyPath:context:)) Raises an exception. [`removeObserver(_:fromObjectsAt:forKeyPath:context:)`](/documentation/Foundation/NSArray/removeObserver(_:fromObjectsAt:forKeyPath:context:)) Raises an exception. [`addObserver(_:toObjectsAt:forKeyPath:options:context:)`](/documentation/Foundation/NSArray/addObserver(_:toObjectsAt:forKeyPath:options:context:)) Registers an observer to receive key value observer notifications for the specified key-path relative to the objects at the indexes. [`removeObserver(_:fromObjectsAt:forKeyPath:)`](/documentation/Foundation/NSArray/removeObserver(_:fromObjectsAt:forKeyPath:)) Removes `anObserver` from all key value observer notifications associated with the specified `keyPath` relative to the array’s objects at `indexes`. ### Key-Value Coding [`setValue(_:forKey:)`](/documentation/Foundation/NSArray/setValue(_:forKey:)) Invokes [`setValue(_:forKey:)`](/documentation/Foundation/NSArray/setValue(_:forKey:)) on each of the array’s items using the specified `value` and `key`. [`value(forKey:)`](/documentation/Foundation/NSArray/value(forKey:)) Returns an array containing the results of invoking [`value(forKey:)`](/documentation/Foundation/NSArray/value(forKey:)) using `key` on each of the array’s objects. ### Randomly Shuffling an Array [`shuffled()`](/documentation/Foundation/NSArray/shuffled()) Returns a new array that lists this array’s elements in a random order. [`shuffled(using:)`](/documentation/Foundation/NSArray/shuffled(using:)) Returns a new array that lists this array’s elements in a random order, using the specified random source. ### Comparing with Another Array [`differenceFromArray:`](/documentation/Foundation/NSArray/differenceFromArray:) Compares two arrays to create a difference object that represents the changes between them. [`differenceFromArray:withOptions:`](/documentation/Foundation/NSArray/differenceFromArray:withOptions:) Compares two arrays, with options, to create a difference object that represents the changes between them. [`differenceFromArray:withOptions:usingEquivalenceTest:`](/documentation/Foundation/NSArray/differenceFromArray:withOptions:usingEquivalenceTest:) Compares two arrays, using the provided block and with options, to create a difference object that represents the changes between them. [`NSOrderedCollectionDifference`](/documentation/Foundation/NSOrderedCollectionDifference) An object representing the difference between two ordered collections. [`NSOrderedCollectionDifferenceCalculationOptions`](/documentation/Foundation/NSOrderedCollectionDifferenceCalculationOptions) Constants that specify the options to use when creating an ordered collection difference. ### New Methods [`init(coder:)`](/documentation/Foundation/NSArray/init(coder:)) ### Constants [`NSBinarySearchingOptions`](/documentation/Foundation/NSBinarySearchingOptions) Options for searches and insertions using [`index(of:inSortedRange:options:usingComparator:)`](/documentation/Foundation/NSArray/index(of:inSortedRange:options:usingComparator:)). --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)