Add methods scanning already-sorted sequences

Add a method for already-sorted sequences that returns each unique value, paired with the count of each value. Add another method that returns each unique value. Have both eager and lazy variants for each method.

Author: CTMacUser

CHANGELOG.md

@@ -12,6 +12,12 @@ This project follows semantic versioning.
 
 - Bidirectional collections have a new `ends(with:)` method that matches
   the behavior of the standard library's `starts(with:)` method. ([#224])
+- Sequences that are already sorted can use the `countSortedDuplicates` and
+  `withoutSortedDuplicates` methods, with eager and lazy versions.
+  The former returns each unique value paired with the count of
+  that value's occurances.
+  The latter returns each unique value,
+  turning a possibly non-decreasing sequence to a strictly-increasing one.
 
 <!-- *No new changes.* -->
 

Guides/README.md

@@ -32,6 +32,7 @@ These guides describe the design and intention behind the APIs included in the `
 - [`suffix(while:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Suffix.md): Returns the suffix of a collection where all element pass a given predicate.
 - [`trimmingPrefix(while:)`, `trimmingSuffix(while)`, `trimming(while:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Trim.md): Returns a slice by trimming elements from a collection's start, end, or both. The mutating `trim...` methods trim a collection in place.
 - [`uniqued()`, `uniqued(on:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Unique.md): The unique elements of a collection, preserving their order.
+- [`withoutSortedDuplicates()`, `withoutSortedDuplicates(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/SortedDuplicates.md): Given an already-sorted sequence and the sorting predicate, reduce all runs of a unique value to a single element each. Has eager and lazy variants.
 - [`minAndMax()`, `minAndMax(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/MinMax.md): Returns the smallest and largest elements of a sequence.
 
 #### Partial sorting
@@ -42,6 +43,7 @@ These guides describe the design and intention behind the APIs included in the `
 
 - [`adjacentPairs()`](https://github.com/apple/swift-algorithms/blob/main/Guides/AdjacentPairs.md): Lazily iterates over tuples of adjacent elements.
 - [`chunked(by:)`, `chunked(on:)`, `chunks(ofCount:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Chunked.md): Eager and lazy operations that break a collection into chunks based on either a binary predicate or when the result of a projection changes or chunks of a given count.
+- [`countSortedDuplicates()`, `countSortedDuplicates(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/SortedDuplicates.md): Given an already-sorted sequence and the sorting predicate, return each unique value, pairing each with the number of occurances. Has eager and lazy variants.
 - [`firstNonNil(_:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/FirstNonNil.md): Returns the first non-`nil` result from transforming a sequence's elements.
 - [`grouped(by:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Grouped.md): Group up elements using the given closure, returning a Dictionary of those groups, keyed by the results of the closure.
 - [`indexed()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Indexed.md): Iterate over tuples of a collection's indices and elements. 

Guides/SortedDuplicates.md

@@ -0,0 +1,65 @@
+# Sorted Duplicates
+[[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/SortedDuplicates.swift) |
+ [Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/SortedDuplicatesTests.swift)]
+
+Being a given a sequence that is already sorted, recognize each run of
+identical values.
+Use that to determine the length of each identical-value run of
+identical values.
+Or filter out the duplicate values by removing all occurances of
+a given value besides the first.
+
+```swift
+// Put examples here
+```
+
+## Detailed Design
+
+```swift
+extension Sequence {
+    public func countSortedDuplicates(
+        by areInIncreasingOrder: (Element, Element) throws -> Bool
+    ) rethrows -> [(value: Element, count: Int)]
+
+    public func withoutSortedDuplicates(
+        by areInIncreasingOrder: (Element, Element) throws -> Bool
+    ) rethrows -> [Element]
+}
+
+extension Sequence where Self.Element : Comparable {
+    public func countSortedDuplicates() -> [(value: Element, count: Int)]
+
+    public func withoutSortedDuplicates() -> [Element]
+}
+
+extension LazySequenceProtocol {
+    public func countSortedDuplicates(
+        by areInIncreasingOrder: @escaping (Element, Element) -> Bool
+    ) -> LazyCountDuplicatesSequence<Elements>
+
+    public func withoutSortedDuplicates(
+        by areInIncreasingOrder: @escaping (Element, Element) -> Bool
+    ) -> some (Sequence<Element> & LazySequenceProtocol)
+}
+
+extension LazySequenceProtocol where Self.Element : Comparable {
+    public func countSortedDuplicates()
+     -> LazyCountDuplicatesSequence<Elements>
+
+    public func withoutSortedDuplicates()
+     -> some (Sequence<Element> & LazySequenceProtocol)
+}
+
+public struct LazyCountDuplicatesSequence<Base: Sequence>
+    : LazySequenceProtocol
+{ /*...*/ }
+
+public struct CountDuplicatesIterator<Base: IteratorProtocol>
+    : IteratorProtocol
+{ /*...*/ }
+```
+
+### Complexity
+
+Calling the lazy methods, those defined on `LazySequenceProtocol`, is O(_1_).
+Calling the eager methods, those returning an array, is O(_n_).

Sources/Algorithms/Documentation.docc/Selecting.md

@@ -18,8 +18,24 @@ or iterate of elements with their indices.
 
 - ``Swift/Collection/indexed()``
 
+### Counting each Element in a Sorted Sequence
+
+- ``Swift/Sequence/countSortedDuplicates(by:)``
+- ``Swift/Sequence/countSortedDuplicates()``
+- ``Swift/LazySequenceProtocol/countSortedDuplicates(by:)``
+- ``Swift/LazySequenceProtocol/countSortedDuplicates()``
+
+### Removing Duplicates from a Sorted Sequence
+
+- ``Swift/Sequence/withoutSortedDuplicates(by:)``
+- ``Swift/Sequence/withoutSortedDuplicates()``
+- ``Swift/LazySequenceProtocol/withoutSortedDuplicates(by:)``
+- ``Swift/LazySequenceProtocol/withoutSortedDuplicates()``
+
 ### Supporting Types
 
 - ``IndexedCollection``
 - ``StridingSequence``
 - ``StridingCollection``
+- ``LazyCountDuplicatesSequence``
+- ``CountDuplicatesIterator``