Array

struct Array<Element>

An ordered, random-access collection.

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.firstIndex(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.

Note: The ContiguousArray and ArraySlice types are not bridged; instances of those types always have a contiguous block of memory as their storage.

Inheritance BidirectionalCollection, Collection, CustomDebugStringConvertible, CustomReflectable, CustomStringConvertible, Decodable, Encodable, Equatable, ExpressibleByArrayLiteral, Hashable, MutableCollection, RandomAccessCollection, RangeReplaceableCollection, Sequence View Protocol Hierarchy →
Associated Types
Index = Int

The index type for arrays, Int.

Indices = Range<Int>

The type that represents the indices that are valid for subscripting an array, in ascending order.

Iterator = IndexingIterator<[Element]>

The type that allows iteration over an array's elements.

Import import Swift

Initializers

init()

Creates a new, empty array.

This is equivalent to initializing with an empty array literal. For example:

var emptyArray = Array<Int>()
print(emptyArray.isEmpty)
// Prints "true"

emptyArray = []
print(emptyArray.isEmpty)
// Prints "true"

Declaration

init()
init(_:)

Creates an array containing the elements of a sequence.

You can use this initializer to create an array from any other type that conforms to the Sequence protocol. For example, you might want to create an array with the integers from 1 through 7. Use this initializer around a range instead of typing all those numbers in an array literal.

let numbers = Array(1...7)
print(numbers)
// Prints "[1, 2, 3, 4, 5, 6, 7]"

You can also use this initializer to convert a complex sequence or collection type back to an array. For example, the keys property of a dictionary isn't an array with its own storage, it's a collection that maps its elements from the dictionary only when they're accessed, saving the time and space needed to allocate an array. If you need to pass those keys to a method that takes an array, however, use this initializer to convert that list from its type of LazyMapCollection<Dictionary<String, Int>, Int> to a simple [String].

func cacheImagesWithNames(names: [String]) {
    // custom image loading and caching
 }

let namedHues: [String: Int] = ["Vermillion": 18, "Magenta": 302,
        "Gold": 50, "Cerise": 320]
let colorNames = Array(namedHues.keys)
cacheImagesWithNames(colorNames)

print(colorNames)
// Prints "["Gold", "Cerise", "Magenta", "Vermillion"]"

s: The sequence of elements to turn into an array.

Declaration

init<S>(_ s: S)

Declared In

Array , RangeReplaceableCollection
init(arrayLiteral:)

Creates an array from the given array literal.

Do not call this initializer directly. It is used by the compiler when you use an array literal. Instead, create a new array by using an array literal as its value. To do this, enclose a comma-separated list of values in square brackets.

Here, an array of strings is created from an array literal holding only strings.

let ingredients = ["cocoa beans", "sugar", "cocoa butter", "salt"]

elements: A variadic list of elements of the new array.

Declaration

init(arrayLiteral elements: [Element].Element...)
init(from:)

Creates a new array by decoding from the given decoder.

This initializer throws an error if reading from the decoder fails, or if the data read is corrupted or otherwise invalid.

decoder: The decoder to read data from.

Declaration

init(from decoder: Decoder)
init(repeating:count:)

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

Here's an example of creating an array initialized with five strings containing the letter Z.

let fiveZs = Array(repeating: "Z", count: 5)
print(fiveZs)
// Prints "["Z", "Z", "Z", "Z", "Z"]"

Parameters: repeatedValue: The element to repeat. count: The number of times to repeat the value passed in the repeating parameter. count must be zero or greater.

Declaration

init(repeating repeatedValue: [Element].Element, count: Int)

Declared In

Array , RangeReplaceableCollection

Instance Variables

var capacity: Int

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

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.

The following example creates an array of integers from an array literal, then appends the elements of another collection. Before appending, the array allocates new storage that is large enough store the resulting elements.

var numbers = [10, 20, 30, 40, 50]
// numbers.count == 5
// numbers.capacity == 5

numbers.append(contentsOf: stride(from: 60, through: 100, by: 10))
// numbers.count == 10
// numbers.capacity == 12

Declaration

var capacity: Int { get }
var count: Int

The number of elements in the array.

Declaration

var count: Int { get }

Declared In

Array , Collection
var customMirror: Mirror

A mirror that reflects the array.

Declaration

var customMirror: Mirror { get }
var debugDescription: String

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

Declaration

var debugDescription: String { get }
var description: String

A textual representation of the array and its elements.

Declaration

var description: String { get }
var endIndex: Int

The array's "past the end" position---that is, the position one greater than the last valid subscript argument.

When you need a range that includes the last element of an array, use the half-open range operator (..<) with endIndex. The ..< operator creates a range that doesn't include the upper bound, so it's always safe to use with endIndex. For example:

let numbers = [10, 20, 30, 40, 50]
if let i = numbers.firstIndex(of: 30) {
    print(numbers[i ..< numbers.endIndex])
}
// Prints "[30, 40, 50]"

If the array is empty, endIndex is equal to startIndex.

Declaration

var endIndex: Int { get }
var first: Array<Element>.Element?

The first element of the collection.

If the collection is empty, the value of this property is nil.

let numbers = [10, 20, 30, 40, 50]
if let firstNumber = numbers.first {
    print(firstNumber)
}
// Prints "10"

Declaration

var first: Array<Element>.Element? { get }

Declared In

Collection
var hashValue: Int

Hashes the essential components of this value by feeding them into the given hasher.

hasher: The hasher to use when combining the components of this instance.

Declaration

var hashValue: Int { get }
var isEmpty: Bool

A Boolean value indicating whether the collection is empty.

When you need to check whether your collection is empty, use the isEmpty property instead of checking that the count property is equal to zero. For collections that don't conform to RandomAccessCollection, accessing the count property iterates through the elements of the collection.

let horseName = "Silver"
if horseName.isEmpty {
    print("I've been through the desert on a horse with no name.")
} else {
    print("Hi ho, \(horseName)!")
}
// Prints "Hi ho, Silver!")

Complexity: O(1)

Declaration

var isEmpty: Bool { get }

Declared In

Collection
var last: Array<Element>.Element?

The last element of the collection.

If the collection is empty, the value of this property is nil.

let numbers = [10, 20, 30, 40, 50]
if let lastNumber = numbers.last {
    print(lastNumber)
}
// Prints "50"

Declaration

var last: Array<Element>.Element? { get }

Declared In

BidirectionalCollection
var lazy: LazyCollection<Array<Element>>

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

Use the lazy property when chaining operations to prevent intermediate operations from allocating storage, or when you only need a part of the final collection to avoid unnecessary computation.

Declaration

var lazy: LazyCollection<Array<Element>> { get }

Declared In

Collection
var startIndex: Int

The position of the first element in a nonempty array.

For an instance of Array, startIndex is always zero. If the array is empty, startIndex is equal to endIndex.

Declaration

var startIndex: Int { get }
var underestimatedCount: Int

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

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the length of the collection.

Declaration

var underestimatedCount: Int { get }

Declared In

Collection , Sequence

Subscripts

subscript(_: (UnboundedRange_)

Declaration

subscript(x: (UnboundedRange_) -> ()) -> Array<Element>.SubSequence

Declared In

MutableCollection, Collection
subscript(_: Int)

Accesses the element at the specified position.

The following example uses indexed subscripting to update an array's second element. After assigning the new value ("Butler") at a specific position, that value is immediately available at that same position.

var streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
streets[1] = "Butler"
print(streets[1])
// Prints "Butler"

index: The position of the element to access. index must be greater than or equal to startIndex and less than endIndex.

Complexity: Reading an element from an array is O(1). Writing is O(1) unless the array's storage is shared with another array, in which case writing is O(n), where n is the length of the array. If the array uses a bridged NSArray instance as its storage, the efficiency is unspecified.

Declaration

subscript(index: Int) -> Element
subscript(_: Range<Int>)

Accesses a contiguous subrange of the array's elements.

The returned ArraySlice instance uses the same indices for the same elements as the original array. In particular, that slice, unlike an array, may have a nonzero startIndex and an endIndex that is not equal to count. Always use the slice's startIndex and endIndex properties instead of assuming that its indices start or end at a particular value.

This example demonstrates getting a slice of an array of strings, finding the index of one of the strings in the slice, and then using that index in the original array.

let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2 ..< streets.endIndex]
print(streetsSlice)
// Prints "["Channing", "Douglas", "Evarts"]"

let i = streetsSlice.firstIndex(of: "Evarts")    // 4
print(streets[i!])
// Prints "Evarts"

bounds: A range of integers. The bounds of the range must be valid indices of the array.

Declaration

subscript(bounds: Range<Int>) -> ArraySlice<Element>
subscript(_: Range<Array<Element>.Index>)

Accesses a contiguous subrange of the collection's elements.

The accessed slice uses the same indices for the same elements as the original collection. Always use the slice's startIndex property instead of assuming that its indices start at a particular value.

This example demonstrates getting a slice of an array of strings, finding the index of one of the strings in the slice, and then using that index in the original array.

let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2 ..< streets.endIndex]
print(streetsSlice)
// Prints "["Channing", "Douglas", "Evarts"]"

let index = streetsSlice.firstIndex(of: "Evarts")    // 4
streets[index!] = "Eustace"
print(streets[index!])
// Prints "Eustace"

bounds: A range of the collection's indices. The bounds of the range must be valid indices of the collection.

Declaration

subscript(bounds: Range<Array<Element>.Index>) -> Slice<Array<Element>>

Declared In

MutableCollection
subscript<R>(_: R)

Declaration

subscript<R>(r: R) -> Array<Element>.SubSequence where R : RangeExpression, Array<Element>.Index == R.Bound

Declared In

MutableCollection, Collection

Instance Methods

func allSatisfy(_:)

Returns a Boolean value indicating whether every element of a sequence satisfies a given predicate.

predicate: A closure that takes an element of the sequence as its argument and returns a Boolean value that indicates whether the passed element satisfies a condition. Returns: true if the sequence contains only elements that satisfy predicate; otherwise, false.

Declaration

func allSatisfy(_ predicate: (Array<Element>.Element) throws -> Bool) rethrows -> Bool

Declared In

Sequence
mutating func append(_:)

Adds a new element at the end of the array.

Use this method to append a single element to the end of a mutable array.

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

Because arrays increase their allocated capacity using an exponential strategy, appending a single element to an array is an O(1) operation when averaged over many calls to the append(_:) method. When an array has additional capacity and is not sharing its storage with another instance, appending an element is O(1). When an array needs to reallocate storage before appending or its storage is shared with another copy, appending is O(n), where n is the length of the array.

newElement: The element to append to the array.

Complexity: Amortized O(1) over many additions. If the array uses a bridged NSArray instance as its storage, the efficiency is unspecified.

Declaration

mutating func append(_ newElement: [Element].Element)

Declared In

Array, RangeReplaceableCollection
mutating func append(contentsOf:)

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

Use this method to append the elements of a sequence to the end of this array. This example appends the elements of a Range<Int> instance to an array of integers.

var numbers = [1, 2, 3, 4, 5]
numbers.append(contentsOf: 10...15)
print(numbers)
// Prints "[1, 2, 3, 4, 5, 10, 11, 12, 13, 14, 15]"

newElements: The elements to append to the array.

Complexity: O(n), where n is the length of the resulting array.

Declaration

mutating func append<S>(contentsOf newElements: S)

Declared In

Array, RangeReplaceableCollection
func compactMap(_:)

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

Use this method to receive an array of nonoptional values when your transformation produces an optional value.

In this example, note the difference in the result of using map and compactMap with a transformation that returns an optional Int value.

let possibleNumbers = ["1", "2", "three", "///4///", "5"]

let mapped: [Int?] = possibleNumbers.map { str in Int(str) }
// [1, 2, nil, nil, 5]

let compactMapped: [Int] = possibleNumbers.compactMap { str in Int(str) }
// [1, 2, 5]

transform: A closure that accepts an element of this sequence as its argument and returns an optional value. Returns: An array of the non-nil results of calling transform with each element of the sequence.

Complexity: O(m + n), where m is the length of this sequence and n is the length of the result.

Declaration

func compactMap<ElementOfResult>(_ transform: (Array<Element>.Element) throws -> ElementOfResult?) rethrows -> [ElementOfResult]

Declared In

Sequence
func contains(where:)

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

You can use the predicate to check for an element of a type that doesn't conform to the Equatable protocol, such as the HTTPResponse enumeration in this example.

enum HTTPResponse {
    case ok
    case error(Int)
}

let lastThreeResponses: [HTTPResponse] = [.ok, .ok, .error(404)]
let hadError = lastThreeResponses.contains { element in
    if case .error = element {
        return true
    } else {
        return false
    }
}
// 'hadError' == true

Alternatively, a predicate can be satisfied by a range of Equatable elements or a general condition. This example shows how you can check an array for an expense greater than $100.

let expenses = [21.37, 55.21, 9.32, 10.18, 388.77, 11.41]
let hasBigPurchase = expenses.contains { $0 > 100 }
// 'hasBigPurchase' == true

predicate: A closure that takes an element of the sequence as its argument and returns a Boolean value that indicates whether the passed element represents a match. Returns: true if the sequence contains an element that satisfies predicate; otherwise, false.

Declaration

func contains(where predicate: (Array<Element>.Element) throws -> Bool) rethrows -> Bool

Declared In

Sequence
func distance(from: Array<Element>.Index, to: Array<Element>.Index)

Returns the distance between two indices.

Unless the collection conforms to the BidirectionalCollection protocol, start must be less than or equal to end.

Parameters: start: A valid index of the collection. end: Another valid index of the collection. If end is equal to start, the result is zero. Returns: The distance between start and end. The result can be negative only if the collection conforms to the BidirectionalCollection protocol.

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the resulting distance.

Declaration

func distance(from start: Array<Element>.Index, to end: Array<Element>.Index) -> Int

Declared In

Collection
func distance(from:to:)

Returns the distance between two indices.

Parameters: start: A valid index of the collection. end: Another valid index of the collection. If end is equal to start, the result is zero. Returns: The distance between start and end.

Declaration

func distance(from start: Int, to end: Int) -> Int

Declared In

Array, BidirectionalCollection
func distance<T>(from: Array<Element>.Index, to: Array<Element>.Index)

Deprecated: all index distances are now of type Int.

Declaration

func distance<T>(from start: Array<Element>.Index, to end: Array<Element>.Index) -> T where T : BinaryInteger

Declared In

Collection
func drop(while:)

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

predicate: A closure that takes an element of the sequence as its argument and returns true if the element should be skipped or false if it should be included. Once the predicate returns false it will not be called again.

Complexity: O(n), where n is the length of the collection.

Declaration

func drop(while predicate: (Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>.SubSequence

Declared In

Collection
func dropFirst()

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

The following example drops the first element from an array of integers.

let numbers = [1, 2, 3, 4, 5]
print(numbers.dropFirst())
// Prints "[2, 3, 4, 5]"

If the sequence has no elements, the result is an empty subsequence.

let empty: [Int] = []
print(empty.dropFirst())
// Prints "[]"

Returns: A subsequence starting after the first element of the sequence.

Complexity: O(1)

Declaration

func dropFirst() -> Array<Element>.SubSequence

Declared In

Sequence
func dropFirst(_:)

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

If the number of elements to drop exceeds the number of elements in the collection, the result is an empty subsequence.

let numbers = [1, 2, 3, 4, 5]
print(numbers.dropFirst(2))
// Prints "[3, 4, 5]"
print(numbers.dropFirst(10))
// Prints "[]"

n: The number of elements to drop from the beginning of the collection. n must be greater than or equal to zero. Returns: A subsequence starting after the specified number of elements.

Complexity: O(n), where n is the number of elements to drop from the beginning of the collection.

Declaration

func dropFirst(_ n: Int) -> Array<Element>.SubSequence

Declared In

Collection
func dropLast()

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

The sequence must be finite.

let numbers = [1, 2, 3, 4, 5]
print(numbers.dropLast())
// Prints "[1, 2, 3, 4]"

If the sequence has no elements, the result is an empty subsequence.

let empty: [Int] = []
print(empty.dropLast())
// Prints "[]"

Returns: A subsequence leaving off the last element of the sequence.

Complexity: O(n), where n is the length of the sequence.

Declaration

func dropLast() -> Array<Element>.SubSequence

Declared In

Sequence
func dropLast(_:)

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

If the number of elements to drop exceeds the number of elements in the collection, the result is an empty subsequence.

let numbers = [1, 2, 3, 4, 5]
print(numbers.dropLast(2))
// Prints "[1, 2, 3]"
print(numbers.dropLast(10))
// Prints "[]"

n: The number of elements to drop off the end of the collection. n must be greater than or equal to zero. Returns: A subsequence that leaves off n elements from the end.

Complexity: O(n), where n is the number of elements to drop.

Declaration

func dropLast(_ n: Int) -> Array<Element>.SubSequence

Declared In

BidirectionalCollection, Collection
func elementsEqual(_:by:)

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

At least one of the sequences must be finite.

The predicate must be a equivalence relation over the elements. That is, for any elements a, b, and c, the following conditions must hold:

  • areEquivalent(a, a) is always true. (Reflexivity)
  • areEquivalent(a, b) implies areEquivalent(b, a). (Symmetry)
  • If areEquivalent(a, b) and areEquivalent(b, c) are both true, then areEquivalent(a, c) is also true. (Transitivity)

Parameters: other: A sequence to compare to this sequence. areEquivalent: A predicate that returns true if its two arguments are equivalent; otherwise, false. Returns: true if this sequence and other contain equivalent items, using areEquivalent as the equivalence test; otherwise, false.

Declaration

func elementsEqual<OtherSequence>(_ other: OtherSequence, by areEquivalent: (Array<Element>.Element, OtherSequence.Element) throws -> Bool) rethrows -> Bool where OtherSequence : Sequence

Declared In

Sequence
func encode(to:)

Encodes the elements of this array into the given encoder in an unkeyed container.

This function throws an error if any values are invalid for the given encoder's format.

encoder: The encoder to write data to.

Declaration

func encode(to encoder: Encoder) throws
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.

This example enumerates the characters of the string "Swift" and prints each character along with its place in the string.

for (n, c) in "Swift".enumerated() {
    print("\(n): '\(c)'")
}
// Prints "0: 'S'"
// Prints "1: 'w'"
// Prints "2: 'i'"
// Prints "3: 'f'"
// Prints "4: 't'"

When you enumerate a collection, the integer part of each pair is a counter for the enumeration, but is not necessarily the index of the paired value. These counters can be used as indices only in instances of zero-based, integer-indexed collections, such as Array and ContiguousArray. For other collections the counters may be out of range or of the wrong type to use as an index. To iterate over the elements of a collection with its indices, use the zip(_:_:) function.

This example iterates over the indices and elements of a set, building a list consisting of indices of names with five or fewer letters.

let names: Set = ["Sofia", "Camilla", "Martina", "Mateo", "Nicolás"]
var shorterIndices: [SetIndex<String>] = []
for (i, name) in zip(names.indices, names) {
    if name.count <= 5 {
        shorterIndices.append(i)
    }
}

Now that the shorterIndices array holds the indices of the shorter names in the names set, you can use those indices to access elements in the set.

for i in shorterIndices {
    print(names[i])
}
// Prints "Sofia"
// Prints "Mateo"

Returns: A sequence of pairs enumerating the sequence.

Declaration

func enumerated() -> EnumeratedSequence<Array<Element>>

Declared In

Sequence
func filter(_:)

Returns a new collection of the same type containing, in order, the elements of the original collection that satisfy the given predicate.

In this example, filter(_:) is used to include only names shorter than five characters.

let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let shortNames = cast.filter { $0.count < 5 }
print(shortNames)
// Prints "["Kim", "Karl"]"

isIncluded: A closure that takes an element of the sequence as its argument and returns a Boolean value indicating whether the element should be included in the returned array. Returns: An array of the elements that isIncluded allowed.

Declaration

func filter(_ isIncluded: (Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>

Declared In

RangeReplaceableCollection, Sequence
func first(where:)

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

The following example uses the first(where:) method to find the first negative number in an array of integers:

let numbers = [3, 7, 4, -2, 9, -6, 10, 1]
if let firstNegative = numbers.first(where: { $0 < 0 }) {
    print("The first negative number is \(firstNegative).")
}
// Prints "The first negative number is -2."

predicate: A closure that takes an element of the sequence as its argument and returns a Boolean value indicating whether the element is a match. Returns: The first element of the sequence that satisfies predicate, or nil if there is no element that satisfies predicate.

Declaration

func first(where predicate: (Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>.Element?

Declared In

Sequence
func firstIndex(where:)

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

You can use the predicate to find an element of a type that doesn't conform to the Equatable protocol or to find an element that matches particular criteria. Here's an example that finds a student name that begins with the letter "A":

let students = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
if let i = students.firstIndex(where: { $0.hasPrefix("A") }) {
    print("\(students[i]) starts with 'A'!")
}
// Prints "Abena starts with 'A'!"

predicate: A closure that takes an element as its argument and returns a Boolean value that indicates whether the passed element represents a match. Returns: The index of the first element for which predicate returns true. If no elements in the collection satisfy the given predicate, returns nil.

Declaration

func firstIndex(where predicate: (Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>.Index?

Declared In

Collection
func flatMap(_:)

Declaration

func flatMap(_ transform: (Array<Element>.Element) throws -> String?) rethrows -> [String]

Declared In

Collection
func flatMap<ElementOfResult>(_: (Array<Element>.Element) throws -> ElementOfResult?)

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

Use this method to receive an array of nonoptional values when your transformation produces an optional value.

In this example, note the difference in the result of using map and flatMap with a transformation that returns an optional Int value.

let possibleNumbers = ["1", "2", "three", "///4///", "5"]

let mapped: [Int?] = possibleNumbers.map { str in Int(str) }
// [1, 2, nil, nil, 5]

let flatMapped: [Int] = possibleNumbers.flatMap { str in Int(str) }
// [1, 2, 5]

transform: A closure that accepts an element of this sequence as its argument and returns an optional value. Returns: An array of the non-nil results of calling transform with each element of the sequence.

Complexity: O(m + n), where m is the length of this sequence and n is the length of the result.

Declaration

func flatMap<ElementOfResult>(_ transform: (Array<Element>.Element) throws -> ElementOfResult?) rethrows -> [ElementOfResult]

Declared In

Sequence
func flatMap<SegmentOfResult>(_: (Array<Element>.Element) throws -> SegmentOfResult)

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

Use this method to receive a single-level collection when your transformation produces a sequence or collection for each element.

In this example, note the difference in the result of using map and flatMap with a transformation that returns an array.

let numbers = [1, 2, 3, 4]

let mapped = numbers.map { Array(repeating: $0, count: $0) }
// [[1], [2, 2], [3, 3, 3], [4, 4, 4, 4]]

let flatMapped = numbers.flatMap { Array(repeating: $0, count: $0) }
// [1, 2, 2, 3, 3, 3, 4, 4, 4, 4]

In fact, s.flatMap(transform) is equivalent to Array(s.map(transform).joined()).

transform: A closure that accepts an element of this sequence as its argument and returns a sequence or collection. Returns: The resulting flattened array.

Complexity: O(m + n), where m is the length of this sequence and n is the length of the result.

Declaration

func flatMap<SegmentOfResult>(_ transform: (Array<Element>.Element) throws -> SegmentOfResult) rethrows -> [SegmentOfResult.Element] where SegmentOfResult : Sequence

Declared In

Sequence
func forEach(_:)

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

The two loops in the following example produce the same output:

let numberWords = ["one", "two", "three"]
for word in numberWords {
    print(word)
}
// Prints "one"
// Prints "two"
// Prints "three"

numberWords.forEach { word in
    print(word)
}
// Same as above

Using the forEach method is distinct from a for-in loop in two important ways:

  1. You cannot use a break or continue statement to exit the current call of the body closure or skip subsequent calls.
  2. Using the return statement in the body closure will exit only from the current call to body, not from any outer scope, and won't skip subsequent calls.

body: A closure that takes an element of the sequence as a parameter.

Declaration

func forEach(_ body: (Array<Element>.Element) throws -> Void) rethrows

Declared In

Sequence
func formIndex(_: inout Array<Element>.Index, offsetBy: Int)

Offsets the given index by the specified distance.

The value passed as n must not offset i beyond the bounds of the collection.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol.

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func formIndex(_ i: inout Array<Element>.Index, offsetBy n: Int)

Declared In

Collection
func formIndex<T>(_: inout Array<Element>.Index, offsetBy: T)

Deprecated: all index distances are now of type Int.

Declaration

func formIndex<T>(_ i: inout Array<Element>.Index, offsetBy n: T)

Declared In

Collection
func formIndex(_: inout Array<Element>.Index, offsetBy: Int, limitedBy: Array<Element>.Index)

Offsets the given index by the specified distance, or so that it equals the given limiting index.

The value passed as n must not offset i beyond the bounds of the collection, unless the index passed as limit prevents offsetting beyond those bounds.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol. limit: A valid index of the collection to use as a limit. If n > 0, a limit that is less than i has no effect. Likewise, if n < 0, a limit that is greater than i has no effect. Returns: true if i has been offset by exactly n steps without going beyond limit; otherwise, false. When the return value is false, the value of i is equal to limit.

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func formIndex(_ i: inout Array<Element>.Index, offsetBy n: Int, limitedBy limit: Array<Element>.Index) -> Bool

Declared In

Collection
func formIndex<T>(_: inout Array<Element>.Index, offsetBy: T, limitedBy: Array<Element>.Index)

Deprecated: all index distances are now of type Int.

Declaration

func formIndex<T>(_ i: inout Array<Element>.Index, offsetBy n: T, limitedBy limit: Array<Element>.Index) -> Bool where T : BinaryInteger

Declared In

Collection
func formIndex(after:)

Replaces the given index with its successor.

i: A valid index of the collection. i must be less than endIndex.

Declaration

func formIndex(after i: inout Int)

Declared In

Array, Collection
func formIndex(before:)

Replaces the given index with its predecessor.

i: A valid index of the collection. i must be greater than startIndex.

Declaration

func formIndex(before i: inout Int)

Declared In

Array, BidirectionalCollection
func hash(into:)

Hashes the essential components of this value by feeding them into the given hasher.

Implement this method to conform to the Hashable protocol. The components used for hashing must be the same as the components compared in your type's == operator implementation. Call hasher.combine(_:) with each of these components.

Important: Never call finalize() on hasher. Doing so may become a compile-time error in the future.

hasher: The hasher to use when combining the components of this instance.

Declaration

func hash(into hasher: inout Hasher)
func index(_: Array<Element>.Index, offsetBy: Int)

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

The following example obtains an index advanced four positions from a string's starting index and then prints the character at that position.

let s = "Swift"
let i = s.index(s.startIndex, offsetBy: 4)
print(s[i])
// Prints "t"

The value passed as n must not offset i beyond the bounds of the collection.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol. Returns: An index offset by n from the index i. If n is positive, this is the same value as the result of n calls to index(after:). If n is negative, this is the same value as the result of -n calls to index(before:).

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func index(_ i: Array<Element>.Index, offsetBy n: Int) -> Array<Element>.Index

Declared In

Collection
func index(_:offsetBy:)

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

The following example obtains an index advanced four positions from an array's starting index and then prints the element at that position.

let numbers = [10, 20, 30, 40, 50]
let i = numbers.index(numbers.startIndex, offsetBy: 4)
print(numbers[i])
// Prints "50"

The value passed as n must not offset i beyond the bounds of the collection.

Parameters: i: A valid index of the array. n: The distance to offset i. Returns: An index offset by n from the index i. If n is positive, this is the same value as the result of n calls to index(after:). If n is negative, this is the same value as the result of -n calls to index(before:).

Declaration

func index(_ i: Int, offsetBy n: Int) -> Int

Declared In

Array, BidirectionalCollection
func index<T>(_: Array<Element>.Index, offsetBy: T)

Deprecated: all index distances are now of type Int.

Declaration

func index<T>(_ i: Array<Element>.Index, offsetBy n: T) -> Array<Element>.Index where T : BinaryInteger

Declared In

Collection
func index(_: Array<Element>.Index, offsetBy: Int, limitedBy: Array<Element>.Index)

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

The following example obtains an index advanced four positions from a string's starting index and then prints the character at that position. The operation doesn't require going beyond the limiting s.endIndex value, so it succeeds.

let s = "Swift"
if let i = s.index(s.startIndex, offsetBy: 4, limitedBy: s.endIndex) {
    print(s[i])
}
// Prints "t"

The next example attempts to retrieve an index six positions from s.startIndex but fails, because that distance is beyond the index passed as limit.

let j = s.index(s.startIndex, offsetBy: 6, limitedBy: s.endIndex)
print(j)
// Prints "nil"

The value passed as n must not offset i beyond the bounds of the collection, unless the index passed as limit prevents offsetting beyond those bounds.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol. limit: A valid index of the collection to use as a limit. If n > 0, a limit that is less than i has no effect. Likewise, if n < 0, a limit that is greater than i has no effect. Returns: An index offset by n from the index i, unless that index would be beyond limit in the direction of movement. In that case, the method returns nil.

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func index(_ i: Array<Element>.Index, offsetBy n: Int, limitedBy limit: Array<Element>.Index) -> Array<Element>.Index?

Declared In

Collection
func index(_:offsetBy:limitedBy:)

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

The following example obtains an index advanced four positions from an array's starting index and then prints the element at that position. The operation doesn't require going beyond the limiting numbers.endIndex value, so it succeeds.

let numbers = [10, 20, 30, 40, 50]
if let i = numbers.index(numbers.startIndex,
                         offsetBy: 4,
                         limitedBy: numbers.endIndex) {
    print(numbers[i])
}
// Prints "50"

The next example attempts to retrieve an index ten positions from numbers.startIndex, but fails, because that distance is beyond the index passed as limit.

let j = numbers.index(numbers.startIndex,
                      offsetBy: 10,
                      limitedBy: numbers.endIndex)
print(j)
// Prints "nil"

The value passed as n must not offset i beyond the bounds of the collection, unless the index passed as limit prevents offsetting beyond those bounds.

Parameters: i: A valid index of the array. n: The distance to offset i. limit: A valid index of the collection to use as a limit. If n > 0, limit has no effect if it is less than i. Likewise, if n < 0, limit has no effect if it is greater than i. Returns: An index offset by n from the index i, unless that index would be beyond limit in the direction of movement. In that case, the method returns nil.

Declaration

func index(_ i: Int, offsetBy n: Int, limitedBy limit: Int) -> Int?

Declared In

Array, RandomAccessCollection, BidirectionalCollection
func index<T>(_: Array<Element>.Index, offsetBy: T, limitedBy: Array<Element>.Index)

Deprecated: all index distances are now of type Int.

Declaration

func index<T>(_ i: Array<Element>.Index, offsetBy n: T, limitedBy limit: Array<Element>.Index) -> Array<Element>.Index? where T : BinaryInteger

Declared In

Collection
func index(after:)

Returns the position immediately after the given index.

i: A valid index of the collection. i must be less than endIndex. Returns: The index immediately after i.

Declaration

func index(after i: Int) -> Int
func index(before:)

Returns the position immediately before the given index.

i: A valid index of the collection. i must be greater than startIndex. Returns: The index immediately before i.

Declaration

func index(before i: Int) -> Int
mutating func insert(_:at:)

Inserts a new element at the specified position.

The new element is inserted before the element currently at the specified index. If you pass the array's endIndex property as the index parameter, the new element is appended to the array.

var numbers = [1, 2, 3, 4, 5]
numbers.insert(100, at: 3)
numbers.insert(200, at: numbers.endIndex)

print(numbers)
// Prints "[1, 2, 3, 100, 4, 5, 200]"

newElement: The new element to insert into the array.

i: The position at which to insert the new element. index must be a valid index of the array or equal to its endIndex property.

Complexity: O(n), where n is the length of the array.

Declaration

mutating func insert(_ newElement: [Element].Element, at i: Int)

Declared In

Array, RangeReplaceableCollection
mutating func insert(contentsOf:at:)

Inserts the elements of a sequence into the collection at the specified position.

The new elements are inserted before the element currently at the specified index. If you pass the collection's endIndex property as the index parameter, the new elements are appended to the collection.

Here's an example of inserting a range of integers into an array of the same type:

var numbers = [1, 2, 3, 4, 5]
numbers.insert(contentsOf: 100...103, at: 3)
print(numbers)
// Prints "[1, 2, 3, 100, 101, 102, 103, 4, 5]"

Calling this method may invalidate any existing indices for use with this collection.

newElements: The new elements to insert into the collection.

i: The position at which to insert the new elements. index must be a valid index of the collection.

Complexity: O(m), where m is the combined length of the collection and newElements. If i is equal to the collection's endIndex property, the complexity is O(n), where n is the length of newElements.

Declaration

mutating func insert<C>(contentsOf newElements: C, at i: Array<Element>.Index)

Declared In

RangeReplaceableCollection
func last(where:)

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

This example uses the last(where:) method to find the last negative number in an array of integers:

let numbers = [3, 7, 4, -2, 9, -6, 10, 1]
if let lastNegative = numbers.last(where: { $0 < 0 }) {
    print("The last negative number is \(firstNegative).")
}
// Prints "The last negative number is -6."

predicate: A closure that takes an element of the sequence as its argument and returns a Boolean value indicating whether the element is a match. Returns: The last element of the sequence that satisfies predicate, or nil if there is no element that satisfies predicate.

Declaration

func last(where predicate: (Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>.Element?

Declared In

BidirectionalCollection
func lastIndex(where:)

Returns the index of the last element in the collection that matches the given predicate.

You can use the predicate to find an element of a type that doesn't conform to the Equatable protocol or to find an element that matches particular criteria. This example finds the index of the last name that begins with the letter "A":

let students = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
if let i = students.lastIndex(where: { $0.hasPrefix("A") }) {
    print("\(students[i]) starts with 'A'!")
}
// Prints "Akosua starts with 'A'!"

predicate: A closure that takes an element as its argument and returns a Boolean value that indicates whether the passed element represents a match. Returns: The index of the last element in the collection that matches predicate, or nil if no elements match.

Declaration

func lastIndex(where predicate: (Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>.Index?

Declared In

BidirectionalCollection
func lexicographicallyPrecedes(_:by:)

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

The predicate must be a strict weak ordering over the elements. That is, for any elements a, b, and c, the following conditions must hold:

  • areInIncreasingOrder(a, a) is always false. (Irreflexivity)
  • If areInIncreasingOrder(a, b) and areInIncreasingOrder(b, c) are both true, then areInIncreasingOrder(a, c) is also true. (Transitive comparability)
  • Two elements are incomparable if neither is ordered before the other according to the predicate. If a and b are incomparable, and b and c are incomparable, then a and c are also incomparable. (Transitive incomparability)

Parameters: other: A sequence to compare to this sequence. areInIncreasingOrder: A predicate that returns true if its first argument should be ordered before its second argument; otherwise, false. Returns: true if this sequence precedes other in a dictionary ordering as ordered by areInIncreasingOrder; otherwise, false.

Note: This method implements the mathematical notion of lexicographical ordering, which has no connection to Unicode. If you are sorting strings to present to the end user, use String APIs that perform localized comparison instead.

Declaration

func lexicographicallyPrecedes<OtherSequence>(_ other: OtherSequence, by areInIncreasingOrder: (Array<Element>.Element, Array<Element>.Element) throws -> Bool) rethrows -> Bool where OtherSequence : Sequence, Array<Element>.Element == OtherSequence.Element

Declared In

Sequence
func map(_:)

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

In this example, map is used first to convert the names in the array to lowercase strings and then to count their characters.

let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let lowercaseNames = cast.map { $0.lowercased() }
// 'lowercaseNames' == ["vivien", "marlon", "kim", "karl"]
let letterCounts = cast.map { $0.count }
// 'letterCounts' == [6, 6, 3, 4]

transform: A mapping closure. transform accepts an element of this sequence as its parameter and returns a transformed value of the same or of a different type. Returns: An array containing the transformed elements of this sequence.

Declaration

func map<T>(_ transform: (Array<Element>.Element) throws -> T) rethrows -> [T]

Declared In

Collection, Sequence
@warn_unqualified_access func max(by:)

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

The predicate must be a strict weak ordering over the elements. That is, for any elements a, b, and c, the following conditions must hold:

  • areInIncreasingOrder(a, a) is always false. (Irreflexivity)
  • If areInIncreasingOrder(a, b) and areInIncreasingOrder(b, c) are both true, then areInIncreasingOrder(a, c) is also true. (Transitive comparability)
  • Two elements are incomparable if neither is ordered before the other according to the predicate. If a and b are incomparable, and b and c are incomparable, then a and c are also incomparable. (Transitive incomparability)

This example shows how to use the max(by:) method on a dictionary to find the key-value pair with the highest value.

let hues = ["Heliotrope": 296, "Coral": 16, "Aquamarine": 156]
let greatestHue = hues.max { a, b in a.value < b.value }
print(greatestHue)
// Prints "Optional(("Heliotrope", 296))"

areInIncreasingOrder: A predicate that returns true if its first argument should be ordered before its second argument; otherwise, false. Returns: The sequence's maximum element if the sequence is not empty; otherwise, nil.

Declaration

@warn_unqualified_access func max(by areInIncreasingOrder: (Array<Element>.Element, Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>.Element?

Declared In

Sequence
func min(by:)

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

The predicate must be a strict weak ordering over the elements. That is, for any elements a, b, and c, the following conditions must hold:

  • areInIncreasingOrder(a, a) is always false. (Irreflexivity)
  • If areInIncreasingOrder(a, b) and areInIncreasingOrder(b, c) are both true, then areInIncreasingOrder(a, c) is also true. (Transitive comparability)
  • Two elements are incomparable if neither is ordered before the other according to the predicate. If a and b are incomparable, and b and c are incomparable, then a and c are also incomparable. (Transitive incomparability)

This example shows how to use the min(by:) method on a dictionary to find the key-value pair with the lowest value.

let hues = ["Heliotrope": 296, "Coral": 16, "Aquamarine": 156]
let leastHue = hues.min { a, b in a.value < b.value }
print(leastHue)
// Prints "Optional(("Coral", 16))"

areInIncreasingOrder: A predicate that returns true if its first argument should be ordered before its second argument; otherwise, false. Returns: The sequence's minimum element, according to areInIncreasingOrder. If the sequence has no elements, returns nil.

Declaration

func min(by areInIncreasingOrder: (Array<Element>.Element, Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>.Element?

Declared In

Sequence
mutating func partition(by: (Array<Element>.Element) throws -> Bool)

Reorders the elements of the collection such that all the elements that match the given predicate are after all the elements that don't match.

After partitioning a collection, there is a pivot index p where no element before p satisfies the belongsInSecondPartition predicate and every element at or after p satisfies belongsInSecondPartition.

In the following example, an array of numbers is partitioned by a predicate that matches elements greater than 30.

var numbers = [30, 40, 20, 30, 30, 60, 10]
let p = numbers.partition(by: { $0 > 30 })
// p == 5
// numbers == [30, 10, 20, 30, 30, 60, 40]

The numbers array is now arranged in two partitions. The first partition, numbers[..<p], is made up of the elements that are not greater than 30. The second partition, numbers[p...], is made up of the elements that are greater than 30.

let first = numbers[..<p]
// first == [30, 10, 20, 30, 30]
let second = numbers[p...]
// second == [60, 40]

belongsInSecondPartition: A predicate used to partition the collection. All elements satisfying this predicate are ordered after all elements not satisfying it. Returns: The index of the first element in the reordered collection that matches belongsInSecondPartition. If no elements in the collection match belongsInSecondPartition, the returned index is equal to the collection's endIndex.

Complexity: O(n)

Declaration

mutating func partition(by belongsInSecondPartition: (Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>.Index

Declared In

MutableCollection
mutating func popLast()

Removes and returns the last element of the collection.

Calling this method may invalidate all saved indices of this collection. Do not rely on a previously stored index value after altering a collection with any operation that can change its length.

Returns: The last element of the collection if the collection is not empty; otherwise, nil.

Complexity: O(1)

Declaration

mutating func popLast() -> Array<Element>.Element?

Declared In

RangeReplaceableCollection
func prefix(_:)

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

If the maximum length exceeds the number of elements in the collection, the result contains all the elements in the collection.

let numbers = [1, 2, 3, 4, 5]
print(numbers.prefix(2))
// Prints "[1, 2]"
print(numbers.prefix(10))
// Prints "[1, 2, 3, 4, 5]"

maxLength: The maximum number of elements to return. maxLength must be greater than or equal to zero. Returns: A subsequence starting at the beginning of this collection with at most maxLength elements.

Declaration

func prefix(_ maxLength: Int) -> Array<Element>.SubSequence

Declared In

Collection
func prefix(through:)

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

The resulting subsequence includes the element at the position end. The following example searches for the index of the number 40 in an array of integers, and then prints the prefix of the array up to, and including, that index:

let numbers = [10, 20, 30, 40, 50, 60]
if let i = numbers.firstIndex(of: 40) {
    print(numbers.prefix(through: i))
}
// Prints "[10, 20, 30, 40]"

Using the prefix(through:) method is equivalent to using a partial closed range as the collection's subscript. The subscript notation is preferred over prefix(through:).

if let i = numbers.firstIndex(of: 40) {
    print(numbers[...i])
}
// Prints "[10, 20, 30, 40]"

end: The index of the last element to include in the resulting subsequence. end must be a valid index of the collection that is not equal to the endIndex property. Returns: A subsequence up to, and including, the end position.

Complexity: O(1)

Declaration

func prefix(through position: Array<Element>.Index) -> Array<Element>.SubSequence

Declared In

Collection
func prefix(upTo:)

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

The resulting subsequence does not include the element at the position end. The following example searches for the index of the number 40 in an array of integers, and then prints the prefix of the array up to, but not including, that index:

let numbers = [10, 20, 30, 40, 50, 60]
if let i = numbers.firstIndex(of: 40) {
    print(numbers.prefix(upTo: i))
}
// Prints "[10, 20, 30]"

Passing the collection's starting index as the end parameter results in an empty subsequence.

print(numbers.prefix(upTo: numbers.startIndex))
// Prints "[]"

Using the prefix(upTo:) method is equivalent to using a partial half-open range as the collection's subscript. The subscript notation is preferred over prefix(upTo:).

if let i = numbers.firstIndex(of: 40) {
    print(numbers[..<i])
}
// Prints "[10, 20, 30]"

end: The "past the end" index of the resulting subsequence. end must be a valid index of the collection. Returns: A subsequence up to, but not including, the end position.

Complexity: O(1)

Declaration

func prefix(upTo end: Array<Element>.Index) -> Array<Element>.SubSequence

Declared In

Collection
func prefix(while:)

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

predicate: A closure that takes an element of the sequence as its argument and returns true if the element should be included or false if it should be excluded. Once the predicate returns false it will not be called again.

Complexity: O(n), where n is the length of the collection.

Declaration

func prefix(while predicate: (Array<Element>.Element) throws -> Bool) rethrows -> Array<Element>.SubSequence

Declared In

Collection
func randomElement()

Returns a random element of the collection.

Call randomElement() to select a random element from an array or another collection. This example picks a name at random from an array:

let names = ["Zoey", "Chloe", "Amani", "Amaia"]
let randomName = names.randomElement()!
// randomName == "Amani"

This method uses the default random generator, Random.default. The call to names.randomElement() above is equivalent to calling names.randomElement(using: &Random.default).

Returns: A random element from the collection. If the collection is empty, the method returns nil.

Declaration

func randomElement() -> Array<Element>.Element?

Declared In

Collection
func randomElement(using:)

Returns a random element of the collection, using the given generator as a source for randomness.

Call randomElement(using:) to select a random element from an array or another collection when you are using a custom random number generator. This example picks a name at random from an array:

let names = ["Zoey", "Chloe", "Amani", "Amaia"]
let randomName = names.randomElement(using: &myGenerator)!
// randomName == "Amani"

generator: The random number generator to use when choosing a random element. Returns: A random element from the collection. If the collection is empty, the method returns nil.

Declaration

func randomElement<T>(using generator: inout T) -> Array<Element>.Element? where T : RandomNumberGenerator

Declared In

Collection
func reduce(_:_:)

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

Use the reduce(_:_:) method to produce a single value from the elements of an entire sequence. For example, you can use this method on an array of numbers to find their sum or product.

The nextPartialResult closure is called sequentially with an accumulating value initialized to initialResult and each element of the sequence. This example shows how to find the sum of an array of numbers.

let numbers = [1, 2, 3, 4]
let numberSum = numbers.reduce(0, { x, y in
    x + y
})
// numberSum == 10

When numbers.reduce(_:_:) is called, the following steps occur:

  1. The nextPartialResult closure is called with initialResult---0 in this case---and the first element of numbers, returning the sum: 1.
  2. The closure is called again repeatedly with the previous call's return value and each element of the sequence.
  3. When the sequence is exhausted, the last value returned from the closure is returned to the caller.

If the sequence has no elements, nextPartialResult is never executed and initialResult is the result of the call to reduce(_:_:).

Parameters: initialResult: The value to use as the initial accumulating value. initialResult is passed to nextPartialResult the first time the closure is executed. nextPartialResult: A closure that combines an accumulating value and an element of the sequence into a new accumulating value, to be used in the next call of the nextPartialResult closure or returned to the caller. Returns: The final accumulated value. If the sequence has no elements, the result is initialResult.

Declaration

func reduce<Result>(_ initialResult: Result, _ nextPartialResult: (Result, Array<Element>.Element) throws -> Result) rethrows -> Result

Declared In

Sequence
func reduce(into:_:)

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

Use the reduce(into:_:) method to produce a single value from the elements of an entire sequence. For example, you can use this method on an array of integers to filter adjacent equal entries or count frequencies.

This method is preferred over reduce(_:_:) for efficiency when the result is a copy-on-write type, for example an Array or a Dictionary.

The updateAccumulatingResult closure is called sequentially with a mutable accumulating value initialized to initialResult and each element of the sequence. This example shows how to build a dictionary of letter frequencies of a string.

let letters = "abracadabra"
let letterCount = letters.reduce(into: [:]) { counts, letter in
    counts[letter, default: 0] += 1
}
// letterCount == ["a": 5, "b": 2, "r": 2, "c": 1, "d": 1]

When letters.reduce(into:_:) is called, the following steps occur:

  1. The updateAccumulatingResult closure is called with the initial accumulating value---[:] in this case---and the first character of letters, modifying the accumulating value by setting 1 for the key "a".
  2. The closure is called again repeatedly with the updated accumulating value and each element of the sequence.
  3. When the sequence is exhausted, the accumulating value is returned to the caller.

If the sequence has no elements, updateAccumulatingResult is never executed and initialResult is the result of the call to reduce(into:_:).

Parameters: initialResult: The value to use as the initial accumulating value. updateAccumulatingResult: A closure that updates the accumulating value with an element of the sequence. Returns: The final accumulated value. If the sequence has no elements, the result is initialResult.

Declaration

func reduce<Result>(into initialResult: Result, _ updateAccumulatingResult: (inout Result, Array<Element>.Element) throws -> ()) rethrows -> Result

Declared In

Sequence
mutating func remove(at:)

Removes and returns the element at the specified position.

All the elements following the specified position are moved up to close the gap.

var measurements: [Double] = [1.1, 1.5, 2.9, 1.2, 1.5, 1.3, 1.2]
let removed = measurements.remove(at: 2)
print(measurements)
// Prints "[1.1, 1.5, 1.2, 1.5, 1.3, 1.2]"

index: The position of the element to remove. index must be a valid index of the array. Returns: The element at the specified index.

Complexity: O(n), where n is the length of the array.

Declaration

mutating func remove(at index: Int) -> [Element].Element

Declared In

Array, RangeReplaceableCollection
mutating func removeAll(keepingCapacity:)

Removes all elements from the array.

keepCapacity: Pass true to keep the existing capacity of the array after removing its elements. The default value is false.

Complexity: O(n), where n is the length of the array.

Declaration

mutating func removeAll(keepingCapacity keepCapacity: Bool = default)

Declared In

Array, RangeReplaceableCollection
mutating func removeAll(where: (Array<Element>.Element) throws -> Bool)

Removes all the elements that satisfy the given predicate.

Use this method to remove every element in a collection that meets particular criteria. This example removes all the vowels from a string:

var phrase = "The rain in Spain stays mainly in the plain."

let vowels: Set<Character> = ["a", "e", "i", "o", "u"]
phrase.removeAll(where: { vowels.contains($0) })
// phrase == "Th rn n Spn stys mnly n th pln."

predicate: A closure that takes an element of the sequence as its argument and returns a Boolean value indicating whether the element should be removed from the collection.

Complexity: O(n), where n is the length of the collection.

Declaration

mutating func removeAll(where predicate: (Array<Element>.Element) throws -> Bool) rethrows

Declared In

RangeReplaceableCollection
mutating func removeFirst()

Removes and returns the first element of the collection.

The collection must not be empty.

var bugs = ["Aphid", "Bumblebee", "Cicada", "Damselfly", "Earwig"]
bugs.removeFirst()
print(bugs)
// Prints "["Bumblebee", "Cicada", "Damselfly", "Earwig"]"

Calling this method may invalidate any existing indices for use with this collection.

Returns: The removed element.

Complexity: O(n), where n is the length of the collection.

Declaration

mutating func removeFirst() -> Array<Element>.Element

Declared In

RangeReplaceableCollection
mutating func removeFirst(_:)

Removes the specified number of elements from the beginning of the collection.

var bugs = ["Aphid", "Bumblebee", "Cicada", "Damselfly", "Earwig"]
bugs.removeFirst(3)
print(bugs)
// Prints "["Damselfly", "Earwig"]"

Calling this method may invalidate any existing indices for use with this collection.

n: The number of elements to remove from the collection. n must be greater than or equal to zero and must not exceed the number of elements in the collection.

Complexity: O(n), where n is the length of the collection.

Declaration

mutating func removeFirst(_ n: Int)

Declared In

RangeReplaceableCollection
mutating func removeLast()

Removes and returns the last element of the collection.

The collection must not be empty.

Calling this method may invalidate all saved indices of this collection. Do not rely on a previously stored index value after altering a collection with any operation that can change its length.

Returns: The last element of the collection.

Complexity: O(1)

Declaration

mutating func removeLast() -> Array<Element>.Element

Declared In

RangeReplaceableCollection
mutating func removeLast(_:)

Removes the specified number of elements from the end of the collection.

Attempting to remove more elements than exist in the collection triggers a runtime error.

Calling this method may invalidate all saved indices of this collection. Do not rely on a previously stored index value after altering a collection with any operation that can change its length.

n: The number of elements to remove from the collection. n must be greater than or equal to zero and must not exceed the number of elements in the collection.

Complexity: O(n), where n is the specified number of elements.

Declaration

mutating func removeLast(_ n: Int)

Declared In

RangeReplaceableCollection
mutating func removeSubrange(_: Range<Array<Element>.Index>)

Removes the elements in the specified subrange from the collection.

All the elements following the specified position are moved to close the gap. This example removes three elements from the middle of an array of measurements.

var measurements = [1.2, 1.5, 2.9, 1.2, 1.5]
measurements.removeSubrange(1..<4)
print(measurements)
// Prints "[1.2, 1.5]"

Calling this method may invalidate any existing indices for use with this collection.

bounds: The range of the collection to be removed. The bounds of the range must be valid indices of the collection.

Complexity: O(n), where n is the length of the collection.

Declaration

mutating func removeSubrange(_ bounds: Range<Array<Element>.Index>)

Declared In

RangeReplaceableCollection
mutating func removeSubrange<R>(_: R)

Removes the elements in the specified subrange from the collection.

All the elements following the specified position are moved to close the gap. This example removes three elements from the middle of an array of measurements.

var measurements = [1.2, 1.5, 2.9, 1.2, 1.5]
measurements.removeSubrange(1..<4)
print(measurements)
// Prints "[1.2, 1.5]"

Calling this method may invalidate any existing indices for use with this collection.

bounds: The range of the collection to be removed. The bounds of the range must be valid indices of the collection.

Complexity: O(n), where n is the length of the collection.

Declaration

mutating func removeSubrange<R>(_ bounds: R)

Declared In

RangeReplaceableCollection
mutating func replaceSubrange(_:with:)

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

This method has the effect of removing the specified range of elements from the array and inserting the new elements at the same location. The number of new elements need not match the number of elements being removed.

In this example, three elements in the middle of an array of integers are replaced by the five elements of a Repeated<Int> instance.

 var nums = [10, 20, 30, 40, 50]
 nums.replaceSubrange(1...3, with: repeatElement(1, count: 5))
 print(nums)
 // Prints "[10, 1, 1, 1, 1, 1, 50]"

If you pass a zero-length range as the subrange parameter, this method inserts the elements of newElements at subrange.startIndex. Calling the insert(contentsOf:at:) method instead is preferred.

Likewise, if you pass a zero-length collection as the newElements parameter, this method removes the elements in the given subrange without replacement. Calling the removeSubrange(_:) method instead is preferred.

Parameters: subrange: The subrange of the array to replace. The start and end of a subrange must be valid indices of the array. newElements: The new elements to add to the array.

Complexity: O(subrange.count) if you are replacing a suffix of the array with an empty collection; otherwise, O(n), where n is the length of the array.

Declaration

mutating func replaceSubrange<C>(_ subrange: Range<Int>, with newElements: C)

Declared In

Array, RangeReplaceableCollection
mutating func reserveCapacity(_:)

Reserves enough space to store the specified number of elements.

If you are adding a known number of elements to an array, use this method to avoid multiple reallocations. This method ensures that the array has unique, mutable, contiguous storage, with space allocated for at least the requested number of elements.

Calling the reserveCapacity(_:) method on an array with bridged storage triggers a copy to contiguous storage even if the existing storage has room to store minimumCapacity elements.

For performance reasons, the size of the newly allocated storage might be greater than the requested capacity. Use the array's capacity property to determine the size of the new storage.

Preserving an Array's Geometric Growth Strategy

If you implement a custom data structure backed by an array that grows dynamically, naively calling the reserveCapacity(_:) method can lead to worse than expected performance. Arrays need to follow a geometric allocation pattern for appending elements to achieve amortized constant-time performance. The Array type's append(_:) and append(contentsOf:) methods take care of this detail for you, but reserveCapacity(_:) allocates only as much space as you tell it to (padded to a round value), and no more. This avoids over-allocation, but can result in insertion not having amortized constant-time performance.

The following code declares values, an array of integers, and the addTenQuadratic() function, which adds ten more values to the values array on each call.

  var values: [Int] = [0, 1, 2, 3]

  // Don't use 'reserveCapacity(_:)' like this
  func addTenQuadratic() {
      let newCount = values.count + 10
      values.reserveCapacity(newCount)
      for n in values.count..<newCount {
          values.append(n)
      }
  }

The call to reserveCapacity(_:) increases the values array's capacity by exactly 10 elements on each pass through addTenQuadratic(), which is linear growth. Instead of having constant time when averaged over many calls, the function may decay to performance that is linear in values.count. This is almost certainly not what you want.

In cases like this, the simplest fix is often to simply remove the call to reserveCapacity(_:), and let the append(_:) method grow the array for you.

  func addTen() {
      let newCount = values.count + 10
      for n in values.count..<newCount {
          values.append(n)
      }
  }

If you need more control over the capacity of your array, implement your own geometric growth strategy, passing the size you compute to reserveCapacity(_:).

minimumCapacity: The requested number of elements to store.

Complexity: O(n), where n is the number of elements in the array.

Declaration

mutating func reserveCapacity(_ minimumCapacity: Int)

Declared In

Array, RangeReplaceableCollection
mutating func reverse()

Reverses the elements of the collection in place.

The following example reverses the elements of an array of characters:

var characters: [Character] = ["C", "a", "f", "é"]
characters.reverse()
print(characters)
// Prints "["é", "f", "a", "C"]

Complexity: O(n), where n is the number of elements in the collection.

Declaration

mutating func reverse()

Declared In

MutableCollection
func reversed()

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

You can reverse a collection without allocating new space for its elements by calling this reversed() method. A ReversedCollection instance wraps an underlying collection and provides access to its elements in reverse order. This example prints the characters of a string in reverse order:

let word = "Backwards"
for char in word.reversed() {
    print(char, terminator: "")
}
// Prints "sdrawkcaB"

If you need a reversed collection of the same type, you may be able to use the collection's sequence-based or collection-based initializer. For example, to get the reversed version of a string, reverse its characters and initialize a new String instance from the result.

let reversedWord = String(word.reversed())
print(reversedWord)
// Prints "sdrawkcaB"

Complexity: O(1)

Declaration

func reversed() -> ReversedCollection<Array<Element>>

Declared In

BidirectionalCollection, Sequence
mutating func shuffle()

Shuffles the collection in place.

Use the shuffle() method to randomly reorder the elements of an array.

var names = ["Alejandro", "Camila", "Diego", "Luciana", "Luis", "Sofía"]
names.shuffle(using: myGenerator)
// names == ["Luis", "Camila", "Luciana", "Sofía", "Alejandro", "Diego"]

This method uses the default random generator, Random.default. The call to names.shuffle() above is equivalent to calling names.shuffle(using: &Random.default).

Complexity: O(n)

Declaration

mutating func shuffle()

Declared In

MutableCollection
mutating func shuffle(using:)

Shuffles the collection in place, using the given generator as a source for randomness.

You use this method to randomize the elements of a collection when you are using a custom random number generator. For example, you can use the shuffle(using:) method to randomly reorder the elements of an array.

var names = ["Alejandro", "Camila", "Diego", "Luciana", "Luis", "Sofía"]
names.shuffle(using: &myGenerator)
// names == ["Sofía", "Alejandro", "Camila", "Luis", "Diego", "Luciana"]

generator: The random number generator to use when shuffling the collection.

Complexity: O(n)

Declaration

mutating func shuffle<T>(using generator: inout T)

Declared In

MutableCollection
func shuffled()

Returns the elements of the sequence, shuffled.

For example, you can shuffle the numbers between 0 and 9 by calling the shuffled() method on that range:

let numbers = 0...9
let shuffledNumbers = numbers.shuffled()
// shuffledNumbers == [1, 7, 6, 2, 8, 9, 4, 3, 5, 0]

This method uses the default random generator, Random.default. The call to numbers.shuffled() above is equivalent to calling numbers.shuffled(using: &Random.default).

Returns: A shuffled array of this sequence's elements.

Complexity: O(n)

Declaration

func shuffled() -> [Array<Element>.Element]

Declared In

Sequence
func shuffled(using:)

Returns the elements of the sequence, shuffled using the given generator as a source for randomness.

You use this method to randomize the elements of a sequence when you are using a custom random number generator. For example, you can shuffle the numbers between 0 and 9 by calling the shuffled(using:) method on that range:

let numbers = 0...9
let shuffledNumbers = numbers.shuffled(using: &myGenerator)
// shuffledNumbers == [8, 9, 4, 3, 2, 6, 7, 0, 5, 1]

generator: The random number generator to use when shuffling the sequence. Returns: An array of this sequence's elements in a shuffled order.

Complexity: O(n)

Declaration

func shuffled<T>(using generator: inout T) -> [Array<Element>.Element] where T : RandomNumberGenerator

Declared In

Sequence
mutating func sort(by:)

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

When you want to sort a collection of elements that doesn't conform to the Comparable protocol, pass a closure to this method that returns true when the first element passed should be ordered before the second.

The predicate must be a strict weak ordering over the elements. That is, for any elements a, b, and c, the following conditions must hold:

  • areInIncreasingOrder(a, a) is always false. (Irreflexivity)
  • If areInIncreasingOrder(a, b) and areInIncreasingOrder(b, c) are both true, then areInIncreasingOrder(a, c) is also true. (Transitive comparability)
  • Two elements are incomparable if neither is ordered before the other according to the predicate. If a and b are incomparable, and b and c are incomparable, then a and c are also incomparable. (Transitive incomparability)

The sorting algorithm is not stable. A nonstable sort may change the relative order of elements for which areInIncreasingOrder does not establish an order.

In the following example, the closure provides an ordering for an array of a custom enumeration that describes an HTTP response. The predicate orders errors before successes and sorts the error responses by their error code.

enum HTTPResponse {
    case ok
    case error(Int)
}

var responses: [HTTPResponse] = [.error(500), .ok, .ok, .error(404), .error(403)]
responses.sort {
    switch ($0, $1) {
    // Order errors by code
    case let (.error(aCode), .error(bCode)):
        return aCode < bCode

    // All successes are equivalent, so none is before any other
    case (.ok, .ok): return false

    // Order errors before successes
    case (.error, .ok): return true
    case (.ok, .error): return false
    }
}
print(responses)
// Prints "[.error(403), .error(404), .error(500), .ok, .ok]"

Alternatively, use this method to sort a collection of elements that do conform to Comparable when you want the sort to be descending instead of ascending. Pass the greater-than operator (>) operator as the predicate.

var students = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
students.sort(by: >)
print(students)
// Prints "["Peter", "Kweku", "Kofi", "Akosua", "Abena"]"

areInIncreasingOrder: A predicate that returns true if its first argument should be ordered before its second argument; otherwise, false. If areInIncreasingOrder throws an error during the sort, the elements may be in a different order, but none will be lost.

Declaration

mutating func sort(by areInIncreasingOrder: (Array<Element>.Element, Array<Element>.Element) throws -> Bool) rethrows

Declared In

MutableCollection
func sorted(by:)

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

When you want to sort a sequence of elements that don't conform to the Comparable protocol, pass a predicate to this method that returns true when the first element passed should be ordered before the second. The elements of the resulting array are ordered according to the given predicate.

The predicate must be a strict weak ordering over the elements. That is, for any elements a, b, and c, the following conditions must hold:

  • areInIncreasingOrder(a, a) is always false. (Irreflexivity)
  • If areInIncreasingOrder(a, b) and areInIncreasingOrder(b, c) are both true, then areInIncreasingOrder(a, c) is also true. (Transitive comparability)
  • Two elements are incomparable if neither is ordered before the other according to the predicate. If a and b are incomparable, and b and c are incomparable, then a and c are also incomparable. (Transitive incomparability)

The sorting algorithm is not stable. A nonstable sort may change the relative order of elements for which areInIncreasingOrder does not establish an order.

In the following example, the predicate provides an ordering for an array of a custom HTTPResponse type. The predicate orders errors before successes and sorts the error responses by their error code.

enum HTTPResponse {
    case ok
    case error(Int)
}

let responses: [HTTPResponse] = [.error(500), .ok, .ok, .error(404), .error(403)]
let sortedResponses = responses.sorted {
    switch ($0, $1) {
    // Order errors by code
    case let (.error(aCode), .error(bCode)):
        return aCode < bCode

    // All successes are equivalent, so none is before any other
    case (.ok, .ok): return false

    // Order errors before successes
    case (.error, .ok): return true
    case (.ok, .error): return false
    }
}
print(sortedResponses)
// Prints "[.error(403), .error(404), .error(500), .ok, .ok]"

You also use this method to sort elements that conform to the Comparable protocol in descending order. To sort your sequence in descending order, pass the greater-than operator (>) as the areInIncreasingOrder parameter.

let students: Set = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
let descendingStudents = students.sorted(by: >)
print(descendingStudents)
// Prints "["Peter", "Kweku", "Kofi", "Akosua", "Abena"]"

Calling the related sorted() method is equivalent to calling this method and passing the less-than operator (<) as the predicate.

print(students.sorted())
// Prints "["Abena", "Akosua", "Kofi", "Kweku", "Peter"]"
print(students.sorted(by: <))
// Prints "["Abena", "Akosua", "Kofi", "Kweku", "Peter"]"

areInIncreasingOrder: A predicate that returns true if its first argument should be ordered before its second argument; otherwise, false. Returns: A sorted array of the sequence's elements.

Declaration

func sorted(by areInIncreasingOrder: (Array<Element>.Element, Array<Element>.Element) throws -> Bool) rethrows -> [Array<Element>.Element]

Declared In

Sequence
func split(_:omittingEmptySubsequences:whereSeparator:)

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

The resulting array consists of at most maxSplits + 1 subsequences. Elements that are used to split the sequence are not returned as part of any subsequence.

The following examples show the effects of the maxSplits and omittingEmptySubsequences parameters when splitting a string using a closure that matches spaces. The first use of split returns each word that was originally separated by one or more spaces.

let line = "BLANCHE:   I don't want realism. I want magic!"
print(line.split(whereSeparator: { $0 == " " }))
// Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"

The second example passes 1 for the maxSplits parameter, so the original string is split just once, into two new strings.

print(line.split(maxSplits: 1, whereSeparator: { $0 == " " }))
// Prints "["BLANCHE:", "  I don\'t want realism. I want magic!"]"

The final example passes false for the omittingEmptySubsequences parameter, so the returned array contains empty strings where spaces were repeated.

print(line.split(omittingEmptySubsequences: false, whereSeparator: { $0 == " " }))
// Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"

Parameters: maxSplits: The maximum number of times to split the collection, or one less than the number of subsequences to return. If maxSplits + 1 subsequences are returned, the last one is a suffix of the original collection containing the remaining elements. maxSplits must be greater than or equal to zero. The default value is Int.max. omittingEmptySubsequences: If false, an empty subsequence is returned in the result for each pair of consecutive elements satisfying the isSeparator predicate and for each element at the start or end of the collection satisfying the isSeparator predicate. The default value is true. isSeparator: A closure that takes an element as an argument and returns a Boolean value indicating whether the collection should be split at that element. Returns: An array of subsequences, split from this collection's elements.

Declaration

func split(maxSplits: Int = default, omittingEmptySubsequences: Bool = default, whereSeparator isSeparator: (Array<Element>.Element) throws -> Bool) rethrows -> [Array<Element>.SubSequence]

Declared In

Collection
func starts(with:by:)

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.

The predicate must be a equivalence relation over the elements. That is, for any elements a, b, and c, the following conditions must hold:

  • areEquivalent(a, a) is always true. (Reflexivity)
  • areEquivalent(a, b) implies areEquivalent(b, a). (Symmetry)
  • If areEquivalent(a, b) and areEquivalent(b, c) are both true, then areEquivalent(a, c) is also true. (Transitivity)

Parameters: possiblePrefix: A sequence to compare to this sequence. areEquivalent: A predicate that returns true if its two arguments are equivalent; otherwise, false. Returns: true if the initial elements of the sequence are equivalent to the elements of possiblePrefix; otherwise, false. If possiblePrefix has no elements, the return value is true.

Declaration

func starts<PossiblePrefix>(with possiblePrefix: PossiblePrefix, by areEquivalent: (Array<Element>.Element, PossiblePrefix.Element) throws -> Bool) rethrows -> Bool where PossiblePrefix : Sequence

Declared In

Sequence
func suffix(_:)

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

If the maximum length exceeds the number of elements in the collection, the result contains the entire collection.

let numbers = [1, 2, 3, 4, 5]
print(numbers.suffix(2))
// Prints "[4, 5]"
print(numbers.suffix(10))
// Prints "[1, 2, 3, 4, 5]"

maxLength: The maximum number of elements to return. maxLength must be greater than or equal to zero. Returns: A subsequence terminating at the end of the collection with at most maxLength elements.

Complexity: O(n), where n is equal to maxLength.

Declaration

func suffix(_ maxLength: Int) -> Array<Element>.SubSequence

Declared In

BidirectionalCollection, Collection
func suffix(from:)

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

The following example searches for the index of the number 40 in an array of integers, and then prints the suffix of the array starting at that index:

let numbers = [10, 20, 30, 40, 50, 60]
if let i = numbers.firstIndex(of: 40) {
    print(numbers.suffix(from: i))
}
// Prints "[40, 50, 60]"

Passing the collection's endIndex as the start parameter results in an empty subsequence.

print(numbers.suffix(from: numbers.endIndex))
// Prints "[]"

Using the suffix(from:) method is equivalent to using a partial range from the index as the collection's subscript. The subscript notation is preferred over suffix(from:).

if let i = numbers.firstIndex(of: 40) {
    print(numbers[i...])
}
// Prints "[40, 50, 60]"

start: The index at which to start the resulting subsequence. start must be a valid index of the collection. Returns: A subsequence starting at the start position.

Complexity: O(1)

Declaration

func suffix(from start: Array<Element>.Index) -> Array<Element>.SubSequence

Declared In

Collection
mutating func swapAt(_:_:)

Exchanges the values at the specified indices of the collection.

Both parameters must be valid indices of the collection that are not equal to endIndex. Calling swapAt(_:_:) with the same index as both i and j has no effect.

Parameters: i: The index of the first value to swap. j: The index of the second value to swap.

Declaration

mutating func swapAt(_ i: Array<Element>.Index, _ j: Array<Element>.Index)

Declared In

MutableCollection
func withUnsafeBufferPointer(_:)

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

Often, the optimizer can eliminate bounds checks within an array algorithm, but when that fails, invoking the same algorithm on the buffer pointer passed into your closure lets you trade safety for speed.

The following example shows how you can iterate over the contents of the buffer pointer:

let numbers = [1, 2, 3, 4, 5]
let sum = numbers.withUnsafeBufferPointer { buffer -> Int in
    var result = 0
    for i in stride(from: buffer.startIndex, to: buffer.endIndex, by: 2) {
        result += buffer[i]
    }
    return result
}
// 'sum' == 9

The pointer passed as an argument to body is valid only during the execution of withUnsafeBufferPointer(_:). Do not store or return the pointer for later use.

body: A closure with an UnsafeBufferPointer parameter that points to the contiguous storage for the array. If no such storage exists, it is created. If body has a return value, that value is also used as the return value for the withUnsafeBufferPointer(_:) method. The pointer argument is valid only for the duration of the method's execution. Returns: The return value, if any, of the body closure parameter.

Declaration

func withUnsafeBufferPointer<R>(_ body: (UnsafeBufferPointer<[Element].Element>) throws -> R) rethrows -> R
func withUnsafeBytes(_:)

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

The array's Element type must be a trivial type, which can be copied with just a bit-for-bit copy without any indirection or reference-counting operations. Generally, native Swift types that do not contain strong or weak references are trivial, as are imported C structs and enums.

The following example copies the bytes of the numbers array into a buffer of UInt8:

var numbers = [1, 2, 3]
var byteBuffer: [UInt8] = []
numbers.withUnsafeBytes {
    byteBuffer.append(contentsOf: $0)
}
// byteBuffer == [1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, ...]

body: A closure with an UnsafeRawBufferPointer parameter that points to the contiguous storage for the array. If no such storage exists, it is created. If body has a return value, that value is also used as the return value for the withUnsafeBytes(_:) method. The argument is valid only for the duration of the closure's execution. Returns: The return value, if any, of the body closure parameter.

Declaration

func withUnsafeBytes<R>(_ body: (UnsafeRawBufferPointer) throws -> R) rethrows -> R
mutating func withUnsafeMutableBufferPointer(_:)

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

Often, the optimizer can eliminate bounds checks within an array algorithm, but when that fails, invoking the same algorithm on the buffer pointer passed into your closure lets you trade safety for speed.

The following example shows how modifying the contents of the UnsafeMutableBufferPointer argument to body alters the contents of the array:

var numbers = [1, 2, 3, 4, 5]
numbers.withUnsafeMutableBufferPointer { buffer in
    for i in stride(from: buffer.startIndex, to: buffer.endIndex - 1, by: 2) {
        buffer.swapAt(i, i + 1)
    }
}
print(numbers)
// Prints "[2, 1, 4, 3, 5]"

The pointer passed as an argument to body is valid only during the execution of withUnsafeMutableBufferPointer(_:). Do not store or return the pointer for later use.

Warning: Do not rely on anything about the array that is the target of this method during execution of the body closure; it might not appear to have its correct value. Instead, use only the UnsafeMutableBufferPointer argument to body.

body: A closure with an UnsafeMutableBufferPointer parameter that points to the contiguous storage for the array. If no such storage exists, it is created. If body has a return value, that value is also used as the return value for the withUnsafeMutableBufferPointer(_:) method. The pointer argument is valid only for the duration of the method's execution. Returns: The return value, if any, of the body closure parameter.

Declaration

mutating func withUnsafeMutableBufferPointer<R>(_ body: (inout UnsafeMutableBufferPointer<[Element].Element>) throws -> R) rethrows -> R
mutating func withUnsafeMutableBytes(_:)

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

The array's Element type must be a trivial type, which can be copied with just a bit-for-bit copy without any indirection or reference-counting operations. Generally, native Swift types that do not contain strong or weak references are trivial, as are imported C structs and enums.

The following example copies bytes from the byteValues array into numbers, an array of Int:

var numbers: [Int32] = [0, 0]
var byteValues: [UInt8] = [0x01, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00]

numbers.withUnsafeMutableBytes { destBytes in
    byteValues.withUnsafeBytes { srcBytes in
        destBytes.copyBytes(from: srcBytes)
    }
}
// numbers == [1, 2]

The pointer passed as an argument to body is valid only for the lifetime of the closure. Do not escape it from the closure for later use.

Warning: Do not rely on anything about the array that is the target of this method during execution of the body closure; it might not appear to have its correct value. Instead, use only the UnsafeMutableRawBufferPointer argument to body.

body: A closure with an UnsafeMutableRawBufferPointer parameter that points to the contiguous storage for the array. If no such storage exists, it is created. If body has a return value, that value is also used as the return value for the withUnsafeMutableBytes(_:) method. The argument is valid only for the duration of the closure's execution. Returns: The return value, if any, of the body closure parameter.

Declaration

mutating func withUnsafeMutableBytes<R>(_ body: (UnsafeMutableRawBufferPointer) throws -> R) rethrows -> R

Conditionally Inherited Items

The initializers, methods, and properties listed below may be available on this type under certain conditions (such as methods that are available on Array when its elements are Equatable) or may not ever be available if that determination is beyond SwiftDoc.org's capabilities. Please open an issue on GitHub if you see something out of place!

Where Element : Collection

func joined()

Returns the elements of this collection of collections, concatenated.

In this example, an array of three ranges is flattened so that the elements of each range can be iterated in turn.

let ranges = [0..<3, 8..<10, 15..<17]

// A for-in loop over 'ranges' accesses each range:
for range in ranges {
  print(range)
}
// Prints "0..<3"
// Prints "8..<10"
// Prints "15..<17"

// Use 'joined()' to access each element of each range:
for index in ranges.joined() {
    print(index, terminator: " ")
}
// Prints: "0 1 2 8 9 15 16"

Returns: A flattened view of the elements of this collection of collections.

Declaration

func joined() -> FlattenCollection<Array<Element>>

Declared In

Collection

Where Element : Comparable

func lexicographicallyPrecedes(_:)

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

This example uses the lexicographicallyPrecedes method to test which array of integers comes first in a lexicographical ordering.

let a = [1, 2, 2, 2]
let b = [1, 2, 3, 4]

print(a.lexicographicallyPrecedes(b))
// Prints "true"
print(b.lexicographicallyPrecedes(b))
// Prints "false"

other: A sequence to compare to this sequence. Returns: true if this sequence precedes other in a dictionary ordering; otherwise, false.

Note: This method implements the mathematical notion of lexicographical ordering, which has no connection to Unicode. If you are sorting strings to present to the end user, use String APIs that perform localized comparison.

Declaration

func lexicographicallyPrecedes<OtherSequence>(_ other: OtherSequence) -> Bool where OtherSequence : Sequence, Array<Element>.Element == OtherSequence.Element

Declared In

Sequence
@warn_unqualified_access func max()

Returns the maximum element in the sequence.

This example finds the largest value in an array of height measurements.

let heights = [67.5, 65.7, 64.3, 61.1, 58.5, 60.3, 64.9]
let greatestHeight = heights.max()
print(greatestHeight)
// Prints "Optional(67.5)"

Returns: The sequence's maximum element. If the sequence has no elements, returns nil.

Declaration

@warn_unqualified_access func max() -> Array<Element>.Element?

Declared In

Sequence
@warn_unqualified_access func min()

Returns the minimum element in the sequence.

This example finds the smallest value in an array of height measurements.

let heights = [67.5, 65.7, 64.3, 61.1, 58.5, 60.3, 64.9]
let lowestHeight = heights.min()
print(lowestHeight)
// Prints "Optional(58.5)"

Returns: The sequence's minimum element. If the sequence has no elements, returns nil.

Declaration

@warn_unqualified_access func min() -> Array<Element>.Element?

Declared In

Sequence
mutating func sort()

Sorts the collection in place.

You can sort any mutable collection of elements that conform to the Comparable protocol by calling this method. Elements are sorted in ascending order.

The sorting algorithm is not stable. A nonstable sort may change the relative order of elements that compare equal.

Here's an example of sorting a list of students' names. Strings in Swift conform to the Comparable protocol, so the names are sorted in ascending order according to the less-than operator (<).

var students = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
students.sort()
print(students)
// Prints "["Abena", "Akosua", "Kofi", "Kweku", "Peter"]"

To sort the elements of your collection in descending order, pass the greater-than operator (>) to the sort(by:) method.

students.sort(by: >)
print(students)
// Prints "["Peter", "Kweku", "Kofi", "Akosua", "Abena"]"

Declaration

mutating func sort()

Declared In

MutableCollection
func sorted()

Returns the elements of the sequence, sorted.

You can sort any sequence of elements that conform to the Comparable protocol by calling this method. Elements are sorted in ascending order.

The sorting algorithm is not stable. A nonstable sort may change the relative order of elements that compare equal.

Here's an example of sorting a list of students' names. Strings in Swift conform to the Comparable protocol, so the names are sorted in ascending order according to the less-than operator (<).

let students: Set = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
let sortedStudents = students.sorted()
print(sortedStudents)
// Prints "["Abena", "Akosua", "Kofi", "Kweku", "Peter"]"

To sort the elements of your sequence in descending order, pass the greater-than operator (>) to the sorted(by:) method.

let descendingStudents = students.sorted(by: >)
print(descendingStudents)
// Prints "["Peter", "Kweku", "Kofi", "Akosua", "Abena"]"

Returns: A sorted array of the sequence's elements.

Declaration

func sorted() -> [Array<Element>.Element]

Declared In

Sequence

Where Element : Equatable

func contains(_:)

Returns a Boolean value indicating whether the sequence contains the given element.

This example checks to see whether a favorite actor is in an array storing a movie's cast.

let cast = ["Vivien", "Marlon", "Kim", "Karl"]
print(cast.contains("Marlon"))
// Prints "true"
print(cast.contains("James"))
// Prints "false"

element: The element to find in the sequence. Returns: true if the element was found in the sequence; otherwise, false.

Declaration

func contains(_ element: Array<Element>.Element) -> Bool

Declared In

Sequence
func elementsEqual(_:)

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

At least one of the sequences must be finite.

This example tests whether one countable range shares the same elements as another countable range and an array.

let a = 1...3
let b = 1...10

print(a.elementsEqual(b))
// Prints "false"
print(a.elementsEqual([1, 2, 3]))
// Prints "true"

other: A sequence to compare to this sequence. Returns: true if this sequence and other contain the same elements in the same order.

Declaration

func elementsEqual<OtherSequence>(_ other: OtherSequence) -> Bool where OtherSequence : Sequence, Array<Element>.Element == OtherSequence.Element

Declared In

Sequence
func firstIndex(of:)

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

After using firstIndex(of:) to find the position of a particular element in a collection, you can use it to access the element by subscripting. This example shows how you can modify one of the names in an array of students.

var students = ["Ben", "Ivy", "Jordell", "Maxime"]
if let i = students.firstIndex(of: "Maxime") {
    students[i] = "Max"
}
print(students)
// Prints "["Ben", "Ivy", "Jordell", "Max"]"

element: An element to search for in the collection. Returns: The first index where element is found. If element is not found in the collection, returns nil.

Declaration

func firstIndex(of element: Array<Element>.Element) -> Array<Element>.Index?

Declared In

Collection
func lastIndex(of:)

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

After using lastIndex(of:) to find the position of the last instance of a particular element in a collection, you can use it to access the element by subscripting. This example shows how you can modify one of the names in an array of students.

var students = ["Ben", "Ivy", "Jordell", "Ben", "Maxime"]
if let i = students.lastIndex(of: "Ben") {
    students[i] = "Benjamin"
}
print(students)
// Prints "["Ben", "Ivy", "Jordell", "Benjamin", "Max"]"

element: An element to search for in the collection. Returns: The last index where element is found. If element is not found in the collection, returns nil.

Declaration

func lastIndex(of element: Array<Element>.Element) -> Array<Element>.Index?

Declared In

BidirectionalCollection
func split(_:maxSplits:omittingEmptySubsequences:)

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

The resulting array consists of at most maxSplits + 1 subsequences. Elements that are used to split the collection are not returned as part of any subsequence.

The following examples show the effects of the maxSplits and omittingEmptySubsequences parameters when splitting a string at each space character (" "). The first use of split returns each word that was originally separated by one or more spaces.

let line = "BLANCHE:   I don't want realism. I want magic!"
print(line.split(separator: " "))
// Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"

The second example passes 1 for the maxSplits parameter, so the original string is split just once, into two new strings.

print(line.split(separator: " ", maxSplits: 1))
// Prints "["BLANCHE:", "  I don\'t want realism. I want magic!"]"

The final example passes false for the omittingEmptySubsequences parameter, so the returned array contains empty strings where spaces were repeated.

print(line.split(separator: " ", omittingEmptySubsequences: false))
// Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"

Parameters: separator: The element that should be split upon. maxSplits: The maximum number of times to split the collection, or one less than the number of subsequences to return. If maxSplits + 1 subsequences are returned, the last one is a suffix of the original collection containing the remaining elements. maxSplits must be greater than or equal to zero. The default value is Int.max. omittingEmptySubsequences: If false, an empty subsequence is returned in the result for each consecutive pair of separator elements in the collection and for each instance of separator at the start or end of the collection. If true, only nonempty subsequences are returned. The default value is true. Returns: An array of subsequences, split from this collection's elements.

Declaration

func split(separator: Array<Element>.Element, maxSplits: Int = default, omittingEmptySubsequences: Bool = default) -> [Array<Element>.SubSequence]

Declared In

Collection, Sequence
func starts(with:)

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

This example tests whether one countable range begins with the elements of another countable range.

let a = 1...3
let b = 1...10

print(b.starts(with: a))
// Prints "true"

Passing a sequence with no elements or an empty collection as possiblePrefix always results in true.

print(b.starts(with: []))
// Prints "true"

possiblePrefix: A sequence to compare to this sequence. Returns: true if the initial elements of the sequence are the same as the elements of possiblePrefix; otherwise, false. If possiblePrefix has no elements, the return value is true.

Declaration

func starts<PossiblePrefix>(with possiblePrefix: PossiblePrefix) -> Bool where PossiblePrefix : Sequence, Array<Element>.Element == PossiblePrefix.Element

Declared In

Sequence

Where Element : Sequence

func joined()

Returns the elements of this sequence of sequences, concatenated.

In this example, an array of three ranges is flattened so that the elements of each range can be iterated in turn.

let ranges = [0..<3, 8..<10, 15..<17]

// A for-in loop over 'ranges' accesses each range:
for range in ranges {
  print(range)
}
// Prints "0..<3"
// Prints "8..<10"
// Prints "15..<17"

// Use 'joined()' to access each element of each range:
for index in ranges.joined() {
    print(index, terminator: " ")
}
// Prints: "0 1 2 8 9 15 16"

Returns: A flattened view of the elements of this sequence of sequences.

Declaration

func joined() -> FlattenSequence<Array<Element>>

Declared In

Sequence
func joined(_:)

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

This example shows how an array of [Int] instances can be joined, using another [Int] instance as the separator:

let nestedNumbers = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
let joined = nestedNumbers.joined(separator: [-1, -2])
print(Array(joined))
// Prints "[1, 2, 3, -1, -2, 4, 5, 6, -1, -2, 7, 8, 9]"

separator: A sequence to insert between each of this sequence's elements. Returns: The joined sequence of elements.

Declaration

func joined<Separator>(separator: Separator) -> JoinedSequence<Array<Element>> where Separator : Sequence, Separator.Element == Array<Element>.Element.Element

Declared In

Sequence

Where Element : StringProtocol

func joined(_:)

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

The following example shows how an array of strings can be joined to a single, comma-separated string:

let cast = ["Vivien", "Marlon", "Kim", "Karl"]
let list = cast.joined(separator: ", ")
print(list)
// Prints "Vivien, Marlon, Kim, Karl"

separator: A string to insert between each of the elements in this sequence. The default separator is an empty string. Returns: A single, concatenated string.

Declaration

func joined(separator: String = default) -> String

Declared In

Sequence

Where Index : Strideable, Indices == Range, Index.Stride == Int

var indices: Range<Array<Element>.Index>

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

Declaration

var indices: Range<Array<Element>.Index> { get }

Declared In

RandomAccessCollection
func distance(from:to:)

Returns the distance between two indices.

Parameters: start: A valid index of the collection. end: Another valid index of the collection. If end is equal to start, the result is zero. Returns: The distance between start and end.

Complexity: O(1)

Declaration

func distance(from start: Array<Element>.Index, to end: Array<Element>.Index) -> Array<Element>.Index.Stride

Declared In

RandomAccessCollection
func index(_:offsetBy:)

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

The following example obtains an index advanced four positions from an array's starting index and then prints the element at that position.

let numbers = [10, 20, 30, 40, 50]
let i = numbers.index(numbers.startIndex, offsetBy: 4)
print(numbers[i])
// Prints "50"

The value passed as n must not offset i beyond the bounds of the collection.

Parameters: i: A valid index of the collection. n: The distance to offset i. Returns: An index offset by n from the index i. If n is positive, this is the same value as the result of n calls to index(after:). If n is negative, this is the same value as the result of -n calls to index(before:).

Complexity: O(1)

Declaration

func index(_ i: Array<Element>.Index, offsetBy n: Array<Element>.Index.Stride) -> Array<Element>.Index

Declared In

RandomAccessCollection
func index(after:)

Returns the position immediately after the given index.

i: A valid index of the collection. i must be less than endIndex. Returns: The index value immediately after i.

Declaration

func index(after i: Array<Element>.Index) -> Array<Element>.Index

Declared In

RandomAccessCollection
func index(before:)

Returns the position immediately after the given index.

i: A valid index of the collection. i must be greater than startIndex. Returns: The index value immediately before i.

Declaration

func index(before i: Array<Element>.Index) -> Array<Element>.Index

Declared In

RandomAccessCollection

Where Indices == DefaultIndices

var indices: DefaultIndices<Array<Element>>

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

A collection's indices property can hold a strong reference to the collection itself, causing the collection to be non-uniquely referenced. If you mutate the collection while iterating over its indices, a strong reference can cause an unexpected copy of the collection. To avoid the unexpected copy, use the index(after:) method starting with startIndex to produce indices instead.

var c = MyFancyCollection([10, 20, 30, 40, 50])
var i = c.startIndex
while i != c.endIndex {
    c[i] /= 5
    i = c.index(after: i)
}
// c == MyFancyCollection([2, 4, 6, 8, 10])

Declaration

var indices: DefaultIndices<Array<Element>> { get }

Declared In

Collection

Where Iterator == IndexingIterator

func makeIterator()

Returns an iterator over the elements of the collection.

Declaration

func makeIterator() -> IndexingIterator<Array<Element>>

Declared In

Collection

Where SubSequence == AnySequence

func drop(while:)

Returns a subsequence by skipping the initial, consecutive elements that satisfy the given predicate.

The following example uses the drop(while:) method to skip over the positive numbers at the beginning of the numbers array. The result begins with the first element of numbers that does not satisfy predicate.

let numbers = [3, 7, 4, -2, 9, -6, 10, 1]
let startingWithNegative = numbers.drop(while: { $0 > 0 })
// startingWithNegative == [-2, 9, -6, 10, 1]

If predicate matches every element in the sequence, the result is an empty sequence.

predicate: A closure that takes an element of the sequence as its argument and returns a Boolean value indicating whether the element should be included in the result. Returns: A subsequence starting after the initial, consecutive elements that satisfy predicate.

Complexity: O(n), where n is the length of the collection.

Declaration

func drop(while predicate: (Array<Element>.Element) throws -> Bool) rethrows -> AnySequence<Array<Element>.Element>

Declared In

Sequence
func dropFirst(_:)

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

If the number of elements to drop exceeds the number of elements in the sequence, the result is an empty subsequence.

let numbers = [1, 2, 3, 4, 5]
print(numbers.dropFirst(2))
// Prints "[3, 4, 5]"
print(numbers.dropFirst(10))
// Prints "[]"

n: The number of elements to drop from the beginning of the sequence. n must be greater than or equal to zero. Returns: A subsequence starting after the specified number of elements.

Complexity: O(1).

Declaration

func dropFirst(_ n: Int) -> AnySequence<Array<Element>.Element>

Declared In

Sequence
func dropLast(_:)

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

The sequence must be finite. If the number of elements to drop exceeds the number of elements in the sequence, the result is an empty subsequence.

let numbers = [1, 2, 3, 4, 5]
print(numbers.dropLast(2))
// Prints "[1, 2, 3]"
print(numbers.dropLast(10))
// Prints "[]"

n: The number of elements to drop off the end of the sequence. n must be greater than or equal to zero. Returns: A subsequence leaving off the specified number of elements.

Complexity: O(n), where n is the length of the sequence.

Declaration

func dropLast(_ n: Int) -> AnySequence<Array<Element>.Element>

Declared In

Sequence
func prefix(_:)

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

If the maximum length exceeds the number of elements in the sequence, the result contains all the elements in the sequence.

let numbers = [1, 2, 3, 4, 5]
print(numbers.prefix(2))
// Prints "[1, 2]"
print(numbers.prefix(10))
// Prints "[1, 2, 3, 4, 5]"

maxLength: The maximum number of elements to return. The value of maxLength must be greater than or equal to zero. Returns: A subsequence starting at the beginning of this sequence with at most maxLength elements.

Complexity: O(1)

Declaration

func prefix(_ maxLength: Int) -> AnySequence<Array<Element>.Element>

Declared In

Sequence
func prefix(while:)

Returns a subsequence containing the initial, consecutive elements that satisfy the given predicate.

The following example uses the prefix(while:) method to find the positive numbers at the beginning of the numbers array. Every element of numbers up to, but not including, the first negative value is included in the result.

let numbers = [3, 7, 4, -2, 9, -6, 10, 1]
let positivePrefix = numbers.prefix(while: { $0 > 0 })
// positivePrefix == [3, 7, 4]

If predicate matches every element in the sequence, the resulting sequence contains every element of the sequence.

predicate: A closure that takes an element of the sequence as its argument and returns a Boolean value indicating whether the element should be included in the result. Returns: A subsequence of the initial, consecutive elements that satisfy predicate.

Complexity: O(n), where n is the length of the collection.

Declaration

func prefix(while predicate: (Array<Element>.Element) throws -> Bool) rethrows -> AnySequence<Array<Element>.Element>

Declared In

Sequence
func split(_:omittingEmptySubsequences:whereSeparator:)

Returns the longest possible subsequences of the sequence, in order, that don't contain elements satisfying the given predicate. Elements that are used to split the sequence are not returned as part of any subsequence.

The following examples show the effects of the maxSplits and omittingEmptySubsequences parameters when splitting a string using a closure that matches spaces. The first use of split returns each word that was originally separated by one or more spaces.

let line = "BLANCHE:   I don't want realism. I want magic!"
print(line.split(whereSeparator: { $0 == " " })
          .map(String.init))
// Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"

The second example passes 1 for the maxSplits parameter, so the original string is split just once, into two new strings.

print(
   line.split(maxSplits: 1, whereSeparator: { $0 == " " })
                  .map(String.init))
// Prints "["BLANCHE:", "  I don\'t want realism. I want magic!"]"

The final example passes true for the allowEmptySlices parameter, so the returned array contains empty strings where spaces were repeated.

print(
    line.split(
        omittingEmptySubsequences: false,
        whereSeparator: { $0 == " " }
    ).map(String.init))
// Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"

Parameters: maxSplits: The maximum number of times to split the sequence, or one less than the number of subsequences to return. If maxSplits + 1 subsequences are returned, the last one is a suffix of the original sequence containing the remaining elements. maxSplits must be greater than or equal to zero. The default value is Int.max. omittingEmptySubsequences: If false, an empty subsequence is returned in the result for each pair of consecutive elements satisfying the isSeparator predicate and for each element at the start or end of the sequence satisfying the isSeparator predicate. If true, only nonempty subsequences are returned. The default value is true. isSeparator: A closure that returns true if its argument should be used to split the sequence; otherwise, false. Returns: An array of subsequences, split from this sequence's elements.

Declaration

func split(maxSplits: Int = default, omittingEmptySubsequences: Bool = default, whereSeparator isSeparator: (Array<Element>.Element) throws -> Bool) rethrows -> [AnySequence<Array<Element>.Element>]

Declared In

Sequence
func suffix(_:)

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

The sequence must be finite. If the maximum length exceeds the number of elements in the sequence, the result contains all the elements in the sequence.

let numbers = [1, 2, 3, 4, 5]
print(numbers.suffix(2))
// Prints "[4, 5]"
print(numbers.suffix(10))
// Prints "[1, 2, 3, 4, 5]"

maxLength: The maximum number of elements to return. The value of maxLength must be greater than or equal to zero. Complexity: O(n), where n is the length of the sequence.

Declaration

func suffix(_ maxLength: Int) -> AnySequence<Array<Element>.Element>

Declared In

Sequence

Where SubSequence == Slice

subscript(_: Range<Array<Element>.Index>)

Accesses a contiguous subrange of the collection's elements.

The accessed slice uses the same indices for the same elements as the original collection. Always use the slice's startIndex property instead of assuming that its indices start at a particular value.

This example demonstrates getting a slice of an array of strings, finding the index of one of the strings in the slice, and then using that index in the original array.

let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2 ..< streets.endIndex]
print(streetsSlice)
// Prints "["Channing", "Douglas", "Evarts"]"

let index = streetsSlice.firstIndex(of: "Evarts")    // 4
print(streets[index!])
// Prints "Evarts"

bounds: A range of the collection's indices. The bounds of the range must be valid indices of the collection.

Complexity: O(1)

Declaration

subscript(bounds: Range<Array<Element>.Index>) -> Slice<Array<Element>> { get }

Declared In

Collection