Struct dendron::node::Node

impl<T> Node<T>

Node object creation and internals.

pub fn downgrade(&self) -> NodeWeak<T>

Downgrades the reference to a weak one.

use dendron::Node;

let root = Node::new_tree("root");
let root_weak = root.downgrade();
assert!(root_weak.upgrade().is_some());

drop(root);
assert!(root_weak.upgrade().is_none());

impl<T> Node<T>

Tree hierarchy edit grants and prohibitions.

pub fn bundle_new_hierarchy_edit_prohibition(
self
) -> Result<FrozenNode<T>, HierarchyEditProhibitionError>

Returns the FrozenNode, a node with tree hierarchy edit prohibition bundled.

Failures

Fails if the hierarchy is already granted to be edited.

Examples

use dendron::Node;

let node = Node::new_tree("root");
let frozen = node.bundle_new_hierarchy_edit_prohibition()?;

pub fn bundle_new_hierarchy_edit_grant(
self
) -> Result<HotNode<T>, HierarchyEditGrantError>

Returns the HotNode, a node with tree hierarchy edit grant bundled.

Failures

Fails if the hierarchy is already granted to be edited.

Examples

use dendron::Node;

let node = Node::new_tree("root");
let hot_node = node.bundle_new_hierarchy_edit_grant()?;

pub fn bundle_hierarchy_edit_prohibition(
self,
prohibition: &HierarchyEditProhibition<T>
) -> FrozenNode<T>

Returns the FrozenNode, a node with tree hierarchy edit prohibition bundled.

Panics

Panics if the hierarchy prohibition grant is not valid for the given node.

Failures

Fails if the hierarchy is already prohibited to be edited.

Examples

use dendron::Node;

let node = Node::new_tree("root");
let prohibition = node.tree().prohibit_hierarchy_edit()?;

let frozen_node = node.bundle_hierarchy_edit_prohibition(&prohibition);

pub fn bundle_hierarchy_edit_grant(
self,
grant: &HierarchyEditGrant<T>
) -> HotNode<T>

Returns the HotNode, a node with tree hierarchy edit grant bundled.

Panics

Panics if the hierarchy edit grant is not valid for the given node.

Failures

Fails if the hierarchy is already granted to be edited.

Examples

use dendron::Node;

let node = Node::new_tree("root");
let grant = node.tree().grant_hierarchy_edit()?;

let hot_node = node.bundle_hierarchy_edit_grant(&grant);

impl<T> Node<T>

Data access.

pub fn try_borrow_data(&self) -> Result<Ref<'_, T>, BorrowError>

Returns a reference to the data associated to the node.

Failures

Fails if the data is currently mutably (i.e. exclusively) borrowed.

Examples

use dendron::Node;

let node = Node::new_tree("root");
assert_eq!(
    *node
        .try_borrow_data()
        .expect("should not fail since not mutably borrowed from other place"),
    "root"
);

pub fn borrow_data(&self) -> Ref<'_, T>

Returns a reference to the data associated to the node.

Panics

Panics if the data is already mutably borrowed.

Examples

use dendron::Node;

let node = Node::new_tree("root");
assert_eq!(*node.borrow_data(), "root");

pub fn try_borrow_data_mut(&self) -> Result<RefMut<'_, T>, BorrowMutError>

Returns a mutable reference to the data associated to the node.

Failures

Fails if the data is currently borrowed.

Examples

use dendron::Node;

let node = Node::new_tree("root");
*node
    .try_borrow_data_mut()
    .expect("should not fail since not borrowed from other place")
    = "ROOT";
assert_eq!(*node.borrow_data(), "ROOT");

pub fn borrow_data_mut(&self) -> RefMut<'_, T>

Returns a mutable reference to the data associated to the node.

Panics

Panics if the data is already mutably borrowed.

Examples

use dendron::Node;

let node = Node::new_tree("root");
*node.borrow_data_mut() = "ROOT";
assert_eq!(*node.borrow_data(), "ROOT");

pub fn ptr_eq(&self, other: &Self) -> bool

Returns true if the two Nodes point to the same allocation.

Examples

use dendron::Node;

let node1 = Node::new_tree("root");
let node2 = Node::new_tree("root");

assert!(node1.ptr_eq(&node1));

assert!(node1 == node2, "same content and hierarchy");
assert!(
    !node1.ptr_eq(&node2),
    "same content and hierarchy but different allocation"
);

impl<T> Node<T>

Neighbor nodes accessor.

pub fn tree(&self) -> Tree<T>

Returns the tree the node belongs to.

Examples

use dendron::Node;

let node = Node::new_tree("root");
let tree = node.tree();

assert!(tree.root().ptr_eq(&node));

pub fn belongs_to(&self, tree: &Tree<T>) -> bool

Returns true if the node belongs to the given tree.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child = root.create_as_last_child(&grant, "child");
//  root
//  `-- child

let other_node = Node::new_tree("other");

assert!(root.belongs_to(&root.tree()));
assert!(child.belongs_to(&root.tree()));

assert!(!root.belongs_to(&other_node.tree()));

pub fn belongs_to_same_tree(&self, other: &Self) -> bool

Returns true if the given node belong to the same tree.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child = root.create_as_last_child(&grant, "child");
//  root
//  `-- child

let other_node = Node::new_tree("other");

assert!(root.belongs_to_same_tree(&child));
assert!(child.belongs_to_same_tree(&root));

assert!(!root.belongs_to_same_tree(&other_node));

pub fn is_root(&self) -> bool

Returns true if the node is the root.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child = root.create_as_last_child(&grant, "child");
//  root
//  `-- child

assert!(root.is_root());
assert!(!child.is_root());

pub fn root(&self) -> Self

Returns the root node.

Examples

use dendron::Node;

let node = Node::new_tree("root");
let tree = node.tree();

assert!(tree.root().ptr_eq(&node));

pub fn parent(&self) -> Option<Self>

Returns the parent node.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child = root.create_as_last_child(&grant, "child");
//  root
//  `-- child

assert!(child.parent().expect("has parent").ptr_eq(&root));
assert!(root.parent().is_none());

pub fn prev_sibling(&self) -> Option<Self>

Returns the previous sibling.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
//  root
//  |-- child0
//  `-- child1

assert!(child0.prev_sibling().is_none());
assert!(child1.prev_sibling().expect("has prev sibling").ptr_eq(&child0));
assert!(root.prev_sibling().is_none());

pub fn next_sibling(&self) -> Option<Self>

Returns the next sibling.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
//  root
//  |-- child0
//  `-- child1

assert!(child0.next_sibling().expect("has next sibling").ptr_eq(&child1));
assert!(child1.next_sibling().is_none());
assert!(root.prev_sibling().is_none());

pub fn first_sibling(&self) -> Self

Returns the first sibling.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child2 = root.create_as_last_child(&grant, "child2");
//  root
//  |-- child0
//  |-- child1
//  `-- child2

assert!(child0.first_sibling().ptr_eq(&child0));
assert!(child1.first_sibling().ptr_eq(&child0));
assert!(child2.first_sibling().ptr_eq(&child0));

assert!(root.first_sibling().ptr_eq(&root));

pub fn last_sibling(&self) -> Self

Returns the last sibling.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child2 = root.create_as_last_child(&grant, "child2");
//  root
//  |-- child0
//  |-- child1
//  `-- child2

assert!(child0.last_sibling().ptr_eq(&child2));
assert!(child1.last_sibling().ptr_eq(&child2));
assert!(child2.last_sibling().ptr_eq(&child2));

assert!(root.first_sibling().ptr_eq(&root));

pub fn first_last_sibling(&self) -> (Self, Self)

Returns the first and the last sibling.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child2 = root.create_as_last_child(&grant, "child2");
//  root
//  |-- child0
//  |-- child1
//  `-- child2

let (first_sib, last_sib) = child1.first_last_sibling();
assert!(first_sib.ptr_eq(&child0));
assert!(last_sib.ptr_eq(&child2));

let (root_first_sib, root_last_sib) = root.first_last_sibling();
assert!(root_first_sib.ptr_eq(&root));
assert!(root_last_sib.ptr_eq(&root));

pub fn first_child(&self) -> Option<Self>

Returns the first child node.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
//  root
//  |-- child0
//  `-- child1

assert!(root.first_child().expect("has children").ptr_eq(&child0));
assert!(child0.first_child().is_none());

pub fn last_child(&self) -> Option<Self>

Returns the last child node.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
//  root
//  |-- child0
//  `-- child1

assert!(root.last_child().expect("has children").ptr_eq(&child1));
assert!(child0.last_child().is_none());

pub fn first_last_child(&self) -> Option<(Self, Self)>

Returns the first and the last child nodes.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child2 = root.create_as_last_child(&grant, "child2");
//  root
//  |-- child0
//  |-- child1
//  `-- child2

let (first_child, last_child) = root.first_last_child()
    .expect("has children");
assert!(first_child.ptr_eq(&child0));
assert!(last_child.ptr_eq(&child2));

assert!(child1.first_last_child().is_none());

pub fn has_prev_sibling(&self) -> bool

Returns true if the previous sibling exists.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
//  root
//  |-- child0
//  `-- child1

assert!(!child0.has_prev_sibling());
assert!(child1.has_prev_sibling());
assert!(!root.has_prev_sibling());

pub fn has_next_sibling(&self) -> bool

Returns true if the next sibling exists.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
//  root
//  |-- child0
//  `-- child1

assert!(child0.has_next_sibling());
assert!(!child1.has_next_sibling());
assert!(!root.has_next_sibling());

pub fn num_children(&self) -> usize

Returns the number of children.

This is O(1) operation.

Examples

use dendron::Node;

let root = Node::new_tree("root");
assert_eq!(root.num_children(), 0);
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
assert_eq!(root.num_children(), 1);
let child1 = root.create_as_last_child(&grant, "child1");
assert_eq!(root.num_children(), 2);
let child2 = root.create_as_last_child(&grant, "child2");
assert_eq!(root.num_children(), 3);
let child2_0 = child2.create_as_last_child(&grant, "child2_0");
//  root
//  |-- child0
//  |-- child1
//  `-- child2
//      `-- child2_0

assert_eq!(root.count_children(), 3);
assert_eq!(child0.count_children(), 0);
assert_eq!(child1.count_children(), 0);
assert_eq!(child2.count_children(), 1);
assert_eq!(child2_0.count_children(), 0);

pub fn has_children(&self) -> bool

Returns true if the node has any children.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child1_0 = child1.create_as_last_child(&grant, "child1_0");
//  root
//  |-- child0
//  `-- child1
//      `-- child1_0

assert!(root.has_children());
assert!(child1.has_children());

assert!(!child0.has_children());
assert!(!child1_0.has_children());

pub fn has_one_child(&self) -> bool

👎Deprecated since 0.1.1: use Node::num_children

Returns true if the node has just one child.

Use num_children method instead, i.e. use self.num_children() == 1.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child1_0 = child1.create_as_last_child(&grant, "child1_0");
//  root
//  |-- child0
//  `-- child1
//      `-- child1_0

assert!(child1.has_one_child());

assert!(!root.has_one_child());
assert!(!child0.has_one_child());
assert!(!child1_0.has_one_child());

pub fn has_multiple_children(&self) -> bool

👎Deprecated since 0.1.1: use Node::num_children

Returns true if the node has two or more children.

Use num_children method instead, i.e. use self.num_children() > 1.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child1_0 = child1.create_as_last_child(&grant, "child1_0");
//  root
//  |-- child0
//  `-- child1
//      `-- child1_0

assert!(root.has_multiple_children());

assert!(!child0.has_multiple_children());
assert!(!child1.has_multiple_children());
assert!(!child1_0.has_multiple_children());

pub fn count_children(&self) -> usize

👎Deprecated since 0.1.1: use Node::num_children

Returns the number of children.

Use num_children method instead.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child2 = root.create_as_last_child(&grant, "child2");
let child2_0 = child2.create_as_last_child(&grant, "child2_0");
//  root
//  |-- child0
//  |-- child1
//  `-- child2
//      `-- child2_0

assert_eq!(root.count_children(), 3);
assert_eq!(child0.count_children(), 0);
assert_eq!(child1.count_children(), 0);
assert_eq!(child2.count_children(), 1);
assert_eq!(child2_0.count_children(), 0);

pub fn count_preceding_siblings(&self) -> usize

Returns the number of preceding siblings.

Note that this is O(N) operation.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child2 = root.create_as_last_child(&grant, "child2");
let child2_0 = child2.create_as_last_child(&grant, "child2_0");
//  root
//  |-- child0
//  |-- child1
//  `-- child2
//      `-- child2_0

assert_eq!(root.count_preceding_siblings(), 0);
assert_eq!(child0.count_preceding_siblings(), 0);
assert_eq!(child1.count_preceding_siblings(), 1);
assert_eq!(child2.count_preceding_siblings(), 2);
assert_eq!(child2_0.count_preceding_siblings(), 0);

pub fn count_following_siblings(&self) -> usize

Returns the number of following siblings.

Note that this is O(N) operation.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child2 = root.create_as_last_child(&grant, "child2");
let child2_0 = child2.create_as_last_child(&grant, "child2_0");
//  root
//  |-- child0
//  |-- child1
//  `-- child2
//      `-- child2_0

assert_eq!(root.count_following_siblings(), 0);
assert_eq!(child0.count_following_siblings(), 2);
assert_eq!(child1.count_following_siblings(), 1);
assert_eq!(child2.count_following_siblings(), 0);
assert_eq!(child2_0.count_following_siblings(), 0);

pub fn count_ancestors(&self) -> usize

Returns the number of ancestors.

Note that this is O(N) operation.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "child0");
let child1 = root.create_as_last_child(&grant, "child1");
let child1_0 = child1.create_as_last_child(&grant, "child1_0");
//  root
//  |-- child0
//  `-- child1
//      `-- child1_0

assert_eq!(root.count_ancestors(), 0);
assert_eq!(child0.count_ancestors(), 1);
assert_eq!(child1.count_ancestors(), 1);
assert_eq!(child1_0.count_ancestors(), 2);

impl<T> Node<T>

Tree traverser.

pub fn depth_first_traverse(&self) -> DepthFirstTraverser<T> ⓘ

Returns the depth-first traverser.

Examples

use dendron::{Node, tree_node};
use dendron::traverse::DftEvent;

let root = tree_node! {
    "root", [
        "0",
        "1",
        /("2", [
            "2-0",
            "2-1",
        ]),
    ]
};

let events = root.depth_first_traverse()
    .map(|ev| ev.map(|node| *node.borrow_data()))
    .collect::<Vec<_>>();
assert_eq!(
    events,
    &[
        DftEvent::Open("root"),
        DftEvent::Open("0"),
        DftEvent::Close("0"),
        DftEvent::Open("1"),
        DftEvent::Close("1"),
        DftEvent::Open("2"),
        DftEvent::Open("2-0"),
        DftEvent::Close("2-0"),
        DftEvent::Open("2-1"),
        DftEvent::Close("2-1"),
        DftEvent::Close("2"),
        DftEvent::Close("root"),
    ]
);

pub fn depth_first_reverse_traverse(&self) -> ReverseDepthFirstTraverser<T> ⓘ

Returns the reverse depth-first traverser.

Examples

use dendron::{Node, tree_node};
use dendron::traverse::DftEvent;

let root = tree_node! {
    "root", [
        "0",
        "1",
        /("2", [
            "2-0",
            "2-1",
        ]),
    ]
};

let events = root.depth_first_reverse_traverse()
    .map(|ev| ev.map(|node| *node.borrow_data()))
    .collect::<Vec<_>>();
assert_eq!(
    events,
    &[
        DftEvent::Close("root"),
        DftEvent::Close("2"),
        DftEvent::Close("2-1"),
        DftEvent::Open("2-1"),
        DftEvent::Close("2-0"),
        DftEvent::Open("2-0"),
        DftEvent::Open("2"),
        DftEvent::Close("1"),
        DftEvent::Open("1"),
        DftEvent::Close("0"),
        DftEvent::Open("0"),
        DftEvent::Open("root"),
    ]
);

The iterator returns depth first traversal events in reverse order.

let events = root.depth_first_traverse()
    .map(|ev| ev.map(|node| *node.borrow_data()))
    .collect::<Vec<_>>();
let mut reverse_events = root.depth_first_reverse_traverse()
    .map(|ev| ev.map(|node| *node.borrow_data()))
    .collect::<Vec<_>>();

reverse_events.reverse();
assert_eq!(events, reverse_events);

pub fn children(&self) -> SiblingsTraverser<T> ⓘ

Returns the children traverser.

Examples

use dendron::{Node, tree_node};
use dendron::traverse::DftEvent;

let root = tree_node! {
    "root", [
        "0",
        "1",
        /("2", [
            "2-0",
            "2-1",
        ]),
    ]
};

let children = root.children()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(children, &["0", "1", "2"]);

pub fn children_reverse(&self) -> ReverseSiblingsTraverser<T> ⓘ

Returns the reverse children traverser.

Examples

use dendron::{Node, tree_node};
use dendron::traverse::DftEvent;

let root = tree_node! {
    "root", [
        "0",
        "1",
        /("2", [
            "2-0",
            "2-1",
        ]),
    ]
};

let children = root.children_reverse()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(children, &["2", "1", "0"]);

pub fn ancestors(&self) -> AncestorsTraverser<T> ⓘ

Returns the ancestors traverser.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let ancestors = child1_0.ancestors()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(ancestors, &["1", "root"]);

pub fn ancestors_or_self(&self) -> AncestorsTraverser<T> ⓘ

Returns the ancestors traverser.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let ancestors_or_self = child1_0.ancestors_or_self()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(ancestors_or_self, &["1-0", "1", "root"]);

pub fn siblings(&self) -> SiblingsTraverser<T> ⓘ

Returns the siblings traverser.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child2 = root.create_as_last_child(&grant, "2");
let child2_0 = child2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  `-- 2
//      `-- 2-0

let siblings = child1.siblings()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(siblings, &["0", "1", "2"]);

pub fn siblings_reverse(&self) -> ReverseSiblingsTraverser<T> ⓘ

Returns the reverse siblings traverser.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child2 = root.create_as_last_child(&grant, "2");
let child2_0 = child2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  `-- 2
//      `-- 2-0

let siblings = child1.siblings_reverse()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(siblings, &["2", "1", "0"]);

pub fn preceding_siblings_or_self_reverse(&self) -> ReverseSiblingsTraverser<T> ⓘ

Returns the reverse preceding siblings traverser.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child2 = root.create_as_last_child(&grant, "2");
let child2_0 = child2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  `-- 2
//      `-- 2-0

let siblings = child1.preceding_siblings_or_self_reverse()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(siblings, &["1", "0"]);

pub fn preceding_siblings_reverse(&self) -> ReverseSiblingsTraverser<T> ⓘ

Returns the reverse preceding siblings traverser.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child2 = root.create_as_last_child(&grant, "2");
let child2_0 = child2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  `-- 2
//      `-- 2-0

let siblings = child1.preceding_siblings_reverse()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(siblings, &["0"]);

pub fn following_siblings_or_self(&self) -> SiblingsTraverser<T> ⓘ

Returns the following siblings traverser.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child2 = root.create_as_last_child(&grant, "2");
let child2_0 = child2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  `-- 2
//      `-- 2-0

let siblings = child1.following_siblings_or_self()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(siblings, &["1", "2"]);

pub fn following_siblings(&self) -> SiblingsTraverser<T> ⓘ

Returns the following siblings traverser.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child2 = root.create_as_last_child(&grant, "2");
let child2_0 = child2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  `-- 2
//      `-- 2-0

let siblings = child1.following_siblings()
    .map(|node| *node.borrow_data())
    .collect::<Vec<_>>();
assert_eq!(siblings, &["2"]);

impl<T> Node<T>

Node creation and hierarchy modification.

pub fn new_tree(root_data: T) -> Self

Creates and returns a new node as the root of a new tree.

Examples

use dendron::Node;

let root = Node::new_tree("root");

pub fn detach_subtree(&self, grant: &HierarchyEditGrant<T>)

Detaches the node and its descendant from the current tree, and let it be another tree.

Detaching the root node does nothing, but valid grant should be passed even in this case.

Panics

Panics if the hierarchy edit grant is not valid for the given node.

Failures

Fails if the resulting hierarchy will be invalid as a tree.

Examples

use dendron::{Node, tree_node};

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
let child1_1 = child1.create_as_last_child(&grant, "1-1");
let child2 = root.create_as_last_child(&grant, "2");
let child2_0 = child2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  |   |-- 1-0
//  |   `-- 1-1
//  `-- 2
//      `-- 2-0

child1.detach_subtree(&grant);
//  root
//  |-- 0
//  `-- 2
//      `-- 2-0
//  1
//  |-- 1-0
//  `-- 1-1

// Nodes in the detached subtree is now part of another tree.
assert!(!child1.root().ptr_eq(&root));
assert!(!root.belongs_to_same_tree(&child1));
assert!(!root.belongs_to_same_tree(&child1_0));
assert!(!root.belongs_to_same_tree(&child1_1));
assert_eq!(
    root,
    tree_node! {
        "root", [
            "0",
            /("2", ["2-0"]),
        ]
    }
);

// Hierarchy of subtree is preserved.
assert!(child1.belongs_to_same_tree(&child1_0));
assert!(child1.belongs_to_same_tree(&child1_1));
assert_eq!(
    child1,
    tree_node! {
        "1", [
            "1-0",
            "1-1",
        ]
    }
);

pub fn try_create_node_as(
 &self,
 grant: &HierarchyEditGrant<T>,
 data: T,
 dest: AdoptAs
) -> Result<Self, HierarchyError>

Creates a node as the specified neighbor of self, and returns the new node.

Failures

Fails if creation of a node at the specified position will make the tree hierarchy invalid.

Panics

Panics if the hierarchy edit grant is not valid for the given node.

Examples

`AdoptAs::FirstChild`

use dendron::{AdoptAs, Node};

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let new = child1
    .try_create_node_as(&grant, "new", AdoptAs::FirstChild)
    .expect("creating valid hierarchy");
//  root
//  |-- 0
//  `-- 1
//      |-- new
//      `-- 1-0

assert!(child1.first_child().expect("has children").ptr_eq(&new));
assert!(child1_0.prev_sibling().expect("has a sibling").ptr_eq(&new));

`AdoptAs::LastChild`

use dendron::{AdoptAs, Node};

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let new = child1
    .try_create_node_as(&grant, "new", AdoptAs::LastChild)
    .expect("creating valid hierarchy");
//  root
//  |-- 0
//  `-- 1
//      |-- 1-0
//      `-- new

assert!(child1.last_child().expect("has children").ptr_eq(&new));
assert!(child1_0.next_sibling().expect("has a sibling").ptr_eq(&new));

`AdoptAs::PreviousSibling`

use dendron::{AdoptAs, Node};

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let new = child1
    .try_create_node_as(&grant, "new", AdoptAs::PreviousSibling)
    .expect("creating valid hierarchy");
//  root
//  |-- 0
//  |-- new
//  `-- 1
//      `-- 1-0

assert!(child0.next_sibling().expect("has siblings").ptr_eq(&new));
assert!(child1.prev_sibling().expect("has siblings").ptr_eq(&new));

`AdoptAs::NextSibling`

use dendron::{AdoptAs, Node};

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let new = child1
    .try_create_node_as(&grant, "new", AdoptAs::NextSibling)
    .expect("creating valid hierarchy");
//  root
//  |-- 0
//  |-- 1
//  |   `-- 1-0
//  `-- new

assert!(root.last_child().expect("has children").ptr_eq(&new));
assert!(child1.next_sibling().expect("has siblings").ptr_eq(&new));

pub fn create_node_as(
 &self,
 grant: &HierarchyEditGrant<T>,
 data: T,
 dest: AdoptAs
) -> Self

Creates a node as the specified neighbor of self, and returns the new node.

See try_create_node_as for usage examples.

Panics

Panics if:

the hierarchy edit grant is not valid for the given node, or
creation of a node at the specified position will make the tree hierarchy invalid.

pub fn create_as_first_child(
 &self,
 grant: &HierarchyEditGrant<T>,
 data: T
) -> Self

Creates a node as the first child of self.

Panics

Panics if the hierarchy edit grant is not valid for the given node.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let new = child1.create_as_first_child(&grant, "new");
//  root
//  |-- 0
//  `-- 1
//      |-- new
//      `-- 1-0

assert!(child1.first_child().expect("has children").ptr_eq(&new));
assert!(child1_0.prev_sibling().expect("has a sibling").ptr_eq(&new));

pub fn create_as_last_child(&self, grant: &HierarchyEditGrant<T>, data: T) -> Self

Creates a node as the last child of self.

Panics

Panics if the hierarchy edit grant is not valid for the given node.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let new = child1.create_as_last_child(&grant, "new");
//  root
//  |-- 0
//  `-- 1
//      |-- 1-0
//      `-- new

assert!(child1.last_child().expect("has children").ptr_eq(&new));
assert!(child1_0.next_sibling().expect("has a sibling").ptr_eq(&new));

pub fn try_create_as_prev_sibling(
 &self,
 grant: &HierarchyEditGrant<T>,
 data: T
) -> Result<Self, HierarchyError>

Creates a node as the previous sibling of self.

Failures

Returns HierarchyError::SiblingsWithoutParent as an error if self is a root node.

Panics

Panics if the hierarchy edit grant is not valid for the given node.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let new = child1.try_create_as_prev_sibling(&grant, "new")
    .expect("creating valid hierarchy");
//  root
//  |-- 0
//  |-- new
//  `-- 1
//      `-- 1-0

assert!(child0.next_sibling().expect("has siblings").ptr_eq(&new));
assert!(child1.prev_sibling().expect("has siblings").ptr_eq(&new));

pub fn create_as_prev_sibling(
 &self,
 grant: &HierarchyEditGrant<T>,
 data: T
) -> Self

Creates a node as the previous sibling of self.

See try_create_as_prev_sibling for usage examples.

Panics

Panics if:

the hierarchy edit grant is not valid for the given node, or
self is a root node.

pub fn try_create_as_next_sibling(
 &self,
 grant: &HierarchyEditGrant<T>,
 data: T
) -> Result<Self, HierarchyError>

Creates a node as the next sibling of self.

Failures

Returns HierarchyError::SiblingsWithoutParent as an error if self is a root node.

Panics

Panics if the hierarchy edit grant is not valid for the given node.

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let new = child1.try_create_as_next_sibling(&grant, "new")
    .expect("creating valid hierarchy");
//  root
//  |-- 0
//  |-- 1
//  |   `-- 1-0
//  `-- new

assert!(root.last_child().expect("has children").ptr_eq(&new));
assert!(child1.next_sibling().expect("has siblings").ptr_eq(&new));

pub fn create_as_next_sibling(
 &self,
 grant: &HierarchyEditGrant<T>,
 data: T
) -> Self

Creates a node as the next sibling of self.

See try_create_as_next_sibling for usage examples.

Panics

Panics if:

the hierarchy edit grant is not valid for the given node, or
self is a root node.

pub fn create_as_interrupting_parent(
 &self,
 grant: &HierarchyEditGrant<T>,
 data: T
) -> Self

Creates a new node that interrupts between self and the parent.

If self was the root, the new node will become a new root of the tree and self will be only child of the new root.

Before:

root
`-- this
    |-- child0
    |-- child1
    `-- child2

After self.create_as_interrupting_parent:

root
`-- this
    `-- new
        |-- child0
        |-- child1
        `-- child2

Examples

use dendron::{tree_node, Node};

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let _prev = root.create_as_last_child(&grant, "prev");
let this = root.create_as_last_child(&grant, "this");
let _child0 = this.create_as_last_child(&grant, "child0");
let _child1 = this.create_as_last_child(&grant, "child1");
let _child2 = this.create_as_last_child(&grant, "child2");
let _next = root.create_as_last_child(&grant, "next");
//  root
//  |-- prev
//  |-- this
//  |   |-- child0
//  |   |-- child1
//  |   `-- child2
//  `-- next

let new = this.create_as_interrupting_parent(&grant, "new");

//  root
//  |-- prev
//  |-- new
//  |   `-- this
//  |       |-- child0
//  |       |-- child1
//  |       `-- child2
//  `-- next
let expected = tree_node! {
    "root", [
        "prev",
        /("new", [
            /("this", [
                "child0",
                "child1",
                "child2",
            ]),
        ]),
        "next",
    ]
};

assert_eq!(root, expected);
assert!(root.root().ptr_eq(&root));

assert!(new.first_child().unwrap().ptr_eq(&this));
assert!(this.parent().unwrap().ptr_eq(&new));

assert_eq!(new.num_children(), 1, "`this`");
assert_eq!(this.num_children(), 3, "`child0`, `child1`, and `child2`");

If self is a root:

use dendron::{tree_node, Node};

let this = Node::new_tree("this");
let grant = this.tree().grant_hierarchy_edit()?;
let _child0 = this.create_as_last_child(&grant, "child0");
let _child1 = this.create_as_last_child(&grant, "child1");
//  this
//  |-- child0
//  `-- child1

let new = this.create_as_interrupting_parent(&grant, "new");

//  new
//  `-- this
//      |-- child0
//      `-- child1
let expected = tree_node! {
    "new", [
        /("this", [
            "child0",
            "child1",
        ]),
    ]
};

assert_eq!(new, expected);
assert!(this.root().ptr_eq(&new));

assert!(new.first_child().unwrap().ptr_eq(&this));
assert!(this.parent().unwrap().ptr_eq(&new));

assert_eq!(new.num_children(), 1, "`this`");
assert_eq!(this.num_children(), 2, "`child0` and `child1`");

pub fn create_as_interrupting_child(
 &self,
 grant: &HierarchyEditGrant<T>,
 data: T
) -> Self

Creates a new node that interrupts between self and the children.

Examples

use dendron::{tree_node, Node};

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let _prev = root.create_as_last_child(&grant, "prev");
let this = root.create_as_last_child(&grant, "this");
let _child0 = this.create_as_last_child(&grant, "child0");
let _child1 = this.create_as_last_child(&grant, "child1");
let _child2 = this.create_as_last_child(&grant, "child2");
let _next = root.create_as_last_child(&grant, "next");
//  root
//  |-- prev
//  |-- this
//  |   |-- child0
//  |   |-- child1
//  |   `-- child2
//  `-- next

let new = this.create_as_interrupting_child(&grant, "new");

//  root
//  |-- prev
//  |-- this
//  |   `-- new
//  |       |-- child0
//  |       |-- child1
//  |       `-- child2
//  `-- next
let expected = tree_node! {
    "root", [
        "prev",
        /("this", [
            /("new", [
                "child0",
                "child1",
                "child2",
            ]),
        ]),
        "next",
    ]
};

assert_eq!(root, expected);
assert!(root.root().ptr_eq(&root));

assert!(this.first_child().unwrap().ptr_eq(&new));
assert!(new.parent().unwrap().ptr_eq(&this));

assert_eq!(new.num_children(), 3, "`child0`, `child1`, and `child2`");
assert_eq!(this.num_children(), 1, "`new`");

pub fn try_replace_with_children(
&self,
grant: &HierarchyEditGrant<T>
) -> Result<(), HierarchyError>

Inserts the children at the position of the node, and detach the node.

self will become the root of a new single-node tree.

Before:

parent
|-- prev
|-- self
|   |-- child0
|   |   `-- grandchild0-0
|   `-- child1
`-- next

After self.try_replace_with_children():

parent
|-- prev
|-- child0
|   `-- grandchild0-0
|-- child1
`-- next

self (detached)

Failures

Fails if:

the node is the root and has multiple children, or
- In this case, HierarchyError::SiblingsWithoutParent error is returned.
the node is the root and has no children.
- In this case, HierarchyError::EmptyTree error is returned.

Panics

Panics if the hierarchy edit grant is not valid for the given node.

pub fn replace_with_children(&self, grant: &HierarchyEditGrant<T>)

Inserts the children at the position of the node, and detach the node.

self will become the root of a new single-node tree.

See try_replace_with_children method.

Panics

Panics if:

the hierarchy edit grant is not valid for the given node,
the node is the root and has multiple children, or
the node is the root and has no children.

pub fn try_clone_subtree(&self) -> Result<Self, BorrowError>where
T: Clone,

Clones the subtree and returns it as a new independent tree.

Failures

Fails if any data associated to the node in the subtree is mutably (i.e. exclusively) borrowed.

Examples

use dendron::Node;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0

let cloned = child1.try_clone_subtree()
    .expect("data are currently not borrowed");
//  root
//  |-- 0
//  `-- 1
//      `-- 1-0
//  1
//  `-- 1-0

// Cloned subtree is independent tree.
assert!(!cloned.belongs_to_same_tree(&root));
// Descendants are also cloned.
assert_eq!(cloned, child1);

pub fn clone_subtree(&self) -> Selfwhere
T: Clone,

Clones the subtree and returns it as a new independent tree.

Panics

Panics if any data associated to the node in the subtree is mutably (i.e. exclusively) borrowed.

pub fn try_clone_insert_subtree(
 &self,
 dest: InsertAs<&HotNode<T>>
) -> Result<HotNode<T>, HierarchyError>where
 T: Clone,

Clones the node with its subtree, and inserts it to the given destination.

Returns the root node of the cloned new subtree.

Failures

Fails if:

the hierarchy to be created is invalid, or
any data associated to the node in the subtree is mutably (i.e. exclusively) borrowed.
- Returns BorrowNodeData in this case.

Examples

use dendron::{InsertAs, Node, tree_node};

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let node0 = root.create_as_last_child(&grant, "0");
let node1 = root.create_as_last_child(&grant, "1");
let node1_0 = node1.create_as_last_child(&grant, "1-0");
let node1_0_0 = node1_0.create_as_last_child(&grant, "1-0-0");
let node1_1 = node1.create_as_last_child(&grant, "1-1");
let node2 = root.create_as_last_child(&grant, "2");
let node2_0 = node2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  |   |-- 1-0
//  |   |   `-- 1-0-0
//  |   `-- 1-1
//  `-- 2
//      `-- 2-0

let node2_0_hot = node2_0.bundle_hierarchy_edit_grant(&grant);
let cloned = node1
    .try_clone_insert_subtree(InsertAs::PreviousSiblingOf(&node2_0_hot))
    .expect("creating valid hierarchy");
//  root
//  |-- 0
//  |-- 1
//  |   |-- 1-0
//  |   |   `-- 1-0-0
//  |   `-- 1-1
//  `-- 2
//      |-- 1
//      |   |-- 1-0
//      |   |   `-- 1-0-0
//      |   `-- 1-1
//      `-- 2-0

assert!(!cloned.plain().ptr_eq(&node1));
// Cloned node belongs to the same tree.
assert!(cloned.plain().belongs_to_same_tree(&node1));

assert_eq!(
    root,
    tree_node! {
        "root", [
            "0",
            /("1", [
                /("1-0", ["1-0-0"]),
                "1-1",
            ]),
            /("2", [
                /("1", [
                    /("1-0", ["1-0-0"]),
                    "1-1",
                ]),
                "2-0"
            ]),
        ]
    }
);

pub fn clone_insert_subtree(&self, dest: InsertAs<&HotNode<T>>) -> HotNode<T>where
T: Clone,

Clones the node with its subtree, and inserts it to the given destination.

Returns the root node of the cloned new subtree.

See try_clone_insert_subtree for detail.

Panics

Panics if:

the hierarchy to be created is invalid, or
any data associated to the node in the subtree is mutably (i.e. exclusively) borrowed.

pub fn try_detach_insert_subtree(
 &self,
 grant: &HierarchyEditGrant<T>,
 dest: InsertAs<&HotNode<T>>
) -> Result<(), HierarchyError>

Detaches the node with its subtree, and inserts it to the given destination.

Failures

Fails if the node (being moved) is an ancestor of the destination.

Panics

Panics if the hierarchy edit grant is not valid for the given node.

Examples

use dendron::{InsertAs, Node, tree_node};

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let node0 = root.create_as_last_child(&grant, "0");
let node1 = root.create_as_last_child(&grant, "1");
let node1_0 = node1.create_as_last_child(&grant, "1-0");
let node1_0_0 = node1_0.create_as_last_child(&grant, "1-0-0");
let node1_1 = node1.create_as_last_child(&grant, "1-1");
let node2 = root.create_as_last_child(&grant, "2");
let node2_0 = node2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  |   |-- 1-0
//  |   |   `-- 1-0-0
//  |   `-- 1-1
//  `-- 2
//      `-- 2-0

let node2_0_hot = node2_0.bundle_hierarchy_edit_grant(&grant);
node1
    .try_detach_insert_subtree(
        &grant,
        InsertAs::PreviousSiblingOf(&node2_0_hot)
    )
    .expect("creating valid hierarchy");
//  root
//  |-- 0
//  `-- 2
//      |-- 1
//      |   |-- 1-0
//      |   |   `-- 1-0-0
//      |   `-- 1-1
//      `-- 2-0

assert!(node1.parent().expect("has a parent").ptr_eq(&node2));
// Cloned node belongs to the same tree.
assert!(node1.belongs_to_same_tree(&node2));

assert_eq!(
    root,
    tree_node! {
        "root", [
            "0",
            /("2", [
                /("1", [
                    /("1-0", ["1-0-0"]),
                    "1-1",
                ]),
                "2-0"
            ]),
        ]
    }
);

pub fn detach_insert_subtree(
 &self,
 grant: &HierarchyEditGrant<T>,
 dest: InsertAs<&HotNode<T>>
)

Detaches the node with its subtree, and inserts it to the given destination.

See Node::try_detach_insert_subtree for detail.

Panics

Panics if:

the hierarchy edit grant is not valid for the given node, or
the node (being moved) is an ancestor of the destination.

impl<T> Node<T>

Comparison.

pub fn try_eq(&self, other: &Node) -> Result<bool, BorrowError>where
T: PartialEq,

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Failures

May return Err(_) if associated data of some nodes are already borrowed exclusively (i.e. mutably).

Examples

use dendron::{tree_node, Node};

//  root
//  |-- 0
//  |   |-- 0-0
//  |   `-- 0-1
//  |       `-- 0-1-0
//  `-- 1
let node1: Node<&'static str> = tree_node! {
    "root", [
        /("0", [
            "0-0",
            /("0-1", [
                "0-1-0",
            ]),
        ]),
        "1",
    ]
};

//  0
//  |-- 0-0
//  `-- 0-1
//      `-- 0-1-0
let node2: Node<String> = tree_node! {
    "0".to_owned(), [
        "0-0".into(),
        /("0-1".into(), [
            "0-1-0".into(),
        ]),
    ]
};

assert!(
    !node1.try_eq(&node2).expect("data are not borrowed"),
    "node1 and node2 are not equal"
);

let node1_first_child = node1.first_child().expect("node1 has a child");
assert!(
    node1_first_child.try_eq(&node2).expect("data are not borrowed"),
    "the first child of node1 and node2 are equal"
);

impl<T: Clone> Node<T>

Serialization.

pub fn to_events(&self) -> TreeSerializeIter<T> ⓘ

Returns an iterator of serialized events for the subtree.

Examples

use dendron::Node;
use dendron::serial::Event;

let root = Node::new_tree("root");
let grant = root.tree().grant_hierarchy_edit()?;
let child0 = root.create_as_last_child(&grant, "0");
let child1 = root.create_as_last_child(&grant, "1");
let child1_0 = child1.create_as_last_child(&grant, "1-0");
let child1_1 = child1.create_as_last_child(&grant, "1-1");
let child2 = root.create_as_last_child(&grant, "2");
let child2_0 = child2.create_as_last_child(&grant, "2-0");
//  root
//  |-- 0
//  |-- 1
//  |   |-- 1-0
//  |   `-- 1-1
//  `-- 2
//      `-- 2-0

let events = root.to_events()
    .collect::<Result<Vec<_>, _>>()
    .expect("data are not exclusively borrowed now");
assert_eq!(
    events,
    &[
        Event::Open("root"),
        Event::Open("0"),
        // Close `1`.
        Event::Close(1),
        Event::Open("1"),
        Event::Open("1-0"),
        // Close `1-0`.
        Event::Close(1),
        Event::Open("1-1"),
        // Close `1-1` and `2`.
        Event::Close(2),
        Event::Open("2"),
        Event::Open("2-0"),
        // Close `2-0`, `2`, and `root`.
        Event::Close(3),
    ]
);

impl<T> Node<T>

Debug printing.

pub fn debug_pretty_print(&self) -> DebugPrettyPrint<'_, T>

Returns the pretty-printable proxy object to the node and descendants.

(No) guarantees

This is provided mainly for debugging purpose. Node that the output format is not guaranteed to be stable, and any format changes won’t be considered as breaking changes.

Examples

use dendron::tree_node;

let root = tree_node! {
    "root", [
        /("0", [
            "0\n0",
            "0\n1",
        ]),
        "1",
        /("2", [
            /("2\n0", [
                "2\n0\n0",
            ])
        ]),
    ]
};

let printable = root.debug_pretty_print();

let expected_debug = r#""root"
|-- "0"
|   |-- "0\n0"
|   `-- "0\n1"
|-- "1"
`-- "2"
    `-- "2\n0"
        `-- "2\n0\n0""#;
assert_eq!(format!("{:?}", printable), expected_debug);

let expected_display = r#"root
|-- 0
|   |-- 0
|   |   0
|   `-- 0
|       1
|-- 1
`-- 2
    `-- 2
        0
        `-- 2
            0
            0"#;
assert_eq!(printable.to_string(), expected_display);

pub fn debug_print_local(&self) -> DebugPrintNodeLocal<'_, T>

Returns a debug-printable proxy that does not dump neighbor nodes.

(No) guarantees

This is provided mainly for debugging purpose. Node that the output format is not guaranteed to be stable, and any format changes won’t be considered as breaking changes.

Examples

use dendron::{Node, tree_node};

let root = tree_node! {
    "root", [
        /("0", [
            "0-0",
            "0-1",
        ]),
    ]
};

let printable = root.debug_print_local();

println!("default oneliner = {:?}", printable);
println!("alternate multiline = {:#?}", printable);

pub fn debug_print_subtree(&self) -> DebugPrintSubtree<'_, T>

Returns a debug-printable proxy that dumps descendant nodes.

(No) guarantees

This is provided mainly for debugging purpose. Node that the output format is not guaranteed to be stable, and any format changes won’t be considered as breaking changes.

Examples

use dendron::{Node, tree_node};

let root = tree_node! {
    "root", [
        /("0", [
            "0-0",
            "0-1",
        ]),
    ]
};

let printable = root.debug_print_subtree();

println!("default oneliner = {:?}", printable);
println!("alternate multiline = {:#?}", printable);

Trait Implementations§

impl<T> Clone for Node<T>

fn clone(&self) -> Self

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

impl<T: Debug> Debug for Node<T>

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

Formats the value using the given formatter. Read more

impl<T> From<FrozenNode<T>> for Node<T>

fn from(node: FrozenNode<T>) -> Self

Converts to this type from the input type.

impl<T> From<HotNode<T>> for Node<T>

fn from(node: HotNode<T>) -> Self

Converts to this type from the input type.

impl<T, U: PartialEq> PartialEq<&FrozenNode> for Node<T>where
T: PartialEq,

fn eq(&self, other: &&FrozenNode) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<&HotNode> for Node<T>where
T: PartialEq,

fn eq(&self, other: &&HotNode) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<&Node> for FrozenNode<T>where
T: PartialEq,

fn eq(&self, other: &&Node) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<&Node> for HotNode<T>where
T: PartialEq,

fn eq(&self, other: &&Node) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<FrozenNode> for &Node<T>where
T: PartialEq,

fn eq(&self, other: &FrozenNode) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<FrozenNode> for Node<T>where
T: PartialEq,

fn eq(&self, other: &FrozenNode) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<HotNode> for &Node<T>where
T: PartialEq,

fn eq(&self, other: &HotNode) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<HotNode> for Node<T>where
T: PartialEq,

fn eq(&self, other: &HotNode) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<Node> for &FrozenNode<T>where
T: PartialEq,

fn eq(&self, other: &Node) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<Node> for &HotNode<T>where
T: PartialEq,

fn eq(&self, other: &Node) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<Node> for FrozenNode<T>where
T: PartialEq,

fn eq(&self, other: &Node) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<Node> for HotNode<T>where
T: PartialEq,

fn eq(&self, other: &Node) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use Node::try_eq, FrozenNode::plain, and HotNode::plain methods.

Examples

See the documentation for Node::try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T, U: PartialEq> PartialEq<Node> for Node<T>where
T: PartialEq,

fn eq(&self, other: &Node) -> bool

Compares two subtrees.

Returns Ok(true) if the two subtree are equal, even if they are stored in different allocation.

Panics

May panic if associated data of some nodes are already borrowed exclusively (i.e. mutably).

To avoid panicking, use try_eq method.

Examples

See the documentation for try_eq method.

1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

impl<T: Eq> Eq for Node<T>

Auto Trait Implementations§

impl<T> !UnwindSafe for Node<T>

Blanket Implementations§

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

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

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

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

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

const: unstable · source§

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

Mutably borrows from an owned value. Read more

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

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

const: unstable · 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.

impl<T> ToOwned for Twhere
T: Clone,

type Owned = T

The resulting type after obtaining ownership.

fn to_owned(&self) -> T

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

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

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

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

type Error = Infallible

The type returned in the event of a conversion error.

const: unstable · source§

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

Performs the conversion.

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