Add guide, doc comments, tests

Author: Tim Vermeulen

Guides/Joined.md

@@ -0,0 +1,102 @@
+#  Joined
+
+[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Joined.swift) | 
+ [Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/JoinedTests.swift)]
+
+Concatenate a sequence of sequences, inserting a separator between each element.
+
+The separator can be either a single element or a sequence of elements, and it
+can optionally depend on the sequences right before and after it by returning it
+from a closure:
+
+```swift
+for number in [[1], [2, 3], [4, 5, 6]].joined(by: 100) {
+    print(number)
+}
+// 1, 100, 2, 3, 100, 4, 5, 6
+
+for number in [[10], [20, 30], [40, 50, 60]].joined(by: { [$0.count, $1.count] }) {
+    print(number)
+}
+// 10, 1, 2, 20, 30, 2, 3, 40, 50, 60
+```
+
+## Detailed Design
+
+The versions that take a closure are executed eagerly and are defined on
+`Sequence`:
+
+```swift
+extension Sequence where Element: Sequence {
+    public func joined(
+        by separator: (Element, Element) throws -> Element.Element
+    ) rethrows -> [Element.Element]
+    
+    public func joined<Separator>(
+        by separator: (Element, Element) throws -> Separator
+    ) rethrows -> [Element.Element]
+        where Separator: Sequence, Separator.Element == Element.Element
+}
+```
+
+The versions that do not take a closure are defined on both `Sequence` and
+`Collection` because the resulting collections need to precompute their start
+index to ensure O(1) access:
+
+```swift
+extension Sequence where Element: Sequence {
+    public func joined(by separator: Element.Element)
+        -> JoinedBySequence<Self, CollectionOfOne<Element.Element>>
+        
+    public func joined<Separator>(
+        by separator: Separator
+    ) -> JoinedBySequence<Self, Separator>
+        where Separator: Collection, Separator.Element == Element.Element
+}
+
+extension Collection where Element: Sequence {
+    public func joined(by separator: Element.Element)
+        -> JoinedByCollection<Self, CollectionOfOne<Element.Element>>
+        
+    public func joined<Separator>(
+        by separator: Separator
+    ) -> JoinedByCollection<Self, Separator>
+        where Separator: Collection, Separator.Element == Element.Element
+}
+```
+
+Note that the sequence separator of the closure-less version defined on
+`Sequence` is required to be a `Collection`, because a plain `Sequence` cannot in
+general be iterated over multiple times.
+
+The closure-based versions also have lazy variants that are defined on both
+`LazySequenceProtocol` and `LazyCollectionProtocol` for the same reason as
+explained above:
+
+```swift
+extension LazySequenceProtocol where Element: Sequence {
+    public func joined(
+        by separator: @escaping (Element, Element) -> Element.Element
+    ) -> JoinedByClosureSequence<Self, CollectionOfOne<Element.Element>>
+  
+    public func joined<Separator>(
+        by separator: @escaping (Element, Element) -> Separator
+    ) -> JoinedByClosureSequence<Self, Separator>
+}
+
+extension LazyCollectionProtocol where Element: Collection {
+    public func joined(
+        by separator: @escaping (Element, Element) -> Element.Element
+    ) -> JoinedByClosureCollection<Self, CollectionOfOne<Element.Element>>
+  
+    public func joined<Separator>(
+        by separator: @escaping (Element, Element) -> Separator
+    ) -> JoinedByClosureCollection<Self, Separator>
+}
+```
+
+`JoinedBySequence`, `JoinedByClosureSequence`, `JoinedByCollection`, and
+`JoinedByClosureCollection` conform to `LazySequenceProtocol` when the base
+sequence conforms. `JoinedByCollection` and `JoinedByClosureCollection` also
+conform to `LazyCollectionProtocol` and `BidirectionalCollection` when the base
+collection conforms.

Sources/Algorithms/EitherSequence.swift

@@ -13,6 +13,7 @@
 // Either
 //===----------------------------------------------------------------------===//
 
+/// A general-purpose sum type.
 @usableFromInline
 internal enum Either<Left, Right> {
   case left(Left)
@@ -53,6 +54,7 @@ extension Either: Comparable where Left: Comparable, Right: Comparable {
 // EitherSequence
 //===----------------------------------------------------------------------===//
 
+/// A sequence that has one of the two specified types.
 @usableFromInline
 internal enum EitherSequence<Left: Sequence, Right: Sequence>
   where Left.Element == Right.Element

Sources/Algorithms/FlattenCollection.swift

@@ -9,6 +9,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// A collection consisting of all the elements contained in a collection of
+/// collections.
 @usableFromInline
 internal struct FlattenCollection<Base: Collection> where Base.Element: Collection {
   @usableFromInline
@@ -98,7 +100,8 @@ extension FlattenCollection: Collection {
       else { return base[start.outer].distance(from: startInner, to: end.inner!) }
 
     let firstPart = base[start.outer][startInner...].count
-    let middlePart = base[start.outer..<end.outer].dropFirst().reduce(0, { $0 + $1.count })
+    let middlePart = base[start.outer..<end.outer].dropFirst()
+      .reduce(0, { $0 + $1.count })
     let lastPart = end.inner.map { base[end.outer][..<$0].count } ?? 0
 
     return firstPart + middlePart + lastPart
@@ -226,7 +229,11 @@ extension FlattenCollection: Collection {
     if let indexInner = index.inner {
       let element = base[index.outer]
 
-      if let inner = element.index(indexInner, offsetBy: -remainder, limitedBy: element.startIndex) {
+      if let inner = element.index(
+          indexInner,
+          offsetBy: -remainder,
+          limitedBy: element.startIndex
+      ) {
         return Index(outer: index.outer, inner: inner)
       }
 
@@ -238,7 +245,11 @@ extension FlattenCollection: Collection {
     while outer != limit.outer {
       let element = base[outer]
 
-      if let inner = element.index(element.endIndex, offsetBy: -remainder, limitedBy: element.startIndex) {
+      if let inner = element.index(
+          element.endIndex,
+          offsetBy: -remainder,
+          limitedBy: element.startIndex
+      ) {
         return Index(outer: outer, inner: inner)
       }
 
@@ -247,8 +258,11 @@ extension FlattenCollection: Collection {
     }
 
     let element = base[outer]
-    return element.index(element.endIndex, offsetBy: -remainder, limitedBy: limit.inner!)
-      .map { inner in Index(outer: outer, inner: inner) }
+    return element.index(
+      element.endIndex,
+      offsetBy: -remainder,
+      limitedBy: limit.inner!
+    ).map { inner in Index(outer: outer, inner: inner) }
   }
 }
 
@@ -273,11 +287,18 @@ extension FlattenCollection: BidirectionalCollection
   }
 }
 
+extension FlattenCollection: LazySequenceProtocol
+  where Base: LazySequenceProtocol, Base.Element: LazySequenceProtocol {}
+extension FlattenCollection: LazyCollectionProtocol
+  where Base: LazyCollectionProtocol, Base.Element: LazyCollectionProtocol {}
+
 //===----------------------------------------------------------------------===//
 // joined()
 //===----------------------------------------------------------------------===//
 
 extension Collection where Element: Collection {
+  /// Returns the concatenation of the elements in this collection of
+  /// collections.
   @inlinable
   internal func joined() -> FlattenCollection<Self> {
     FlattenCollection(base: self)

Sources/Algorithms/Intersperse.swift

@@ -284,6 +284,10 @@ extension Intersperse: LazyCollectionProtocol
 // InterspersedMap
 //===----------------------------------------------------------------------===//
 
+
+/// A sequence over the results of applying a closure to the sequence's
+/// elements, with a separator that separates each pair of adjacent transformed
+/// values.
 @usableFromInline
 internal struct InterspersedMap<Base: Sequence, Result> {
   @usableFromInline
@@ -360,7 +364,7 @@ extension InterspersedMap: Collection where Base: Collection {
   @usableFromInline
   internal struct Index: Comparable {
     @usableFromInline
-    internal enum Representation {
+    internal enum Representation: Equatable {
       case element(Base.Index)
       case separator(previous: Base.Index, next: Base.Index)
     }
@@ -573,6 +577,14 @@ extension InterspersedMap: BidirectionalCollection
   }
 }
 
+extension InterspersedMap.Index.Representation: Hashable
+  where Base.Index: Hashable {}
+
+extension InterspersedMap: LazySequenceProtocol
+  where Base: LazySequenceProtocol {}
+extension InterspersedMap: LazyCollectionProtocol
+  where Base: LazyCollectionProtocol {}
+
 //===----------------------------------------------------------------------===//
 // interspersed(with:)
 //===----------------------------------------------------------------------===//
@@ -616,8 +628,21 @@ extension Sequence {
 //===----------------------------------------------------------------------===//
 // lazy.interspersed(_:with:)
 //===----------------------------------------------------------------------===//
-  
+
 extension LazySequenceProtocol {
+  /// Returns a sequence over the results of applying a closure to the
+  /// sequence's elements, with a separator that separates each pair of adjacent
+  /// transformed values.
+  ///
+  /// The transformation closure lets you intersperse a sequence using a
+  /// separator of a different type than the original's sequence's elements.
+  /// Each separator is produced by a closure that is given access to the
+  /// two elements in the original sequence right before and after it.
+  ///
+  ///     let strings = [1, 2, 2].interspersedMap(String.init,
+  ///         with: { $0 == $1 ? " == " : " != " })
+  ///     print(strings.joined()) // "1 != 2 == 2"
+  ///
   @usableFromInline
   internal func interspersedMap<Result>(
     _ transform: @escaping (Element) -> Result,