introduce the Comparable trait for btree internals

conradludgate · conradludgate · commit 5a6240c57edd · 2025-08-29T09:19:42.000+01:00
diff --git a/library/alloc/src/collections/btree/cmp.rs b/library/alloc/src/collections/btree/cmp.rs
@@ -0,0 +1,52 @@
+//! Complements to the [`core::cmp`] module
+
+use core::borrow::Borrow;
+use core::cmp::Ordering;
+
+/// Key equivalence trait.
+///
+/// This trait allows hash table lookup to be customized. It has one blanket
+/// implementation that uses the regular solution with `Borrow` and `Eq`, just
+/// like `HashMap` does, so that you can pass `&str` to lookup into a map with
+/// `String` keys and so on.
+///
+/// # Contract
+///
+/// The implementor **must** hash like `Q`, if it is hashable.
+pub(crate) trait Equivalent<Q: ?Sized> {
+    // /// Compare self to `key` and return `true` if they are equal.
+    // fn equivalent(&self, key: &Q) -> bool;
+}
+
+impl<K: ?Sized, Q: ?Sized> Equivalent<Q> for K
+where
+    K: Borrow<Q>,
+    Q: Eq,
+{
+    // #[inline]
+    // fn equivalent(&self, key: &Q) -> bool {
+    //     PartialEq::eq(self.borrow(), key)
+    // }
+}
+
+/// Key ordering trait.
+///
+/// This trait allows ordered map lookup to be customized. It has one blanket
+/// implementation that uses the regular solution with `Borrow` and `Ord`, just
+/// like `BTreeMap` does, so that you can pass `&str` to lookup into a map with
+/// `String` keys and so on.
+pub(crate) trait Comparable<Q: ?Sized>: Equivalent<Q> {
+    /// Compare self to `key` and return their ordering.
+    fn compare(&self, key: &Q) -> Ordering;
+}
+
+impl<K: ?Sized, Q: ?Sized> Comparable<Q> for K
+where
+    K: Borrow<Q>,
+    Q: Ord,
+{
+    #[inline]
+    fn compare(&self, key: &Q) -> Ordering {
+        Ord::cmp(self.borrow(), key)
+    }
+}
diff --git a/library/alloc/src/collections/btree/mod.rs b/library/alloc/src/collections/btree/mod.rs
@@ -1,5 +1,6 @@
 mod append;
 mod borrow;
+mod cmp;
 mod dedup_sorted_iter;
 mod fix;
 pub(super) mod map;
diff --git a/library/alloc/src/collections/btree/navigate.rs b/library/alloc/src/collections/btree/navigate.rs
@@ -1,7 +1,7 @@
-use core::borrow::Borrow;
 use core::ops::RangeBounds;
 use core::{hint, ptr};
 
+use super::cmp::Comparable;
 use super::node::ForceResult::*;
 use super::node::{Handle, NodeRef, marker};
 use super::search::SearchBound;
@@ -267,7 +267,7 @@ impl<BorrowType: marker::BorrowType, K, V> NodeRef<BorrowType, K, V, marker::Lea
     ) -> LeafRange<BorrowType, K, V>
     where
         Q: Ord,
-        K: Borrow<Q>,
+        K: Comparable<Q>,
         R: RangeBounds<Q>,
     {
         match self.search_tree_for_bifurcation(&range) {
@@ -316,7 +316,7 @@ impl<'a, K: 'a, V: 'a> NodeRef<marker::Immut<'a>, K, V, marker::LeafOrInternal>
     pub(super) fn range_search<Q, R>(self, range: R) -> LeafRange<marker::Immut<'a>, K, V>
     where
         Q: ?Sized + Ord,
-        K: Borrow<Q>,
+        K: Comparable<Q>,
         R: RangeBounds<Q>,
     {
         // SAFETY: our borrow type is immutable.
@@ -342,7 +342,7 @@ impl<'a, K: 'a, V: 'a> NodeRef<marker::ValMut<'a>, K, V, marker::LeafOrInternal>
     pub(super) fn range_search<Q, R>(self, range: R) -> LeafRange<marker::ValMut<'a>, K, V>
     where
         Q: ?Sized + Ord,
-        K: Borrow<Q>,
+        K: Comparable<Q>,
         R: RangeBounds<Q>,
     {
         unsafe { self.find_leaf_edges_spanning_range(range) }
@@ -746,8 +746,7 @@ impl<BorrowType: marker::BorrowType, K, V> NodeRef<BorrowType, K, V, marker::Lea
         mut bound: SearchBound<&Q>,
     ) -> Handle<NodeRef<BorrowType, K, V, marker::Leaf>, marker::Edge>
     where
-        Q: Ord,
-        K: Borrow<Q>,
+        K: Comparable<Q>,
     {
         let mut node = self;
         loop {
@@ -769,8 +768,7 @@ impl<BorrowType: marker::BorrowType, K, V> NodeRef<BorrowType, K, V, marker::Lea
         mut bound: SearchBound<&Q>,
     ) -> Handle<NodeRef<BorrowType, K, V, marker::Leaf>, marker::Edge>
     where
-        Q: Ord,
-        K: Borrow<Q>,
+        K: Comparable<Q>,
     {
         let mut node = self;
         loop {
diff --git a/library/alloc/src/collections/btree/search.rs b/library/alloc/src/collections/btree/search.rs
@@ -1,10 +1,10 @@
-use core::borrow::Borrow;
 use core::cmp::Ordering;
 use core::ops::{Bound, RangeBounds};
 
 use SearchBound::*;
 use SearchResult::*;
 
+use super::cmp::Comparable;
 use super::node::ForceResult::*;
 use super::node::{Handle, NodeRef, marker};
 
@@ -51,8 +51,7 @@ impl<BorrowType: marker::BorrowType, K, V> NodeRef<BorrowType, K, V, marker::Lea
         key: &Q,
     ) -> SearchResult<BorrowType, K, V, marker::LeafOrInternal, marker::Leaf>
     where
-        Q: Ord,
-        K: Borrow<Q>,
+        K: Comparable<Q>,
     {
         loop {
             self = match self.search_node(key) {
@@ -95,7 +94,7 @@ impl<BorrowType: marker::BorrowType, K, V> NodeRef<BorrowType, K, V, marker::Lea
     >
     where
         Q: Ord,
-        K: Borrow<Q>,
+        K: Comparable<Q>,
         R: RangeBounds<Q>,
     {
         // Determine if map or set is being searched
@@ -161,8 +160,8 @@ impl<BorrowType: marker::BorrowType, K, V> NodeRef<BorrowType, K, V, marker::Lea
         bound: SearchBound<&'r Q>,
     ) -> (Handle<Self, marker::Edge>, SearchBound<&'r Q>)
     where
-        Q: ?Sized + Ord,
-        K: Borrow<Q>,
+        Q: ?Sized,
+        K: Comparable<Q>,
     {
         let (edge_idx, bound) = self.find_lower_bound_index(bound);
         let edge = unsafe { Handle::new_edge(self, edge_idx) };
@@ -175,8 +174,8 @@ impl<BorrowType: marker::BorrowType, K, V> NodeRef<BorrowType, K, V, marker::Lea
         bound: SearchBound<&'r Q>,
     ) -> (Handle<Self, marker::Edge>, SearchBound<&'r Q>)
     where
-        Q: ?Sized + Ord,
-        K: Borrow<Q>,
+        Q: ?Sized,
+        K: Comparable<Q>,
     {
         let (edge_idx, bound) = unsafe { self.find_upper_bound_index(bound, 0) };
         let edge = unsafe { Handle::new_edge(self, edge_idx) };
@@ -197,8 +196,7 @@ impl<BorrowType, K, V, Type> NodeRef<BorrowType, K, V, Type> {
         key: &Q,
     ) -> SearchResult<BorrowType, K, V, Type, Type>
     where
-        Q: Ord,
-        K: Borrow<Q>,
+        K: Comparable<Q>,
     {
         match unsafe { self.find_key_index(key, 0) } {
             IndexResult::KV(idx) => Found(unsafe { Handle::new_kv(self, idx) }),
@@ -216,17 +214,16 @@ impl<BorrowType, K, V, Type> NodeRef<BorrowType, K, V, Type> {
     /// `start_index` must be a valid edge index for the node.
     unsafe fn find_key_index<Q: ?Sized>(&self, key: &Q, start_index: usize) -> IndexResult
     where
-        Q: Ord,
-        K: Borrow<Q>,
+        K: Comparable<Q>,
     {
         let node = self.reborrow();
         let keys = node.keys();
         debug_assert!(start_index <= keys.len());
         for (offset, k) in unsafe { keys.get_unchecked(start_index..) }.iter().enumerate() {
-            match key.cmp(k.borrow()) {
-                Ordering::Greater => {}
+            match k.compare(key) {
+                Ordering::Less => {}
                 Ordering::Equal => return IndexResult::KV(start_index + offset),
-                Ordering::Less => return IndexResult::Edge(start_index + offset),
+                Ordering::Greater => return IndexResult::Edge(start_index + offset),
             }
         }
         IndexResult::Edge(keys.len())
@@ -242,8 +239,8 @@ impl<BorrowType, K, V, Type> NodeRef<BorrowType, K, V, Type> {
         bound: SearchBound<&'r Q>,
     ) -> (usize, SearchBound<&'r Q>)
     where
-        Q: ?Sized + Ord,
-        K: Borrow<Q>,
+        Q: ?Sized,
+        K: Comparable<Q>,
     {
         match bound {
             Included(key) => match unsafe { self.find_key_index(key, 0) } {
@@ -270,8 +267,8 @@ impl<BorrowType, K, V, Type> NodeRef<BorrowType, K, V, Type> {
         start_index: usize,
     ) -> (usize, SearchBound<&'r Q>)
     where
-        Q: ?Sized + Ord,
-        K: Borrow<Q>,
+        Q: ?Sized,
+        K: Comparable<Q>,
     {
         match bound {
             Included(key) => match unsafe { self.find_key_index(key, start_index) } {
