Simultaneous Minimum and Maximum Evaluation

CHANGELOG.md

@@ -12,7 +12,8 @@ package updates, you can specify your package dependency using
 
 ## [Unreleased]
 
-*No changes yet.*
+- `minAndMax()` finds both the smallest and largest elements of a sequence in a
+  single pass.
 
 ---
 

Guides/MinMax.md

@@ -1,4 +1,4 @@
-# Min/Max with Count
+# Minima and/or Maxima
 
 [[Source](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/MinMax.swift) | 
  [Tests](https://github.com/apple/swift-algorithms/blob/main/Tests/SwiftAlgorithmsTests/MinMaxTests.swift)]
@@ -13,6 +13,17 @@ let smallestThree = numbers.min(count: 3, sortedBy: <)
 // [1, 2, 3]
 ```
 
+Return the smallest and largest elements of this sequence, determined by a predicate or in the order defined by `Comparable` conformance.
+
+If you need both the minimum and maximum values of a collection, using these methods can give you a performance boost over running the `min` method followed by the `max` method. Plus they work with single-pass sequences.
+
+```swift
+let numbers = [7, 1, 6, 2, 8, 3, 9]
+if let (smallest, largest) = numbers.minAndMax(by: <) {
+    // Work with 1 and 9....
+}
+```
+
 ## Detailed Design
 
 This adds the `Collection` methods shown below:
@@ -31,6 +42,16 @@ extension Collection {
 }
 ```
 
+And the `Sequence` method:
+
+```swift
+extension Sequence {
+    public func minAndMax(
+        by areInIncreasingOrder: (Element, Element) throws -> Bool
+    ) rethrows -> (min: Element, max: Element)?
+}
+```
+
 Additionally, versions of these methods for `Comparable` types are also provided:
 
 ```swift
@@ -39,20 +60,26 @@ extension Collection where Element: Comparable {
 
     public func max(count: Int) -> [Element]
 }
+
+extension Sequence where Element: Comparable {
+    public func minAndMax() -> (min: Element, max: Element)?
+}
 ```
 
 ### Complexity
 
-The algorithm used is based on [Soroush Khanlou's research on this matter](https://khanlou.com/2018/12/analyzing-complexity/). The total complexity is `O(k log k + nk)`, which will result in a runtime close to `O(n)` if *k* is a small amount. If *k* is a large amount (more than 10% of the collection), we fall back to sorting the entire array. Realistically, this means the worst case is actually `O(n log n)`.
+The algorithm used for minimal- or maximal-ordered subsets is based on [Soroush Khanlou's research on this matter](https://khanlou.com/2018/12/analyzing-complexity/). The total complexity is `O(k log k + nk)`, which will result in a runtime close to `O(n)` if *k* is a small amount. If *k* is a large amount (more than 10% of the collection), we fall back to sorting the entire array. Realistically, this means the worst case is actually `O(n log n)`.
 
 Here are some benchmarks we made that demonstrates how this implementation (SmallestM) behaves when *k* increases (before implementing the fallback):
 
 ![Benchmark](Resources/SortedPrefix/FewElements.png)
 ![Benchmark 2](Resources/SortedPrefix/ManyElements.png)
 
+The algorithm used for simultaneous minimum and maximum is slightly optimized. At each iteration, two elements are read, their relative order is determined, then each is compared against exactly one of the current extrema for potential replacement. When a comparison predicate has to analyze every component of both operands, the optimized algorithm isn't much faster than the straightforward approach. But when a predicate only needs to compare a small part of each instance, the optimization shines through.
+
 ### Comparison with other languages
 
-**C++:** The `<algorithm>` library defines a `partial_sort` function where the entire array is returned using a partial heap sort.
+**C++:** The `<algorithm>` library defines a `partial_sort` function where the entire array is returned using a partial heap sort. It also defines a `minmax_element` function that scans a range for its minimal and maximal elements.
 
 **Python:** Defines a `heapq` priority queue that can be used to manually achieve the same result.
 

README.md

@@ -28,6 +28,7 @@ Read more about the package, and the intent behind it, in the [announcement on s
 - [`randomStableSample(count:)`, `randomStableSample(count:using:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/RandomSampling.md): Randomly selects a specific number of elements from a collection, preserving their original relative order.
 - [`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.
 - [`uniqued()`, `uniqued(on:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Unique.md): The unique elements of a collection, preserving their order.
+- [`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
 

Sources/Algorithms/MinMax.swift

@@ -383,3 +383,117 @@ extension Collection where Element: Comparable {
     return max(count: count, sortedBy: <)
   }
 }
+
+//===----------------------------------------------------------------------===//
+// Simultaneous minimum and maximum evaluation
+//===----------------------------------------------------------------------===//
+
+extension Sequence {
+  /// Returns both the minimum and maximum elements in the sequence, using the
+  /// given predicate as the comparison between elements.
+  ///
+  /// The predicate must be a *strict weak ordering* over the elements. That
+  /// is, for any elements `a`, `b`, and `c`, the following conditions must
+  /// hold:
+  ///
+  /// - `areInIncreasingOrder(a, a)` is always `false`. (Irreflexivity)
+  /// - If `areInIncreasingOrder(a, b)` and `areInIncreasingOrder(b, c)` are
+  ///   both `true`, then `areInIncreasingOrder(a, c)` is also
+  ///   `true`. (Transitive comparability)
+  /// - Two elements are *incomparable* if neither is ordered before the other
+  ///   according to the predicate. If `a` and `b` are incomparable, and `b`
+  ///   and `c` are incomparable, then `a` and `c` are also incomparable.
+  ///   (Transitive incomparability)
+  ///
+  /// This example shows how to use the `minAndMax(by:)` method on a
+  /// dictionary to find the key-value pair with the lowest value and the pair
+  /// with the highest value.
+  ///
+  ///     let hues = ["Heliotrope": 296, "Coral": 16, "Aquamarine": 156]
+  ///     if let extremeHues = hues.minAndMax(by: {$0.value < $1.value}) {
+  ///         print(extremeHues.min, extremeHues.max)
+  ///     } else {
+  ///         print("There are no hues")
+  ///     }
+  ///     // Prints: "(key: "Coral", value: 16) (key: "Heliotrope", value: 296)"
+  ///
+  /// - Precondition: The sequence is finite.
+  ///
+  /// - Parameter areInIncreasingOrder: A predicate that returns `true`
+  ///   if its first argument should be ordered before its second
+  ///   argument; otherwise, `false`.
+  /// - Returns: A tuple with the sequence's minimum element, followed by its
+  ///   maximum element. For either member, if the sequence provides multiple
+  ///   qualifying elements, the one chosen is unspecified. The same element may
+  ///   be used for both members if all the elements are equivalent. If the
+  ///   sequence has no elements, returns `nil`.
+  ///
+  /// - Complexity: O(*n*), where *n* is the length of the sequence.
+  public func minAndMax(
+    by areInIncreasingOrder: (Element, Element) throws -> Bool
+  ) rethrows -> (min: Element, max: Element)? {
+    var iterator = makeIterator()
+    guard var lowest = iterator.next() else { return nil }
+
+    var highest = iterator.next() ?? lowest
+    if try areInIncreasingOrder(highest, lowest) {
+      swap(&lowest, &highest)
+    }
+    while let element = iterator.next() {
+      guard let following = iterator.next() else {
+        if try areInIncreasingOrder(element, lowest) {
+          lowest = element
+        } else if try !areInIncreasingOrder(element, highest) {
+          highest = element
+        }
+        break
+      }
+
+      if try areInIncreasingOrder(following, element) {
+        if try areInIncreasingOrder(following, lowest) {
+          lowest = following
+        }
+        if try !areInIncreasingOrder(element, highest) {
+          highest = element
+        }
+      } else {
+        if try areInIncreasingOrder(element, lowest) {
+          lowest = element
+        }
+        if try !areInIncreasingOrder(following, highest) {
+          highest = following
+        }
+      }
+    }
+    return (lowest, highest)
+  }
+}
+
+extension Sequence where Element: Comparable {
+  /// Returns both the minimum and maximum elements in the sequence.
+  ///
+  /// This example finds the smallest and largest values in an array of height
+  /// measurements.
+  ///
+  ///     let heights = [67.5, 65.7, 64.3, 61.1, 58.5, 60.3, 64.9]
+  ///     if let (lowestHeight, greatestHeight) = heights.minAndMax() {
+  ///         print(lowestHeight, greatestHeight)
+  ///     } else {
+  ///         print("The list of heights is empty")
+  ///     }
+  ///     // Prints: "58.5 67.5"
+  ///
+  /// - Precondition: The sequence is finite.
+  ///
+  /// - Returns: A tuple with the sequence's minimum element, followed by its
+  ///   maximum element. For either member, if there is a tie for the extreme
+  ///   value, the element chosen is unspecified. The same element may be used
+  ///   for both members if all the elements are equal. If the sequence has no
+  ///   elements, returns `nil`.
+  ///
+  /// - Complexity: O(*n*), where *n* is the length of the sequence.
+  @inlinable
+  public func minAndMax() -> (min: Element, max: Element)? {
+    return minAndMax(by: <)
+  }
+}

Tests/SwiftAlgorithmsTests/MinMaxTests.swift

@@ -185,3 +185,67 @@ final class SortedPrefixTests: XCTestCase {
     }
   }
 }
+
+final class MinAndMaxTests: XCTestCase {
+  /// Confirms that empty sequences yield no results.
+  func testEmpty() {
+    XCTAssertNil(EmptyCollection<Int>().minAndMax())
+  }
+
+  /// Confirms the same element is used when there is only one.
+  func testSingleElement() {
+    let result = CollectionOfOne(2).minAndMax()
+    XCTAssertEqual(result?.min, 2)
+    XCTAssertEqual(result?.max, 2)
+  }
+
+  /// Confirms the same value is used when all the elements have it.
+  func testSingleValueMultipleElements() {
+    let result = repeatElement(3.3, count: 5).minAndMax()
+    XCTAssertEqual(result?.min, 3.3)
+    XCTAssertEqual(result?.max, 3.3)
+
+    // Even count
+    let result2 = repeatElement("c" as Character, count: 6).minAndMax()
+    XCTAssertEqual(result2?.min, "c")
+    XCTAssertEqual(result2?.max, "c")
+  }
+
+  /// Confirms when the minimum value is constantly updated, but the maximum
+  /// never is.
+  func testRampDown() {
+    let result = (1...5).reversed().minAndMax()
+    XCTAssertEqual(result?.min, 1)
+    XCTAssertEqual(result?.max, 5)
+
+    // Even count
+    let result2 = "fedcba".minAndMax()
+    XCTAssertEqual(result2?.min, "a")
+    XCTAssertEqual(result2?.max, "f")
+  }
+
+  /// Confirms when the maximum value is constantly updated, but the minimum
+  /// never is.
+  func testRampUp() {
+    let result = (1...5).minAndMax()
+    XCTAssertEqual(result?.min, 1)
+    XCTAssertEqual(result?.max, 5)
+
+    // Even count
+    let result2 = "abcdef".minAndMax()
+    XCTAssertEqual(result2?.min, "a")
+    XCTAssertEqual(result2?.max, "f")
+  }
+
+  /// Confirms when the maximum and minimum change during a run.
+  func testUpsAndDowns() {
+    let result = [4, 3, 3, 5, 2, 0, 7, 6].minAndMax()
+    XCTAssertEqual(result?.min, 0)
+    XCTAssertEqual(result?.max, 7)
+
+    // Odd count
+    let result2 = "gfabdec".minAndMax()
+    XCTAssertEqual(result2?.min, "a")
+    XCTAssertEqual(result2?.max, "g")
+  }
+}