Skip to content

Commit fc8fdfd

Browse files
natecook1000natecook1000
authored
Curate documentation for Algorithms module (#201)
1 parent bfcaaa8 commit fc8fdfd

17 files changed

+377
-5
lines changed

‎Sources/Algorithms/AdjacentPairs.swift

+13-2
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@
1010
//===----------------------------------------------------------------------===//
1111

1212
extension Sequence {
13-
/// Creates a sequence of adjacent pairs of elements from this sequence.
13+
/// Returns a sequence of overlapping adjacent pairs of the elements of this
14+
/// sequence.
1415
///
1516
/// In the `AdjacentPairsSequence` returned by this method, the elements of
1617
/// the *i*th pair are the *i*th and *(i+1)*th elements of the underlying
@@ -24,14 +25,19 @@ extension Sequence {
2425
/// // Prints "(2, 3)"
2526
/// // Prints "(3, 4)"
2627
/// // Prints "(4, 5)"
28+
///
29+
/// The resulting sequence is empty when called on an empty or single-element
30+
/// sequence.
31+
///
32+
/// - Complexity: O(1)
2733
@inlinable
2834
public func adjacentPairs() -> AdjacentPairsSequence<Self> {
2935
AdjacentPairsSequence(base: self)
3036
}
3137
}
3238

3339
extension Collection {
34-
/// A collection of adjacent pairs of elements built from an underlying
40+
/// Returns a collection of overlapping adjacent pairs of the elements of this
3541
/// collection.
3642
///
3743
/// In an `AdjacentPairsCollection`, the elements of the *i*th pair are the
@@ -46,6 +52,11 @@ extension Collection {
4652
/// // Prints "(2, 3)"
4753
/// // Prints "(3, 4)"
4854
/// // Prints "(4, 5)"
55+
///
56+
/// The resulting collection is empty when called on an empty or
57+
/// single-element collection.
58+
///
59+
/// - Complexity: O(1)
4960
@inlinable
5061
public func adjacentPairs() -> AdjacentPairsCollection<Self> {
5162
AdjacentPairsCollection(base: self)

‎Sources/Algorithms/Combinations.swift

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

‎Sources/Algorithms/Documentation.docc/Algorithms.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# ``Algorithms``
2+
3+
**Swift Algorithms** is an open-source package of sequence and collection algorithms,
4+
along with their related types.
5+
6+
## Overview
7+
8+
This library adds a variety of extended operations to the Swift standard library's
9+
`Sequence` and `Collection` protocols, via extension methods and global functions.
10+
11+
## Topics
12+
13+
- <doc:CombinationsPermutations>
14+
- <doc:SlicingSplitting>
15+
- <doc:Chunking>
16+
- <doc:Joining>
17+
- <doc:Extending>
18+
- <doc:Trimming>
19+
- <doc:Sampling>
20+
- <doc:MinAndMax>
21+
- <doc:Selecting>
22+
- <doc:Filtering>
23+
- <doc:Reductions>
24+
- <doc:Partitioning>

‎Sources/Algorithms/Documentation.docc/Chunking.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Chunking
2+
3+
Break collections into consecutive chunks by length, count, or based on closure-based logic.
4+
5+
## Overview
6+
7+
## Topics
8+
9+
### Chunking a Collection by Count
10+
11+
- ``Swift/Collection/chunks(ofCount:)``
12+
- ``Swift/Collection/evenlyChunked(in:)``
13+
14+
### Chunking a Collection by Predicate
15+
16+
- ``Swift/Collection/chunked(on:)``
17+
- ``Swift/Collection/chunked(by:)``
18+
- ``Swift/LazySequenceProtocol/chunked(by:)``
19+
- ``Swift/LazySequenceProtocol/chunked(by:)``
20+
- ``Swift/LazySequenceProtocol/chunked(on:)``
21+
22+
### Supporting Types
23+
24+
- ``ChunkedByCollection``
25+
- ``ChunkedOnCollection``
26+
- ``ChunksOfCountCollection``
27+
- ``EvenlyChunkedCollection``

‎Sources/Algorithms/Documentation.docc/CombinationsPermutations.md

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Combinations and Permutations
2+
3+
Find the combinations and permutations of any collection's elements,
4+
or the product of two different collections.
5+
6+
## Topics
7+
8+
### Combinations
9+
10+
- ``Swift/Collection/combinations(ofCount:)-26o4x``
11+
- ``Swift/Collection/combinations(ofCount:)-53jql``
12+
13+
### Permutations
14+
15+
- ``Swift/Collection/permutations(ofCount:)-7rc99``
16+
- ``Swift/Collection/permutations(ofCount:)-5zvhn``
17+
18+
### Unique Permutations
19+
20+
- ``Swift/Collection/uniquePermutations(ofCount:)-2extq``
21+
- ``Swift/Collection/uniquePermutations(ofCount:)-48r1k``
22+
23+
### Product
24+
25+
- ``product(_:_:)``
26+
27+
### Supporting Types
28+
29+
- ``CombinationsSequence``
30+
- ``PermutationsSequence``
31+
- ``UniquePermutationsSequence``
32+
- ``Product2Sequence``

‎Sources/Algorithms/Documentation.docc/DeprecatedScan.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# DeprecatedScan
2+
3+
These methods are deprecated, use the `reductions` family of methods instead.
4+
5+
## Overview
6+
7+
## Topics
8+
9+
- ``Swift/Sequence/scan(_:)``
10+
- ``Swift/Sequence/scan(_:_:)``
11+
- ``Swift/Sequence/scan(into:_:)``
12+
- ``Swift/LazySequenceProtocol/scan(_:)``
13+
- ``Swift/LazySequenceProtocol/scan(_:_:)``
14+
- ``Swift/LazySequenceProtocol/scan(into:_:)``

‎Sources/Algorithms/Documentation.docc/Extending.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Extending
2+
3+
Chain two collections end-to-end,
4+
or repeat a collection forever or a specific number of times.
5+
6+
## Topics
7+
8+
### Chaining Two Collections
9+
10+
- ``chain(_:_:)``
11+
12+
### Cycling a Collection
13+
14+
- ``Swift/Collection/cycled()``
15+
- ``Swift/Collection/cycled(times:)``
16+
17+
### Supporting Types
18+
19+
- ``Chain2Sequence``
20+
- ``CycledSequence``
21+
- ``CycledTimesCollection``

‎Sources/Algorithms/Documentation.docc/Filtering.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Filtering
2+
3+
Remove duplicated elements or strip the `nil` values from a sequence or collection.
4+
5+
## Overview
6+
7+
<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
8+
9+
## Topics
10+
11+
### Uniqueing Elements
12+
13+
- ``Swift/Sequence/uniqued()``
14+
- ``Swift/Sequence/uniqued(on:)``
15+
- ``Swift/LazySequenceProtocol/uniqued(on:)``
16+
17+
### Filtering out nil Elements
18+
19+
- ``Swift/Collection/compacted()``
20+
- ``Swift/Sequence/compacted()``
21+
22+
### Supporting Types
23+
24+
- ``UniquedSequence``
25+
- ``CompactedSequence``
26+
- ``CompactedCollection``

‎Sources/Algorithms/Documentation.docc/Joining.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Joining
2+
3+
Join the parts of a collection of collections,
4+
providing a connecting element or collection,
5+
or a closure that produces the connector.
6+
7+
## Topics
8+
9+
### Joining by an Element
10+
11+
- ``Swift/Sequence/joined(by:)-6mrf9``
12+
- ``Swift/Sequence/joined(by:)-9hyaf``
13+
- ``Swift/Collection/joined(by:)-430ue``
14+
- ``Swift/LazySequenceProtocol/joined(by:)-3yjw0``
15+
- ``Swift/LazySequenceProtocol/joined(by:)-47xvy``
16+
17+
### Joining by a Collection
18+
19+
- ``Swift/Sequence/joined(by:)-62j1h``
20+
- ``Swift/Sequence/joined(by:)-9b108``
21+
- ``Swift/Collection/joined(by:)-28n3b``
22+
- ``Swift/LazySequenceProtocol/joined(by:)-4neii``
23+
- ``Swift/LazySequenceProtocol/joined(by:)-49xws``
24+
25+
### Interspersing Elements
26+
27+
- ``Swift/Sequence/interspersed(with:)``
28+
29+
### Supporting Types
30+
31+
- ``JoinedBySequence``
32+
- ``JoinedByCollection``
33+
- ``JoinedByClosureSequence``
34+
- ``JoinedByClosureCollection``
35+
- ``InterspersedSequence``

‎Sources/Algorithms/Documentation.docc/MinAndMax.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Finding the Minimum and Maximum
2+
3+
Find the minimum and maximum elements simultaneously,
4+
or a specific number of elements at the minimum and maximum.
5+
6+
## Topics
7+
8+
### Finding Minimum or Maximum Elements
9+
10+
- ``Swift/Sequence/min(count:)``
11+
- ``Swift/Collection/min(count:)``
12+
- ``Swift/Sequence/min(count:sortedBy:)``
13+
- ``Swift/Collection/min(count:sortedBy:)``
14+
- ``Swift/Sequence/max(count:)``
15+
- ``Swift/Collection/max(count:)``
16+
- ``Swift/Sequence/max(count:sortedBy:)``
17+
- ``Swift/Collection/max(count:sortedBy:)``
18+
19+
### Finding the Minimum and Maximum Elements Simulataneously
20+
21+
- ``Swift/Sequence/minAndMax()``
22+
- ``Swift/Sequence/minAndMax(by:)``
23+

‎Sources/Algorithms/Documentation.docc/Partitioning.md

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Partitioning and Rotating
2+
3+
Partition a collection according to a unary predicate,
4+
rotate a collection around a particular index,
5+
or find the index where a collection is already partitioned.
6+
7+
## Topics
8+
9+
### Stable Partition
10+
11+
- ``Swift/MutableCollection/stablePartition(by:)``
12+
- ``Swift/MutableCollection/stablePartition(subrange:by:)``
13+
- ``Swift/Sequence/partitioned(by:)``
14+
- ``Swift/Collection/partitioned(by:)``
15+
16+
### Partition of Subranges
17+
18+
- ``Swift/MutableCollection/partition(subrange:by:)-5vdh7``
19+
- ``Swift/MutableCollection/partition(subrange:by:)-4gpqz``
20+
21+
### Finding a Partition Index
22+
23+
- ``Swift/Collection/partitioningIndex(where:)``
24+
25+
### Rotation
26+
27+
- ``Swift/MutableCollection/rotate(toStartAt:)-9fp48``
28+
- ``Swift/MutableCollection/rotate(toStartAt:)-2r55j``
29+
- ``Swift/MutableCollection/rotate(subrange:toStartAt:)-ov6a``
30+
- ``Swift/MutableCollection/rotate(subrange:toStartAt:)-5teoq``
31+
32+
### Reversing
33+
34+
- ``Swift/MutableCollection/reverse(subrange:)``

‎Sources/Algorithms/Documentation.docc/Reductions.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Reductions
2+
3+
Find the incremental values of a sequence "reduce" operation.
4+
5+
## Topics
6+
7+
- ``Swift/Sequence/reductions(_:)``
8+
- ``Swift/Sequence/reductions(_:_:)``
9+
- ``Swift/Sequence/reductions(into:_:)``
10+
- ``Swift/LazySequenceProtocol/reductions(_:)``
11+
- ``Swift/LazySequenceProtocol/reductions(_:_:)``
12+
- ``Swift/LazySequenceProtocol/reductions(into:_:)``
13+
14+
### Supporting Types
15+
16+
- ``InclusiveReductionsSequence``
17+
- ``ExclusiveReductionsSequence``
18+
19+
### Deprecated Methods
20+
21+
- <doc:DeprecatedScan>

‎Sources/Algorithms/Documentation.docc/Sampling.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Random Sampling
2+
3+
Choose a specified number of random elements from a sequence or collection.
4+
5+
## Topics
6+
7+
### Random Sampling
8+
9+
- ``Swift/Sequence/randomSample(count:)``
10+
- ``Swift/Collection/randomSample(count:)``
11+
- ``Swift/Collection/randomStableSample(count:)``
12+
13+
### Random Sampling with a Generator
14+
15+
- ``Swift/Sequence/randomSample(count:using:)``
16+
- ``Swift/Collection/randomSample(count:using:)``
17+
- ``Swift/Collection/randomStableSample(count:using:)``

‎Sources/Algorithms/Documentation.docc/Selecting.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Selecting Elements
2+
3+
Select elements at a particular interval, the first mapped value,
4+
or iterate of elements with their indices.
5+
6+
## Topics
7+
8+
### Selecting Elements at an Interval
9+
10+
- ``Swift/Sequence/striding(by:)``
11+
- ``Swift/Collection/striding(by:)``
12+
13+
### Conditionally Finding the First Mapped Value
14+
15+
- ``Swift/Sequence/firstNonNil(_:)``
16+
17+
### Iterating Over Elements with Their Indices
18+
19+
- ``Swift/Collection/indexed()``
20+
21+
### Supporting Types
22+
23+
- ``IndexedCollection``
24+
- ``StridingSequence``
25+
- ``StridingCollection``

‎Sources/Algorithms/Documentation.docc/SlicingSplitting.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Slicing and Splitting
2+
3+
Iterate over tuple pairs of adjacent elements, overlapping windows of a specified size, or lazily-calculated splits.
4+
5+
## Topics
6+
7+
### Adjacent Pairs
8+
9+
- ``Swift/Sequence/adjacentPairs()``
10+
- ``Swift/Collection/adjacentPairs()``
11+
12+
### Windows
13+
14+
- ``Swift/Collection/windows(ofCount:)``
15+
16+
### Lazily Splitting a Collection
17+
18+
These methods…
19+
20+
- ``Swift/LazySequenceProtocol/split(separator:maxSplits:omittingEmptySubsequences:)-4q4x8``
21+
- ``Swift/LazySequenceProtocol/split(maxSplits:omittingEmptySubsequences:whereSeparator:)-68oqf``
22+
- ``Swift/LazySequenceProtocol/split(separator:maxSplits:omittingEmptySubsequences:)-a46s``
23+
- ``Swift/LazySequenceProtocol/split(maxSplits:omittingEmptySubsequences:whereSeparator:)-3rwee``
24+
25+
### Supporting Types
26+
27+
- ``AdjacentPairsSequence``
28+
- ``AdjacentPairsCollection``
29+
- ``WindowsOfCountCollection``
30+
- ``SplitSequence``
31+
- ``SplitCollection``

0 commit comments

Comments
 (0)