[stdlib] Adding a deprecated version of flatMap to warn misuses. (#7823)

Due to implicit promotion to optional it is possible to call flatMap
with a closure, that does not return an optional. This way the code
works, but is unnecessary inefficient. Such uses of flatMap can and
should be replaced with map.

stdlib/public/core/SequenceAlgorithms.swift.gyb

@@ -717,6 +717,13 @@ extension Sequence {
     }
     return result
   }
+
+  @available(*, deprecated, message: "This call uses implicit promotion to optional. Please use map instead.")
+  public func flatMap<T>(
+    _ transform: (${GElement}) throws -> T
+  ) rethrows -> [T] {
+    return try map(transform)
+  }
 }
 
 extension Sequence {

test/Constraints/closures.swift

@@ -513,7 +513,8 @@ func returnsArray() -> [Int] { return [] }
 
 returnsArray().flatMap { $0 }.flatMap { }
 // expected-warning@-1 {{expression of type 'Int' is unused}}
-// expected-warning@-2 {{result of call to 'flatMap' is unused}}
+// expected-warning@-2 {{Please use map instead.}}
+// expected-warning@-3 {{result of call to 'flatMap' is unused}}
 
 // rdar://problem/30271695
 _ = ["hi"].flatMap { $0.isEmpty ? nil : $0 }

test/DebugInfo/generic_arg5.swift

@@ -17,7 +17,7 @@ public func foo<Type>(_ values : [S<Type>])
   // CHECK: ![[TY]] = !DICompositeType({{.*}}identifier: "_T012generic_arg51SVyAA3fooySayACyxGGlFQq_GD")
   // CHECK: ![[EXPR]] = !DIExpression(DW_OP_deref)
   let _ = values.flatMap { arg in
-    return arg
+    return .some(arg)
   }
 
 }

test/stdlib/FlatMapDiagnostics.swift.gyb

@@ -0,0 +1,39 @@
+//===--- FlatMapDiagnostics.swift -----------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+// RUN: rm -rf %t && mkdir -p %t
+// RUN: %gyb %s -o %t/FlatMapDiagnostics.swift
+// RUN: %target-swift-frontend -typecheck -verify %t/FlatMapDiagnostics.swift
+
+
+% for Type in [
+%   'Sequence',
+%   'Collection',
+%   'LazySequenceProtocol',
+%   'LazyCollectionProtocol']:
+
+func testGeneric${Type}<T : ${Type}>(xs: T) {
+  _ = xs.flatMap { $0 } // expected-warning {{Please use map instead.}}
+}
+
+% end
+
+func testArray(xs: [Int]) {
+ _ = xs.flatMap { $0 } // expected-warning {{Please use map instead.}}
+ _ = xs.lazy.flatMap { $0 } // expected-warning {{Please use map instead.}}
+}
+
+func testGenericLazyBidirectionalCollection<
+  T : LazyCollectionProtocol & BidirectionalCollection
+>(xs: T) where T.Elements : BidirectionalCollection {
+  _ = xs.flatMap { $0 } // expected-warning {{Please use map instead.}}
+}
+