SR-1519: Add Sequence.first(predicate:)

Author: Russ Bishop

stdlib/private/StdlibCollectionUnittest/CheckSequenceType.swift

@@ -127,7 +127,11 @@ public struct FindTest {
   ) {
     self.expected = expected
     self.element = MinimalEquatableValue(element)
-    self.sequence = sequence.map(MinimalEquatableValue.init)
+    var elementIndex = 0
+    self.sequence = sequence.map {
+    	defer { elementIndex += 1 }
+    	return MinimalEquatableValue($0, identity: elementIndex) 
+    }
     self.expectedLeftoverSequence = expectedLeftoverSequence.map(
       MinimalEquatableValue.init)
     self.loc = SourceLoc(file, line, comment: "test data")

stdlib/public/core/Sequence.swift

@@ -564,6 +564,18 @@ 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 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 match or `nil` if there was no match.
+  @warn_unused_result
+  func first(
+    predicate: @noescape (Iterator.Element) throws -> Bool
+  ) rethrows -> Iterator.Element?
+
   @warn_unused_result
   func _customContainsEquatableElement(
     _ element: Iterator.Element
@@ -950,13 +962,32 @@ extension Sequence {
   ///
   /// - Parameter body: A closure that takes an element of the sequence as a
   ///   parameter.
+  @warn_unused_result
   public func forEach(
     _ body: @noescape (Iterator.Element) throws -> Void
   ) rethrows {
     for element in self {
       try body(element)
     }
   }
+  
+  /// Returns the first element of the sequence that satisfies the given
+  /// predicate or nil if no such element is found.
+  ///
+  /// - Parameter 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 match or `nil` if there was no match.
+  public func first(
+    predicate: @noescape (Iterator.Element) throws -> Bool
+  ) rethrows -> Iterator.Element? {
+    for element in self {
+      if try predicate(element) {
+        return element
+      }
+    }
+    return nil
+  }
 }
 
 extension Sequence where Iterator.Element : Equatable {

validation-test/stdlib/SequenceType.swift.gyb

@@ -616,6 +616,26 @@ SequenceTypeTests.test("contains/Predicate") {
   }
 }
 
+//===----------------------------------------------------------------------===//
+// first()
+//===----------------------------------------------------------------------===//
+
+SequenceTypeTests.test("first/Predicate") {
+  for test in findTests {
+    let s = MinimalSequence<MinimalEquatableValue>(elements: test.sequence)
+    let found = s.first { $0 == test.element }
+    expectEqual(
+      test.expected == nil ? nil : test.element,
+      found,
+      stackTrace: SourceLocStack().with(test.loc))
+    if let found = found {
+      expectEqual(
+        test.expected, found.identity,
+        "find() should find only the first element matching its predicate")
+    }
+  }
+}
+
 //===----------------------------------------------------------------------===//
 // reduce()
 //===----------------------------------------------------------------------===//