Rollup merge of rust-lang#68468 - ssomers:btreemap_prefer_middle, r=M…

…ark-Simulacrum

BTreeMap: tag and explain unsafe internal functions or assert preconditions

rust-lang#68418 concluded that it's not desirable to tag all internal functions with preconditions as being unsafe. This PR does it to some functions, documents why, and elsewhere enforces the preconditions with asserts.

src/liballoc/collections/btree/map.rs

@@ -2096,8 +2096,13 @@ where
             }
         }
 
-        let front = Handle::new_edge(min_node, min_edge);
-        let back = Handle::new_edge(max_node, max_edge);
+        // Safety guarantee: `min_edge` is always in range for `min_node`, because
+        // `min_edge` is unconditionally calculated for each iteration's value of `min_node`,
+        // either (if not found) as the edge index returned by `search_linear`,
+        // or (if found) as the KV index returned by `search_linear`, possibly + 1.
+        // Likewise for `max_node` versus `max_edge`.
+        let front = unsafe { Handle::new_edge(min_node, min_edge) };
+        let back = unsafe { Handle::new_edge(max_node, max_edge) };
         match (front.force(), back.force()) {
             (Leaf(f), Leaf(b)) => {
                 return (f, b);