feat: add State::remove_entries() and entry_range().

This makes it possible to, among other things, delete all
occurrences of a particular entry.

Author: Byron

gix-index/src/access/mod.rs

@@ -1,4 +1,5 @@
 use std::cmp::Ordering;
+use std::ops::Range;
 
 use bstr::{BStr, ByteSlice, ByteVec};
 use filetime::FileTime;
@@ -223,6 +224,30 @@ impl State {
     pub fn is_sparse(&self) -> bool {
         self.is_sparse
     }
+
+    /// Return the range of entries that exactly match the given `path`, in all available stages, or `None` if no entry with such
+    /// path exists.
+    ///
+    /// The range can be used to access the respective entries via [`entries()`](Self::entries()) or [`entries_mut()](Self::entries_mut()).
+    pub fn entry_range(&self, path: &BStr) -> Option<Range<usize>> {
+        let mut stage_at_index = 0;
+        let idx = self
+            .entries
+            .binary_search_by(|e| {
+                let res = e.path(self).cmp(path);
+                if res.is_eq() {
+                    stage_at_index = e.stage();
+                }
+                res
+            })
+            .ok()?;
+
+        let (start, end) = (
+            self.walk_entry_stages(path, idx, Ordering::Less).unwrap_or(idx),
+            self.walk_entry_stages(path, idx, Ordering::Greater).unwrap_or(idx) + 1,
+        );
+        Some(start..end)
+    }
 }
 
 /// Mutation
@@ -333,6 +358,25 @@ impl State {
                 .then_with(|| compare(a, b))
         });
     }
+
+    /// Physically remove all entries for which `should_remove(idx, path, entry)` returns `true`, traversing them from first to last.
+    ///
+    /// Note that the memory used for the removed entries paths is not freed, as it's append-only.
+    ///
+    /// ### Performance
+    ///
+    /// To implement this operation typically, one would rather add [entry::Flags::REMOVE] to each entry to remove
+    /// them when [writing the index](Self::write_to()).
+    pub fn remove_entries(&mut self, mut should_remove: impl FnMut(usize, &BStr, &mut Entry) -> bool) {
+        let mut index = 0;
+        let paths = &self.path_backing;
+        self.entries.retain_mut(|e| {
+            let path = e.path_in(paths);
+            let res = !should_remove(index, path, e);
+            index += 1;
+            res
+        });
+    }
 }
 
 /// Extensions

gix-index/tests/index/access.rs

@@ -29,18 +29,54 @@ fn entry_by_path_with_conflicting_file() {
         2,
         "we always find our stage while in a merge"
     );
+}
+
+#[test]
+fn prefixed_entries_with_multi_stage_file() {
+    let file = Fixture::Loose("conflicting-file").open();
+
     assert_eq!(
         file.prefixed_entries("fil".into()).expect("present"),
         file.entries(),
         "it's possible to get the entire range"
     );
+    assert_eq!(
+        file.prefixed_entries("file".into()).expect("present"),
+        file.entries(),
+        "it's possible to get the entire range even if the same path matches multiple times"
+    );
     assert_eq!(
         file.prefixed_entries("".into()).expect("present"),
         file.entries(),
         "empty prefix matches all"
     );
 }
 
+#[test]
+fn entry_range() {
+    let file = Fixture::Loose("conflicting-file").open();
+
+    assert_eq!(
+        file.entry_range("file".into()),
+        Some(0..3),
+        "three stages, all but stage zero"
+    );
+    assert_eq!(file.entry_range("foo".into()), None, "does not exist");
+}
+
+#[test]
+fn remove_entries() {
+    let mut file = Fixture::Loose("conflicting-file").open();
+
+    file.remove_entries(|idx, _, _| idx == 0);
+    assert_eq!(file.entries().len(), 2);
+    file.remove_entries(|idx, _, _| idx == 0);
+    assert_eq!(file.entries().len(), 1);
+    file.remove_entries(|idx, _, _| idx == 0);
+    assert_eq!(file.entries().len(), 0);
+    file.remove_entries(|_, _, _| unreachable!("should not be called"));
+}
+
 #[test]
 fn sort_entries() {
     let mut file = Fixture::Generated("v4_more_files_IEOT").open();