[4.2] [stdlib] Add last(where) and lastIndex(of/where) (#16134)

* Merge pull request #16089 from natecook1000/nc-firstindex

[stdlib] Rename index(...) methods to firstIndex(...)

* [stdlib] Implement sequence/collection methods for searching from the end (#13337)

This implements the new last(where:), and lastIndex(of/where:) methods as
extensions on `BidirectionalCollection`, which partially implements SE-204.
The protocol requirements for `Sequence` and `Collection` as described
in the proposal need to wait until there's a solution for picking up the
specialized versions in types that conditionally conform to `BidirectionalCollection`.

Author: natecook1000

benchmark/single-source/CSVParsing.swift

@@ -31,7 +31,7 @@ func parseQuotedField(_ remainder: inout Substring) throws -> Substring? {
     var result: Substring = "" // we accumulate the result
 
     while !remainder.isEmpty {
-        guard let nextQuoteIndex = remainder.index(of: "\"") else {
+        guard let nextQuoteIndex = remainder.firstIndex(of: "\"") else {
             throw ParseError(message: "Expected a closing \"")
         }
 

benchmark/single-source/RemoveWhere.swift

@@ -46,7 +46,7 @@ extension RangeReplaceableCollection {
 
 extension RangeReplaceableCollection where Self: MutableCollection {
   mutating func removeWhere_move(where match: (Element) throws -> Bool) rethrows  {
-    guard var i = try index(where: match) else { return }
+    guard var i = try firstIndex(where: match) else { return }
 
     var j = index(after: i)
     while j != endIndex {
@@ -62,7 +62,7 @@ extension RangeReplaceableCollection where Self: MutableCollection {
   }
 
   mutating func removeWhere_swap(where match: (Element) throws -> Bool) rethrows {
-    guard var i = try index(where: match) else { return }
+    guard var i = try firstIndex(where: match) else { return }
 
     var j = index(after: i)
     while j != endIndex {

stdlib/private/StdlibCollectionUnittest/CheckCollectionType.swift

@@ -110,6 +110,27 @@ public struct SuffixFromTest {
   }
 }
 
+public struct FindLastTest {
+  public let expected: Int?
+  public let comparisons: Int
+  public let element: MinimalEquatableValue
+  public let sequence: [MinimalEquatableValue]
+  public let loc: SourceLoc
+  
+  public init(
+    expected: Int?, comparisons: Int, element: Int, sequence: [Int],
+    file: String = #file, line: UInt = #line
+    ) {
+    self.expected = expected
+    self.comparisons = comparisons
+    self.element = MinimalEquatableValue(element)
+    self.sequence = sequence.enumerated().map {
+      return MinimalEquatableValue($1, identity: $0)
+    }
+    self.loc = SourceLoc(file, line, comment: "test data")
+  }
+}
+
 public let subscriptRangeTests = [
   // Slice an empty collection.
   SubscriptRangeTest(
@@ -305,6 +326,68 @@ let removeFirstTests: [RemoveFirstNTest] = [
   ),
 ]
 
+let findLastTests = [
+  FindLastTest(
+    expected: nil,
+    comparisons: 0,
+    element: 42,
+    sequence: []),
+  
+  FindLastTest(
+    expected: nil,
+    comparisons: 1,
+    element: 42,
+    sequence: [ 1010 ]),
+  FindLastTest(
+    expected: 0,
+    comparisons: 1,
+    element: 1010,
+    sequence: [ 1010 ]),
+  
+  FindLastTest(
+    expected: nil,
+    comparisons: 2,
+    element: 42,
+    sequence: [ 1010, 1010 ]),
+  FindLastTest(
+    expected: 1,
+    comparisons: 1,
+    element: 1010,
+    sequence: [ 1010, 1010 ]),
+  
+  FindLastTest(
+    expected: nil,
+    comparisons: 4,
+    element: 42,
+    sequence: [ 1010, 2020, 3030, 4040 ]),
+  FindLastTest(
+    expected: 0,
+    comparisons: 4,
+    element: 1010,
+    sequence: [ 1010, 2020, 3030, 4040 ]),
+  FindLastTest(
+    expected: 1,
+    comparisons: 3,
+    element: 2020,
+    sequence: [ 1010, 2020, 3030, 4040 ]),
+  FindLastTest(
+    expected: 2,
+    comparisons: 2,
+    element: 3030,
+    sequence: [ 1010, 2020, 3030, 4040 ]),
+  FindLastTest(
+    expected: 3,
+    comparisons: 1,
+    element: 4040,
+    sequence: [ 1010, 2020, 3030, 4040 ]),
+  
+  FindLastTest(
+    expected: 3,
+    comparisons: 2,
+    element: 2020,
+    sequence: [ 1010, 2020, 3030, 2020, 4040 ]),
+]
+
 extension Collection {
   public func nthIndex(_ offset: Int) -> Index {
     return self.index(self.startIndex, offsetBy: numericCast(offset))
@@ -814,13 +897,13 @@ extension TestSuite {
     }
 
     //===------------------------------------------------------------------===//
-    // index(of:)/index(where:)
+    // firstIndex(of:)/firstIndex(where:)
     //===------------------------------------------------------------------===//
 
-    self.test("\(testNamePrefix).index(of:)/semantics") {
+    self.test("\(testNamePrefix).firstIndex(of:)/semantics") {
       for test in findTests {
         let c = makeWrappedCollectionWithEquatableElement(test.sequence)
-        var result = c.index(of: wrapValueIntoEquatable(test.element))
+        var result = c.firstIndex(of: wrapValueIntoEquatable(test.element))
         expectType(
           Optional<CollectionWithEquatableElement.Index>.self,
           &result)
@@ -834,12 +917,12 @@ extension TestSuite {
       }
     }
 
-    self.test("\(testNamePrefix).index(where:)/semantics") {
+    self.test("\(testNamePrefix).firstIndex(where:)/semantics") {
       for test in findTests {
         let closureLifetimeTracker = LifetimeTracked(0)
         expectEqual(1, LifetimeTracked.instances)
         let c = makeWrappedCollectionWithEquatableElement(test.sequence)
-        let result = c.index {
+        let result = c.firstIndex {
           (candidate) in
           _blackHole(closureLifetimeTracker)
           return
@@ -1222,6 +1305,12 @@ extension TestSuite {
       return makeCollection(elements.map(wrapValue))
     }
 
+    func makeWrappedCollectionWithEquatableElement(
+      _ elements: [MinimalEquatableValue]
+    ) -> CollectionWithEquatableElement {
+      return makeCollectionOfEquatable(elements.map(wrapValueIntoEquatable))
+    }
+
     testNamePrefix += String(describing: C.Type.self)
 
     // FIXME: swift-3-indexing-model - add tests for the follow?
@@ -1254,6 +1343,92 @@ extension TestSuite {
       }
     }
 
+    //===------------------------------------------------------------------===//
+    // last(where:)
+    //===------------------------------------------------------------------===//
+
+    self.test("\(testNamePrefix).last(where:)/semantics") {
+      for test in findLastTests {
+        let c = makeWrappedCollectionWithEquatableElement(test.sequence)
+        var closureCounter = 0
+        let closureLifetimeTracker = LifetimeTracked(0)
+        let found = c.last(where: {
+          _blackHole(closureLifetimeTracker)
+          closureCounter += 1
+          return $0 == wrapValueIntoEquatable(test.element)
+        })
+        expectEqual(
+          test.expected == nil ? nil : wrapValueIntoEquatable(test.element),
+          found,
+          stackTrace: SourceLocStack().with(test.loc))
+        expectEqual(
+          test.comparisons,
+          closureCounter,
+          stackTrace: SourceLocStack().with(test.loc))
+        if let expectedIdentity = test.expected {
+          expectEqual(
+            expectedIdentity, extractValueFromEquatable(found!).identity,
+            "last(where:) should find only the first element matching its predicate")
+        }
+      }
+    }
+
+    //===------------------------------------------------------------------===//
+    // lastIndex(of:)/lastIndex(where:)
+    //===------------------------------------------------------------------===//
+
+    self.test("\(testNamePrefix).lastIndex(of:)/semantics") {
+      for test in findLastTests {
+        let c = makeWrappedCollectionWithEquatableElement(test.sequence)
+        MinimalEquatableValue.timesEqualEqualWasCalled = 0
+        let wrappedElement = wrapValueIntoEquatable(test.element)
+        var result = c.lastIndex(of: wrappedElement)
+        expectType(
+          Optional<CollectionWithEquatableElement.Index>.self,
+          &result)
+        let zeroBasedIndex = result.map {
+          numericCast(c.distance(from: c.startIndex, to: $0)) as Int
+        }
+        expectEqual(
+          test.expected,
+          zeroBasedIndex,
+          stackTrace: SourceLocStack().with(test.loc))
+        if wrappedElement is MinimalEquatableValue {
+          expectEqual(
+            test.comparisons,
+            MinimalEquatableValue.timesEqualEqualWasCalled,
+            stackTrace: SourceLocStack().with(test.loc))
+        }
+      }
+    }
+
+    self.test("\(testNamePrefix).lastIndex(where:)/semantics") {
+      for test in findLastTests {
+        let closureLifetimeTracker = LifetimeTracked(0)
+        expectEqual(1, LifetimeTracked.instances)
+        let c = makeWrappedCollectionWithEquatableElement(test.sequence)
+        var closureCounter = 0
+        let result = c.lastIndex(where: {
+          (candidate) in
+          _blackHole(closureLifetimeTracker)
+          closureCounter += 1
+          return
+            extractValueFromEquatable(candidate).value == test.element.value
+        })
+        let zeroBasedIndex = result.map {
+          numericCast(c.distance(from: c.startIndex, to: $0)) as Int
+        }
+        expectEqual(
+          test.expected,
+          zeroBasedIndex,
+          stackTrace: SourceLocStack().with(test.loc))
+        expectEqual(
+          test.comparisons,
+          closureCounter,
+          stackTrace: SourceLocStack().with(test.loc))
+      }
+    }
+
     //===------------------------------------------------------------------===//
     // removeLast()/slice
     //===------------------------------------------------------------------===//

stdlib/private/StdlibCollectionUnittest/CheckSequenceType.swift

@@ -149,7 +149,7 @@ public struct FindTest {
 
   public init(
     expected: Int?, element: Int, sequence: [Int],
-    expectedLeftoverSequence: [Int],
+    expectedLeftoverSequence: [Int] = [],
     file: String = #file, line: UInt = #line
   ) {
     self.expected = expected
@@ -1935,17 +1935,17 @@ self.test("\(testNamePrefix).forEach/semantics") {
 }
 
 //===----------------------------------------------------------------------===//
-// first()
+// first(where:)
 //===----------------------------------------------------------------------===//
 
-self.test("\(testNamePrefix).first/semantics") {
+self.test("\(testNamePrefix).first(where:)/semantics") {
   for test in findTests {
     let s = makeWrappedSequenceWithEquatableElement(test.sequence)
     let closureLifetimeTracker = LifetimeTracked(0)
-    let found = s.first {
+    let found = s.first(where: {
       _blackHole(closureLifetimeTracker)
       return $0 == wrapValueIntoEquatable(test.element)
-    }
+    })
     expectEqual(
       test.expected == nil ? nil : wrapValueIntoEquatable(test.element),
       found,

stdlib/private/StdlibCollectionUnittest/MinimalCollections.swift

@@ -333,7 +333,7 @@ internal struct _CollectionStateTransition {
       transitions = Box<[_CollectionStateTransition]>([])
       _CollectionStateTransition._allTransitions[previousState] = transitions
     }
-    if let i = transitions!.value.index(where: { $0._operation == operation }) {
+    if let i = transitions!.value.firstIndex(where: { $0._operation == operation }) {
       self = transitions!.value[i]
       return
     }

stdlib/public/core/Arrays.swift.gyb

@@ -137,22 +137,22 @@ if True:
 /// tasked with finding the first two days with absences in the session. To
 /// find the indices of the two days in question, follow these steps:
 ///
-/// 1) Call `index(where:)` to find the index of the first element in the
+/// 1) Call `firstIndex(where:)` to find the index of the first element in the
 ///    `absences` array that is greater than zero.
 /// 2) Create a slice of the `absences` array starting after the index found in
 ///    step 1.
-/// 3) Call `index(where:)` again, this time on the slice created in step 2.
-///    Where in some languages you might pass a starting index into an
+/// 3) Call `firstIndex(where:)` again, this time on the slice created in step
+///    2. Where in some languages you might pass a starting index into an
 ///    `indexOf` method to find the second day, in Swift you perform the same
 ///    operation on a slice of the original array.
 /// 4) Print the results using the indices found in steps 1 and 3 on the
 ///    original `absences` array.
 ///
 /// Here's an implementation of those steps:
 ///
-///     if let i = absences.index(where: { $0 > 0 }) {                      // 1
+///     if let i = absences.firstIndex(where: { $0 > 0 }) {                 // 1
 ///         let absencesAfterFirst = absences[(i + 1)...]                   // 2
-///         if let j = absencesAfterFirst.index(where: { $0 > 0 }) {        // 3
+///         if let j = absencesAfterFirst.firstIndex(where: { $0 > 0 }) {   // 3
 ///             print("The first day with absences had \(absences[i]).")    // 4
 ///             print("The second day with absences had \(absences[j]).")
 ///         }
@@ -293,7 +293,7 @@ if True:
 /// You can replace an existing element with a new value by assigning the new
 /// value to the subscript.
 ///
-///     if let i = students.index(of: "Maxime") {
+///     if let i = students.firstIndex(of: "Maxime") {
 ///         students[i] = "Max"
 ///     }
 ///     // ["Ivy", "Jordell", "Liam", "Max", "Shakia"]
@@ -533,7 +533,7 @@ extension ${Self}: RandomAccessCollection, MutableCollection {
   /// safe to use with `endIndex`. For example:
   ///
   ///     let numbers = [10, 20, 30, 40, 50]
-  ///     if let i = numbers.index(of: 30) {
+  ///     if let i = numbers.firstIndex(of: 30) {
   ///         print(numbers[i ..< numbers.endIndex])
   ///     }
   ///     // Prints "[30, 40, 50]"
@@ -784,7 +784,7 @@ extension ${Self}: RandomAccessCollection, MutableCollection {
   ///     print(streetsSlice)
   ///     // Prints "["Channing", "Douglas", "Evarts"]"
   ///
-  ///     let i = streetsSlice.index(of: "Evarts")    // 4
+  ///     let i = streetsSlice.firstIndex(of: "Evarts")    // 4
   ///     print(streets[i!])
   ///     // Prints "Evarts"
   ///

stdlib/public/core/BidirectionalCollection.swift

@@ -119,7 +119,7 @@ where SubSequence: BidirectionalCollection, Indices: BidirectionalCollection {
   ///     print(streetsSlice)
   ///     // Prints "["Channing", "Douglas", "Evarts"]"
   ///
-  ///     let index = streetsSlice.index(of: "Evarts")    // 4
+  ///     let index = streetsSlice.firstIndex(of: "Evarts")    // 4
   ///     print(streets[index!])
   ///     // Prints "Evarts"
   ///

stdlib/public/core/ClosedRange.swift

@@ -308,6 +308,12 @@ where Bound : Strideable, Bound.Stride : SignedInteger
     return lowerBound <= element && element <= upperBound
               ? .inRange(element) : nil
   }
+
+  @inlinable
+  public func _customLastIndexOfEquatableElement(_ element: Bound) -> Index?? {
+    // The first and last elements are the same because each element is unique.
+    return _customIndexOfEquatableElement(element)
+  }
 }
 
 extension Comparable {