gix_object::tree

Struct Editor

source
pub struct Editor<'a> { /* private fields */ }
Expand description

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.

Implementations§

source§

impl<'a> Editor<'a>

Cursor handling

source

pub fn to_cursor(&mut self) -> Cursor<'_, '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.

source

pub fn cursor_at<I, C>(&mut self, rela_path: I) -> Result<Cursor<'_, 'a>, Error>
where I: IntoIterator<Item = C>, C: AsRef<BStr>,

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.

source§

impl<'a> Editor<'a>

Lifecycle

source

pub fn new(root: Tree, find: &'a dyn FindExt, object_hash: Kind) -> Self

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. object_hash denotes the kind of hash to create.

source§

impl Editor<'_>

Operations

source

pub fn write<E>( &mut self, out: impl FnMut(&Tree) -> Result<ObjectId, E>, ) -> Result<ObjectId, E>

Write the entire in-memory state of all changed trees (and only changed trees) to out. Note that the returned object id can be the empty tree if everything was removed or if nothing was added to the tree.

The last call to out will be the changed root tree, whose object-id will also be returned. out is free to do any kind of additional validation, like to assure that all entries in the tree exist. We don’t assure that as there is no validation that inserted entries are valid object ids.

Future calls to 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().

§Validation

Note that no additional validation is performed to assure correctness of entry-names. It is absolutely and intentionally possible to write out invalid trees with this method. Higher layers are expected to perform detailed validation.

source

pub fn remove<I, C>(&mut self, rela_path: I) -> Result<&mut Self, Error>
where I: IntoIterator<Item = C>, C: AsRef<BStr>,

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.

Note that trying to remove a path with an empty component is also forbidden.

source

pub fn upsert<I, C>( &mut self, rela_path: I, kind: EntryKind, id: ObjectId, ) -> Result<&mut Self, Error>
where I: IntoIterator<Item = C>, C: AsRef<BStr>,

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 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, even though that’s normally not allowed in Git trees.

source

pub fn set_root(&mut self, root: Tree) -> &mut Self

Set the root tree of the modification to root, assuring it has a well-known state.

Note that this erases all previous edits.

This is useful if the same editor is re-used for various trees.

Trait Implementations§

source§

impl<'a> Clone for Editor<'a>

source§

fn clone(&self) -> Editor<'a>

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for Editor<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a> Freeze for Editor<'a>

§

impl<'a> !RefUnwindSafe for Editor<'a>

§

impl<'a> !Send for Editor<'a>

§

impl<'a> !Sync for Editor<'a>

§

impl<'a> Unpin for Editor<'a>

§

impl<'a> !UnwindSafe for Editor<'a>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.