feat: add State::prefixed_entries() returning a range of entries with a given prefix.

This is useful to limit entry traversal and thus do less work.

Author: Byron

gix-index/src/access/mod.rs

@@ -158,6 +158,34 @@ impl State {
         Some(&self.entries[idx])
     }
 
+    /// Return the slice of entries which all share the same `prefix`, or `None` if there isn't a single such entry.
+    pub fn prefixed_entries(&self, prefix: &BStr) -> Option<&[Entry]> {
+        if prefix.is_empty() {
+            return Some(self.entries());
+        }
+        let prefix_len = prefix.len();
+        let mut low = self
+            .entries
+            .partition_point(|e| e.path(self).get(..prefix_len).map_or(true, |p| p < prefix));
+        let mut high = low
+            + self.entries[low..].partition_point(|e| e.path(self).get(..prefix_len).map_or(false, |p| p <= prefix));
+
+        let low_entry = &self.entries[low];
+        if low_entry.stage() != 0 {
+            low = self
+                .entry_index_by_idx_and_stage(low_entry.path(self), low, 0, low_entry.stage().cmp(&0))
+                .unwrap_or(low);
+        }
+        if let Some(high_entry) = self.entries.get(high) {
+            if low_entry.stage() != 2 {
+                high = self
+                    .entry_index_by_idx_and_stage(high_entry.path(self), high, 2, high_entry.stage().cmp(&2))
+                    .unwrap_or(high);
+            }
+        }
+        (low != high).then_some(low..high).map(|range| &self.entries[range])
+    }
+
     /// Return the entry at `idx` or _panic_ if the index is out of bounds.
     ///
     /// The `idx` is typically returned by [`entry_by_path_and_stage()`][State::entry_by_path_and_stage()].

gix-index/tests/index/access.rs

@@ -28,7 +28,17 @@ fn entry_by_path_with_conflicting_file() {
         file.entry_by_path("file".into()).expect("found").stage(),
         2,
         "we always find our stage while in a merge"
-    )
+    );
+    assert_eq!(
+        file.prefixed_entries("fil".into()).expect("present"),
+        file.entries(),
+        "it's possible to get the entire range"
+    );
+    assert_eq!(
+        file.prefixed_entries("".into()).expect("present"),
+        file.entries(),
+        "empty prefix matches all"
+    );
 }
 
 #[test]
@@ -65,4 +75,31 @@ fn sort_entries() {
         new_entry_path,
         "we can find the correct entry now"
     );
+
+    check_prefix(&file, "a", &["a", "an initially incorrectly ordered entry"]);
+    check_prefix(
+        &file,
+        "d",
+        &["d/a", "d/b", "d/c", "d/last/123", "d/last/34", "d/last/6"],
+    );
+    check_prefix(
+        &file,
+        "d/",
+        &["d/a", "d/b", "d/c", "d/last/123", "d/last/34", "d/last/6"],
+    );
+    check_prefix(&file, "d/last", &["d/last/123", "d/last/34", "d/last/6"]);
+    check_prefix(&file, "d/las", &["d/last/123", "d/last/34", "d/last/6"]);
+    check_prefix(&file, "x", &["x"]);
+}
+
+fn check_prefix(index: &gix_index::State, prefix: &str, expected: &[&str]) {
+    assert_eq!(
+        index
+            .prefixed_entries(prefix.into())
+            .expect("present")
+            .iter()
+            .map(|e| e.path(index))
+            .collect::<Vec<_>>(),
+        expected
+    );
 }