range: remove dead helpers (optimize_range_query, estimate_range_size, last-leaf helper); add differential range tests; docs: agent guideline to delete dead code immediately

Author: KentBeck

agent.md

@@ -19,5 +19,6 @@
 
 - Hygiene before commit
   - Always remove dead code introduced by refactors.
+  - Delete code as soon as it is dead.
   - Always format the workspace: `cd rust && cargo fmt --all`.
   - Always run all tests: `cargo test --workspace` (and benches if relevant).

rust/src/range_queries.rs

@@ -133,85 +133,5 @@ impl<K: Ord + Clone, V: Clone> BPlusTreeMap<K, V> {
     // RANGE OPTIMIZATION HELPERS
     // ============================================================================
 
-    /// Optimize range queries by pre-calculating bounds and positions.
-    #[allow(dead_code)]
-    pub fn optimize_range_query<R>(&self, range: R) -> Option<(NodeId, usize, NodeId, usize)>
-    where
-        R: RangeBounds<K>,
-    {
-        let start_pos = match range.start_bound() {
-            Bound::Included(key) | Bound::Excluded(key) => self.find_leaf_for_key(key)?,
-            Bound::Unbounded => {
-                let first_leaf = self.get_first_leaf_id()?;
-                (first_leaf, 0)
-            }
-        };
-
-        let end_pos = match range.end_bound() {
-            Bound::Included(key) | Bound::Excluded(key) => self.find_leaf_for_key(key)?,
-            Bound::Unbounded => {
-                // Find the last leaf and its last position
-                self.find_last_leaf_position()?
-            }
-        };
-
-        Some((start_pos.0, start_pos.1, end_pos.0, end_pos.1))
-    }
-
-    /// Find the last leaf node and its last valid position.
-    fn find_last_leaf_position(&self) -> Option<(NodeId, usize)> {
-        // Start from root and go to rightmost leaf
-        let mut current = &self.root;
-
-        loop {
-            match current {
-                NodeRef::Leaf(leaf_id, _) => {
-                    if let Some(leaf) = self.get_leaf(*leaf_id) {
-                        let last_index = if leaf.keys_is_empty() {
-                            0
-                        } else {
-                            leaf.keys_len() - 1
-                        };
-                        return Some((*leaf_id, last_index));
-                    } else {
-                        return None;
-                    }
-                }
-                NodeRef::Branch(branch_id, _) => {
-                    if let Some(branch) = self.get_branch(*branch_id) {
-                        if let Some(last_child) = branch.children.last() {
-                            current = last_child;
-                        } else {
-                            return None;
-                        }
-                    } else {
-                        return None;
-                    }
-                }
-            }
-        }
-    }
-
-    // ============================================================================
-    // RANGE STATISTICS
-    // ============================================================================
-
-    /// Estimate the number of elements in a range without iterating.
-    #[allow(dead_code)]
-    pub fn estimate_range_size<R>(&self, range: R) -> usize
-    where
-        R: RangeBounds<K>,
-    {
-        // Simple estimation based on tree structure
-        // This could be optimized further with more sophisticated algorithms
-        match (range.start_bound(), range.end_bound()) {
-            (Bound::Unbounded, Bound::Unbounded) => self.len(),
-            _ => {
-                // For now, use a simple heuristic
-                // In a real implementation, this could use tree statistics
-                // to provide better estimates without full iteration
-                self.len() / 4 // Conservative estimate
-            }
-        }
-    }
+    // (Removed dead code: optimize_range_query, estimate_range_size, find_last_leaf_position)
 }

rust/tests/range_differential.rs

@@ -0,0 +1,101 @@
+use bplustree::BPlusTreeMap;
+use std::collections::BTreeMap;
+
+fn populate_maps(capacity: usize, data: &[i32]) -> (BPlusTreeMap<i32, i32>, BTreeMap<i32, i32>) {
+    let mut tree = BPlusTreeMap::new(capacity).unwrap();
+    let mut map = BTreeMap::new();
+    for &k in data {
+        tree.insert(k, k * 10);
+        map.insert(k, k * 10);
+    }
+    (tree, map)
+}
+
+#[test]
+fn test_range_differential_basic_boundaries() {
+    // Use small capacities to force multiple leaves and boundary transitions
+    for &cap in &[4_usize, 5, 8] {
+        let data: Vec<i32> = (0..20).collect();
+        let (tree, map) = populate_maps(cap, &data);
+
+        // Helper to compare results for a range expression
+        let assert_same = |lhs: Vec<(i32, i32)>, rhs: Vec<(i32, i32)>, label: &str| {
+            assert_eq!(lhs, rhs, "mismatch for range: {} (cap={})", label, cap);
+        };
+
+        // Closed-open typical range
+        let got: Vec<_> = tree.range(3..7).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(3..7).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "3..7");
+
+        // Closed-closed
+        let got: Vec<_> = tree.range(3..=7).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(3..=7).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "3..=7");
+
+        // Open-ended start
+        let got: Vec<_> = tree.range(..5).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(..5).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "..5");
+
+        // Open-ended end
+        let got: Vec<_> = tree.range(5..).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(5..).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "5..");
+
+        // Full range
+        let got: Vec<_> = tree.range(..).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(..).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "..");
+
+        // Singleton ranges
+        let got: Vec<_> = tree.range(4..=4).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(4..=4).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "4..=4");
+
+        // Empty by construction
+        let got: Vec<_> = tree.range(4..4).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(4..4).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "4..4 (empty)");
+    }
+}
+
+#[test]
+fn test_range_differential_gaps_and_nonexistent_bounds() {
+    // Data with gaps to test non-existing bound keys and cross-leaf traversal
+    for &cap in &[4_usize, 5, 8] {
+        let data = vec![0, 1, 2, 4, 7, 8, 10, 13, 14, 18];
+        let (tree, map) = populate_maps(cap, &data);
+
+        let assert_same = |lhs: Vec<(i32, i32)>, rhs: Vec<(i32, i32)>, label: &str| {
+            assert_eq!(lhs, rhs, "mismatch for range: {} (cap={})", label, cap);
+        };
+
+        // Start/end on non-existent keys (between 2 and 4; between 8 and 10)
+        let got: Vec<_> = tree.range(3..9).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(3..9).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "3..9");
+
+        // Inclusive upper bound non-existent
+        let got: Vec<_> = tree.range(3..=9).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(3..=9).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "3..=9");
+
+        // Exclusive lower bound non-existent
+        let got: Vec<_> = tree.range(3..=4).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(3..=4).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "3..=4");
+
+        // Entirely out-of-range
+        let got: Vec<_> = tree.range(100..200).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(100..200).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "100..200 (empty)");
+
+        // Negative lower bound below min
+        let got: Vec<_> = tree.range(-5..3).map(|(k, v)| (*k, *v)).collect();
+        let exp: Vec<_> = map.range(-5..3).map(|(k, v)| (*k, *v)).collect();
+        assert_same(got, exp, "-5..3");
+
+        // Intentionally avoid inverted ranges: std::BTreeMap panics for start > end
+    }
+}