feat: add TreeRefIter::offset_to_next_entry().

Add a function to help resume the iterator without holding onto the data directly.

Author: Byron

gix-object/src/tree/ref_iter.rs

@@ -1,8 +1,7 @@
+use crate::{tree, tree::EntryRef, TreeRef, TreeRefIter};
 use bstr::BStr;
 use winnow::{error::ParserError, prelude::*};
 
-use crate::{tree, tree::EntryRef, TreeRef, TreeRefIter};
-
 impl<'a> TreeRefIter<'a> {
     /// Instantiate an iterator from the given tree data.
     pub fn from_bytes(data: &'a [u8]) -> TreeRefIter<'a> {
@@ -126,6 +125,21 @@ impl<'a> TreeRefIter<'a> {
     pub fn entries(self) -> Result<Vec<EntryRef<'a>>, crate::decode::Error> {
         self.collect()
     }
+
+    /// Return the offset in bytes that our data advanced from `buf`, the original buffer
+    /// to the beginning of the data of the tree.
+    ///
+    /// Then the tree-iteration can be resumed at the entry that would otherwise be returned next.
+    pub fn offset_to_next_entry(&self, buf: &[u8]) -> usize {
+        let before = (*buf).as_ptr();
+        let after = (*self.data).as_ptr();
+
+        debug_assert!(
+            before <= after,
+            "`TreeRefIter::offset_to_next_entry(): {after:?} <= {before:?}) violated"
+        );
+        (after as usize - before as usize) / std::mem::size_of::<u8>()
+    }
 }
 
 impl<'a> Iterator for TreeRefIter<'a> {

gix-object/tests/object/tree/iter.rs

@@ -23,6 +23,24 @@ fn error_handling() {
     );
 }
 
+#[test]
+fn offset_to_next_entry() {
+    let buf = fixture_name("tree", "everything.tree");
+    let mut iter = TreeRefIter::from_bytes(&buf);
+    assert_eq!(iter.offset_to_next_entry(&buf), 0, "first entry is always at 0");
+    iter.next();
+
+    let actual = iter.offset_to_next_entry(&buf);
+    assert_eq!(actual, 31, "now the offset increases");
+    assert_eq!(
+        TreeRefIter::from_bytes(&buf[actual..])
+            .next()
+            .map(|e| e.unwrap().filename),
+        iter.next().map(|e| e.unwrap().filename),
+        "One can now start the iteration at a certain entry"
+    );
+}
+
 #[test]
 fn everything() -> crate::Result {
     assert_eq!(