diff --git a/Sources/Algorithms/AdjacentPairs.swift b/Sources/Algorithms/AdjacentPairs.swift index 1c1fd71..dd8473d 100644 --- a/Sources/Algorithms/AdjacentPairs.swift +++ b/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,6 +25,11 @@ 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 { AdjacentPairsSequence(base: self) @@ -31,7 +37,7 @@ extension Sequence { } 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 { AdjacentPairsCollection(base: self) diff --git a/Sources/Algorithms/Combinations.swift b/Sources/Algorithms/Combinations.swift index 2f26e9c..95c9c5e 100644 --- a/Sources/Algorithms/Combinations.swift +++ b/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 { precondition(k >= 0, "Can't have combinations with a negative number of elements.") diff --git a/Sources/Algorithms/Documentation.docc/Algorithms.md b/Sources/Algorithms/Documentation.docc/Algorithms.md new file mode 100644 index 0000000..4626905 --- /dev/null +++ b/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 + +- +- +- +- +- +- +- +- +- +- +- +- diff --git a/Sources/Algorithms/Documentation.docc/Chunking.md b/Sources/Algorithms/Documentation.docc/Chunking.md new file mode 100644 index 0000000..3c0699a --- /dev/null +++ b/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`` diff --git a/Sources/Algorithms/Documentation.docc/CombinationsPermutations.md b/Sources/Algorithms/Documentation.docc/CombinationsPermutations.md new file mode 100644 index 0000000..54199fa --- /dev/null +++ b/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`` diff --git a/Sources/Algorithms/Documentation.docc/DeprecatedScan.md b/Sources/Algorithms/Documentation.docc/DeprecatedScan.md new file mode 100644 index 0000000..c122730 --- /dev/null +++ b/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:_:)`` diff --git a/Sources/Algorithms/Documentation.docc/Extending.md b/Sources/Algorithms/Documentation.docc/Extending.md new file mode 100644 index 0000000..5d45a15 --- /dev/null +++ b/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`` diff --git a/Sources/Algorithms/Documentation.docc/Filtering.md b/Sources/Algorithms/Documentation.docc/Filtering.md new file mode 100644 index 0000000..46b7255 --- /dev/null +++ b/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 + +Text + +## 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`` diff --git a/Sources/Algorithms/Documentation.docc/Joining.md b/Sources/Algorithms/Documentation.docc/Joining.md new file mode 100644 index 0000000..2c567c2 --- /dev/null +++ b/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`` diff --git a/Sources/Algorithms/Documentation.docc/MinAndMax.md b/Sources/Algorithms/Documentation.docc/MinAndMax.md new file mode 100644 index 0000000..56e2cc8 --- /dev/null +++ b/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:)`` + diff --git a/Sources/Algorithms/Documentation.docc/Partitioning.md b/Sources/Algorithms/Documentation.docc/Partitioning.md new file mode 100644 index 0000000..d1b1fdc --- /dev/null +++ b/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:)`` diff --git a/Sources/Algorithms/Documentation.docc/Reductions.md b/Sources/Algorithms/Documentation.docc/Reductions.md new file mode 100644 index 0000000..81d7ea2 --- /dev/null +++ b/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 + +- diff --git a/Sources/Algorithms/Documentation.docc/Sampling.md b/Sources/Algorithms/Documentation.docc/Sampling.md new file mode 100644 index 0000000..b94f662 --- /dev/null +++ b/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:)`` diff --git a/Sources/Algorithms/Documentation.docc/Selecting.md b/Sources/Algorithms/Documentation.docc/Selecting.md new file mode 100644 index 0000000..e5bed60 --- /dev/null +++ b/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`` diff --git a/Sources/Algorithms/Documentation.docc/SlicingSplitting.md b/Sources/Algorithms/Documentation.docc/SlicingSplitting.md new file mode 100644 index 0000000..78db68a --- /dev/null +++ b/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`` diff --git a/Sources/Algorithms/Documentation.docc/Trimming.md b/Sources/Algorithms/Documentation.docc/Trimming.md new file mode 100644 index 0000000..8052a22 --- /dev/null +++ b/Sources/Algorithms/Documentation.docc/Trimming.md @@ -0,0 +1,27 @@ +# Trimming + +Remove unwanted elements from the start, the end, or both ends of a collection. + +## Topics + +### Trimming Both Ends of a Collection + +- ``Swift/BidirectionalCollection/trimming(while:)`` +- ``Swift/BidirectionalCollection/trim(while:)-781az`` +- ``Swift/BidirectionalCollection/trim(while:)-6cbz3`` + +### Trimming from the Start + +- ``Swift/Collection/trimmingPrefix(while:)`` +- ``Swift/Collection/trimPrefix(while:)-2r8n8`` +- ``Swift/Collection/trimPrefix(while:)-93obt`` + +### Trimming from the End + +- ``Swift/BidirectionalCollection/trimmingSuffix(while:)`` +- ``Swift/BidirectionalCollection/trimSuffix(while:)-33ubj`` +- ``Swift/BidirectionalCollection/trimSuffix(while:)-3o6x9`` + +### Finding the Suffix of a Collection + +- ``Swift/BidirectionalCollection/suffix(while:)`` diff --git a/Sources/Algorithms/Indexed.swift b/Sources/Algorithms/Indexed.swift index ea5598a..6298b6d 100644 --- a/Sources/Algorithms/Indexed.swift +++ b/Sources/Algorithms/Indexed.swift @@ -94,6 +94,10 @@ extension Collection { /// Returns a collection of pairs *(i, x)*, where *i* represents an index of /// the collection, and *x* represents an element. /// + /// The `indexed()` method is similar to the standard library's `enumerated()` + /// method, but provides the index with each element instead of a zero-based + /// counter. + /// /// This example iterates over the indices and elements of a set, building an /// array consisting of indices of names with five or fewer letters. /// @@ -105,7 +109,7 @@ extension Collection { /// } /// } /// - /// Returns: A collection of paired indices and elements of this collection. + /// - Returns: A collection of paired indices and elements of this collection. @inlinable public func indexed() -> IndexedCollection { IndexedCollection(base: self)