|
12 | 12 | extension _BTree { |
13 | 13 | /// A mutable cursor to an element of the B-Tree represented as a path. |
14 | 14 | /// |
15 | | - /// There are two variants of a B-Tree cursor, a 'concrete' cursor which points at a specific element which |
16 | | - /// already exists in the tree, and a 'non-concrete' cursor which points to a specific slot, representing an |
17 | | - /// element which does not exist within the tree. It is therefore an invalid operation to operate on a |
18 | | - /// non-concrete cursor's element (as it may be out-of-bounds). However, you can convert a |
19 | | - /// non-concrete cursor to a concrete cursor using the |
20 | | - /// ``_BTree.UnsafeCursor.makeConcrete()`` operation. Concrete cursor checks are no-ops in |
21 | | - /// non-debug builds. |
22 | | - /// |
23 | 15 | /// Cursors consume the original tree on which they were created. It is undefined behavior to operate or |
24 | | - /// read a tree on which a cursor was created. While this is the case, the original tree must remain alive |
25 | | - /// for the entire lifetime of a cursor. Certain cursor operations, will yield a new tree root which can be |
26 | | - /// used to obtain a usable tree reference. It is invalid to use a cursor after such operations. |
27 | | - /// |
28 | | - /// If you wish to retrieve your tree and an operation yielding a new tree root has not been called yet, you |
29 | | - /// may use ``_BTree.UnsafeCursor.finish()``. |
| 16 | + /// read a tree on which a cursor was created. A cursor strongly references the tree on which it was |
| 17 | + /// operating on. Once operations with a cursor are finished, the tree can be restored using |
| 18 | + /// `_BTree.UnsafeCursor.apply(to:)`. |
30 | 19 | /// |
31 | 20 | /// This is a heavier alternative to ``_BTree.Index``, however this allows mutable operations to be |
32 | 21 | /// efficiently performed. |
@@ -380,9 +369,7 @@ extension _BTree { |
380 | 369 | /// the cursors lifetime. |
381 | 370 | /// |
382 | 371 | /// - Parameter key: The key to search for |
383 | | - /// - Returns: A `cursor` to the key or where the key should be inserted, and a `found` |
384 | | - /// parameter indicating whether or not the key exists within the tree, iff `found` is true, the cursor |
385 | | - /// is concrete. |
| 372 | + /// - Returns: A cursor to the key or where the key should be inserted. |
386 | 373 | /// - Complexity: O(`log n`) |
387 | 374 | @inlinable |
388 | 375 | internal mutating func takeCursor(at index: Index) -> UnsafeCursor { |
@@ -441,8 +428,7 @@ extension _BTree { |
441 | 428 | /// |
442 | 429 | /// - Parameter key: The key to search for |
443 | 430 | /// - Returns: A `cursor` to the key or where the key should be inserted, and a `found` |
444 | | - /// parameter indicating whether or not the key exists within the tree, iff `found` is true, the cursor |
445 | | - /// is concrete. |
| 431 | + /// parameter indicating whether or not the key exists within the tree. |
446 | 432 | /// - Complexity: O(`log n`) |
447 | 433 | @inlinable |
448 | 434 | internal mutating func takeCursor( |
|
0 commit comments