feat: TreeRef::bisect_entry() to correctly find an entry by name

Author: Byron

gix-object/src/lib.rs

@@ -215,6 +215,8 @@ pub enum Object {
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct TreeRef<'a> {
     /// The directories and files contained in this tree.
+    ///
+    /// Beware that the sort order isn't *quite* by name, so one may bisect only with a [`tree::EntryRef`] to handle ordering correctly.
     #[cfg_attr(feature = "serde", serde(borrow))]
     pub entries: Vec<tree::EntryRef<'a>>,
 }
@@ -231,6 +233,8 @@ pub struct TreeRefIter<'a> {
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct Tree {
     /// The directories and files contained in this tree. They must be and remain sorted by [`filename`][tree::Entry::filename].
+    ///
+    /// Beware that the sort order isn't *quite* by name, so one may bisect only with a [`tree::Entry`] to handle ordering correctly.
     pub entries: Vec<tree::Entry>,
 }
 

gix-object/src/tree/ref_iter.rs

@@ -1,3 +1,4 @@
+use bstr::BStr;
 use std::convert::TryFrom;
 
 use nom::error::ParseError;
@@ -17,6 +18,27 @@ impl<'a> TreeRef<'a> {
         decode::tree(data).map(|(_, t)| t).map_err(crate::decode::Error::from)
     }
 
+    /// Find an entry named `name` knowing if the entry is a directory or not, using a binary search.
+    ///
+    /// Note that it's impossible to binary search by name alone as the sort order is special.
+    pub fn bisect_entry(&self, name: &BStr, is_dir: bool) -> Option<EntryRef<'a>> {
+        static NULL_HASH: gix_hash::ObjectId = gix_hash::Kind::shortest().null();
+
+        let search = EntryRef {
+            mode: if is_dir {
+                tree::EntryMode::Tree
+            } else {
+                tree::EntryMode::Blob
+            },
+            filename: name,
+            oid: &NULL_HASH,
+        };
+        self.entries
+            .binary_search_by(|e| e.cmp(&search))
+            .ok()
+            .map(|idx| self.entries[idx])
+    }
+
     /// Create an instance of the empty tree.
     ///
     /// It's particularly useful as static part of a program.

gix-object/tests/tree/mod.rs

@@ -143,6 +143,28 @@ mod entries {
 
         tree.entries.sort();
         assert_eq!(tree.entries, expected);
+        let mut failures_when_searching_by_name = 0;
+        for entry in expected {
+            assert!(
+                tree.entries.binary_search_by(|e| e.cmp(&entry)).is_ok(),
+                "ordering works with binary search"
+            );
+            failures_when_searching_by_name += usize::from(
+                tree.entries
+                    .binary_search_by(|e| e.filename.cmp(entry.filename))
+                    .is_err(),
+            );
+            assert_eq!(
+                tree.bisect_entry(entry.filename, entry.mode.is_tree())
+                    .expect("entry is present"),
+                entry
+            )
+        }
+
+        assert_eq!(
+            failures_when_searching_by_name, 2,
+            "it's not possible to do a binary search by name alone"
+        );
 
         let mut tree: Tree = tree.into();
         let expected = tree.entries.clone();