Add tree::Editor::cursor() to allow speedier creation of sub-trees.

Author: Byron

gix-object/src/tree/editor.rs

@@ -1,45 +1,29 @@
-use crate::tree::EntryKind;
+use crate::tree::{Editor, EntryKind};
 use crate::{tree, Tree};
 use bstr::{BStr, BString, ByteSlice, ByteVec};
 use gix_hash::ObjectId;
 use gix_hashtable::hash_map::Entry;
 use std::cmp::Ordering;
 
-/// The state needed to apply edits instantly to in-memory trees.
-///
-/// It's made so that each tree is looked at in the object database at most once, and held in memory for
-/// all edits until everything is flushed to write all changed trees.
-///
-/// The editor is optimized to edit existing trees, but can deal with building entirely new trees as well
-/// with some penalties.
-///
-/// ### Note
-///
-/// For reasons of efficiency, internally a SHA1 based hashmap is used to avoid having to store full paths
-/// to each edited tree. The chance of collision is low, but could be engineered to overwrite or write into
-/// an unintended tree.
-#[doc(alias = "TreeUpdateBuilder", alias = "git2")]
-pub struct Editor<'a> {
-    /// A way to lookup trees.
-    find: &'a dyn crate::FindExt,
-    /// All trees we currently hold in memory. Each of these may change while adding and removing entries.
-    /// null-object-ids mark tree-entries whose value we don't know yet, they are placeholders that will be
-    /// dropped when writing at the latest.
-    trees: gix_hashtable::HashMap<ObjectId, Tree>,
-    /// A buffer to build up paths when finding the tree to edit.
-    path_buf: BString,
-    /// Our buffer for storing tree-data in, right before decoding it.
-    tree_buf: Vec<u8>,
+/// A way to constrain all [tree-edits](Editor) to a given subtree.
+pub struct Cursor<'a, 'find> {
+    /// The underlying editor
+    parent: &'a mut Editor<'find>,
+    /// Our own location, used as prefix for all operations.
+    /// Note that it's assumed to always contain a tree.
+    prefix: BString,
 }
 
 /// Lifecycle
 impl<'a> Editor<'a> {
     /// Create a new editor that uses `root` as base for all edits. Use `find` to lookup existing
     /// trees when edits are made. Each tree will only be looked-up once and then edited in place from
     /// that point on.
-    pub fn new(root: Tree, find: &'a dyn crate::FindExt) -> Self {
+    /// `object_hash` denotes the kind of hash to create.
+    pub fn new(root: Tree, find: &'a dyn crate::FindExt, object_hash: gix_hash::Kind) -> Self {
         Editor {
             find,
+            object_hash,
             trees: gix_hashtable::HashMap::from_iter(Some((empty_path_hash(), root))),
             path_buf: Vec::with_capacity(256).into(),
             tree_buf: Vec::with_capacity(512),
@@ -60,15 +44,63 @@ impl<'a> Editor<'a> {
     /// Future calls to [`upsert`](Self::upsert) or similar will keep working on the last seen state of the
     /// just-written root-tree.
     /// If this is not desired, use [set_root()](Self::set_root()).
-    pub fn write<E>(&mut self, mut out: impl FnMut(&Tree) -> Result<ObjectId, E>) -> Result<ObjectId, E> {
+    pub fn write<E>(&mut self, out: impl FnMut(&Tree) -> Result<ObjectId, E>) -> Result<ObjectId, E> {
+        self.path_buf.clear();
+        self.write_at_pathbuf(out, WriteMode::Normal)
+    }
+
+    /// Remove the entry at `rela_path`, loading all trees on the path accordingly.
+    /// It's no error if the entry doesn't exist, or if `rela_path` doesn't lead to an existing entry at all.
+    pub fn remove<I, C>(&mut self, rela_path: I) -> Result<&mut Self, crate::find::existing_object::Error>
+    where
+        I: IntoIterator<Item = C>,
+        C: AsRef<BStr>,
+    {
+        self.path_buf.clear();
+        self.upsert_or_remove_at_pathbuf(rela_path, None)
+    }
+
+    /// Insert a new entry of `kind` with `id` at `rela_path`, an iterator over each path component in the tree,
+    /// like `a/b/c`. Names are matched case-sensitively.
+    ///
+    /// Existing leaf-entries will be overwritten unconditionally, and it is assumed that `id` is available in the object database
+    /// or will be made available at a later point to assure the integrity of the produced tree.
+    ///
+    /// Intermediate trees will be created if they don't exist in the object database, otherwise they will be loaded and entries
+    /// will be inserted into them instead.
+    ///
+    /// Note that `id` can be [null](ObjectId::null()) to create a placeholder. These will not be written, and paths leading
+    /// through them will not be considered a problem.
+    ///
+    /// `id` can also be an empty tree, along with [the respective `kind`](EntryKind::Tree), even though that's normally not allowed
+    /// in Git trees.
+    pub fn upsert<I, C>(
+        &mut self,
+        rela_path: I,
+        kind: EntryKind,
+        id: ObjectId,
+    ) -> Result<&mut Self, crate::find::existing_object::Error>
+    where
+        I: IntoIterator<Item = C>,
+        C: AsRef<BStr>,
+    {
+        self.path_buf.clear();
+        self.upsert_or_remove_at_pathbuf(rela_path, Some((kind, id, UpsertMode::Normal)))
+    }
+
+    fn write_at_pathbuf<E>(
+        &mut self,
+        mut out: impl FnMut(&Tree) -> Result<ObjectId, E>,
+        mode: WriteMode,
+    ) -> Result<ObjectId, E> {
         assert_ne!(self.trees.len(), 0, "there is at least the root tree");
 
         // back is for children, front is for parents.
         let mut parents = vec![(
             None::<usize>,
-            BString::default(),
+            self.path_buf.clone(),
             self.trees
-                .remove(&empty_path_hash())
+                .remove(&path_hash(&self.path_buf))
                 .expect("root tree is always present"),
         )];
         let mut children = Vec::new();
@@ -102,12 +134,17 @@ impl<'a> Editor<'a> {
                     }
                 } else if parents.is_empty() {
                     debug_assert!(children.is_empty(), "we consume children before parents");
-                    debug_assert!(rela_path.is_empty(), "this should always be the root tree");
+                    debug_assert_eq!(rela_path, self.path_buf, "this should always be the root tree");
 
                     // There may be left-over trees if they are replaced with blobs for example.
                     let root_tree_id = out(&tree)?;
-                    self.trees.clear();
-                    self.trees.insert(empty_path_hash(), tree);
+                    match mode {
+                        WriteMode::Normal => {
+                            self.trees.clear();
+                        }
+                        WriteMode::FromCursor => {}
+                    }
+                    self.trees.insert(path_hash(&self.path_buf), tree);
                     return Ok(root_tree_id);
                 } else if !tree.entries.is_empty() {
                     out(&tree)?;
@@ -120,56 +157,21 @@ impl<'a> Editor<'a> {
         unreachable!("we exit as soon as everything is consumed")
     }
 
-    /// Remove the entry at `rela_path`, loading all trees on the path accordingly.
-    /// It's no error if the entry doesn't exist, or if `rela_path` doesn't lead to an existing entry at all.
-    pub fn remove<I, C>(&mut self, rela_path: I) -> Result<&mut Self, crate::find::existing_object::Error>
-    where
-        I: IntoIterator<Item = C>,
-        C: AsRef<BStr>,
-    {
-        self.upsert_or_remove(rela_path, None)
-    }
-
-    /// Insert a new entry of `kind` with `id` at `rela_path`, an iterator over each path component in the tree,
-    /// like `a/b/c`. Names are matched case-sensitively.
-    ///
-    /// Existing leaf-entries will be overwritten unconditionally, and it is assumed that `id` is available in the object database
-    /// or will be made available at a later point to assure the integrity of the produced tree.
-    ///
-    /// Intermediate trees will be created if they don't exist in the object database, otherwise they will be loaded and entries
-    /// will be inserted into them instead.
-    ///
-    /// Note that `id` can be [null](ObjectId::null()) to create a placeholder. These will not be written, and paths leading
-    /// through them will not be considered a problem.
-    ///
-    /// `id` can also be an empty tree, along with [the respective `kind`](EntryKind::Tree), even though that's normally not allowed
-    /// in Git trees.
-    pub fn upsert<I, C>(
+    fn upsert_or_remove_at_pathbuf<I, C>(
         &mut self,
         rela_path: I,
-        kind: EntryKind,
-        id: ObjectId,
+        kind_and_id: Option<(EntryKind, ObjectId, UpsertMode)>,
     ) -> Result<&mut Self, crate::find::existing_object::Error>
     where
         I: IntoIterator<Item = C>,
         C: AsRef<BStr>,
     {
-        self.upsert_or_remove(rela_path, Some((kind, id)))
-    }
-
-    fn upsert_or_remove<I, C>(
-        &mut self,
-        rela_path: I,
-        kind_and_id: Option<(EntryKind, ObjectId)>,
-    ) -> Result<&mut Self, crate::find::existing_object::Error>
-    where
-        I: IntoIterator<Item = C>,
-        C: AsRef<BStr>,
-    {
-        let mut cursor = self.trees.get_mut(&empty_path_hash()).expect("root is always present");
-        self.path_buf.clear();
+        let mut cursor = self
+            .trees
+            .get_mut(&path_hash(&self.path_buf))
+            .expect("root is always present");
         let mut rela_path = rela_path.into_iter().peekable();
-        let new_kind_is_tree = kind_and_id.map_or(false, |(kind, _)| kind == EntryKind::Tree);
+        let new_kind_is_tree = kind_and_id.map_or(false, |(kind, _, _)| kind == EntryKind::Tree);
         while let Some(name) = rela_path.next() {
             let name = name.as_ref();
             let is_last = rela_path.peek().is_none();
@@ -206,7 +208,7 @@ impl<'a> Editor<'a> {
                                 }
                             }
                         }
-                        Some((kind, id)) => {
+                        Some((kind, id, _mode)) => {
                             let entry = &mut cursor.entries[idx];
                             if is_last {
                                 // unconditionally overwrite what's there.
@@ -229,7 +231,7 @@ impl<'a> Editor<'a> {
                 }
                 Err(insertion_idx) => match kind_and_id {
                     None => break,
-                    Some((kind, id)) => {
+                    Some((kind, id, _mode)) => {
                         cursor.entries.insert(
                             insertion_idx,
                             tree::Entry {
@@ -238,17 +240,14 @@ impl<'a> Editor<'a> {
                                 oid: if is_last { id } else { id.kind().null() },
                             },
                         );
-                        if is_last {
-                            break;
-                        }
                         None
                     }
                 },
             };
             if needs_sorting {
                 cursor.entries.sort();
             }
-            if is_last {
+            if is_last && kind_and_id.map_or(false, |(_, _, mode)| mode == UpsertMode::Normal) {
                 break;
             }
             push_path_component(&mut self.path_buf, name);
@@ -279,6 +278,96 @@ impl<'a> Editor<'a> {
     }
 }
 
+mod cursor {
+    use crate::tree::editor::{Cursor, UpsertMode, WriteMode};
+    use crate::tree::{Editor, EntryKind};
+    use crate::Tree;
+    use bstr::{BStr, BString};
+    use gix_hash::ObjectId;
+
+    /// Cursor handling
+    impl<'a> Editor<'a> {
+        /// Turn ourselves as a cursor, which points to the same tree as the editor.
+        ///
+        /// This is useful if a method takes a [`Cursor`], not an [`Editor`].
+        pub fn to_cursor(&mut self) -> Cursor<'_, 'a> {
+            Cursor {
+                parent: self,
+                prefix: BString::default(),
+            }
+        }
+
+        /// Create a cursor at the given `rela_path`, which must be a tree or is turned into a tree as its own edit.
+        ///
+        /// The returned cursor will then allow applying edits to the tree at `rela_path` as root.
+        /// If `rela_path` is a single empty string, it is equivalent to using the current instance itself.
+        pub fn cursor_at<I, C>(&mut self, rela_path: I) -> Result<Cursor<'_, 'a>, crate::find::existing_object::Error>
+        where
+            I: IntoIterator<Item = C>,
+            C: AsRef<BStr>,
+        {
+            self.path_buf.clear();
+            self.upsert_or_remove_at_pathbuf(
+                rela_path,
+                Some((EntryKind::Tree, self.object_hash.null(), UpsertMode::AssureTreeOnly)),
+            )?;
+            Ok(Cursor {
+                prefix: self.path_buf.clone(), /* set during the upsert call */
+                parent: self,
+            })
+        }
+    }
+
+    impl<'a, 'find> Cursor<'a, 'find> {
+        /// Like [`Editor::upsert()`], but with the constraint of only editing in this cursor's tree.
+        pub fn upsert<I, C>(
+            &mut self,
+            rela_path: I,
+            kind: EntryKind,
+            id: ObjectId,
+        ) -> Result<&mut Self, crate::find::existing_object::Error>
+        where
+            I: IntoIterator<Item = C>,
+            C: AsRef<BStr>,
+        {
+            self.parent.path_buf.clone_from(&self.prefix);
+            self.parent
+                .upsert_or_remove_at_pathbuf(rela_path, Some((kind, id, UpsertMode::Normal)))?;
+            Ok(self)
+        }
+
+        /// Like [`Editor::remove()`], but with the constraint of only editing in this cursor's tree.
+        pub fn remove<I, C>(&mut self, rela_path: I) -> Result<&mut Self, crate::find::existing_object::Error>
+        where
+            I: IntoIterator<Item = C>,
+            C: AsRef<BStr>,
+        {
+            self.parent.path_buf.clone_from(&self.prefix);
+            self.parent.upsert_or_remove_at_pathbuf(rela_path, None)?;
+            Ok(self)
+        }
+
+        /// Like [`Editor::write()`], but will write only the subtree of the cursor.
+        pub fn write<E>(&mut self, out: impl FnMut(&Tree) -> Result<ObjectId, E>) -> Result<ObjectId, E> {
+            self.parent.path_buf.clone_from(&self.prefix);
+            self.parent.write_at_pathbuf(out, WriteMode::FromCursor)
+        }
+    }
+}
+
+#[derive(Copy, Clone, Eq, PartialEq)]
+enum UpsertMode {
+    Normal,
+    /// Only make sure there is a tree at the given location (requires kind tree and null-id)
+    AssureTreeOnly,
+}
+
+enum WriteMode {
+    Normal,
+    /// Perform less cleanup to assure parent-editor still stays intact
+    FromCursor,
+}
+
 fn cmp_entry_with_name(a: &tree::Entry, filename: &BStr, is_tree: bool) -> Ordering {
     let common = a.filename.len().min(filename.len());
     a.filename[..common].cmp(&filename[..common]).then_with(|| {