feat!: tree::depthfirst() traversal

A depth-first traversal yields the `.git/index` order.

It's a breaking change as the `Visitor` trait gets another way
to pop a tracked path, suitable for the stack used for depth first.

Author: Byron

Cargo.lock

@@ -2,7 +2,8 @@ use std::collections::VecDeque;
 
 use gix_hash::ObjectId;
 
-/// The error is part of the item returned by the [`traverse()`][impl_::traverse()] function.
+/// The error is part of the item returned by the [`breadthfirst()`](crate::tree::breadthfirst())  and
+///[`depthfirst()`](crate::tree::depthfirst()) functions.
 #[derive(Debug, thiserror::Error)]
 #[allow(missing_docs)]
 pub enum Error {
@@ -28,7 +29,7 @@ impl State {
     }
 }
 
-pub(crate) mod impl_ {
+pub(super) mod function {
     use std::borrow::BorrowMut;
 
     use gix_object::{FindExt, TreeRefIter};
@@ -38,6 +39,8 @@ pub(crate) mod impl_ {
 
     /// Start a breadth-first iteration over the `root` trees entries.
     ///
+    /// Note that non-trees will be listed first, so the natural order of entries within a tree is lost.
+    ///
     /// * `root`
     ///   * the tree to iterate in a nested fashion.
     /// * `state` - all state used for the iteration. If multiple iterations are performed, allocations can be minimized by reusing
@@ -46,9 +49,9 @@ pub(crate) mod impl_ {
     ///    an iterator over entries if the object is present and is a tree. Caching should be implemented within this function
     ///    as needed. The return value is `Option<TreeIter>` which degenerates all error information. Not finding a commit should also
     ///    be considered an errors as all objects in the tree DAG should be present in the database. Hence [`Error::Find`] should
-    ///    be escalated into a more specific error if its encountered by the caller.
+    ///    be escalated into a more specific error if it's encountered by the caller.
     /// * `delegate` - A way to observe entries and control the iteration while allowing the optimizer to let you pay only for what you use.
-    pub fn traverse<StateMut, Find, V>(
+    pub fn breadthfirst<StateMut, Find, V>(
         root: TreeRefIter<'_>,
         mut state: StateMut,
         objects: Find,

gix-traverse/src/tree/breadthfirst.rs

@@ -0,0 +1,111 @@
+pub use super::breadthfirst::Error;
+
+/// The state used and potentially shared by multiple tree traversals, reusing memory.
+#[derive(Default, Clone)]
+pub struct State {
+    freelist: Vec<Vec<u8>>,
+}
+
+impl State {
+    /// Pop one empty buffer from the free-list.
+    pub fn pop_buf(&mut self) -> Vec<u8> {
+        match self.freelist.pop() {
+            None => Vec::new(),
+            Some(mut buf) => {
+                buf.clear();
+                buf
+            }
+        }
+    }
+
+    /// Make `buf` available for re-use with [`Self::pop_buf()`].
+    pub fn push_buf(&mut self, buf: Vec<u8>) {
+        self.freelist.push(buf);
+    }
+}
+
+pub(super) mod function {
+    use super::{Error, State};
+    use crate::tree::visit::Action;
+    use crate::tree::Visit;
+    use gix_hash::ObjectId;
+    use gix_object::{FindExt, TreeRefIter};
+    use std::borrow::BorrowMut;
+
+    /// A depth-first traversal of the `root` tree, that preserves the natural order of a tree while immediately descending
+    /// into sub-trees.
+    ///
+    /// `state` can be passed to re-use memory during multiple invocations.
+    pub fn depthfirst<StateMut, Find, V>(
+        root: ObjectId,
+        mut state: StateMut,
+        objects: Find,
+        delegate: &mut V,
+    ) -> Result<(), Error>
+    where
+        Find: gix_object::Find,
+        StateMut: BorrowMut<State>,
+        V: Visit,
+    {
+        enum Machine {
+            GetTree(ObjectId),
+            Iterate {
+                tree_buf: Vec<u8>,
+                byte_offset_to_next_entry: usize,
+            },
+        }
+
+        let state = state.borrow_mut();
+        let mut stack = vec![Machine::GetTree(root)];
+        'outer: while let Some(item) = stack.pop() {
+            match item {
+                Machine::GetTree(id) => {
+                    let mut buf = state.pop_buf();
+                    objects.find_tree_iter(&id, &mut buf)?;
+                    stack.push(Machine::Iterate {
+                        tree_buf: buf,
+                        byte_offset_to_next_entry: 0,
+                    });
+                }
+                Machine::Iterate {
+                    tree_buf: buf,
+                    byte_offset_to_next_entry,
+                } => {
+                    let mut iter = TreeRefIter::from_bytes(&buf[byte_offset_to_next_entry..]);
+                    delegate.pop_back_tracked_path_and_set_current();
+                    while let Some(entry) = iter.next() {
+                        let entry = entry?;
+                        if entry.mode.is_tree() {
+                            delegate.push_path_component(entry.filename);
+                            let res = delegate.visit_tree(&entry);
+                            delegate.pop_path_component();
+                            match res {
+                                Action::Continue => {
+                                    delegate.push_back_tracked_path_component(entry.filename);
+                                }
+                                Action::Cancel => break 'outer,
+                                Action::Skip => continue,
+                            }
+
+                            let next_step = Machine::GetTree(entry.oid.to_owned());
+                            stack.push(Machine::Iterate {
+                                byte_offset_to_next_entry: iter.offset_to_next_entry(&buf),
+                                tree_buf: buf,
+                            });
+                            stack.push(next_step);
+                            continue 'outer;
+                        } else {
+                            delegate.push_path_component(entry.filename);
+                            if let Action::Cancel = delegate.visit_nontree(&entry) {
+                                break 'outer;
+                            }
+                            delegate.pop_path_component();
+                        }
+                    }
+                    state.push_buf(buf);
+                }
+            }
+        }
+        Ok(())
+    }
+}

gix-traverse/src/tree/depthfirst.rs

@@ -5,7 +5,15 @@ use gix_object::bstr::{BStr, BString};
 /// A trait to allow responding to a traversal designed to observe all entries in a tree, recursively while keeping track of
 /// paths if desired.
 pub trait Visit {
-    /// Sets the full path path in front of the queue so future calls to push and pop components affect it instead.
+    /// Sets the full path in the back of the queue so future calls to push and pop components affect it instead.
+    ///
+    /// Note that the first call is made without an accompanying call to [`Self::push_back_tracked_path_component()`]
+    ///
+    /// This is used by the depth-first traversal of trees.
+    fn pop_back_tracked_path_and_set_current(&mut self);
+    /// Sets the full path in front of the queue so future calls to push and pop components affect it instead.
+    ///
+    /// This is used by the breadth-first traversal of trees.
     fn pop_front_tracked_path_and_set_current(&mut self);
     /// Append a `component` to the end of a path, which may be empty.
     fn push_back_tracked_path_component(&mut self, component: &BStr);
@@ -66,4 +74,8 @@ pub mod recorder;
 
 ///
 pub mod breadthfirst;
-pub use breadthfirst::impl_::traverse as breadthfirst;
+pub use breadthfirst::function::breadthfirst;
+
+///
+pub mod depthfirst;
+pub use depthfirst::function::depthfirst;

gix-traverse/src/tree/mod.rs

@@ -92,6 +92,12 @@ impl Recorder {
 }
 
 impl Visit for Recorder {
+    fn pop_back_tracked_path_and_set_current(&mut self) {
+        if let Some(Location::Path) = self.location {
+            self.path = self.path_deque.pop_back().unwrap_or_default();
+        }
+    }
+
     fn pop_front_tracked_path_and_set_current(&mut self) {
         if let Some(Location::Path) = self.location {
             self.path = self

gix-traverse/src/tree/recorder.rs

@@ -11,10 +11,11 @@ edition = "2021"
 rust-version = "1.65"
 
 [[test]]
-name = "test"
-path = "traverse.rs"
+name = "traverse"
+path = "traverse/main.rs"
 
 [dev-dependencies]
+insta = "1.40.0"
 gix-traverse = { path = ".." }
 gix-testtools = { path = "../../tests/tools" }
 gix-odb = { path = "../../gix-odb" }