protocol Collection A sequence whose elements can be traversed multiple times, nondestructively, and accessed by indexed subscript. Collections are used extensively throughout the standard library. When you use arrays, dictionaries, views of a string's contents and other types, you benefit from the operations that the Collection protocol declares and implements. In addition to the methods that collections inherit from the Sequence protocol, you gain access to methods that depend on accessing an element at a specific position when using a collection. For example, if you want to print only the first word in a string, search for the index of the first space and then create a subsequence up to that position. let text = "Buffalo buffalo buffalo buffalo." if let firstSpace = text.characters.index(of: " ") { print(String(text.characters.prefix(upTo: firstSpace))) } // Prints "Buffalo" The firstSpace constant is an index into the text.characters collection. firstSpace is the position of the first space in the collection. You can store indices in variables, and pass them to collection algorithms or use them later to access the corresponding element. In the example above, firstSpace is used to extract the prefix that contains elements up to that index. You can pass only valid indices to collection operations. You can find a complete set of a collection's valid indices by starting with the collection's startIndex property and finding every successor up to, and including, the endIndex property. All other values of the Index type, such as the startIndex property of a different collection, are invalid indices for this collection. Saved indices may become invalid as a result of mutating operations; for more information about index invalidation in mutable collections, see the reference for the MutableCollection and RangeReplaceableCollection protocols, as well as for the specific type you're using. Accessing Individual Elements You can access an element of a collection through its subscript with any valid index except the collection's endIndex property, a "past the end" index that does not correspond with any element of the collection. Here's an example of accessing the first character in a string through its subscript: let firstChar = text.characters[text.characters.startIndex] print(firstChar) // Prints "B" The Collection protocol declares and provides default implementations for many operations that depend on elements being accessible by their subscript. For example, you can also access the first character of text using the first property, which has the value of the first element of the collection, or nil if the collection is empty. print(text.characters.first) // Prints "Optional("B")" Traversing a Collection Although a sequence can be consumed as it is traversed, a collection is guaranteed to be multipass: Any element may be repeatedly accessed by saving its index. Moreover, a collection's indices form a finite range of the positions of the collection's elements. This guarantees the safety of operations that depend on a sequence being finite, such as checking to see whether a collection contains an element. Iterating over the elements of a collection by their positions yields the same elements in the same order as iterating over that collection using its iterator. This example demonstrates that the characters view of a string returns the same characters in the same order whether the view's indices or the view itself is being iterated. let word = "Swift" for character in word.characters { print(character) } // Prints "S" // Prints "w" // Prints "i" // Prints "f" // Prints "t" for i in word.characters.indices { print(word.characters[i]) } // Prints "S" // Prints "w" // Prints "i" // Prints "f" // Prints "t" Conforming to the Collection Protocol If you create a custom sequence that can provide repeated access to its elements, make sure that its type conforms to the Collection protocol in order to give a more useful and more efficient interface for sequence and collection operations. To add Collection conformance to your type, you must declare at least the four following requirements: the startIndex and endIndex properties, a subscript that provides at least read-only access to your type's elements, and the index(after:) method for advancing an index into your collection. Expected Performance Types that conform to Collection are expected to provide the startIndex and endIndex properties and subscript access to elements as O(1) operations. Types that are not able to guarantee that expected performance must document the departure, because many collection operations depend on O(1) subscripting performance for their own performance guarantees. The performance of some collection operations depends on the type of index that the collection provides. For example, a random-access collection, which can measure the distance between two indices in O(1) time, will be able to calculate its count property in O(1) time. Conversely, because a forward or bidirectional collection must traverse the entire collection to count the number of contained elements, accessing its count property is an O(n) operation. Inheritance Sequence View Protocol Hierarchy → Associated Types IndexDistance : SignedInteger = Int A type that represents the number of steps between a pair of indices. Iterator : IteratorProtocol = IndexingIterator<Self> A type that provides the collection's iteration interface and encapsulates its iteration state. By default, a collection conforms to the Sequence protocol by supplying IndexingIterator as its associated Iterator type. SubSequence : Sequence = Slice<Self> A sequence that represents a contiguous subrange of the collection's elements. This associated type appears as a requirement in the Sequence protocol, but it is restated here with stricter constraints. In a collection, the subsequence should also conform to Collection. Indices : Sequence = DefaultIndices<Self> A type that represents the indices that are valid for subscripting the collection, in ascending order. Import import Swift Instance Variables var count: Self.IndexDistance The number of elements in the collection. To check whether a collection is empty, use its isEmpty property instead of comparing count to zero. Unless the collection guarantees random-access performance, calculating count can be an O(n) operation. Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the length of the collection. Declaration var count: Self.IndexDistance { get } var first: Self.Iterator.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: Self.Iterator.Element? { get } var indices: Self.Indices Required 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 nonuniquely referenced. If you mutate the collection while iterating over its indices, a strong reference can result in 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: Self.Indices { 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.characters.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 } var underestimatedCount: Int A value less than or equal to the number of elements in the sequence, calculated nondestructively. Complexity: O(1) Declaration var underestimatedCount: Int { get } Declared In Sequence Subscripts subscript(_: Self.Index) Required Accesses the element at the specified position. The following example accesses an element of an array through its subscript to print its value: var streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"] print(streets[1]) // Prints "Bryant" You can subscript a collection with any valid index other than the collection's end index. The end index refers to the position one past the last element of a collection, so it doesn't correspond with an element. position: The position of the element to access. position must be a valid index of the collection that is not equal to the endIndex property. Complexity: O(1) Declaration subscript(position: Self.Index) -> Self.Iterator.Element { get } subscript(_: Range<Self.Index>) Required Accesses a contiguous subrange of the collection's elements. The accessed slice uses the same indices for the same elements as the original collection uses. 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.index(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<Self.Index>) -> Self.SubSequence { get } Instance Methods func distance(from:to:) Required 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: Self.Index, to end: Self.Index) -> Self.IndexDistance 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 a Boolean value indicating whether the element is a match. Complexity: O(n), where n is the length of the collection. Declaration func drop(while predicate: (Self.Iterator.Element) throws -> Bool) rethrows -> Self.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 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(n), where n is the number of elements to drop from the beginning of the sequence. Declaration func dropFirst(_ n: Int) -> Self.SubSequence Declared In Sequence func dropLast(_:) Returns a subsequence containing all but the specified 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) -> Self.SubSequence Declared In Sequence func filter(_:) Returns an array containing, in order, the elements of the sequence 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.characters.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 includeElement allowed. Declaration func filter(_ isIncluded: (Self.Iterator.Element) throws -> Bool) rethrows -> [Self.Iterator.Element] 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: You cannot use a break or continue statement to exit the current call of the body closure or skip subsequent calls. 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: (Self.Iterator.Element) throws -> Swift.Void) rethrows Declared In Sequence func index(_:offsetBy:) Required 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:). See Also: index(_:offsetBy:limitedBy:), formIndex(_:offsetBy:) Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n. Declaration func index(_ i: Self.Index, offsetBy n: Self.IndexDistance) -> Self.Index func index(_:offsetBy:limitedBy:) Required 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. See Also: index(_:offsetBy:), formIndex(_:offsetBy:limitedBy:) Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n. Declaration func index(_ i: Self.Index, offsetBy n: Self.IndexDistance, limitedBy limit: Self.Index) -> Self.Index? func makeIterator() Required Returns an iterator over the elements of the collection. Declaration func makeIterator() -> Self.Iterator Declared In Collection, 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.lowercaseString } // 'lowercaseNames' == ["vivien", "marlon", "kim", "karl"] let letterCounts = cast.map { $0.characters.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: (Self.Iterator.Element) throws -> T) rethrows -> [T] 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. maxLength must be greater than or equal to zero. Returns: A subsequence starting at the beginning of this sequence with at most maxLength elements. Declaration func prefix(_ maxLength: Int) -> Self.SubSequence Declared In Sequence 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.index(of: 40) { print(numbers.prefix(through: 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) See Also: prefix(upTo:) Declaration func prefix(through position: Self.Index) -> Self.SubSequence 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.index(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 "[]" 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) See Also: prefix(through:) Declaration func prefix(upTo end: Self.Index) -> Self.SubSequence 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: (Self.Iterator.Element) throws -> Bool) rethrows -> Self.SubSequence 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. 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.characters.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.characters.split(maxSplits: 1, whereSeparator: { $0 == " " }) .map(String.init)) // 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.characters.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, omittingEmptySubsequences: Bool, whereSeparator isSeparator: (Self.Iterator.Element) throws -> Bool) rethrows -> [Self.SubSequence] 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. Returns: A subsequence terminating at the end of this sequence with at most maxLength elements. Complexity: O(n), where n is the length of the sequence. Declaration func suffix(_ maxLength: Int) -> Self.SubSequence Declared In Sequence 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.index(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 "[]" 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: Self.Index) -> Self.SubSequence Default Implementations var count: Self.IndexDistance The number of elements in the collection. To check whether a collection is empty, use its isEmpty property instead of comparing count to zero. Unless the collection guarantees random-access performance, calculating count can be an O(n) operation. Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the length of the collection. Declaration var count: Self.IndexDistance { get } var first: Self.Iterator.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: Self.Iterator.Element? { 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.characters.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 } var lazy: LazyCollection<Self> 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. See Also: LazySequenceProtocol, LazyCollectionProtocol. Declaration var lazy: LazyCollection<Self> { get } var lazy: Self Identical to self. Declaration var lazy: Self { 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 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: (Self.Iterator.Element) throws -> Bool) rethrows -> Bool Declared In Sequence 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: (Self.Iterator.Element) throws -> Bool) rethrows -> Self.SubSequence 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() -> Self.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) -> Self.SubSequence 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() -> Self.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 the specified number of elements at the end. Complexity: O(n), where n is the length of the collection. Declaration func dropLast(_ n: Int) -> Self.SubSequence func elementsEqual(_:by:) Returns a Boolean value indicating whether this sequence and another sequence contain equivalent elements, 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. See Also: elementsEqual(_:) Declaration func elementsEqual<OtherSequence where OtherSequence : Sequence, OtherSequence.Iterator.Element == Self.Iterator.Element>(_ other: OtherSequence, by areEquivalent: (Self.Iterator.Element, Self.Iterator.Element) throws -> Bool) rethrows -> Bool Declared In Sequence 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".characters.enumerated() { print("\(n): '\(c)'") } // Prints "0: 'S'" // Prints "1: 'w'" // Prints "2: 'i'" // Prints "3: 'f'" // Prints "4: 't'" When enumerating a collection, the integer part of each pair is a counter for the enumeration, not necessarily the index of the paired value. These counters can only be used as indices 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 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.characters.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<Self> Declared In Sequence func filter(_:) Returns an array containing, in order, the elements of the sequence 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.characters.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 includeElement allowed. Declaration func filter(_ isIncluded: (Self.Iterator.Element) throws -> Bool) rethrows -> [Self.Iterator.Element] Declared In 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: (Self.Iterator.Element) throws -> Bool) rethrows -> Self.Iterator.Element? Declared In Sequence func flatMap<ElementOfResult>(_: (Self.Iterator.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: (Self.Iterator.Element) throws -> ElementOfResult?) rethrows -> [ElementOfResult] Declared In Sequence func flatMap<SegmentOfResult where SegmentOfResult : Sequence>(_: (Self.Iterator.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(count: $0, repeatedValue: $0) } // [[1], [2, 2], [3, 3, 3], [4, 4, 4, 4]] let flatMapped = numbers.flatMap { Array(count: $0, repeatedValue: $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. See Also: joined(), map(_:) Declaration func flatMap<SegmentOfResult where SegmentOfResult : Sequence>(_ transform: (Self.Iterator.Element) throws -> SegmentOfResult) rethrows -> [SegmentOfResult.Iterator.Element] 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: You cannot use a break or continue statement to exit the current call of the body closure or skip subsequent calls. 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: (Self.Iterator.Element) throws -> Swift.Void) rethrows Declared In Sequence func index(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.index(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. See Also: index(of:) Declaration func index(where predicate: (Self.Iterator.Element) throws -> Bool) rethrows -> Self.Index? 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. See Also: lexicographicallyPrecedes(_:) Declaration func lexicographicallyPrecedes<OtherSequence where OtherSequence : Sequence, OtherSequence.Iterator.Element == Self.Iterator.Element>(_ other: OtherSequence, by areInIncreasingOrder: (Self.Iterator.Element, Self.Iterator.Element) throws -> Bool) rethrows -> Bool 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.lowercaseString } // 'lowercaseNames' == ["vivien", "marlon", "kim", "karl"] let letterCounts = cast.map { $0.characters.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: (Self.Iterator.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. See Also: max() Declaration @warn_unqualified_access func max(by areInIncreasingOrder: (Self.Iterator.Element, Self.Iterator.Element) throws -> Bool) rethrows -> Self.Iterator.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. See Also: min() Declaration func min(by areInIncreasingOrder: (Self.Iterator.Element, Self.Iterator.Element) throws -> Bool) rethrows -> Self.Iterator.Element? Declared In Sequence 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) -> Self.SubSequence 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.index(of: 40) { print(numbers.prefix(through: 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) See Also: prefix(upTo:) Declaration func prefix(through position: Self.Index) -> Self.SubSequence 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.index(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 "[]" 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) See Also: prefix(through:) Declaration func prefix(upTo end: Self.Index) -> Self.SubSequence 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: (Self.Iterator.Element) throws -> Bool) rethrows -> Self.SubSequence 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: The nextPartialResult closure is called with initialResult---0 in this case---and the first element of numbers, returning the sum: 1. The closure is called again repeatedly with the previous call's return value and each element of the sequence. 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, Self.Iterator.Element) throws -> Result) rethrows -> Result Declared In Sequence func reversed() Returns an array containing the elements of this sequence in reverse order. The sequence must be finite. Complexity: O(n), where n is the length of the sequence. Returns: An array containing the elements of this sequence in reverse order. Declaration func reversed() -> [Self.Iterator.Element] Declared In Sequence 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. See Also: sorted() Declaration func sorted(by areInIncreasingOrder: (Self.Iterator.Element, Self.Iterator.Element) -> Bool) -> [Self.Iterator.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.characters.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.characters.split( maxSplits: 1, whereSeparator: { $0 == " " } ).map(String.init)) // 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.characters.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 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: (Self.Iterator.Element) throws -> Bool) rethrows -> [Self.SubSequence] Declared In Collection, Sequence 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. See Also: starts(with:) Declaration func starts<PossiblePrefix where PossiblePrefix : Sequence, PossiblePrefix.Iterator.Element == Self.Iterator.Element>(with possiblePrefix: PossiblePrefix, by areEquivalent: (Self.Iterator.Element, Self.Iterator.Element) throws -> Bool) rethrows -> Bool 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 all the elements in the 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. The value of 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 the length of the collection. Declaration func suffix(_ maxLength: Int) -> Self.SubSequence Declared In Collection, Sequence 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.index(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 "[]" 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: Self.Index) -> Self.SubSequence Where Base.Iterator == Iterator func filter(_:) Returns an array containing, in order, the elements of the sequence 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.characters.count < 5 } print(shortNames) // Prints "["Kim", "Karl"]" includeElement: 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 includeElement allowed. Declaration func filter(_ isIncluded: (Self.Base.Iterator.Element) throws -> Bool) rethrows -> [Self.Base.Iterator.Element] Declared In Sequence func makeIterator() Returns an iterator over the elements of this sequence. Declaration func makeIterator() -> Self.Base.Iterator 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.lowercaseString } // 'lowercaseNames' == ["vivien", "marlon", "kim", "karl"] let letterCounts = cast.map { $0.characters.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: (Self.Base.Iterator.Element) throws -> T) rethrows -> [T] Declared In Sequence Where Indices == DefaultIndices, Indices.Index == Index, Indices.IndexDistance == Int, Indices.Iterator == IndexingIterator>, Indices.SubSequence == DefaultIndices, Indices._Element == Index, Indices.IndexDistance.IntegerLiteralType == Int, Indices.IndexDistance.Stride == Int, Indices.IndexDistance._DisabledRangeIndex == Int._DisabledRangeIndex, Indices.Iterator.Element == Index, Indices.IndexDistance.Stride.IntegerLiteralType == Int var indices: DefaultIndices<Self> 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<Self> { get } Where Iterator == IndexingIterator, Iterator.Element == _Element func makeIterator() Returns an iterator over the elements of the collection. Declaration func makeIterator() -> IndexingIterator<Self> Where Iterator == Self func makeIterator() Returns an iterator over the elements of this sequence. Declaration func makeIterator() -> Self Declared In Sequence Where Iterator.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. See Also: flatMap(_:), joined(separator:) Declaration func joined() -> FlattenCollection<Self> Where Iterator.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. See Also: lexicographicallyPrecedes(_:by:) Declaration func lexicographicallyPrecedes<OtherSequence where OtherSequence : Sequence, OtherSequence.Iterator.Element == Self.Iterator.Element>(_ other: OtherSequence) -> Bool Declared In Sequence @warn_unqualified_access func max() Returns the maximum 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 greatestHeight = heights.max() print(greatestHeight) // Prints "Optional(67.5)" Returns: The sequence's maximum element. If the sequence has no elements, returns nil. See Also: max(by:) Declaration @warn_unqualified_access func max() -> Self.Iterator.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. See Also: min(by:) Declaration @warn_unqualified_access func min() -> Self.Iterator.Element? Declared In Sequence 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. See Also: sorted(by:) Declaration func sorted() -> [Self.Iterator.Element] Declared In Sequence Where Iterator.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: Self.Iterator.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. See Also: elementsEqual(_:by:) Declaration func elementsEqual<OtherSequence where OtherSequence : Sequence, OtherSequence.Iterator.Element == Self.Iterator.Element>(_ other: OtherSequence) -> Bool Declared In Sequence func index(of:) Returns the first index where the specified value appears in the collection. After using index(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.index(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. See Also: index(where:) Declaration func index(of element: Self.Iterator.Element) -> Self.Index? 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.characters.split(separator: " ") .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.characters.split(separator: " ", maxSplits: 1) .map(String.init)) // 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.characters.split(separator: " ", omittingEmptySubsequences: false) .map(String.init)) // 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: Self.Iterator.Element, maxSplits: Int = default, omittingEmptySubsequences: Bool = default) -> [Self.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. See Also: starts(with:by:) Declaration func starts<PossiblePrefix where PossiblePrefix : Sequence, PossiblePrefix.Iterator.Element == Self.Iterator.Element>(with possiblePrefix: PossiblePrefix) -> Bool Declared In Sequence Where Iterator.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. See Also: flatMap(_:), joined(separator:) Declaration func joined() -> FlattenSequence<Self> 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. See Also: joined() Declaration func joined<Separator where Separator : Sequence, Separator.Iterator.Element == Self.Iterator.Element.Iterator.Element>(separator: Separator) -> JoinedSequence<Self> Declared In Sequence Where Iterator.Element == String 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 SubSequence : Sequence, SubSequence.SubSequence == SubSequence, SubSequence.Iterator.Element == Iterator.Element 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. See Also: prefix(while:) Declaration func drop(while predicate: (Self.Iterator.Element) throws -> Bool) rethrows -> AnySequence<Self.Iterator.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<Self.Iterator.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<Self.Iterator.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<Self.Iterator.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. See Also: drop(while:) Declaration func prefix(while predicate: (Self.Iterator.Element) throws -> Bool) rethrows -> AnySequence<Self.Iterator.Element> Declared In Sequence Where SubSequence == Self mutating func popFirst() Removes and returns the first element of the collection. Returns: The first element of the collection if the collection is not empty; otherwise, nil. Complexity: O(1) Declaration mutating func popFirst() -> Self.Iterator.Element? mutating func removeFirst() Removes and returns the first element of the collection. The collection must not be empty. Returns: The first element of the collection. Complexity: O(1) See Also: popFirst() Declaration mutating func removeFirst() -> Self.Iterator.Element mutating func removeFirst(_:) Removes the specified number of elements from the beginning of the collection. n: The number of elements to remove. n must be greater than or equal to zero, and must be less than or equal to the number of elements in the collection. Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n). Declaration mutating func removeFirst(_ n: Int) Where SubSequence == Slice, SubSequence.Index == Index, SubSequence.Iterator == IndexingIterator>, SubSequence.SubSequence == Slice, SubSequence._Element == _Element, SubSequence.Iterator.Element == _Element subscript(_: Range<Self.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 uses. 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.index(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<Self.Index>) -> Slice<Self> { get }