Curate documentation for Algorithms module (#201)

Sources/Algorithms/AdjacentPairs.swift

@@ -10,7 +10,8 @@
 //===----------------------------------------------------------------------===//
 
 extension Sequence {
-  /// Creates a sequence of adjacent pairs of elements from this sequence.
+  /// Returns a sequence of overlapping adjacent pairs of the elements of this
+  /// sequence.
   ///
   /// In the `AdjacentPairsSequence` returned by this method, the elements of
   /// the *i*th pair are the *i*th and *(i+1)*th elements of the underlying
@@ -24,14 +25,19 @@ extension Sequence {
   ///     // Prints "(2, 3)"
   ///     // Prints "(3, 4)"
   ///     // Prints "(4, 5)"
+  ///
+  /// The resulting sequence is empty when called on an empty or single-element
+  /// sequence.
+  ///
+  /// - Complexity: O(1)
   @inlinable
   public func adjacentPairs() -> AdjacentPairsSequence<Self> {
     AdjacentPairsSequence(base: self)
   }
 }
 
 extension Collection {
-  /// A collection of adjacent pairs of elements built from an underlying
+  /// Returns a collection of overlapping adjacent pairs of the elements of this
   /// collection.
   ///
   /// In an `AdjacentPairsCollection`, the elements of the *i*th pair are the
@@ -46,6 +52,11 @@ extension Collection {
   ///     // Prints "(2, 3)"
   ///     // Prints "(3, 4)"
   ///     // Prints "(4, 5)"
+  ///
+  /// The resulting collection is empty when called on an empty or
+  /// single-element collection.
+  ///
+  /// - Complexity: O(1)
   @inlinable
   public func adjacentPairs() -> AdjacentPairsCollection<Self> {
     AdjacentPairsCollection(base: self)

Sources/Algorithms/Combinations.swift

@@ -289,8 +289,8 @@ extension Collection {
   /// - Parameter k: The number of elements to include in each combination.
   ///
   /// - Complexity: O(1) for random-access base collections. O(*n*) where *n*
-  /// is the number of elements in the base collection, since
-  /// `CombinationsSequence` accesses the `count` of the base collection.
+  ///   is the number of elements in the base collection, since
+  ///   `CombinationsSequence` accesses the `count` of the base collection.
   @inlinable
   public func combinations(ofCount k: Int) -> CombinationsSequence<Self> {
     precondition(k >= 0, "Can't have combinations with a negative number of elements.")

Sources/Algorithms/Documentation.docc/Algorithms.md

@@ -0,0 +1,24 @@
+# ``Algorithms``
+
+**Swift Algorithms** is an open-source package of sequence and collection algorithms, 
+along with their related types.
+
+## Overview
+
+This library adds a variety of extended operations to the Swift standard library's
+`Sequence` and `Collection` protocols, via extension methods and global functions.
+
+## Topics
+
+- <doc:CombinationsPermutations>
+- <doc:SlicingSplitting>
+- <doc:Chunking>
+- <doc:Joining>
+- <doc:Extending>
+- <doc:Trimming>
+- <doc:Sampling>
+- <doc:MinAndMax>
+- <doc:Selecting>
+- <doc:Filtering>
+- <doc:Reductions>
+- <doc:Partitioning>

Sources/Algorithms/Documentation.docc/Chunking.md

@@ -0,0 +1,27 @@
+# Chunking
+
+Break collections into consecutive chunks by length, count, or based on closure-based logic.
+
+## Overview
+
+## Topics
+
+### Chunking a Collection by Count
+
+- ``Swift/Collection/chunks(ofCount:)``
+- ``Swift/Collection/evenlyChunked(in:)``
+
+### Chunking a Collection by Predicate
+
+- ``Swift/Collection/chunked(on:)``
+- ``Swift/Collection/chunked(by:)``
+- ``Swift/LazySequenceProtocol/chunked(by:)``
+- ``Swift/LazySequenceProtocol/chunked(by:)``
+- ``Swift/LazySequenceProtocol/chunked(on:)``
+
+### Supporting Types
+
+- ``ChunkedByCollection``
+- ``ChunkedOnCollection``
+- ``ChunksOfCountCollection``
+- ``EvenlyChunkedCollection``

Sources/Algorithms/Documentation.docc/CombinationsPermutations.md

@@ -0,0 +1,32 @@
+# Combinations and Permutations
+
+Find the combinations and permutations of any collection's elements,
+or the product of two different collections.
+
+## Topics
+
+### Combinations
+
+- ``Swift/Collection/combinations(ofCount:)-26o4x``
+- ``Swift/Collection/combinations(ofCount:)-53jql``
+
+### Permutations
+
+- ``Swift/Collection/permutations(ofCount:)-7rc99``
+- ``Swift/Collection/permutations(ofCount:)-5zvhn``
+
+### Unique Permutations
+
+- ``Swift/Collection/uniquePermutations(ofCount:)-2extq``
+- ``Swift/Collection/uniquePermutations(ofCount:)-48r1k``
+
+### Product
+
+- ``product(_:_:)``
+
+### Supporting Types
+
+- ``CombinationsSequence``
+- ``PermutationsSequence``
+- ``UniquePermutationsSequence``
+- ``Product2Sequence``

Sources/Algorithms/Documentation.docc/DeprecatedScan.md

@@ -0,0 +1,14 @@
+# DeprecatedScan
+
+These methods are deprecated, use the `reductions` family of methods instead.
+
+## Overview
+
+## Topics
+
+- ``Swift/Sequence/scan(_:)``
+- ``Swift/Sequence/scan(_:_:)``
+- ``Swift/Sequence/scan(into:_:)``
+- ``Swift/LazySequenceProtocol/scan(_:)``
+- ``Swift/LazySequenceProtocol/scan(_:_:)``
+- ``Swift/LazySequenceProtocol/scan(into:_:)``

Sources/Algorithms/Documentation.docc/Extending.md

@@ -0,0 +1,21 @@
+# Extending
+
+Chain two collections end-to-end,
+or repeat a collection forever or a specific number of times.    
+
+## Topics
+
+### Chaining Two Collections
+
+- ``chain(_:_:)``
+
+### Cycling a Collection
+
+- ``Swift/Collection/cycled()``
+- ``Swift/Collection/cycled(times:)``
+
+### Supporting Types
+
+- ``Chain2Sequence``
+- ``CycledSequence``
+- ``CycledTimesCollection``

Sources/Algorithms/Documentation.docc/Filtering.md

@@ -0,0 +1,26 @@
+# Filtering
+
+Remove duplicated elements or strip the `nil` values from a sequence or collection. 
+
+## Overview
+
+<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
+
+## Topics
+
+### Uniqueing Elements
+
+- ``Swift/Sequence/uniqued()``
+- ``Swift/Sequence/uniqued(on:)``
+- ``Swift/LazySequenceProtocol/uniqued(on:)``
+
+### Filtering out nil Elements
+
+- ``Swift/Collection/compacted()``
+- ``Swift/Sequence/compacted()``
+
+### Supporting Types
+
+- ``UniquedSequence``
+- ``CompactedSequence``
+- ``CompactedCollection``

Sources/Algorithms/Documentation.docc/Joining.md

@@ -0,0 +1,35 @@
+# Joining
+
+Join the parts of a collection of collections,
+providing a connecting element or collection,
+or a closure that produces the connector.
+
+## Topics
+
+### Joining by an Element
+
+- ``Swift/Sequence/joined(by:)-6mrf9``
+- ``Swift/Sequence/joined(by:)-9hyaf``
+- ``Swift/Collection/joined(by:)-430ue``
+- ``Swift/LazySequenceProtocol/joined(by:)-3yjw0``
+- ``Swift/LazySequenceProtocol/joined(by:)-47xvy``
+
+### Joining by a Collection 
+
+- ``Swift/Sequence/joined(by:)-62j1h``
+- ``Swift/Sequence/joined(by:)-9b108``
+- ``Swift/Collection/joined(by:)-28n3b``
+- ``Swift/LazySequenceProtocol/joined(by:)-4neii``
+- ``Swift/LazySequenceProtocol/joined(by:)-49xws``
+
+### Interspersing Elements
+
+- ``Swift/Sequence/interspersed(with:)``
+
+### Supporting Types
+
+- ``JoinedBySequence``
+- ``JoinedByCollection``
+- ``JoinedByClosureSequence``
+- ``JoinedByClosureCollection``
+- ``InterspersedSequence``

Sources/Algorithms/Documentation.docc/MinAndMax.md

@@ -0,0 +1,23 @@
+# Finding the Minimum and Maximum
+
+Find the minimum and maximum elements simultaneously,
+or a specific number of elements at the minimum and maximum.   
+
+## Topics
+
+### Finding Minimum or Maximum Elements
+
+- ``Swift/Sequence/min(count:)``
+- ``Swift/Collection/min(count:)``
+- ``Swift/Sequence/min(count:sortedBy:)``
+- ``Swift/Collection/min(count:sortedBy:)``
+- ``Swift/Sequence/max(count:)``
+- ``Swift/Collection/max(count:)``
+- ``Swift/Sequence/max(count:sortedBy:)``
+- ``Swift/Collection/max(count:sortedBy:)``
+
+### Finding the Minimum and Maximum Elements Simulataneously
+
+- ``Swift/Sequence/minAndMax()``
+- ``Swift/Sequence/minAndMax(by:)``
+

Sources/Algorithms/Documentation.docc/Partitioning.md

@@ -0,0 +1,34 @@
+# Partitioning and Rotating
+
+Partition a collection according to a unary predicate,
+rotate a collection around a particular index,
+or find the index where a collection is already partitioned.
+
+## Topics
+
+### Stable Partition
+
+- ``Swift/MutableCollection/stablePartition(by:)``
+- ``Swift/MutableCollection/stablePartition(subrange:by:)``
+- ``Swift/Sequence/partitioned(by:)``
+- ``Swift/Collection/partitioned(by:)``
+
+### Partition of Subranges
+
+- ``Swift/MutableCollection/partition(subrange:by:)-5vdh7``
+- ``Swift/MutableCollection/partition(subrange:by:)-4gpqz``
+
+### Finding a Partition Index
+
+- ``Swift/Collection/partitioningIndex(where:)``
+
+### Rotation
+
+- ``Swift/MutableCollection/rotate(toStartAt:)-9fp48``
+- ``Swift/MutableCollection/rotate(toStartAt:)-2r55j``
+- ``Swift/MutableCollection/rotate(subrange:toStartAt:)-ov6a``
+- ``Swift/MutableCollection/rotate(subrange:toStartAt:)-5teoq``
+
+### Reversing
+
+- ``Swift/MutableCollection/reverse(subrange:)``

Sources/Algorithms/Documentation.docc/Reductions.md

@@ -0,0 +1,21 @@
+# Reductions
+
+Find the incremental values of a sequence "reduce" operation.
+
+## Topics
+
+- ``Swift/Sequence/reductions(_:)``
+- ``Swift/Sequence/reductions(_:_:)``
+- ``Swift/Sequence/reductions(into:_:)``
+- ``Swift/LazySequenceProtocol/reductions(_:)``
+- ``Swift/LazySequenceProtocol/reductions(_:_:)``
+- ``Swift/LazySequenceProtocol/reductions(into:_:)``
+
+### Supporting Types
+
+- ``InclusiveReductionsSequence``
+- ``ExclusiveReductionsSequence``
+
+### Deprecated Methods
+
+- <doc:DeprecatedScan>

Sources/Algorithms/Documentation.docc/Sampling.md

@@ -0,0 +1,17 @@
+# Random Sampling
+
+Choose a specified number of random elements from a sequence or collection.
+
+## Topics
+
+### Random Sampling 
+
+- ``Swift/Sequence/randomSample(count:)``
+- ``Swift/Collection/randomSample(count:)``
+- ``Swift/Collection/randomStableSample(count:)``
+
+### Random Sampling with a Generator
+
+- ``Swift/Sequence/randomSample(count:using:)``
+- ``Swift/Collection/randomSample(count:using:)``
+- ``Swift/Collection/randomStableSample(count:using:)``

Sources/Algorithms/Documentation.docc/Selecting.md

@@ -0,0 +1,25 @@
+# Selecting Elements 
+
+Select elements at a particular interval, the first mapped value,
+or iterate of elements with their indices.
+
+## Topics
+
+### Selecting Elements at an Interval
+
+- ``Swift/Sequence/striding(by:)``
+- ``Swift/Collection/striding(by:)``
+
+### Conditionally Finding the First Mapped Value
+
+- ``Swift/Sequence/firstNonNil(_:)``
+
+### Iterating Over Elements with Their Indices  
+
+- ``Swift/Collection/indexed()``
+
+### Supporting Types
+
+- ``IndexedCollection``
+- ``StridingSequence``
+- ``StridingCollection``

Sources/Algorithms/Documentation.docc/SlicingSplitting.md

@@ -0,0 +1,31 @@
+# Slicing and Splitting
+
+Iterate over tuple pairs of adjacent elements, overlapping windows of a specified size, or lazily-calculated splits.
+
+## Topics
+
+### Adjacent Pairs
+
+- ``Swift/Sequence/adjacentPairs()``
+- ``Swift/Collection/adjacentPairs()``
+
+### Windows
+
+- ``Swift/Collection/windows(ofCount:)``
+
+### Lazily Splitting a Collection
+
+These methods…
+
+- ``Swift/LazySequenceProtocol/split(separator:maxSplits:omittingEmptySubsequences:)-4q4x8``
+- ``Swift/LazySequenceProtocol/split(maxSplits:omittingEmptySubsequences:whereSeparator:)-68oqf``
+- ``Swift/LazySequenceProtocol/split(separator:maxSplits:omittingEmptySubsequences:)-a46s``
+- ``Swift/LazySequenceProtocol/split(maxSplits:omittingEmptySubsequences:whereSeparator:)-3rwee``
+
+### Supporting Types
+
+- ``AdjacentPairsSequence``
+- ``AdjacentPairsCollection``
+- ``WindowsOfCountCollection``
+- ``SplitSequence``
+- ``SplitCollection``