Various refactors

Author: Tim Vermeulen

Guides/Chunked.md

@@ -61,8 +61,9 @@ c.elementsEqual(c.chunked(...).joined())
 
 ## Detailed Design
 
-The two methods are added as extension to `Collection`, with two matching
-versions that return a lazy wrapper added to `LazyCollectionProtocol`.
+The three methods are added as extension to `Collection`. `chunked(by:)` and
+`chunked(on:)` are eager by default, both with a matching version that return a
+lazy wrapper added to `LazySequenceProtocol`.
 
 ```swift
 extension Collection {
@@ -73,9 +74,11 @@ extension Collection {
   public func chunked<Subject: Equatable>(
       on projection: (Element) -> Subject
   ) -> [(Subject, SubSequence)]
+  
+  public func chunks(ofCount count: Int) -> ChunksOfCountCollection<Self>
 }
 
-extension LazyCollectionProtocol {
+extension LazySequenceProtocol where Self: Collection, Elements: Collection {
   public func chunked(
       by belongInSameGroup: @escaping (Element, Element) -> Bool
   ) -> ChunkedByCollection<Elements, Element>
@@ -86,8 +89,10 @@ extension LazyCollectionProtocol {
 }
 ```
 
-The `ChunkedByCollection` and `ChunkedOnCollection` types are bidirectional when 
-the wrapped collection is bidirectional.
+The `ChunkedByCollection`, `ChunkedOnCollection`, and `ChunksOfCountCollection`
+types are bidirectional when the wrapped collection is bidirectional.
+`ChunksOfCountCollection` also conforms to `LazySequenceProtocol` when the base
+collection conforms.
 
 ### Complexity
 

Guides/Compacted.md

@@ -37,8 +37,9 @@ extension Collection {
 
 The `Sequence` version of `compacted()` returns a `CompactedSequence` type,
 while the `Collection` version returns `CompactedCollection`. The collection
-has conditional conformance to `BidirectionalCollection` and
-`LazyCollectionProtocol` when the base collection conforms.
+has conditional conformance to `BidirectionalCollection` when the base
+collection conforms, and both have conditional conformance to 
+`LazySequenceProtocol` when the base collection conforms.
 
 ### Naming
 

Guides/Indexed.md

@@ -21,7 +21,7 @@ for (i, n) in numbers.indexed() {
 
 ## Detailed Design
 
-The `indexed` method returns an `Indexed` type:
+The `indexed` method returns an `IndexedCollection` type:
 
 ```swift
 extension Collection {
@@ -31,5 +31,5 @@ extension Collection {
 
 `IndexedCollection` scales from a collection up to a random-access collection, 
 depending on its base type. `Indexed` also conforms to `LazySequenceProtocol` 
-and `LazyCollectionProtocol` when the base type conforms.
+when the base type conforms.
 

Guides/Intersperse.md

@@ -31,9 +31,9 @@ extension Sequence {
 
 The new `InterspersedSequence` type represents the sequence when the separator
 is inserted between each element. `InterspersedSequence` conforms to
-`Collection`, `BidirectionalCollection`, `RandomAccessCollection`,
-`LazySequenceProtocol` and `LazyCollectionProtocol` when the base sequence
-conforms to those respective protocols.
+`Collection`, `BidirectionalCollection`, `RandomAccessCollection` and
+`LazySequenceProtocol` when the base sequence conforms to those respective 
+protocols.
 
 ### Complexity
 

Guides/Joined.md

@@ -70,8 +70,7 @@ Note that the sequence separator of the closure-less version defined on
 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:
+lazy sequences and collections for the same reason as explained above:
 
 ```swift
 extension LazySequenceProtocol where Element: Sequence {
@@ -84,7 +83,7 @@ extension LazySequenceProtocol where Element: Sequence {
     ) -> JoinedByClosureSequence<Self, Separator>
 }
 
-extension LazyCollectionProtocol where Element: Collection {
+extension LazySequenceProtocol where Self: Collection, Element: Collection {
     public func joined(
         by separator: @escaping (Element, Element) -> Element.Element
     ) -> JoinedByClosureCollection<Self, CollectionOfOne<Element.Element>>
@@ -98,5 +97,4 @@ extension LazyCollectionProtocol where Element: Collection {
 `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.
+conform to `BidirectionalCollection` when the base collection conforms.

Guides/Permutations.md

@@ -120,14 +120,15 @@ Since both result types need to store an array of the collection’s
 indices and mutate the array to generate each permutation, they only
 have `Sequence` conformance. Adding `Collection` conformance would require
 storing the array in the index type, which would in turn lead to copying the
-array at every index advancement. The `PermutationsSequence` type
-conforms to `LazySequenceProtocol` when its base type conforms.
+array at every index advancement. The `PermutationsSequence` and
+`UniquePermutationsSequence` types conforms to `LazySequenceProtocol` when their
+base type conforms.
 
 ### Complexity
 
 Calling `permutations()` is an O(1) operation. Creating the iterator for a
-`Permutations` instance and each call to `Permutations.Iterator.next()` is an
-O(_n_) operation.
+`PermutationsSequence` instance and each call to
+`PermutationsSequence.Iterator.next()` is an O(_n_) operation.
 
 Calling `uniquePermutations()` is an O(_n_) operation, because it preprocesses 
 the collection to find duplicate elements. Creating the iterator for and each 

Guides/Product.md

@@ -43,8 +43,8 @@ collection, and a random-access collection when both base collections have those
 conformances.
 
 We don't provide higher arities (like `Product3Sequence`, `Product4Sequence`,
-etc.) at this time to match the standard library's `Zip2` type. Users can
-compose multiple calls to `product` if they would like higher arities.
+etc.) at this time to match the standard library's `Zip2Sequence` type. Users
+can compose multiple calls to `product` if they would like higher arities.
 
 ### Complexity
 

Guides/LazySplit.md renamed to Guides/Split.md

@@ -1,7 +1,7 @@
-# LazySplit
+# Split
 
-[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/LazySplit.swift) | 
- [Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/LazySplitTests.swift)]
+[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Split.swift) | 
+ [Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/SplitTests.swift)]
 
 Lazily-evaluating versions of
 [`split(maxSplits:omittingEmptySubsequences:whereSeparator:)`](https://developer.apple.com/documentation/swift/sequence/3128814-split)

Guides/Stride.md

@@ -3,38 +3,44 @@
 [[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/Stride.swift) | 
  [Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/StrideTests.swift)]
 
-A type that steps over sequence elements by the specified amount.
+Step over the elements of a sequence elements by a specified amount.
 
 This is available through the `striding(by:)` method on any `Sequence`.
 
 ```swift
 (0...10).striding(by: 2) // == [0, 2, 4, 6, 8, 10]
 ```
 
-If the stride is larger than the count, the resulting wrapper only contains the 
-first element.
+If the stride is larger than the length of the sequence, the resulting wrapper
+only contains the first element.
 
 The stride amount must be a positive value.
 
 ## Detailed Design
 
-The `striding(by:)` method is declared as a `Sequence` extension, and returns a 
-`StridingSequence` type:
+The `striding(by:)` method is declared in extension of both `Sequence` and
+`Collection`:
 
 ```swift
 extension Sequence {
-  public func striding(by step: Int) -> StridingSequence<Self>
+    public func striding(by step: Int) -> StridingSequence<Self>
 }
-```
-
-A custom `Index` type is defined so that it's not possible to get confused when 
-trying to access an index of the stride collection.
 
-```swift
-[0, 1, 2, 3, 4].striding(by: 2)[1] // == 1
-[0, 1, 2, 3, 4].striding(by: 2).map { $0 }[1] // == 2
+extension Collection {
+    public func striding(by step: Int) -> StridingCollection<Self>
+}
 ```
 
+The reason for this distinction is subtle. The `StridingSequence.Iterator` type
+is unable to skip over multiple elements of the wrapped iterator at once since
+that's not part of `IteratorProtocol`'s interface. In order to efficiently
+stride over collections that provide a fast way of skipping multiple elements at
+once, the `StridingCollection` type was added which does not provide a custom
+`Iterator` type and therefore always strides over the underlying collection in
+the fastest way possible. See the related
+[GitHub issue](https://github.com/apple/swift-algorithms/issues/63) for more
+information.
+
 A careful thought was given to the composition of these strides by giving a 
 custom implementation to `index(_:offsetBy:limitedBy)` which multiplies the 
 offset by the stride amount. 

Guides/Windows.md

@@ -36,7 +36,7 @@ collection is empty.
 
 The resulting `WindowsCollection` type is a collection, with conditional
 conformance to the `BidirectionalCollection`, `RandomAccessCollection`, and
-`LazyCollectionProtocol` protocols when the base collection conforms.
+`LazySequenceProtocol` protocols when the base collection conforms.
 
 ### Complexity