Merging Sorted Sequences

Guides/MergeSorted.md

@@ -0,0 +1,125 @@
+# Permutations
+
+[[Source](../Sources/Algorithms/MergeSorted.swift) | 
+ [Tests](../Tests/SwiftAlgorithmsTests/MergeSortedTests.swift)]
+
+A method that returns the merger of the sorted receiver and the sorted argument,
+or a subset of that merger.  The result is also sorted, with the same criteria.
+
+## Detailed Design
+
+The `mergeSorted(with:keeping:by:)` method is declared as a `Sequence`
+extension, and returns a standard `Array` of the same element type.
+
+```swift
+extension Sequence {
+  /// Returns an array listing the merger of this sequence and the given
+  /// sequence, but keeping only the selected subset, assuming both sources are
+  /// sorted according to the given predicate that can compare elements.
+  public func mergeSorted<S: Sequence>(
+    with second: S,
+    keeping selection: SetCombination,
+    by areInIncreasingOrder: (Element, Element) throws -> Bool
+  ) rethrows -> [Element] where S.Element == Element
+}
+```
+
+Besides the sequence that will be combined with the receiver and the predicate
+to be used as the sorting criteria, the following subsets of the merged sequence
+can be selected:
+
+```swift
+/// The manners two (multi)sets may be combined.
+public enum SetCombination: CaseIterable {
+  case nothing, firstMinusSecond, secondMinusFirst, symmetricDifference,
+       intersection, first, second, union, sum
+}
+```
+
+The `.sum` case is the usual merge sort.  The `.nothing`, `.first`, `.second`
+cases are somewhat degenerate and aren't generally used.  The other cases are
+the usual subsets.  The difference between `.union` and `.sum` is that the
+former generates mergers where common elements are included only once, while the
+latter includes both copies of each shared value.  When `.sum` is in place, the
+copies from the second sequence go after all the copies from the first.
+
+When the `Element` type is `Comparable`, the `mergeSorted(with:keeping:)` method
+is added, which defaults the comparison predicate to the standard `<` operator:
+
+```swift
+extension Sequence where Element: Comparable {
+  /// Returns an array listing the merger of this sequence and the given
+  /// sequence, but keeping only the selected subset, and assuming both sources
+  /// are sorted.
+  public func mergeSorted<S: Sequence>(
+    with second: S,
+    keeping selection: SetCombination
+  ) -> [Element] where S.Element == Element
+}
+```
+
+If the ordering predicate does not throw, then the merged sequence may be
+computed on-demand by making at least the receiver lazy:
+
+```swift
+extension LazySequenceProtocol {
+  /// Returns a lazy sequence listing the merger of this lazy sequence and the
+  /// given lazy sequence, but keeping only the selected subset, assuming both
+  /// sources are sorted according to the given predicate that can compare
+  /// elements.
+  public func mergeSorted<S: LazySequenceProtocol>(
+    with second: S,
+    keeping selection: SetCombination,
+    by areInIncreasingOrder: @escaping (Element, Element) -> Bool
+  ) -> MergedSequence<Elements, S.Elements> where S.Element == Element
+
+  /// Returns a lazy sequence listing the merger of this lazy sequence and the
+  /// given sequence, but keeping only the selected subset, assuming both
+  /// sources are sorted according to the given predicate that can compare
+  /// elements.
+  public func mergeSorted<S: Sequence>(
+    with second: S,
+    keeping selection: SetCombination,
+    by areInIncreasingOrder: @escaping (Element, Element) -> Bool
+  ) -> MergedSequence<Elements, S> where S.Element == Element
+}
+
+extension LazySequenceProtocol where Element: Comparable {
+  /// Returns a lazy sequence listing the merger of this lazy sequence and the
+  /// given lazy sequence, but keeping only the selected subset, and assuming
+  /// both sources are sorted.
+  public func mergeSorted<S: LazySequenceProtocol>(
+    with second: S,
+    keeping selection: SetCombination
+  ) -> MergedSequence<Elements, S.Elements> where S.Element == Element
+
+  /// Returns a lazy sequence listing the merger of this lazy sequence and the
+  /// given sequence, but keeping only the selected subset, and assuming both
+  /// sources are sorted.
+  public func mergeSorted<S: Sequence>(
+    with second: S,
+    keeping selection: SetCombination
+  ) -> MergedSequence<Elements, S> where S.Element == Element
+}
+```
+
+If both source sequences also conform to (at least) `Collection`, then the
+returned sequence representing the merger is also a collection.
+
+### Complexity
+
+Calling `mergeSorted(with:keeping:by:)` or `mergeSorted(with:keeping:)` is an
+O(*n* + *m*) operation, where *n* and *m* are the lengths of the operand
+sequences.  Creating an iterator and/or lazy sequence is O(1), while iterating
+through all of lazy sequence will be O(*n* + *m*).  If the kept subset is one of
+the degenerate cases, the complexity will be shorter.
+
+### Comparison with other languages
+
+**C++:** The `<algorithm>` library defines the `set_difference`,
+`set_intersection`, `set_symmetric_difference`, `set_union`, and `merge`
+functions.  They can be all distilled into one algorithm, which the
+`mergeSorted(with:keeping:by:)` method and its overloads do for Swift.  The
+`.firstMinusSecond` and `.secondMinusFirst` subsets are equivalent to calls to
+`set_difference`; `.intersection` to `set_intersection`; `.symmetricDifference`
+to `set_symmetric_difference`; `.union` to `set_union`; and `.sum` to `merge`.

README.md

@@ -33,6 +33,7 @@ Read more about the package, and the intent behind it, in the [announcement on s
 - [`chunked(by:)`, `chunked(on:)`](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.
 - [`indexed()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Indexed.md): Iterate over tuples of a collection's indices and elements. 
 - [`trimming(where:)`](https://github.com/apple/swift-algorithms/blob/main/Guides/Trim.md): Returns a slice by trimming elements from a collection's start and end. 
+- [`mergeSorted(with:keeping:by:)`, `mergeSorted(with:keeping:)`](./Guides/MergeSorted.md): Eager and lazy operations that take another sequence, assume that both the given sequence and the receiver are sorted according to the given predicate (defaults to `<`), and returns the given subset of the sequences' merger (also sorted).
 
 
 ## Adding Swift Algorithms as a Dependency

Tests/SwiftAlgorithmsTests/MergeSortedTests.swift

@@ -0,0 +1,444 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Algorithms open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+import XCTest
+@testable import Algorithms
+
+/// Unit tests for `SetCombination`, `MergedSequence`, and `mergedSorted`.
+final class MergeSortedTests: XCTestCase {
+  /// Check the values and properties of `SetCollection`.
+  func testSelectionType() {
+    XCTAssertEqualSequences(SetCombination.allCases, [.nothing,
+      .firstMinusSecond, .secondMinusFirst, .symmetricDifference, .intersection,
+      .first, .second, .union, .sum
+    ])
+
+    // Use a merged-sequence's iterator to spy on the properties.
+    // (The properties only depend on the case, not the source types nor the
+    // predicate.)
+    let iterators = SetCombination.allCases.map {
+      MergedSequence(EmptyCollection<Double>(), EmptyCollection<Double>(),
+                     keeping: $0, by: <).makeIterator()
+    }
+    XCTAssertEqualSequences(iterators.map(\.exclusivesFromFirst),
+                  [false, true, false, true, false, true, false, true, true])
+    XCTAssertEqualSequences(iterators.map(\.exclusivesFromSecond),
+                  [false, false, true, true, false, false, true, true, true])
+    XCTAssertEqualSequences(iterators.map(\.sharedFromFirst),
+                  [false, false, false, false, true, true, false, true, true])
+    XCTAssertEqualSequences(iterators.map(\.sharedFromSecond),
+                  [false, false, false, false, false, false, true, false, true])
+    XCTAssertEqualSequences(iterators.map(\.extractFromFirst),
+                      [false, true, true, true, true, true, false, true, true])
+    XCTAssertEqualSequences(iterators.map(\.extractFromSecond),
+                      [false, true, true, true, true, false, true, true, true])
+  }
+
+  /// Check the rough underestimated counts.
+  func testUnderestimatedCount() {
+    let empty = EmptyCollection<Double>(), single = CollectionOfOne(1.1),
+        repeated = repeatElement(5.5, count: 5)
+    let emptySelfMergers = SetCombination.allCases.map {
+      MergedSequence(empty, empty, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(emptySelfMergers.map(\.underestimatedCount), [
+      0, 0, 0, 0, 0, 0, 0, 0, 0
+    ])
+
+    let emptySingleMergers = SetCombination.allCases.map {
+      MergedSequence(empty, single, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(emptySingleMergers.map(\.underestimatedCount), [
+      0, 0, 0, 0, 0, 0, 1, 1, 1
+    ])
+
+    let emptyRepeatedMergers = SetCombination.allCases.map {
+      MergedSequence(empty, repeated, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(emptyRepeatedMergers.map(\.underestimatedCount), [
+      0, 0, 0, 0, 0, 0, 5, 5, 5
+    ])
+
+    let singleEmptyMergers = SetCombination.allCases.map {
+      MergedSequence(single, empty, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(singleEmptyMergers.map(\.underestimatedCount), [
+      0, 0, 0, 0, 0, 1, 0, 1, 1
+    ])
+
+    let singleSelfMergers = SetCombination.allCases.map {
+      MergedSequence(single, single, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(singleSelfMergers.map(\.underestimatedCount), [
+      0, 0, 0, 0, 0, 1, 1, 1, 2
+    ])
+
+    let singleRepeatedMergers = SetCombination.allCases.map {
+      MergedSequence(single, repeated, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(singleRepeatedMergers.map(\.underestimatedCount), [
+      0, 0, 0, 0, 0, 1, 5, 5, 6
+    ])
+
+    let repeatedEmptyMergers = SetCombination.allCases.map {
+      MergedSequence(repeated, empty, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(repeatedEmptyMergers.map(\.underestimatedCount), [
+      0, 0, 0, 0, 0, 5, 0, 5, 5
+    ])
+
+    let repeatedSingleMergers = SetCombination.allCases.map {
+      MergedSequence(repeated, single, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(repeatedSingleMergers.map(\.underestimatedCount), [
+      0, 0, 0, 0, 0, 5, 1, 5, 6
+    ])
+
+    let repeatedSelfMergers = SetCombination.allCases.map {
+      MergedSequence(repeated, repeated, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(repeatedSelfMergers.map(\.underestimatedCount), [
+      0, 0, 0, 0, 0, 5, 5, 5, 10
+    ])
+  }
+
+  /// Check results from using empty operands, and using the generating methods.
+  func testEmpty() {
+    let empty = EmptyCollection<Double>()
+    let emptyMergerArrays = SetCombination.allCases.map {
+      empty.mergeSorted(with: empty, keeping: $0)
+    }
+    let emptyResults = Array(repeating: [Double](),
+                             count: SetCombination.allCases.count)
+    XCTAssertEqualSequences(emptyMergerArrays, emptyResults)
+
+    // Call the lazy methods.
+    let emptyMergerSingleLazy = SetCombination.allCases.map {
+      empty.lazy.mergeSorted(with: empty, keeping: $0)
+    }
+    XCTAssertEqualSequences(emptyMergerSingleLazy.map(Array.init), emptyResults)
+
+    let emptyMergerDoubleLazy = SetCombination.allCases.map {
+      empty.lazy.mergeSorted(with: empty.lazy, keeping: $0)
+    }
+    XCTAssertEqualSequences(emptyMergerDoubleLazy.map(Array.init), emptyResults)
+
+    // Quick collection checks
+    XCTAssertEqualSequences(emptyMergerDoubleLazy.map(\.isEmpty), [
+      true, true, true, true, true, true, true, true, true
+    ])
+  }
+
+  /// Check results from using one empty and one non-empty operand.
+  func testExactlyOneEmpty() {
+    let limit = Int.random(in: 1..<100), nonEmpty = 0..<limit,
+        nonEmptyArray = Array(nonEmpty), empty = EmptyCollection<Int>()
+    let nonEmptyVersusEmptyMergers = SetCombination.allCases.map {
+      MergedSequence(nonEmpty, empty, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(nonEmptyVersusEmptyMergers.map(Array.init), [
+      [], nonEmptyArray, [], nonEmptyArray, [], nonEmptyArray, [],
+      nonEmptyArray, nonEmptyArray
+    ])
+
+    let emptyVersusNonEmptyMergers = SetCombination.allCases.map {
+      MergedSequence(empty, nonEmpty, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(emptyVersusNonEmptyMergers.map(Array.init), [
+      [], [], nonEmptyArray, nonEmptyArray, [], [], nonEmptyArray,
+      nonEmptyArray, nonEmptyArray
+    ])
+  }
+
+  /// Check results on using the same nonempty sequence for both operands.
+  func testIdentical() {
+    let sample = Array(1..<Int.random(in: 3..<100))
+    let selfMergers = SetCombination.allCases.map {
+      MergedSequence(sample, sample, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(selfMergers.map(Array.init), [
+      [], [], [], [], sample, sample, sample, sample,
+      Array(sample.map { Array(repeating: $0, count: 2) }.joined())
+    ])
+  }
+
+  /// Check results when one nonempty sequence is a subset of a longer one.
+  func testProperSubset() {
+    let sample = Array(0...20), subSample = [2, 3, 5, 7, 11, 13, 17, 19],
+        inverted = [0, 1, 4, 6, 8, 9, 10, 12, 14, 15, 16, 18, 20]
+    let sampleAndSubMergers = SetCombination.allCases.map {
+      MergedSequence(sample, subSample, keeping: $0, by: <)
+    }
+    let primeRepeatingSample = Array(sample.map {
+      Array(repeating: $0, count: $0.isPrime ? 2 : 1)
+    }.joined())
+
+    XCTAssertEqualSequences(sampleAndSubMergers.map(Array.init), [
+      [], inverted, [], inverted, subSample, sample, subSample, sample,
+      primeRepeatingSample
+    ])
+
+    let subAndSampleMergers = SetCombination.allCases.map {
+      MergedSequence(subSample, sample, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(subAndSampleMergers.map(Array.init), [
+      [], [], inverted, inverted, subSample, subSample, sample, sample,
+      primeRepeatingSample
+    ])
+
+    // Originally, I had "sample" stop before 20, and 20 was left out of
+    // "inverted."  This mean that "sample" ended on an element that was also
+    // part of "subSample."  This lead to some lines of code in the iterator
+    // being missed.
+  }
+
+  /// Check results of two unrelated nonempty sequences.
+  func testDisjoint() {
+    let s1 = [2, 4, 6, 8, 10], s2 = [3, 5, 7, 9, 11], all = Array(2...11)
+    let sample1To2Merger = SetCombination.allCases.map {
+      MergedSequence(s1, s2, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(sample1To2Merger.map(Array.init), [
+      [], s1, s2, all, [], s1, s2, all, all
+    ])
+
+    let sample2To1Merger = SetCombination.allCases.map {
+      MergedSequence(s2, s1, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(sample2To1Merger.map(Array.init), [
+      [], s2, s1, all, [], s2, s1, all, all
+    ])
+  }
+
+  /// Check direct buffer access.
+  func testBufferAccess() {
+    let sample1 = [2, 2], sample2 = [3, 3, 3]
+    let sample1to2Mergers = SetCombination.allCases.map {
+      MergedSequence(sample1, sample2, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(sample1to2Mergers.map { merger in
+      merger.withContiguousStorageIfAvailable { buffer in
+        buffer.reduce(0, +)
+      }
+    }, [0, nil, nil, nil, nil, 4, 9, nil, nil])
+
+    let sample2to1Mergers = SetCombination.allCases.map {
+      MergedSequence(sample2, sample1, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(sample2to1Mergers.map { merger in
+      merger.withContiguousStorageIfAvailable { buffer in
+        buffer.reduce(0, +)
+      }
+    }, [0, nil, nil, nil, nil, 9, 4, nil, nil])
+  }
+
+  /// Check the containment implementation method, indirectly.
+  func testOptimizedContainment() {
+    // Both operands' type supports optimized containment tests.
+    let range1 = 0..<2, range2 = 1..<3
+    let range1to2Mergers = SetCombination.allCases.map {
+      MergedSequence(range1, range2, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(range1to2Mergers.map { $0.contains(0) }, [
+      false, true, false, true, false, true, false, true, true
+    ])
+    XCTAssertEqualSequences(range1to2Mergers.map { $0.contains(1) }, [
+      false, false, false, false, true, true, true, true, true
+    ])
+    XCTAssertEqualSequences(range1to2Mergers.map { $0.contains(2) }, [
+      false, false, true, true, false, false, true, true, true
+    ])
+    XCTAssertEqualSequences(range1to2Mergers.map { $0.contains(3) }, [
+      false, false, false, false, false, false, false, false, false
+    ])
+
+    // Exactly one operand's type supports optimized containment tests.
+    let sample1 = Array(range1)
+    let sampleRangeMergers = SetCombination.allCases.map {
+      MergedSequence(sample1, range2, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(sampleRangeMergers.map { $0.contains(0) }, [
+      false, true, false, true, false, true, false, true, true
+    ])
+    XCTAssertEqualSequences(sampleRangeMergers.map { $0.contains(1) }, [
+      false, false, false, false, true, true, true, true, true
+    ])
+    XCTAssertEqualSequences(sampleRangeMergers.map { $0.contains(2) }, [
+      false, false, true, true, false, false, true, true, true
+    ])
+    XCTAssertEqualSequences(sampleRangeMergers.map { $0.contains(3) }, [
+      false, false, false, false, false, false, false, false, false
+    ])
+
+    // Need to check both sides for the NIL-containment operand type.
+    let rangeSampleMergers = SetCombination.allCases.map {
+      MergedSequence(range2, sample1, keeping: $0, by: <)
+    }
+    XCTAssertEqualSequences(rangeSampleMergers.map { $0.contains(0) }, [
+      false, false, true, true, false, false, true, true, true
+    ])
+    XCTAssertEqualSequences(rangeSampleMergers.map { $0.contains(1) }, [
+      false, false, false, false, true, true, true, true, true
+    ])
+    XCTAssertEqualSequences(rangeSampleMergers.map { $0.contains(2) }, [
+      false, true, false, true, false, true, false, true, true
+    ])
+    XCTAssertEqualSequences(rangeSampleMergers.map { $0.contains(3) }, [
+      false, false, false, false, false, false, false, false, false
+    ])
+  }
+
+  /// Check every combination for the array-returning merger method.
+  func testMoreNonlazyMerging() {
+    let range1 = 0..<10, range2 = 5..<15
+    let range1to2Mergers = SetCombination.allCases.map {
+      range1.mergeSorted(with: range2, keeping: $0)
+    }
+    XCTAssertEqualSequences(range1to2Mergers, [
+      [],
+      [0, 1, 2, 3, 4],
+      [10, 11, 12, 13, 14],
+      [0, 1, 2, 3, 4, 10, 11, 12, 13, 14],
+      [5, 6, 7, 8, 9],
+      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+      [5, 6, 7, 8, 9, 10, 11, 12, 13, 14],
+      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14],
+      [0, 1, 2, 3, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 11, 12, 13, 14]
+    ])
+  }
+
+  /// Check index iteration and dereferencing.
+  func testIndices() {
+    let range1 = 0..<10, range2 = 5...15
+    let range1to2Mergers = SetCombination.allCases.map {
+      (MergedCollection(range1, range2, keeping: $0, by: <),
+       range1.mergeSorted(with: range2, keeping: $0))
+    }
+    XCTAssertEqualSequences(range1to2Mergers.map(\.0.isEmpty),
+                            range1to2Mergers.map(\.1.isEmpty))
+    XCTAssertEqualSequences(range1to2Mergers.map { doubleMerger in
+      doubleMerger.0.indices.map { doubleMerger.0[$0] }
+    }, range1to2Mergers.map(\.1))
+    XCTAssertEqualSequences(range1to2Mergers.map(\.0.iterationSteps
+                                                  .underestimatedCount), [
+      0, 0, 0, 0, 0, 10, 11, 11, 21
+    ])
+    XCTAssertEqualSequences(range1to2Mergers.map {
+      var i = $0.0.startIndex, result = [Int]()
+      result.reserveCapacity($0.0.underestimatedCount)
+      while i < $0.0.endIndex {
+        result.append($0.0[i])
+        $0.0.formIndex(after: &i)
+      }
+      return result
+    }, range1to2Mergers.map(\.1))
+
+    let range2to1Mergers = SetCombination.allCases.map {
+      (MergedCollection(range2, range1, keeping: $0, by: <),
+       range2.mergeSorted(with: range1, keeping: $0))
+    }
+    XCTAssertEqualSequences(range2to1Mergers.map { doubleMerger in
+      doubleMerger.0.indices.map { doubleMerger.0[$0] }
+    }, range2to1Mergers.map(\.1))
+    XCTAssertEqualSequences(range2to1Mergers.map(\.0.iterationSteps
+                                                  .underestimatedCount), [
+      0, 0, 0, 0, 0, 11, 10, 11, 21
+    ])
+    XCTAssertEqualSequences(range2to1Mergers.map {
+      var i = $0.0.startIndex, result = [Int]()
+      result.reserveCapacity($0.0.underestimatedCount)
+      while i < $0.0.endIndex {
+        result.append($0.0[i])
+        $0.0.formIndex(after: &i)
+      }
+      return result
+    }, range2to1Mergers.map(\.1))
+  }
+
+  /// Check the differences when elements from the first sequence are filtered
+  /// out versus the second.
+  func testPropertyOrdering() {
+    let sample1 = [0, 2, 4, 6, 8, 10, 12].map { ($0, true) }
+    let sample2 = [0, 3, 6, 9, 12].map { ($0, false) }
+    let sample1to2Mergers = SetCombination.allCases.map {
+      MergedSequence(sample1, sample2, keeping: $0, by: { x, y in x.0 < y.0 })
+    }
+    XCTAssertEqualSequences(sample1to2Mergers.map { $0.map(\.0) }, [
+      [],
+      [2, 4, 8, 10],
+      [3, 9],
+      [2, 3, 4, 8, 9, 10],
+      [0, 6, 12],
+      [0, 2, 4, 6, 8, 10, 12],
+      [0, 3, 6, 9, 12],
+      [0, 2, 3, 4, 6, 8, 9, 10, 12],
+      [0, 0, 2, 3, 4, 6, 6, 8, 9, 10, 12, 12]
+    ])
+    XCTAssertEqualSequences(sample1to2Mergers.map { $0.map(\.1) }, [
+      [],
+      [true, true, true, true],
+      [false, false],
+      [true, false, true, true, false, true],
+      [true, true, true],
+      [true, true, true, true, true, true, true],
+      [false, false, false, false, false],
+      [true, true, false, true, true, true, false, true, true],
+      [true, false, true, false, true, true, false, true, false, true, true,
+       false]
+    ])
+
+    let sample2to1Mergers = SetCombination.allCases.map {
+      MergedSequence(sample2, sample1, keeping: $0, by: { x, y in x.0 < y.0 })
+    }
+    XCTAssertEqualSequences(sample2to1Mergers.map { $0.map(\.0) }, [
+      [],
+      [3, 9],
+      [2, 4, 8, 10],
+      [2, 3, 4, 8, 9, 10],
+      [0, 6, 12],
+      [0, 3, 6, 9, 12],
+      [0, 2, 4, 6, 8, 10, 12],
+      [0, 2, 3, 4, 6, 8, 9, 10, 12],
+      [0, 0, 2, 3, 4, 6, 6, 8, 9, 10, 12, 12]
+    ])
+    XCTAssertEqualSequences(sample2to1Mergers.map { $0.map(\.1) }, [
+      [],
+      [false, false],
+      [true, true, true, true],
+      [true, false, true, true, false, true],
+      [false, false, false],
+      [false, false, false, false, false],
+      [true, true, true, true, true, true, true],
+      [false, true, false, true, false, true, false, true, false],
+      [false, true, true, false, true, false, true, true, false, true, false,
+       true]
+    ])
+  }
+}
+
+//-----------------------------------------------------------------------------/
+
+extension FixedWidthInteger {
+  /// Confirms if this value is prime, but slowly.
+  fileprivate var isPrime: Bool {
+    guard self >= 2 else { return false }
+    guard self >= 4 else { return true }
+
+    for divisor in 2..<self {
+      let (quotient, remainder) = quotientAndRemainder(dividingBy: divisor)
+      guard remainder != 0 else { return false }
+      guard quotient > divisor else { break }
+
+      // The guards above cover everything.
+    }
+    return true
+  }
+}