Struct HistoryTree 

pub struct HistoryTree<E, Cmd = ()> { /* private fields */ }

A history tree for non-linear undo-redo action.

Implementations

impl<Cmd: Default, E: Default> HistoryTree<E, Cmd>

pub fn new() -> Self

Create a new history tree.

Examples found in repository

examples/history_tree.rs (line 9)

fn main() {
    let mut history_tree: HistoryTree<VecDelta<&str>> = HistoryTree::new();
    let mut state = Recorder::new(vec!["root"]);

    // Right below the root we push a "fork" node, from which we will fork two
    // branches.
    state.push("fork");
    history_tree.commit(&mut state);

    let fork = history_tree.curr_node();

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);

    // Add first node of left branch.
    state.push("left_branch_1");
    history_tree.commit(&mut state);

    let left_branch_1 = history_tree.curr_node();

    // Add second node of left branch.
    state.push("left_branch_2");
    history_tree.commit(&mut state);

    let left_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the left branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Let's now undo the whole left branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);

    // Add first node of right branch.
    state.push("right_branch_1");
    history_tree.commit(&mut state);

    let right_branch_1 = history_tree.curr_node();

    // Add second node of right branch.
    state.push("right_branch_2");
    history_tree.commit(&mut state);

    let right_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the right branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    let root_children = history_tree
        .node(history_tree.node(fork).parent().unwrap())
        .children();
    assert_eq!(root_children, &[fork]);

    assert_eq!(
        history_tree.node(fork).children(),
        &[left_branch_1, right_branch_1]
    );
    assert_eq!(
        history_tree.node(left_branch_1).children(),
        &[left_branch_2]
    );
    assert_eq!(
        history_tree.node(right_branch_1).children(),
        &[right_branch_2]
    );

    // Check out left branch from the apex of the right branch.
    history_tree.checkout(&mut state, left_branch_2);

    assert_eq!(history_tree.curr_node(), left_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Check out the right branch from the apex of the left branch.
    history_tree.checkout(&mut state, right_branch_2);

    assert_eq!(history_tree.curr_node(), right_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    // Let's now undo the whole right branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);
}

impl<Cmd, E> HistoryTree<E, Cmd>

pub fn curr_node(&self) -> HistoryTreeNodeId

Returns the id of the current node.

Examples found in repository

examples/history_tree.rs (line 17)

fn main() {
    let mut history_tree: HistoryTree<VecDelta<&str>> = HistoryTree::new();
    let mut state = Recorder::new(vec!["root"]);

    // Right below the root we push a "fork" node, from which we will fork two
    // branches.
    state.push("fork");
    history_tree.commit(&mut state);

    let fork = history_tree.curr_node();

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);

    // Add first node of left branch.
    state.push("left_branch_1");
    history_tree.commit(&mut state);

    let left_branch_1 = history_tree.curr_node();

    // Add second node of left branch.
    state.push("left_branch_2");
    history_tree.commit(&mut state);

    let left_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the left branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Let's now undo the whole left branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);

    // Add first node of right branch.
    state.push("right_branch_1");
    history_tree.commit(&mut state);

    let right_branch_1 = history_tree.curr_node();

    // Add second node of right branch.
    state.push("right_branch_2");
    history_tree.commit(&mut state);

    let right_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the right branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    let root_children = history_tree
        .node(history_tree.node(fork).parent().unwrap())
        .children();
    assert_eq!(root_children, &[fork]);

    assert_eq!(
        history_tree.node(fork).children(),
        &[left_branch_1, right_branch_1]
    );
    assert_eq!(
        history_tree.node(left_branch_1).children(),
        &[left_branch_2]
    );
    assert_eq!(
        history_tree.node(right_branch_1).children(),
        &[right_branch_2]
    );

    // Check out left branch from the apex of the right branch.
    history_tree.checkout(&mut state, left_branch_2);

    assert_eq!(history_tree.curr_node(), left_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Check out the right branch from the apex of the left branch.
    history_tree.checkout(&mut state, right_branch_2);

    assert_eq!(history_tree.curr_node(), right_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    // Let's now undo the whole right branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);
}

pub fn node(&self, id: HistoryTreeNodeId) -> &HistoryTreeNode<E, Cmd>

Returns an immutable reference to the node with the given id.

Examples found in repository

examples/history_tree.rs (line 65)

fn main() {
    let mut history_tree: HistoryTree<VecDelta<&str>> = HistoryTree::new();
    let mut state = Recorder::new(vec!["root"]);

    // Right below the root we push a "fork" node, from which we will fork two
    // branches.
    state.push("fork");
    history_tree.commit(&mut state);

    let fork = history_tree.curr_node();

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);

    // Add first node of left branch.
    state.push("left_branch_1");
    history_tree.commit(&mut state);

    let left_branch_1 = history_tree.curr_node();

    // Add second node of left branch.
    state.push("left_branch_2");
    history_tree.commit(&mut state);

    let left_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the left branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Let's now undo the whole left branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);

    // Add first node of right branch.
    state.push("right_branch_1");
    history_tree.commit(&mut state);

    let right_branch_1 = history_tree.curr_node();

    // Add second node of right branch.
    state.push("right_branch_2");
    history_tree.commit(&mut state);

    let right_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the right branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    let root_children = history_tree
        .node(history_tree.node(fork).parent().unwrap())
        .children();
    assert_eq!(root_children, &[fork]);

    assert_eq!(
        history_tree.node(fork).children(),
        &[left_branch_1, right_branch_1]
    );
    assert_eq!(
        history_tree.node(left_branch_1).children(),
        &[left_branch_2]
    );
    assert_eq!(
        history_tree.node(right_branch_1).children(),
        &[right_branch_2]
    );

    // Check out left branch from the apex of the right branch.
    history_tree.checkout(&mut state, left_branch_2);

    assert_eq!(history_tree.curr_node(), left_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Check out the right branch from the apex of the left branch.
    history_tree.checkout(&mut state, right_branch_2);

    assert_eq!(history_tree.curr_node(), right_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    // Let's now undo the whole right branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);
}

pub fn parent(&self, id: HistoryTreeNodeId) -> Option<HistoryTreeNodeId>

Returns parent node id of the node with the given id. None for the root.

pub fn cmd(&self, id: HistoryTreeNodeId) -> &Cmd

Returns an immutable reference to the command metadata at the given node.

pub fn cmd_mut(&mut self, id: HistoryTreeNodeId) -> &mut Cmd

Returns a mutable reference to the command metadata at the given node.

impl<Cmd: Default, E> HistoryTree<E, Cmd>

pub fn commit<T>(&mut self, target: &mut T)

where E: ExtractEdit<T>,

Flush the target container and insert its changes as an edit into a new tree leaf under the current node.

Examples found in repository

examples/history_tree.rs (line 15)

fn main() {
    let mut history_tree: HistoryTree<VecDelta<&str>> = HistoryTree::new();
    let mut state = Recorder::new(vec!["root"]);

    // Right below the root we push a "fork" node, from which we will fork two
    // branches.
    state.push("fork");
    history_tree.commit(&mut state);

    let fork = history_tree.curr_node();

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);

    // Add first node of left branch.
    state.push("left_branch_1");
    history_tree.commit(&mut state);

    let left_branch_1 = history_tree.curr_node();

    // Add second node of left branch.
    state.push("left_branch_2");
    history_tree.commit(&mut state);

    let left_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the left branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Let's now undo the whole left branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);

    // Add first node of right branch.
    state.push("right_branch_1");
    history_tree.commit(&mut state);

    let right_branch_1 = history_tree.curr_node();

    // Add second node of right branch.
    state.push("right_branch_2");
    history_tree.commit(&mut state);

    let right_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the right branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    let root_children = history_tree
        .node(history_tree.node(fork).parent().unwrap())
        .children();
    assert_eq!(root_children, &[fork]);

    assert_eq!(
        history_tree.node(fork).children(),
        &[left_branch_1, right_branch_1]
    );
    assert_eq!(
        history_tree.node(left_branch_1).children(),
        &[left_branch_2]
    );
    assert_eq!(
        history_tree.node(right_branch_1).children(),
        &[right_branch_2]
    );

    // Check out left branch from the apex of the right branch.
    history_tree.checkout(&mut state, left_branch_2);

    assert_eq!(history_tree.curr_node(), left_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Check out the right branch from the apex of the left branch.
    history_tree.checkout(&mut state, right_branch_2);

    assert_eq!(history_tree.curr_node(), right_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    // Let's now undo the whole right branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);
}

impl<Cmd, E> HistoryTree<E, Cmd>

pub fn cmd_commit<T>(&mut self, cmd: Cmd, target: &mut T)

where E: ExtractEdit<T>,

Flush the target container and insert its changes into a new tree leaf under the current node as an edit along with additional metadata (“cmd”).

impl<Cmd: Clone, E: Clone> HistoryTree<E, Cmd>

pub fn undo<T>(&mut self, target: &mut T) -> Option<Cmd>

where E: RevertEdit<T>,

Undo the edit at the current tree node, moving one step upwards to the node’s parent.

This does not cause any changes to the tree topology, only the target container and current node are modified.

Examples found in repository

examples/history_tree.rs (line 40)

fn main() {
    let mut history_tree: HistoryTree<VecDelta<&str>> = HistoryTree::new();
    let mut state = Recorder::new(vec!["root"]);

    // Right below the root we push a "fork" node, from which we will fork two
    // branches.
    state.push("fork");
    history_tree.commit(&mut state);

    let fork = history_tree.curr_node();

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);

    // Add first node of left branch.
    state.push("left_branch_1");
    history_tree.commit(&mut state);

    let left_branch_1 = history_tree.curr_node();

    // Add second node of left branch.
    state.push("left_branch_2");
    history_tree.commit(&mut state);

    let left_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the left branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Let's now undo the whole left branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);

    // Add first node of right branch.
    state.push("right_branch_1");
    history_tree.commit(&mut state);

    let right_branch_1 = history_tree.curr_node();

    // Add second node of right branch.
    state.push("right_branch_2");
    history_tree.commit(&mut state);

    let right_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the right branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    let root_children = history_tree
        .node(history_tree.node(fork).parent().unwrap())
        .children();
    assert_eq!(root_children, &[fork]);

    assert_eq!(
        history_tree.node(fork).children(),
        &[left_branch_1, right_branch_1]
    );
    assert_eq!(
        history_tree.node(left_branch_1).children(),
        &[left_branch_2]
    );
    assert_eq!(
        history_tree.node(right_branch_1).children(),
        &[right_branch_2]
    );

    // Check out left branch from the apex of the right branch.
    history_tree.checkout(&mut state, left_branch_2);

    assert_eq!(history_tree.curr_node(), left_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Check out the right branch from the apex of the left branch.
    history_tree.checkout(&mut state, right_branch_2);

    assert_eq!(history_tree.curr_node(), right_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    // Let's now undo the whole right branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);
}

pub fn redo<T>(&mut self, target: &mut T, node: HistoryTreeNodeId) -> Cmd

where E: ApplyEdit<T> + RevertEdit<T>,

Redo the edit at the specified node, moving one step downwards.

This does not cause any changes to the tree topology, only the target container and current node are modified.

pub fn checkout<T>( &mut self, target: &mut T, target_node: HistoryTreeNodeId, ) -> Vec<Cmd>

where E: ApplyEdit<T> + RevertEdit<T>,

Move from the current node to the target node.

First, a sequence of calls to Self::undo is made to climb to the lowest common ancestor, and then a sequence of calls to Self::redo is performed to descend to the target node.

Returns the list of command metadata produced by the redo phase in the order they were applied. If already at target_node, an empty vector is returned.

Examples found in repository

examples/history_tree.rs (line 83)

fn main() {
    let mut history_tree: HistoryTree<VecDelta<&str>> = HistoryTree::new();
    let mut state = Recorder::new(vec!["root"]);

    // Right below the root we push a "fork" node, from which we will fork two
    // branches.
    state.push("fork");
    history_tree.commit(&mut state);

    let fork = history_tree.curr_node();

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);

    // Add first node of left branch.
    state.push("left_branch_1");
    history_tree.commit(&mut state);

    let left_branch_1 = history_tree.curr_node();

    // Add second node of left branch.
    state.push("left_branch_2");
    history_tree.commit(&mut state);

    let left_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the left branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Let's now undo the whole left branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);

    // Add first node of right branch.
    state.push("right_branch_1");
    history_tree.commit(&mut state);

    let right_branch_1 = history_tree.curr_node();

    // Add second node of right branch.
    state.push("right_branch_2");
    history_tree.commit(&mut state);

    let right_branch_2 = history_tree.curr_node();

    // Now we have assembled the whole of the right branch.
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    let root_children = history_tree
        .node(history_tree.node(fork).parent().unwrap())
        .children();
    assert_eq!(root_children, &[fork]);

    assert_eq!(
        history_tree.node(fork).children(),
        &[left_branch_1, right_branch_1]
    );
    assert_eq!(
        history_tree.node(left_branch_1).children(),
        &[left_branch_2]
    );
    assert_eq!(
        history_tree.node(right_branch_1).children(),
        &[right_branch_2]
    );

    // Check out left branch from the apex of the right branch.
    history_tree.checkout(&mut state, left_branch_2);

    assert_eq!(history_tree.curr_node(), left_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "left_branch_1", "left_branch_2"]
    );

    // Check out the right branch from the apex of the left branch.
    history_tree.checkout(&mut state, right_branch_2);

    assert_eq!(history_tree.curr_node(), right_branch_2);
    assert_eq!(
        *state.as_ref(),
        vec!["root", "fork", "right_branch_1", "right_branch_2"]
    );

    // Let's now undo the whole right branch up to the fork node.
    history_tree.undo(&mut state);
    history_tree.undo(&mut state);

    assert_eq!(*state.as_ref(), vec!["root", "fork"]);
    assert_eq!(history_tree.curr_node(), fork);
}

Trait Implementations

impl<E: Clone, Cmd: Clone> Clone for HistoryTree<E, Cmd>

fn clone(&self) -> HistoryTree<E, Cmd>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<E: Debug, Cmd: Debug> Debug for HistoryTree<E, Cmd>

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

Formats the value using the given formatter.

impl<E: Eq, Cmd: Eq> Eq for HistoryTree<E, Cmd>

impl<E: Hash, Cmd: Hash> Hash for HistoryTree<E, Cmd>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<E: PartialEq, Cmd: PartialEq> PartialEq for HistoryTree<E, Cmd>

fn eq(&self, other: &HistoryTree<E, Cmd>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<E: PartialEq, Cmd: PartialEq> StructuralPartialEq for HistoryTree<E, Cmd>