Enum RemoveBehavior

pub enum RemoveBehavior {
    DropChildren,
    LiftChildren,
    OrphanChildren,
}

Describes the possible behaviors of the Tree::remove_node method.

Variants

DropChildren

All children will be dropped recursively. In other words, the entire sub-tree of the Node being removed will be dropped from the tree. Those Nodes will no longer exist and cannot be accessed even if you have the NodeId the previously pointed to them.

This means even without using Clone you might end up with copies of invalid NodeIds. Use this behavior with caution.

use id_tree::*;
use id_tree::InsertBehavior::*;
use id_tree::RemoveBehavior::*;

let mut tree: Tree<i32> = Tree::new();

let root_id = tree.insert(Node::new(0), AsRoot).unwrap();
let child_id = tree.insert(Node::new(1), UnderNode(&root_id)).unwrap();
let grandchild_id = tree.insert(Node::new(2), UnderNode(&child_id)).unwrap();

let child = tree.remove_node(child_id, DropChildren).ok().unwrap();

assert!(tree.get(&grandchild_id).is_err());
assert_eq!(tree.get(&root_id).unwrap().children().len(), 0);
assert_eq!(child.children().len(), 0);
assert_eq!(child.parent(), None);

LiftChildren

If the removed Node (let’s call it A) has a parent, A’s parent will become the parent of A’s children. This effectively just shifts them up one level in the Tree.

If A doesn’t have a parent, then this behaves exactly like RemoveBehavior::OrphanChildren.

use id_tree::*;
use id_tree::InsertBehavior::*;
use id_tree::RemoveBehavior::*;

let mut tree: Tree<i32> = Tree::new();

let root_id = tree.insert(Node::new(0), AsRoot).unwrap();
let child_id = tree.insert(Node::new(1), UnderNode(&root_id)).unwrap();
let grandchild_id = tree.insert(Node::new(2), UnderNode(&child_id)).unwrap();

let child = tree.remove_node(child_id, LiftChildren).ok().unwrap();

assert!(tree.get(&grandchild_id).is_ok());
assert!(tree.get(&root_id).unwrap().children().contains(&grandchild_id));
assert_eq!(child.children().len(), 0);
assert_eq!(child.parent(), None);

OrphanChildren

All children will have their parent references cleared. This means nothing will point to them, but they will still exist in the tree. Those Nodes can still be accessed provided that you have the NodeId that points to them.

use id_tree::*;
use id_tree::InsertBehavior::*;
use id_tree::RemoveBehavior::*;

let mut tree: Tree<i32> = Tree::new();

let root_id = tree.insert(Node::new(0), AsRoot).unwrap();
let child_id = tree.insert(Node::new(1), UnderNode(&root_id)).unwrap();
let grandchild_id = tree.insert(Node::new(2), UnderNode(&child_id)).unwrap();

let child = tree.remove_node(child_id, OrphanChildren).ok().unwrap();

assert!(tree.get(&grandchild_id).is_ok());
assert_eq!(tree.get(&root_id).unwrap().children().len(), 0);
assert_eq!(child.children().len(), 0);
assert_eq!(child.parent(), None);