Final touch up, polishes, and optimizations.

Key Changes:
 - Add duplicate handling functionality to _BTree.Builder
 - Remove transient allocation in SortedDictionary.values _modify
 - Add missing SortedDictionary.Values.subscript _modify
 - Add SortedSet(sortedElements:)
 - Add optimized SetAlgebra implementations
 - Remove remaining high-level offset APIs
 - Various optimizations
 - Expand internal documentation

Minor Changes:
 - Add ability to create dummy node
 - _BTree.Builder.append(key: Key) for sets.
 - Fix bug where findAnyIndex(forKey:) didn't calculate the offset.
 - Remove old, unused files
 - findAnyCursor -> takeCursor (to emphasize consuming nature)
 - Add takeCursor(at: Index)
 - Optimize init(grouping:by:) to use modifyValue to reduce CoW

Optimizations:
 - Use dummy node for transient _modify state rather than allocating new buffer

Author: vihanb

.swiftpm/xcode/xcshareddata/xcschemes/swift-collections-Package.xcscheme

@@ -132,6 +132,20 @@
                ReferencedContainer = "container:">
             </BuildableReference>
          </BuildActionEntry>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "SortedCollections"
+               BuildableName = "SortedCollections"
+               BlueprintName = "SortedCollections"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
       </BuildActionEntries>
    </BuildAction>
    <TestAction
@@ -180,6 +194,16 @@
                ReferencedContainer = "container:">
             </BuildableReference>
          </TestableReference>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "SortedCollectionsTests"
+               BuildableName = "SortedCollectionsTests"
+               BlueprintName = "SortedCollectionsTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
       </Testables>
    </TestAction>
    <LaunchAction

.swiftpm/xcode/xcshareddata/xcschemes/swift-collections-benchmark.xcscheme

@@ -58,12 +58,22 @@
                ReferencedContainer = "container:">
             </BuildableReference>
          </TestableReference>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "SortedCollectionsTests"
+               BuildableName = "SortedCollectionsTests"
+               BlueprintName = "SortedCollectionsTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
       </Testables>
    </TestAction>
    <LaunchAction
-      buildConfiguration = "Debug"
-      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
-      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      buildConfiguration = "Release"
+      selectedDebuggerIdentifier = ""
+      selectedLauncherIdentifier = "Xcode.IDEFoundation.Launcher.PosixSpawn"
       launchStyle = "0"
       useCustomWorkingDirectory = "NO"
       ignoresPersistentStateOnLaunch = "NO"
@@ -80,6 +90,32 @@
             ReferencedContainer = "container:">
          </BuildableReference>
       </BuildableProductRunnable>
+      <CommandLineArguments>
+         <CommandLineArgument
+            argument = "run"
+            isEnabled = "YES">
+         </CommandLineArgument>
+         <CommandLineArgument
+            argument = "-f"
+            isEnabled = "YES">
+         </CommandLineArgument>
+         <CommandLineArgument
+            argument = "SortedDictionary.*init"
+            isEnabled = "YES">
+         </CommandLineArgument>
+         <CommandLineArgument
+            argument = "/Users/vihan/Documents/swift-collections/output"
+            isEnabled = "YES">
+         </CommandLineArgument>
+         <CommandLineArgument
+            argument = "--mode"
+            isEnabled = "YES">
+         </CommandLineArgument>
+         <CommandLineArgument
+            argument = "replace-all"
+            isEnabled = "YES">
+         </CommandLineArgument>
+      </CommandLineArguments>
    </LaunchAction>
    <ProfileAction
       buildConfiguration = "Release"

Sources/SortedCollections/BTree/_BTree+BidirectionalCollection.swift

@@ -26,7 +26,7 @@ extension _BTree: BidirectionalCollection {
   @inline(__always)
   internal var isEmpty: Bool { self.count == 0 }
 
-  // TODO: look into O(1) implementation
+  // TODO: further consider O(1) implementation
   /// Locates the first element and returns a proper path to it, or nil if the BTree is empty.
   /// - Complexity: O(`log n`)
   @inlinable
@@ -92,6 +92,8 @@ extension _BTree: BidirectionalCollection {
     precondition(index.offset < self.count,
                  "Attempt to advance out of collection bounds.")
 
+    // TODO: this might be redundant given the fact the same (but generalized)
+    // logic is implemented in offsetBy
     let shouldSeekWithinLeaf = index.readNode {
       $0.isLeaf && _fastPath(index.slot + 1 < $0.elementCount)
     }
@@ -123,7 +125,6 @@ extension _BTree: BidirectionalCollection {
   internal func formIndex(before index: inout Index) {
     precondition(!self.isEmpty && index.offset != 0,
                  "Attempt to advance out of collection bounds.")
-    // TODO: implement more efficient logic to better move through the tree
     self.formIndex(&index, offsetBy: -1)
   }
 

Sources/SortedCollections/BTree/_BTree+Partial RangeReplaceableCollection.swift

@@ -19,7 +19,6 @@ extension _BTree {
   public func filter(
     _ isIncluded: (Element) throws -> Bool
   ) rethrows -> _BTree {
-    // TODO: optimize implementation to O(n)
     var builder = Builder()
     for element in self where try isIncluded(element) {
       builder.append(element)

Sources/SortedCollections/BTree/_BTree+Sequence.swift

@@ -94,7 +94,6 @@ extension _BTree: Sequence {
         return
       }
 
-      // TODO: maybe convert to unowned(unsafe)
       var nextNode: Unmanaged? = .passUnretained(tree.root.storage)
       while let node = nextNode {
         self.path.append(node)

Sources/SortedCollections/BTree/_BTree+Testing.swift

@@ -379,15 +379,73 @@ extension _BTree {
   /// This 'consumes' the tree, however it expects the callee to retain the root of the tree for the duration of
   /// the cursors lifetime.
   ///
-  /// - Parameters:
-  ///   - key: The key to search for
-  ///   - mutable: whether a mutable cursor should be returned.
+  /// - Parameter key: The key to search for
   /// - Returns: A `cursor` to the key or where the key should be inserted, and a `found`
   ///     parameter indicating whether or not the key exists within the tree, iff `found` is true, the cursor
   ///     is concrete.
   /// - Complexity: O(`log n`)
   @inlinable
-  internal mutating func findAnyCursor(
+  internal mutating func takeCursor(at index: Index) -> UnsafeCursor {
+    var slots = index.childSlots
+    slots.append(UInt16(index.slot))
+    
+    // Initialize parents with some dummy value filling it.
+    var parents =
+      UnsafeCursor.Path(repeating: .passUnretained(self.root.storage))
+    
+    var ownedRoot: Node.Storage
+    do {
+      var tempRoot: Node.Storage? = nil
+      swap(&tempRoot, &self.root._storage)
+      ownedRoot = tempRoot.unsafelyUnwrapped
+    }
+    
+    var node: Unmanaged<Node.Storage> = .passUnretained(ownedRoot)
+    
+    // The depth containing the first instance of a shared
+    var lastUniqueDepth = isKnownUniquelyReferenced(&ownedRoot) ? 0 : -1
+    var isOnUniquePath = isKnownUniquelyReferenced(&ownedRoot)
+    
+    for d in 0..<index.childSlots.depth {
+      node._withUnsafeGuaranteedRef { storage in
+        storage.read { handle in
+          parents.append(node)
+          
+          let slot = Int(index.childSlots[d])
+          node = .passUnretained(handle[childAt: slot].storage)
+          if isOnUniquePath && handle.isChildUnique(atSlot: slot) {
+            lastUniqueDepth += 1
+          } else {
+            isOnUniquePath = false
+          }
+        }
+      }
+    }
+    
+    parents.append(node)
+    
+    let cursor = UnsafeCursor(
+      root: ownedRoot,
+      slots: slots,
+      path: parents,
+      lastUniqueDepth: lastUniqueDepth
+    )
+    
+    return cursor
+  }
+
+  /// Obtains a cursor to a given element in the tree.
+  ///
+  /// This 'consumes' the tree, however it expects the callee to retain the root of the tree for the duration of
+  /// the cursors lifetime.
+  ///
+  /// - Parameter key: The key to search for
+  /// - Returns: A `cursor` to the key or where the key should be inserted, and a `found`
+  ///     parameter indicating whether or not the key exists within the tree, iff `found` is true, the cursor
+  ///     is concrete.
+  /// - Complexity: O(`log n`)
+  @inlinable
+  internal mutating func takeCursor(
     forKey key: Key
   ) -> (cursor: UnsafeCursor, found: Bool) {
     var slots = Index.Offsets(repeating: 0)

Sources/SortedCollections/BTree/_BTree+UnsafeCursor.swift

@@ -12,6 +12,10 @@
 extension _BTree {
   /// Provides an interface for efficiently constructing a filled B-Tree from sorted data.
   ///
+  /// A builder supports duplicate keys, in which case they are inserted in the same order they are recieved.
+  /// However, is the `deduplicating` parameter is passed as `true`, operations will silently drop
+  /// duplicates.
+  ///
   /// This type has a few advantages when constructing a B-Tree over other approaches such as manually
   /// inserting each element or using a cursor:
   ///
@@ -101,31 +105,47 @@ extension _BTree {
     @usableFromInline
     internal let internalCapacity: Int
 
+    @usableFromInline
+    internal let deduplicating: Bool
+    
+    @usableFromInline
+    internal var lastKey: Key?
+    
     /// Creates a new B-Tree builder with default capacities
+    /// - Parameter deduplicating: Whether duplicates should be removed.
     @inlinable
     @inline(__always)
-    internal init() {
+    internal init(deduplicating: Bool = false) {
       self.init(
+        deduplicating: deduplicating,
         leafCapacity: _BTree.defaultLeafCapacity,
         internalCapacity: _BTree.defaultInternalCapacity
       )
     }
 
     /// Creates a new B-Tree builder with a custom uniform capacity configuration
     /// - Parameters:
+    ///   - deduplicating: Whether duplicates should be removed.
     ///   - capacity: The amount of elements per node.
     @inlinable
     @inline(__always)
-    internal init(capacity: Int) {
-      self.init(leafCapacity: capacity, internalCapacity: capacity)
+    internal init(deduplicating: Bool = false, capacity: Int) {
+      self.init(
+        deduplicating: deduplicating,
+        leafCapacity: capacity,
+        internalCapacity: capacity
+      )
     }
 
     /// Creates a new B-Tree builder with a custom capacity configuration
     /// - Parameters:
-    ///   - capacity: The amount of elements per node.
+    ///   - deduplicating: Whether duplicates should be removed.
+    ///   - leafCapacity: The amount of elements per leaf node.
+    ///   - internalCapacity: The amount of elements per internal node.
     @inlinable
     @inline(__always)
     internal init(
+      deduplicating: Bool = false,
       leafCapacity: Int,
       internalCapacity: Int
     ) {
@@ -138,6 +158,8 @@ extension _BTree {
       self._seedling = Node(withCapacity: leafCapacity, isLeaf: true)
       self.leafCapacity = leafCapacity
       self.internalCapacity = internalCapacity
+      self.deduplicating = deduplicating
+      self.lastKey = nil
     }
 
     /// Pops a sapling and it's associated seperator
@@ -176,8 +198,16 @@ extension _BTree {
     /// Appends a new element to the tree
     /// - Parameter element: Element which is after all previous elements in sorted order.
     @inlinable
-    @inline(__always)
     internal mutating func append(_ element: __owned Element) {
+      assert(lastKey == nil || lastKey! <= element.key,
+             "New element must be non-decreasing.")
+      defer { lastKey = element.key }
+      if deduplicating {
+        if let lastKey = lastKey {
+          if lastKey == element.key { return }
+        }
+      }
+      
       switch state {
       case .addingSeperator:
         completeSeedling(withSeperator: element)
@@ -200,7 +230,6 @@ extension _BTree {
     /// Declares that the current seedling is finished with insertion and creates a new seedling to
     /// further operate on.
     @inlinable
-    @inline(__always)
     internal mutating func completeSeedling(
       withSeperator newSeperator: __owned Element
     ) {
@@ -311,7 +340,6 @@ extension _BTree {
     ///
     /// - Returns: A usable, fully-filled B-Tree
     @inlinable
-    @inline(__always)
     internal mutating func finish() -> _BTree {
       var root: Node = seedling
       _seedling = nil
@@ -331,3 +359,12 @@ extension _BTree {
     }
   }
 }
+
+extension _BTree.Builder where Value == Void {
+  /// Appends a value to a B-Tree builder without values.
+  @inlinable
+  @inline(__always)
+  internal mutating func append(_ key: __owned Key) {
+    self.append((key, ()))
+  }
+}