Merge pull request #2529 from russbishop/se0032

[stdlib] SR-1519: Implement SE-0032: Add Sequence.first(predicate:)

Author: gribozavr

stdlib/private/StdlibCollectionUnittest/CheckSequenceType.swift

@@ -127,7 +127,9 @@ public struct FindTest {
   ) {
     self.expected = expected
     self.element = MinimalEquatableValue(element)
-    self.sequence = sequence.map(MinimalEquatableValue.init)
+    self.sequence = sequence.enumerated().map {
+      return MinimalEquatableValue($1, identity: $0) 
+    }
     self.expectedLeftoverSequence = expectedLeftoverSequence.map(
       MinimalEquatableValue.init)
     self.loc = SourceLoc(file, line, comment: "test data")
@@ -1771,6 +1773,30 @@ self.test("\(testNamePrefix).forEach/semantics") {
   }
 }
 
+//===----------------------------------------------------------------------===//
+// first()
+//===----------------------------------------------------------------------===//
+
+self.test("\(testNamePrefix).first/semantics") {
+  for test in findTests {
+    let s = makeWrappedSequenceWithEquatableElement(test.sequence)
+    let closureLifetimeTracker = LifetimeTracked(0)
+    let found = s.first {
+      _blackHole(closureLifetimeTracker)
+      return $0 == wrapValueIntoEquatable(test.element)
+    }
+    expectEqual(
+      test.expected == nil ? nil : wrapValueIntoEquatable(test.element),
+      found,
+      stackTrace: SourceLocStack().with(test.loc))
+    if test.expected != nil {
+      expectEqual(
+        test.expected, (found as? MinimalEquatableValue)?.identity,
+        "find() should find only the first element matching its predicate")
+    }
+  }
+}
+
 //===----------------------------------------------------------------------===//
 // _preprocessingPass()
 //===----------------------------------------------------------------------===//

stdlib/private/StdlibCollectionUnittest/LoggingWrappers.swift.gyb

@@ -81,6 +81,7 @@ public class SequenceLog {
   public static var map = TypeIndexed(0)
   public static var filter = TypeIndexed(0)
   public static var forEach = TypeIndexed(0)
+  public static var first = TypeIndexed(0)
   public static var dropFirst = TypeIndexed(0)
   public static var dropLast = TypeIndexed(0)
   public static var prefixMaxLength = TypeIndexed(0)
@@ -113,7 +114,6 @@ public class CollectionLog : SequenceLog {
   public static var isEmpty = TypeIndexed(0)
   public static var count = TypeIndexed(0)
   public static var _customIndexOfEquatableElement = TypeIndexed(0)
-  public static var first = TypeIndexed(0)
   public static var advance = TypeIndexed(0)
   public static var advanceLimit = TypeIndexed(0)
   public static var distance = TypeIndexed(0)
@@ -243,6 +243,13 @@ public struct ${Self}<
     Log.forEach[selfType] += 1
     try base.forEach(body)
   }
+  
+  public func first(
+    where predicate: @noescape (Base.Iterator.Element) throws -> Bool
+  ) rethrows -> Base.Iterator.Element? {
+    Log.first[selfType] += 1
+    return try base.first(where: predicate)
+  }
 
   public typealias SubSequence = Base.SubSequence
 

stdlib/public/core/Sequence.swift

@@ -564,6 +564,17 @@ public protocol Sequence {
     isSeparator: @noescape (Iterator.Element) throws -> Bool
   ) rethrows -> [SubSequence]
 
+  /// Returns the first element of the sequence that satisfies the given
+  /// predicate or nil if no such element is found.
+  ///
+  /// - Parameter where: 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 match or `nil` if there was no match.
+  func first(
+    where: @noescape (Iterator.Element) throws -> Bool
+  ) rethrows -> Iterator.Element?
+
   @warn_unused_result
   func _customContainsEquatableElement(
     _ element: Iterator.Element
@@ -959,6 +970,34 @@ extension Sequence {
   }
 }
 
+internal enum _StopIteration : ErrorProtocol {
+  case stop
+}
+
+extension Sequence {
+  /// Returns the first element of the sequence that satisfies the given
+  /// predicate or nil if no such element is found.
+  ///
+  /// - Parameter where: 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 match or `nil` if there was no match.
+  public func first(
+    where predicate: @noescape (Iterator.Element) throws -> Bool
+  ) rethrows -> Iterator.Element? {
+    var foundElement: Iterator.Element? = nil
+    do {
+      try self.forEach {
+        if try predicate($0) {
+          foundElement = $0
+          throw _StopIteration.stop
+        }
+      }
+    } catch is _StopIteration { }
+    return foundElement
+  }
+}
+
 extension Sequence where Iterator.Element : Equatable {
   /// Returns the longest possible subsequences of the sequence, in order,
   /// around elements equal to the given element. Elements that are used to

validation-test/stdlib/SequenceType.swift.gyb

@@ -944,6 +944,16 @@ SequenceTypeTests.test("forEach/dispatch") {
   expectCustomizable(tester, tester.log.forEach)
 }
 
+//===----------------------------------------------------------------------===//
+// first()
+//===----------------------------------------------------------------------===//
+
+SequenceTypeTests.test("first/dispatch") {
+  let tester = SequenceLog.dispatchTester([OpaqueValue(1)])
+  tester.first { $0.value == 1 }
+  expectCustomizable(tester, tester.log.first)
+}
+
 //===----------------------------------------------------------------------===//
 // dropFirst()
 //===----------------------------------------------------------------------===//