[stdlib] Rename flatten() to joined() (SE-0133)

Author: jtbandes

stdlib/public/core/FlatMap.swift

@@ -14,14 +14,14 @@ extension LazySequenceProtocol {
   /// Returns the concatenated results of mapping `transform` over
   /// `self`.  Equivalent to 
   ///
-  ///     self.map(transform).flatten()
+  ///     self.map(transform).joined()
   ///
   /// - Complexity: O(1)
   public func flatMap<SegmentOfResult : Sequence>(
     _ transform: (Elements.Iterator.Element) -> SegmentOfResult
   ) -> LazySequence<
     FlattenSequence<LazyMapSequence<Elements, SegmentOfResult>>> {
-    return self.map(transform).flatten()
+    return self.map(transform).joined()
   }
 
   /// Returns a `LazyMapSequence` containing the concatenated non-nil
@@ -47,7 +47,7 @@ extension LazyCollectionProtocol {
   /// Returns the concatenated results of mapping `transform` over
   /// `self`.  Equivalent to 
   ///
-  ///     self.map(transform).flatten()
+  ///     self.map(transform).joined()
   ///
   /// - Complexity: O(1)
   public func flatMap<SegmentOfResult : Collection>(
@@ -56,7 +56,7 @@ extension LazyCollectionProtocol {
     FlattenCollection<
       LazyMapCollection<Elements, SegmentOfResult>>
   > {
-    return self.map(transform).flatten()
+    return self.map(transform).joined()
   }
 
   /// Returns a `LazyMapCollection` containing the concatenated non-nil
@@ -86,7 +86,7 @@ extension LazyCollectionProtocol
   /// Returns the concatenated results of mapping `transform` over
   /// `self`.  Equivalent to 
   ///
-  ///     self.map(transform).flatten()
+  ///     self.map(transform).joined()
   ///
   /// - Complexity: O(1)
   public func flatMap<SegmentOfResult : Collection>(
@@ -95,7 +95,7 @@ extension LazyCollectionProtocol
     FlattenBidirectionalCollection<
       LazyMapBidirectionalCollection<Elements, SegmentOfResult>>>
     where SegmentOfResult : BidirectionalCollection {
-    return self.map(transform).flatten()
+    return self.map(transform).joined()
   }
 
   /// Returns a `LazyMapBidirectionalCollection` containing the concatenated non-nil

stdlib/public/core/Flatten.swift.gyb

@@ -68,13 +68,13 @@ public struct FlattenIterator<Base : IteratorProtocol> : IteratorProtocol, Seque
 /// The elements of this view are a concatenation of the elements of
 /// each sequence in the base.
 ///
-/// The `flatten` property is always lazy, but does not implicitly
+/// The `joined` method is always lazy, but does not implicitly
 /// confer laziness on algorithms applied to its result.  In other
 /// words, for ordinary sequences `s`:
 ///
-/// * `s.flatten()` does not create new storage
-/// * `s.flatten().map(f)` maps eagerly and returns a new array
-/// * `s.lazy.flatten().map(f)` maps lazily and returns a `LazyMapSequence`
+/// * `s.joined()` does not create new storage
+/// * `s.joined().map(f)` maps eagerly and returns a new array
+/// * `s.lazy.joined().map(f)` maps lazily and returns a `LazyMapSequence`
 ///
 /// - See also: `FlattenCollection`
 public struct FlattenSequence<Base : Sequence> : Sequence
@@ -113,8 +113,8 @@ extension Sequence where Iterator.Element : Sequence {
   ///     // Prints "8..<10"
   ///     // Prints "15..<17"
   ///
-  ///     // Use 'flatten()' to access each element of each range:
-  ///     for index in ranges.flatten() {
+  ///     // 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"
@@ -123,9 +123,14 @@ extension Sequence where Iterator.Element : Sequence {
   ///   sequence of sequences.
   ///
   /// - SeeAlso: `flatMap(_:)`, `joined(separator:)`
-  public func flatten() -> FlattenSequence<Self> {
+  public func joined() -> FlattenSequence<Self> {
     return FlattenSequence(_base: self)
   }
+  
+  @available(*, unavailable, renamed: "joined()")
+  public func flatten() -> FlattenSequence<Self> {
+    Builtin.unreachable()
+  }
 }
 
 extension LazySequenceProtocol
@@ -134,11 +139,16 @@ extension LazySequenceProtocol
   Iterator.Element : Sequence {
 
   /// A concatenation of the elements of `self`.
-  public func flatten() -> LazySequence<
+  public func joined() -> LazySequence<
     FlattenSequence<Elements>
   > {
     return FlattenSequence(_base: elements).lazy
   }
+
+  @available(*, unavailable, renamed: "joined()")
+  public func flatten() -> LazySequence<FlattenSequence<Elements>> {
+    Builtin.unreachable()
+  }
 }
 
 % for traversal in ['Forward', 'Bidirectional']:
@@ -209,13 +219,13 @@ extension ${Index} : Comparable {
 /// The elements of this view are a concatenation of the elements of
 /// each collection in the base.
 ///
-/// The `flatten` property is always lazy, but does not implicitly
+/// The `joined` method is always lazy, but does not implicitly
 /// confer laziness on algorithms applied to its result.  In other
 /// words, for ordinary collections `c`:
 ///
-/// * `c.flatten()` does not create new storage
-/// * `c.flatten().map(f)` maps eagerly and returns a new array
-/// * `c.lazy.flatten().map(f)` maps lazily and returns a `LazyMapCollection`
+/// * `c.joined()` does not create new storage
+/// * `c.joined().map(f)` maps eagerly and returns a new array
+/// * `c.lazy.joined().map(f)` maps lazily and returns a `LazyMapCollection`
 ///
 /// - Note: The performance of accessing `startIndex`, `first`, any methods
 ///   that depend on `startIndex`, or of advancing a `${Collection}Index`
@@ -381,8 +391,8 @@ extension ${collectionForTraversal(traversal)}
   ///     // Prints "8..<10"
   ///     // Prints "15..<17"
   ///
-  ///     // Use 'flatten()' to access each element of each range:
-  ///     for index in ranges.flatten() {
+  ///     // 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"
@@ -391,9 +401,14 @@ extension ${collectionForTraversal(traversal)}
   ///   collection of collections.
   ///
   /// - SeeAlso: `flatMap(_:)`, `joined(separator:)`
-  public func flatten() -> ${Collection}<Self> {
+  public func joined() -> ${Collection}<Self> {
     return ${Collection}(self)
   }
+  
+  @available(*, unavailable, renamed: "joined()")
+  public func flatten() -> ${Collection}<Self> {
+    Builtin.unreachable()
+  }
 }
 
 extension LazyCollectionProtocol
@@ -404,9 +419,14 @@ extension LazyCollectionProtocol
   ${constraints % {'Base': 'Elements.'}},
   Iterator.Element == Elements.Iterator.Element {
   /// A concatenation of the elements of `self`.
-  public func flatten() -> LazyCollection<${Collection}<Elements>> {
+  public func joined() -> LazyCollection<${Collection}<Elements>> {
     return ${Collection}(elements).lazy
   }
+  
+  @available(*, unavailable, renamed: "joined()")
+  public func flatten() -> LazyCollection<${Collection}<Elements>> {
+    Builtin.unreachable()
+  }
 }
 
 % end

stdlib/public/core/Sequence.swift

@@ -813,7 +813,7 @@ extension Sequence {
 
     if i != ringBuffer.startIndex {
       return AnySequence(
-        [ringBuffer[i..<ringBuffer.endIndex], ringBuffer[0..<i]].flatten())
+        [ringBuffer[i..<ringBuffer.endIndex], ringBuffer[0..<i]].joined())
     }
     return AnySequence(ringBuffer)
   }

stdlib/public/core/SequenceAlgorithms.swift.gyb

@@ -615,7 +615,7 @@ extension Sequence {
   ///     // [1, 2, 2, 3, 3, 3, 4, 4, 4, 4]
   ///
   /// In fact, `s.flatMap(transform)`  is equivalent to
-  /// `Array(s.map(transform).flatten())`.
+  /// `Array(s.map(transform).joined())`.
   ///
   /// - Parameter transform: A closure that accepts an element of this
   ///   sequence as its argument and returns a sequence or collection.

test/Prototypes/Algorithms.swift.gyb

@@ -691,7 +691,7 @@ suite.test("reverseSubrange") {
         b.reverseSubrange(p..<q)
         expectEqual(
           b,
-          Array([prefix, ArraySlice(a[p..<q].reversed()), suffix].flatten()))
+          Array([prefix, ArraySlice(a[p..<q].reversed()), suffix].joined()))
         }
     }
   }
@@ -709,7 +709,7 @@ suite.test("rotate") {
         for m in p...q {
           var b = a
           let r0 = b._rotateSubrangeForward(p..<q, shiftingToStart: m)
-          let rotated = Array([prefix, a[m..<q], a[p..<m], suffix].flatten())
+          let rotated = Array([prefix, a[m..<q], a[p..<m], suffix].joined())
           expectEqual(b, rotated)
           expectEqual(r0, a.index(p, offsetBy: a[m..<q].count))
 
@@ -738,7 +738,7 @@ suite.test("rotateRandomAccess") {
         for m in p...q {
           var b = a
           let r0 = b[p..<q].rotateRandomAccess(shiftingToStart: m)
-          let rotated = Array([prefix, a[m..<q], a[p..<m], suffix].flatten())
+          let rotated = Array([prefix, a[m..<q], a[p..<m], suffix].joined())
           expectEqual(b, rotated)
           expectEqual(r0, a.index(p, offsetBy: a[m..<q].count))
 

test/Prototypes/CollectionTransformers.swift

@@ -173,7 +173,7 @@ public struct ArrayBuilder<T> : CollectionBuilder {
     _resultParts.append(_resultTail)
     _resultTail = []
     // FIXME: optimize.  parallelize.
-    return Array(_resultParts.flatten())
+    return Array(_resultParts.joined())
   }
 }
 

validation-test/stdlib/Concatenate.swift

@@ -33,21 +33,21 @@ let samples: ContiguousArray<(CountableRange<Int>, X)> = [
 
 for (expected, source) in samples {
   ConcatenateTests.test("forward-\(source)") {
-    checkBidirectionalCollection(expected, source.flatten())
+    checkBidirectionalCollection(expected, source.joined())
   }
 
   ConcatenateTests.test("reverse-\(source)") {
     // FIXME: separate 'expected' and 'reversed' variables are a workaround
     // for: <rdar://problem/20789500>
     let expected = ContiguousArray(expected.lazy.reversed())
-    let reversed = source.flatten().reversed()
+    let reversed = source.joined().reversed()
     checkBidirectionalCollection(expected, reversed)
   }
 
   ConcatenateTests.test("sequence-\(source)") {
     checkSequence(
       ContiguousArray(expected),
-      AnySequence(source).flatten())
+      AnySequence(source).joined())
   }
 }
 

validation-test/stdlib/Lazy.swift.gyb

@@ -1219,14 +1219,14 @@ do {
     tests.test("FlattenSequence/\(data)") {
       var base = MinimalSequence(
         elements: data.map { MinimalSequence(elements: $0) })
-      checkSequence(expected, base.flatten(), resiliencyChecks: .none)
+      checkSequence(expected, base.joined(), resiliencyChecks: .none)
 
       // Checking that flatten doesn't introduce laziness
 
       // checkSequence consumed base, so reassign
       base = MinimalSequence(
         elements: data.map { MinimalSequence(elements: $0) })
-      let flattened = base.flatten()
+      let flattened = base.joined()
       var calls = 0
       _ = flattened.map { _ in calls += 1 }
       expectEqual(
@@ -1240,7 +1240,7 @@ do {
         elements: data.map { MinimalSequence(elements: $0) }
       ).lazy.map { $0 }
 
-      let flattened = base.flatten()
+      let flattened = base.joined()
       var calls = 0
       _ = flattened.map { _ in calls += 1 }
       expectEqual(0, calls, "unexpected eagerness in \(flattened.dynamicType)")
@@ -1252,7 +1252,7 @@ do {
       let base = Minimal${TraversalCollection}(
         elements: data.map { Minimal${TraversalCollection}(elements: $0) })
 
-      let flattened = base.flatten()
+      let flattened = base.joined()
       check${Traversal}Collection(expected, flattened, resiliencyChecks: .none)
 
       // Checking that flatten doesn't introduce laziness
@@ -1269,7 +1269,7 @@ do {
         elements: data.map { Minimal${TraversalCollection}(elements: $0) }
       ).lazy.map { $0 }
 
-      let flattened = base.flatten()
+      let flattened = base.joined()
 
       var calls = 0
       _ = flattened.map { _ in calls += 1 }