Rename BTreeMatchStrategy to BTreeMatchingStrategy; add docs.

Author: lorentey

Sources/BTreeComparisons.swift

@@ -109,7 +109,7 @@ extension BTree {
     /// - Complexity:
     ///    - O(min(`self.count`, `tree.count`)) in general.
     ///    - O(log(`self.count` + `tree.count`)) if there are only a constant amount of interleaving element runs.
-    public func isSubset(of tree: BTree, by strategy: BTreeMatchStrategy) -> Bool {
+    public func isSubset(of tree: BTree, by strategy: BTreeMatchingStrategy) -> Bool {
         return isSubset(of: tree, by: strategy, strict: false)
     }
 
@@ -119,7 +119,7 @@ extension BTree {
     /// - Complexity:
     ///    - O(min(`self.count`, `tree.count`)) in general.
     ///    - O(log(`self.count` + `tree.count`)) if there are only a constant amount of interleaving element runs.
-    public func isStrictSubset(of tree: BTree, by strategy: BTreeMatchStrategy) -> Bool {
+    public func isStrictSubset(of tree: BTree, by strategy: BTreeMatchingStrategy) -> Bool {
         return isSubset(of: tree, by: strategy, strict: true)
     }
 
@@ -128,7 +128,7 @@ extension BTree {
     /// - Complexity:
     ///    - O(min(`self.count`, `tree.count`)) in general.
     ///    - O(log(`self.count` + `tree.count`)) if there are only a constant amount of interleaving element runs.
-    public func isSuperset(of tree: BTree, by strategy: BTreeMatchStrategy) -> Bool {
+    public func isSuperset(of tree: BTree, by strategy: BTreeMatchingStrategy) -> Bool {
         return tree.isSubset(of: self, by: strategy, strict: false)
     }
 
@@ -138,11 +138,11 @@ extension BTree {
     /// - Complexity:
     ///    - O(min(`self.count`, `tree.count`)) in general.
     ///    - O(log(`self.count` + `tree.count`)) if there are only a constant amount of interleaving element runs.
-    public func isStrictSuperset(of tree: BTree, by strategy: BTreeMatchStrategy) -> Bool {
+    public func isStrictSuperset(of tree: BTree, by strategy: BTreeMatchingStrategy) -> Bool {
         return tree.isSubset(of: self, by: strategy, strict: true)
     }
 
-    internal func isSubset(of tree: BTree, by strategy: BTreeMatchStrategy, strict: Bool) -> Bool {
+    internal func isSubset(of tree: BTree, by strategy: BTreeMatchingStrategy, strict: Bool) -> Bool {
         var a = BTreeStrongPath(startOf: self.root)
         var b = BTreeStrongPath(startOf: tree.root)
         var knownStrict = false

Sources/BTreeMerger.swift

@@ -6,8 +6,22 @@
 //  Copyright © 2016 Károly Lőrentey.
 //
 
-public enum BTreeMatchStrategy {
+/// The matching strategy to use when comparing elements from two trees with duplicate keys.
+public enum BTreeMatchingStrategy {
+
+    /// Use a matching strategy appropriate for a set. I.e., match partition classes over key equality rather than individual keys.
+    ///
+    /// This strategy ignores the multiplicity of keys, and only consider whether a key is included in the two trees at all.
+    /// E.g., a single element from one tree will be considered a match for any positive number of elements with the same key in
+    /// the other tree.
     case groupingMatches
+
+    /// Use a matching strategy appropriate for a multiset. I.e., try to establish a one-to-one correspondence between 
+    /// elements from the two trees with equal keys.
+    ///
+    /// This strategy keeps track of the multiplicity of each key, and matches every element from one tree with 
+    /// at most a single element with an equal key from the other tree. If a key has different multiplicities in 
+    /// the two trees, duplicate elements above the lesser multiplicity will not be considered matching.
     case countingMatches
 }
 
@@ -40,7 +54,7 @@ extension BTree {
     /// - Complexity:
     ///    - O(min(`self.count`, `other.count`)) in general.
     ///    - O(log(`self.count` + `other.count`)) if there are only a constant amount of interleaving element runs.
-    public func union(_ other: BTree, by strategy: BTreeMatchStrategy) -> BTree {
+    public func union(_ other: BTree, by strategy: BTreeMatchingStrategy) -> BTree {
         var m = BTreeMerger(first: self, second: other)
         switch strategy {
         case .groupingMatches:
@@ -84,7 +98,7 @@ extension BTree {
     /// - Complexity:
     ///    - O(min(`self.count`, `tree.count`)) in general.
     ///    - O(log(`self.count` + `tree.count`)) if there are only a constant amount of interleaving element runs.
-    public func subtracting(_ other: BTree, by strategy: BTreeMatchStrategy) -> BTree {
+    public func subtracting(_ other: BTree, by strategy: BTreeMatchingStrategy) -> BTree {
         var m = BTreeMerger(first: self, second: other)
         while !m.done {
             m.copyFromFirst(.excludingOtherKey)
@@ -127,7 +141,7 @@ extension BTree {
     /// - Complexity:
     ///    - O(min(`self.count`, `other.count`)) in general.
     ///    - O(log(`self.count` + `other.count`)) if there are only a constant amount of interleaving element runs.
-    public func symmetricDifference(_ other: BTree, by strategy: BTreeMatchStrategy) -> BTree {
+    public func symmetricDifference(_ other: BTree, by strategy: BTreeMatchingStrategy) -> BTree {
         var m = BTreeMerger(first: self, second: other)
         while !m.done {
             m.copyFromFirst(.excludingOtherKey)
@@ -171,7 +185,7 @@ extension BTree {
     /// - Complexity:
     ///    - O(min(`self.count`, `other.count`)) in general.
     ///    - O(log(`self.count` + `other.count`)) if there are only a constant amount of interleaving element runs.
-    public func intersection(_ other: BTree, by strategy: BTreeMatchStrategy) -> BTree {
+    public func intersection(_ other: BTree, by strategy: BTreeMatchingStrategy) -> BTree {
         var m = BTreeMerger(first: self, second: other)
         while !m.done {
             m.skipFromFirst(.excludingOtherKey)
@@ -195,7 +209,7 @@ extension BTree {
     ///
     /// - Requires: `sortedKeys` is sorted in ascending order.
     /// - Complexity: O(*n* + `self.count`), where *n* is the number of keys in `sortedKeys`.
-    public func subtracting<S: Sequence>(sortedKeys: S, by strategy: BTreeMatchStrategy) -> BTree where S.Iterator.Element == Key {
+    public func subtracting<S: Sequence>(sortedKeys: S, by strategy: BTreeMatchingStrategy) -> BTree where S.Iterator.Element == Key {
         if self.isEmpty { return self }
 
         var b = BTreeBuilder<Key, Value>(order: self.order)
@@ -237,7 +251,7 @@ extension BTree {
     ///
     /// - Requires: `sortedKeys` is sorted in ascending order.
     /// - Complexity: O(*n* + `self.count`), where *n* is the number of keys in `sortedKeys`.
-    public func intersection<S: Sequence>(sortedKeys: S, by strategy: BTreeMatchStrategy) -> BTree where S.Iterator.Element == Key {
+    public func intersection<S: Sequence>(sortedKeys: S, by strategy: BTreeMatchingStrategy) -> BTree where S.Iterator.Element == Key {
         if self.isEmpty { return self }
 
         var b = BTreeBuilder<Key, Value>(order: self.order)

Tests/BTreeComparisonTests.swift

@@ -169,7 +169,7 @@ class BTreeComparisonTests: XCTestCase {
         let e = makeTree(Array(0 ..< 50) + Array(51 ..< 100))
         let f = makeTree([50])
 
-        for strategy in [BTreeMatchStrategy.groupingMatches, .countingMatches] {
+        for strategy in [BTreeMatchingStrategy.groupingMatches, .countingMatches] {
             XCTAssertTrue(a.isSubset(of: b, by: strategy))
             XCTAssertFalse(a.isSubset(of: c, by: strategy))
             XCTAssertTrue(a.isSubset(of: d, by: strategy))
@@ -216,7 +216,7 @@ class BTreeComparisonTests: XCTestCase {
         let e = makeTree(Array(0 ..< 50) + Array(51 ..< 100))
         let f = makeTree([50])
 
-        for strategy in [BTreeMatchStrategy.groupingMatches, .countingMatches] {
+        for strategy in [BTreeMatchingStrategy.groupingMatches, .countingMatches] {
             XCTAssertFalse(a.isStrictSubset(of: b, by: strategy))
             XCTAssertFalse(a.isStrictSubset(of: c, by: strategy))
             XCTAssertTrue(a.isStrictSubset(of: d, by: strategy))
@@ -263,7 +263,7 @@ class BTreeComparisonTests: XCTestCase {
         let e = makeTree(Array(0 ..< 50) + Array(51 ..< 100))
         let f = makeTree([50])
 
-        for strategy in [BTreeMatchStrategy.groupingMatches, .countingMatches] {
+        for strategy in [BTreeMatchingStrategy.groupingMatches, .countingMatches] {
             XCTAssertTrue(a.isSuperset(of: b, by: strategy))
             XCTAssertTrue(a.isSuperset(of: c, by: strategy))
             XCTAssertFalse(a.isSuperset(of: d, by: strategy))
@@ -310,7 +310,7 @@ class BTreeComparisonTests: XCTestCase {
         let e = makeTree(Array(0 ..< 50) + Array(51 ..< 100))
         let f = makeTree([50])
 
-        for strategy in [BTreeMatchStrategy.groupingMatches, .countingMatches] {
+        for strategy in [BTreeMatchingStrategy.groupingMatches, .countingMatches] {
             XCTAssertFalse(b.isStrictSuperset(of: a, by: strategy))
             XCTAssertFalse(c.isStrictSuperset(of: a, by: strategy))
             XCTAssertTrue(d.isStrictSuperset(of: a, by: strategy))
@@ -356,7 +356,7 @@ class BTreeComparisonTests: XCTestCase {
         var z = x
         z.removeFirst()
 
-        for strategy in [BTreeMatchStrategy.groupingMatches, .countingMatches] {
+        for strategy in [BTreeMatchingStrategy.groupingMatches, .countingMatches] {
             XCTAssertTrue(x.isSubset(of: x, by: strategy))
             XCTAssertTrue(y.isSubset(of: x, by: strategy))
             XCTAssertTrue(z.isSubset(of: x, by: strategy))