Generic Structure

Array

An ordered, random-access collection.

Overview

Arrays are one of the most commonly used data types in an app. You use arrays to organize your app’s data. Specifically, you use the Array type to hold elements of a single type, the array’s Element type. An array can store any kind of elements—from integers to strings to classes.

Swift makes it easy to create arrays in your code using an array literal: simply surround a comma separated list of values with square brackets. Without any other information, Swift creates an array that includes the specified values, automatically inferring the array’s Element type. For example:

// An array of 'Int' elements
let oddNumbers = [1, 3, 5, 7, 9, 11, 13, 15]

// An array of 'String' elements
let streets = ["Albemarle", "Brandywine", "Chesapeake"]

You can create an empty array by specifying the Element type of your array in the declaration. For example:

// Shortened forms are preferred
var emptyDoubles: [Double] = []

// The full type name is also allowed
var emptyFloats: Array<Float> = Array()

If you need an array that is preinitialized with a fixed number of default values, use the Array(repeating:count:) initializer.

var digitCounts = Array(repeating: 0, count: 10)
print(digitCounts)
// Prints "[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]"

Accessing Array Values

When you need to perform an operation on all of an array’s elements, use a for-in loop to iterate through the array’s contents.

for street in streets {
    print("I don't live on \(street).")
}
// Prints "I don't live on Albemarle."
// Prints "I don't live on Brandywine."
// Prints "I don't live on Chesapeake."

Use the isEmpty property to check quickly whether an array has any elements, or use the count property to find the number of elements in the array.

if oddNumbers.isEmpty {
    print("I don't know any odd numbers.")
} else {
    print("I know \(oddNumbers.count) odd numbers.")
}
// Prints "I know 8 odd numbers."

Use the first and last properties for safe access to the value of the array’s first and last elements. If the array is empty, these properties are nil.

if let firstElement = oddNumbers.first, let lastElement = oddNumbers.last {
    print(firstElement, lastElement, separator: ", ")
}
// Prints "1, 15"

print(emptyDoubles.first, emptyDoubles.last, separator: ", ")
// Prints "nil, nil"

You can access individual array elements through a subscript. The first element of a nonempty array is always at index zero. You can subscript an array with any integer from zero up to, but not including, the count of the array. Using a negative number or an index equal to or greater than count triggers a runtime error. For example:

print(oddNumbers[0], oddNumbers[3], separator: ", ")
// Prints "1, 7"

print(emptyDoubles[0])
// Triggers runtime error: Index out of range

Adding and Removing Elements

Suppose you need to store a list of the names of students that are signed up for a class you’re teaching. During the registration period, you need to add and remove names as students add and drop the class.

var students = ["Ben", "Ivy", "Jordell"]

To add single elements to the end of an array, use the append(_:) method. Add multiple elements at the same time by passing another array or a sequence of any kind to the append(contentsOf:) method.

students.append("Maxime")
students.append(contentsOf: ["Shakia", "William"])
// ["Ben", "Ivy", "Jordell", "Maxime", "Shakia", "William"]

You can add new elements in the middle of an array by using the insert(_:at:) method for single elements and by using insert(contentsOf:at:) to insert multiple elements from another collection or array literal. The elements at that index and later indices are shifted back to make room.

students.insert("Liam", at: 3)
// ["Ben", "Ivy", "Jordell", "Liam", "Maxime", "Shakia", "William"]

To remove elements from an array, use the remove(at:), removeSubrange(_:), and removeLast() methods.

// Ben's family is moving to another state
students.remove(at: 0)
// ["Ivy", "Jordell", "Liam", "Maxime", "Shakia", "William"]

// William is signing up for a different class
students.removeLast()
// ["Ivy", "Jordell", "Liam", "Maxime", "Shakia"]

You can replace an existing element with a new value by assigning the new value to the subscript.

if let i = students.index(of: "Maxime") {
    students[i] = "Max"
}
// ["Ivy", "Jordell", "Liam", "Max", "Shakia"]

Growing the Size of an Array

Every array reserves a specific amount of memory to hold its contents. When you add elements to an array and that array begins to exceed its reserved capacity, the array allocates a larger region of memory and copies its elements into the new storage. The new storage is a multiple of the old storage’s size. This exponential growth strategy means that appending an element happens in constant time, averaging the performance of many append operations. Append operations that trigger reallocation have a performance cost, but they occur less and less often as the array grows larger.

If you know approximately how many elements you will need to store, use the reserveCapacity(_:) method before appending to the array to avoid intermediate reallocations. Use the capacity and count properties to determine how many more elements the array can store without allocating larger storage.

For arrays of most Element types, this storage is a contiguous block of memory. For arrays with an Element type that is a class or @objc protocol type, this storage can be a contiguous block of memory or an instance of NSArray. Because any arbitrary subclass of NSArray can become an Array, there are no guarantees about representation or efficiency in this case.

Modifying Copies of Arrays

Each array has an independent value that includes the values of all of its elements. For simple types such as integers and other structures, this means that when you change a value in one array, the value of that element does not change in any copies of the array. For example:

var numbers = [1, 2, 3, 4, 5]
var numbersCopy = numbers
numbers[0] = 100
print(numbers)
// Prints "[100, 2, 3, 4, 5]"
print(numbersCopy)
// Prints "[1, 2, 3, 4, 5]"

If the elements in an array are instances of a class, the semantics are the same, though they might appear different at first. In this case, the values stored in the array are references to objects that live outside the array. If you change a reference to an object in one array, only that array has a reference to the new object. However, if two arrays contain references to the same object, you can observe changes to that object’s properties from both arrays. For example:

// An integer type with reference semantics
class IntegerReference {
    var value = 10
}
var firstIntegers = [IntegerReference(), IntegerReference()]
var secondIntegers = firstIntegers

// Modifications to an instance are visible from either array
firstIntegers[0].value = 100
print(secondIntegers[0].value)
// Prints "100"

// Replacements, additions, and removals are still visible
// only in the modified array
firstIntegers[0] = IntegerReference()
print(firstIntegers[0].value)
// Prints "10"
print(secondIntegers[0].value)
// Prints "100"

Arrays, like all variable-size collections in the standard library, use copy-on-write optimization. Multiple copies of an array share the same storage until you modify one of the copies. When that happens, the array being modified replaces its storage with a uniquely owned copy of itself, which is then modified in place. Optimizations are sometimes applied that can reduce the amount of copying.

This means that if an array is sharing storage with other copies, the first mutating operation on that array incurs the cost of copying the array. An array that is the sole owner of its storage can perform mutating operations in place.

In the example below, a numbers array is created along with two copies that share the same storage. When the original numbers array is modified, it makes a unique copy of its storage before making the modification. Further modifications to numbers are made in place, while the two copies continue to share the original storage.

var numbers = [1, 2, 3, 4, 5]
var firstCopy = numbers
var secondCopy = numbers

// The storage for 'numbers' is copied here
numbers[0] = 100
numbers[1] = 200
numbers[2] = 300
// 'numbers' is [100, 200, 300, 4, 5]
// 'firstCopy' and 'secondCopy' are [1, 2, 3, 4, 5]

Bridging Between Array and NSArray

When you need to access APIs that require data in an NSArray instance instead of Array, use the type-cast operator (as) to bridge your instance. For bridging to be possible, the Element type of your array must be a class, an @objc protocol (a protocol imported from Objective-C or marked with the @objc attribute), or a type that bridges to a Foundation type.

The following example shows how you can bridge an Array instance to NSArray to use the write(to:atomically:) method. In this example, the colors array can be bridged to NSArray because the colors array’s String elements bridge to NSString. The compiler prevents bridging the moreColors array, on the other hand, because its Element type is Optional<String>, which does not bridge to a Foundation type.

let colors = ["periwinkle", "rose", "moss"]
let moreColors: [String?] = ["ochre", "pine"]

let url = NSURL(fileURLWithPath: "names.plist")
(colors as NSArray).write(to: url, atomically: true)
// true

(moreColors as NSArray).write(to: url, atomically: true)
// error: cannot convert value of type '[String?]' to type 'NSArray'

Bridging from Array to NSArray takes O(1) time and O(1) space if the array’s elements are already instances of a class or an @objc protocol; otherwise, it takes O(n) time and space.

When the destination array’s element type is a class or an @objc protocol, bridging from NSArray to Array first calls the copy(with:) (- copyWithZone: in Objective-C) method on the array to get an immutable copy and then performs additional Swift bookkeeping work that takes O(1) time. For instances of NSArray that are already immutable, copy(with:) usually returns the same array in O(1) time; otherwise, the copying performance is unspecified. If copy(with:) returns the same array, the instances of NSArray and Array share storage using the same copy-on-write optimization that is used when two instances of Array share storage.

When the destination array’s element type is a nonclass type that bridges to a Foundation type, bridging from NSArray to Array performs a bridging copy of the elements to contiguous storage in O(n) time. For example, bridging from NSArray to Array<Int> performs such a copy. No further bridging is required when accessing elements of the Array instance.

Symbols

Initializers

init()

Creates a new, empty array.

init<S>(S)

Creates an array containing the elements of a sequence.

init(arrayLiteral: Element...)

Creates an array from the given array literal.

init(repeating: Element, count: Int)

Creates a new array containing the specified number of a single, repeated value.

Instance Properties

var capacity: Int

The total number of elements that the array can contain without allocating new storage.

var count: Int

The number of elements in the array.

var count: Int

The number of elements in the collection.

var customMirror: Mirror

A mirror that reflects the array.

var debugDescription: String

A textual representation of the array and its elements, suitable for debugging.

var description: String

A textual representation of the array and its elements.

var endIndex: Int

The array’s “past the end” position—that is, the position one greater than the last valid subscript argument.

var first: Element?

The first element of the collection.

var indices: DefaultRandomAccessIndices<Array<Element>>

The indices that are valid for subscripting the collection, in ascending order.

var indices: CountableRange<Int>

The indices that are valid for subscripting the collection, in ascending order.

var isEmpty: Bool

A Boolean value indicating whether the collection is empty.

var last: Element?

The last element of the collection.

var lazy: LazyCollection<Array<Element>>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

var lazy: LazySequence<Array<Element>>

A sequence containing the same elements as this sequence, but on which some operations, such as map and filter, are implemented lazily.

var lazy: LazyBidirectionalCollection<Array<Element>>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

var lazy: LazyRandomAccessCollection<Array<Element>>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

var startIndex: Int

The position of the first element in a nonempty array.

var underestimatedCount: Int

Returns a value less than or equal to the number of elements in the sequence, nondestructively.

var underestimatedCount: Int

A value less than or equal to the number of elements in the collection.

Instance Methods

func append(Element)

Adds a new element at the end of the array.

func append<S>(contentsOf: S)

Adds the elements of a sequence to the end of the array.

func contains(where: (Element) -> Bool)

Returns a Boolean value indicating whether the sequence contains an element that satisfies the given predicate.

func distance(from: Int, to: Int)

Returns the distance between two indices.

func drop(while: (Element) -> Bool)

Returns a subsequence by skipping elements while predicate returns true and returning the remaining elements.

func dropFirst()

Returns a subsequence containing all but the first element of the sequence.

func dropFirst(Int)

Returns a subsequence containing all but the given number of initial elements.

func dropLast()

Returns a subsequence containing all but the last element of the sequence.

func dropLast(Int)

Returns a subsequence containing all but the specified number of final elements.

func elementsEqual<OtherSequence>(OtherSequence)

Returns a Boolean value indicating whether this sequence and another sequence contain the same elements in the same order.

func elementsEqual<OtherSequence>(OtherSequence, by: (Element, Element) -> Bool)

Returns a Boolean value indicating whether this sequence and another sequence contain equivalent elements, using the given predicate as the equivalence test.

func enumerated()

Returns a sequence of pairs (n, x), where n represents a consecutive integer starting at zero, and x represents an element of the sequence.

func filter((Element) -> Bool)

Returns an array containing, in order, the elements of the sequence that satisfy the given predicate.

func first(where: (Element) -> Bool)

Returns the first element of the sequence that satisfies the given predicate.

func flatMap<ElementOfResult>((Element) -> ElementOfResult?)

Returns an array containing the non-nil results of calling the given transformation with each element of this sequence.

func flatMap<SegmentOfResult>((Element) -> SegmentOfResult)

Returns an array containing the concatenated results of calling the given transformation with each element of this sequence.

func forEach((Element) -> Void)

Calls the given closure on each element in the sequence in the same order as a for-in loop.

func formIndex(after: inout Int)func formIndex(before: inout Int)
func index(Int, offsetBy: Int)

Returns an index that is the specified distance from the given index.

func index(Int, offsetBy: Int, limitedBy: Int)

Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.

func index(after: Int)func index(before: Int)
func index(of: Element)

Returns the first index where the specified value appears in the collection.

func index(where: (Element) -> Bool)

Returns the first index in which an element of the collection satisfies the given predicate.

func insert(Element, at: Int)

Inserts a new element at the specified position.

func joined()

Returns the elements of this collection of collections, concatenated.

func joined()

Returns the elements of this collection of collections, concatenated.

func joined()

Returns the elements of this sequence of sequences, concatenated.

func joined(separator: String)

Returns a new string by concatenating the elements of the sequence, adding the given separator between each element.

func joined<Separator>(separator: Separator)

Returns the concatenated elements of this sequence of sequences, inserting the given separator between each element.

func lexicographicallyPrecedes<OtherSequence>(OtherSequence)

Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the less-than operator (<) to compare elements.

func lexicographicallyPrecedes<OtherSequence>(OtherSequence, by: (Element, Element) -> Bool)

Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the given predicate to compare elements.

func makeIterator()

Returns an iterator over the elements of the collection.

func map<T>((Element) -> T)

Returns an array containing the results of mapping the given closure over the sequence’s elements.

func map<T>((Element) -> T)

Returns an array containing the results of mapping the given closure over the sequence’s elements.

func max()

Returns the maximum element in the sequence.

func max(by: (Element, Element) -> Bool)

Returns the maximum element in the sequence, using the given predicate as the comparison between elements.

func min()

Returns the minimum element in the sequence.

func min(by: (Element, Element) -> Bool)

Returns the minimum element in the sequence, using the given predicate as the comparison between elements.

func partition(by: (Element) -> Bool)func partition(by: (Element) -> Bool)
func popLast()

Removes and returns the last element of the array.

func prefix(Int)

Returns a subsequence, up to the specified maximum length, containing the initial elements of the collection.

func prefix(through: Int)

Returns a subsequence from the start of the collection through the specified position.

func prefix(upTo: Int)

Returns a subsequence from the start of the collection up to, but not including, the specified position.

func prefix(while: (Element) -> Bool)

Returns a subsequence containing the initial elements until predicate returns false and skipping the remaining elements.

func reduce<Result>(Result, (Result, Element) -> Result)

Returns the result of combining the elements of the sequence using the given closure.

func remove(at: Int)

Removes and returns the element at the specified position.

func removeAll(keepingCapacity: Bool)

Removes all elements from the array.

func replaceSubrange<C>(Range<Int>, with: C)

Replaces a range of elements with the elements in the specified collection.

func reserveCapacity(Int)

Reserves enough space to store the specified number of elements.

func reversed()

Returns a view presenting the elements of the collection in reverse order.

func sort()

Sorts the collection in place.

func sort(by: (Element, Element) -> Bool)

Sorts the collection in place, using the given predicate as the comparison between elements.

func sorted()

Returns the elements of the collection, sorted.

func sorted()

Returns the elements of the sequence, sorted.

func sorted(by: (Element, Element) -> Bool)

Returns the elements of the collection, sorted using the given predicate as the comparison between elements.

func split(maxSplits: Int, omittingEmptySubsequences: Bool, whereSeparator: (Element) -> Bool)

Returns the longest possible subsequences of the collection, in order, that don’t contain elements satisfying the given predicate.

func split(separator: Element, maxSplits: Int, omittingEmptySubsequences: Bool)

Returns the longest possible subsequences of the collection, in order, around elements equal to the given element.

func split(separator: Element, maxSplits: Int, omittingEmptySubsequences: Bool)

Returns the longest possible subsequences of the sequence, in order, around elements equal to the given element.

func starts<PossiblePrefix>(with: PossiblePrefix)

Returns a Boolean value indicating whether the initial elements of the sequence are the same as the elements in another sequence.

func starts<PossiblePrefix>(with: PossiblePrefix, by: (Element, Element) -> Bool)

Returns a Boolean value indicating whether the initial elements of the sequence are equivalent to the elements in another sequence, using the given predicate as the equivalence test.

func suffix(Int)

Returns a subsequence, up to the given maximum length, containing the final elements of the collection.

func suffix(from: Int)

Returns a subsequence from the specified position to the end of the collection.

func withUnsafeBufferPointer<R>((UnsafeBufferPointer<Element>) -> R)

Calls a closure with a pointer to the array’s contiguous storage.

func withUnsafeBytes<R>((UnsafeRawBufferPointer) -> R)

Calls the given closure with a pointer to the underlying bytes of the array’s contiguous storage.

func withUnsafeMutableBufferPointer<R>((inout UnsafeMutableBufferPointer<Element>) -> R)

Calls the given closure with a pointer to the array’s mutable contiguous storage.

func withUnsafeMutableBytes<R>((UnsafeMutableRawBufferPointer) -> R)

Calls the given closure with a pointer to the underlying bytes of the array’s mutable contiguous storage.

Subscripts

subscript(Int)

Accesses the element at the specified position.

subscript(Range<Int>)

Accesses a contiguous subrange of the array’s elements.

subscript(Range<Int>)

Accesses a contiguous subrange of the collection’s elements.

subscript(Range<Int>)subscript(Range<Int>)

See Also

Related Symbols

ContiguousArray, ArraySlice, Sequence, Collection, RangeReplaceableCollection