Struct dendron::node::HotNode

pub struct HotNode<T> { /* private fields */ }

A Node with a tree hierarchy edit grant bundled.

HotNode can be created by Node::bundle_hierarchy_edit_grant or Node::bundle_new_hierarchy_edit_grant.

Panics

Panics if the number of active edit grants through this node is usize::MAX. This is very unlikely to happen without leaking grants.

Implementations

impl<T> HotNode<T>

pub fn plain(&self) -> Node<T>

Creates a plain node reference for the node.

Examples

use dendron::{HotNode, Node};

let hot = HotNode::new_tree("root");
let plain: Node<_> = hot.plain();

impl<T> HotNode<T>

Tree hierarchy edit grants.

pub fn extract_hierarchy_edit_grant(&self) -> HierarchyEditGrant<T>

Returns a copy of the tree hierarchy edit grant.

Examples

use dendron::HotNode;

let hot = HotNode::new_tree("root");
let grant = hot.extract_hierarchy_edit_grant();

impl<T> HotNode<T>

Data access.

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

Returns a reference to the data associated to the node.

Examples

use dendron::HotNode;

let hot = HotNode::new_tree("root");
assert_eq!(
    *hot
        .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::HotNode;

let hot = HotNode::new_tree("root");
assert_eq!(*hot.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.

Examples

use dendron::HotNode;

let hot = HotNode::new_tree("root");

*hot.try_borrow_data_mut()
    .expect("should not fail since not borrowed from other place")
    = "ROOT";
assert_eq!(*hot.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::HotNode;

let hot = HotNode::new_tree("root");

*hot.borrow_data_mut() = "ROOT";
assert_eq!(*hot.borrow_data(), "ROOT");

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

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

Examples

use dendron::HotNode;

let hot1 = HotNode::new_tree("root");
let hot2 = HotNode::new_tree("root");

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

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

pub fn ptr_eq_plain(&self, other: &Node<T>) -> bool

Returns true if self and the given Node point to the same allocation.

Examples

use dendron::HotNode;

let hot = HotNode::new_tree("root");
assert!(hot.ptr_eq_plain(&hot.plain()));

impl<T> HotNode<T>

Neighbor nodes accessor.

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

Returns the tree the node belongs to.

Examples

use dendron::HotNode;

let hot = HotNode::new_tree("root");
let tree = hot.tree();

assert!(tree.root().ptr_eq(&hot.plain()));

pub fn is_root(&self) -> bool

Returns true if the node is the root.

Examples

use dendron::HotNode;

let root = HotNode::new_tree("root");
let child = root.create_as_last_child("child");
//  root
//  `-- child

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

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

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

Examples

use dendron::HotNode;

let root = HotNode::new_tree("root");
let child = root.create_as_last_child("child");
//  root
//  `-- child

let other_node = HotNode::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 root(&self) -> Self

Returns the hot root node.

Examples

use dendron::HotNode;

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

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

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

Returns the parent node.

See Node::parent for usage examples.

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

Returns the previous sibling.

See Node::prev_sibling for usage examples.

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

Returns the next sibling.

See Node::next_sibling for usage examples.

pub fn first_sibling(&self) -> Self

Returns the first sibling.

See Node::first_sibling for usage examples.

pub fn last_sibling(&self) -> Self

Returns the last sibling.

See Node::last_sibling for usage examples.

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

Returns the first and the last siblings.

See Node::first_last_sibling for usage examples.

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

Returns the first child node.

See Node::first_child for usage examples.

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

Returns the last child node.

See Node::last_child for usage examples.

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

Returns links to the first and the last child nodes.

See Node::first_last_child for usage examples.

pub fn has_prev_sibling(&self) -> bool

Returns true if the previous sibling exists.

See Node::has_prev_sibling for usage examples.

pub fn has_next_sibling(&self) -> bool

Returns true if the next sibling exists.

See Node::has_next_sibling for usage examples.

pub fn has_children(&self) -> bool

Returns true if the node has any children.

See Node::has_children for usage examples.

pub fn num_children(&self) -> usize

Returns the number of children.

This is O(1) operation.

See Node::num_children for usage examples.

pub fn has_one_child(&self) -> bool

👎 Deprecated since 0.1.1:

use HotNode::num_children

Returns true if the node has just one child.

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

See Node::has_one_child for usage examples.

pub fn has_multiple_children(&self) -> bool

👎 Deprecated since 0.1.1:

use HotNode::num_children

Returns true if the node has two or more children.

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

See Node::has_multiple_children for usage examples.

pub fn count_children(&self) -> usize

👎 Deprecated since 0.1.1:

use HotNode::num_children

Returns the number of children.

Use num_children method instead.

See Node::count_children for usage examples.

pub fn count_preceding_siblings(&self) -> usize

Returns the number of preceding siblings.

Note that this is O(N) operation.

See Node::count_preceding_siblings for usage examples.

pub fn count_following_siblings(&self) -> usize

Returns the number of following siblings.

Note that this is O(N) operation.

See Node::count_following_siblings for usage examples.

pub fn count_ancestors(&self) -> usize

Returns the number of ancestors.

Note that this is O(N) operation.

See Node::count_ancestors for usage examples.

impl<T> HotNode<T>

Tree traverser.

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

Returns the depth-first traverser.

See Node::depth_first_traverse for usage examples.

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

Returns the reverse depth-first traverser.

See Node::depth_first_reverse_traverse for usage examples.

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

Returns the children traverser.

See Node::children for usage examples.

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

Returns the reverse children traverser.

See Node::children_reverse for usage examples.

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

Returns the ancestors traverser.

See Node::ancestors for usage examples.

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

Returns the ancestors traverser.

See Node::ancestors_or_self for usage examples.

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

Returns the siblings traverser.

See Node::siblings for usage examples.

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

Returns the reverse siblings traverser.

See Node::siblings_reverse for usage examples.

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

Returns the preceding siblings traverser.

See Node::preceding_siblings_or_self_reverse for usage examples.

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

Returns the preceding siblings traverser.

See Node::preceding_siblings_reverse for usage examples.

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

Returns the following siblings traverser.

See Node::following_siblings_or_self for usage examples.

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

Returns the following siblings traverser.

See Node::following_siblings for usage examples.

impl<T> HotNode<T>

Node creation and hierarchy modification.

pub fn new_tree(root_data: T) -> Self

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

Examples

use dendron::HotNode;

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

pub fn detach_subtree(&self)

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

See Node::detach_subtree for usage examples.

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

Creates a node as the next sibling of self, and returns the new node.

See Node::try_create_node_as for usage examples.

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

Creates a node as the next sibling of self, and returns the new node.

See Node::create_node_as for usage examples.

Panics

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

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

Creates a node as the first child of self.

See Node::create_as_first_child for usage examples.

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

Creates a node as the last child of self.

See Node::create_as_last_child for usage examples.

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

Creates a node as the previous sibling of self.

See Node::try_create_as_prev_sibling for usage examples.

Failures

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

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

Creates a node as the previous sibling of self.

See Node::try_create_as_prev_sibling for usage examples.

Panics

Panics if self is a root node.

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

Creates a node as the next sibling of self.

See Node::try_create_as_next_sibling for usage examples.

Failures

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

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

Creates a node as the next sibling of self.

See Node::try_create_as_next_sibling for usage examples.

Failures

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

pub fn try_replace_with_children(&self) -> 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)

See Node::try_replace_with_children for usage examples.

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.

pub fn replace_with_children(&self)

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 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<Node<T>, BorrowError> where
    T: Clone, 

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

See Node::try_clone_subtree for usage examples.

Failures

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

pub fn clone_subtree(&self) -> Node<T> where
    T: Clone, 

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

See Node::try_clone_subtree for usage examples.

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<Self, 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.

See Node::try_clone_insert_subtree for usage examples.

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.

pub fn clone_insert_subtree(&self, dest: InsertAs<&HotNode<T>>) -> Self 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,
    dest: InsertAs<&HotNode<T>>
) -> Result<(), HierarchyError>

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

Returns the root node of the transplanted subtree.

See Node::try_detach_insert_subtree for usage examples.

pub fn detach_insert_subtree(&self, 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: Clone> HotNode<T>

Serialization.

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

Returns an iterator of serialized events for the subtree.

See Node::to_events for usage examples.

impl<T> HotNode<T>

Debug printing.

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

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

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.

See Node::debug_pretty_print for usage and example output.

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

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

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.

See Node::debug_print_local for usage.

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

Returns a debug-printable proxy that also dumps descendants recursively.

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.

See Node::debug_print_subtree for usage.

Trait Implementations

impl<T> Clone for HotNode<T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for HotNode<T>

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

Formats the value using the given formatter.

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<U>> PartialEq<&'_ FrozenNode<U>> for HotNode<T> where
    T: PartialEq<U>, 

fn eq(&self, other: &&FrozenNode<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &&HotNode<U>) -> 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.

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

This method tests for !=.

impl<T, U: PartialEq<U>> PartialEq<&'_ HotNode<U>> for FrozenNode<T> where
    T: PartialEq<U>, 

fn eq(&self, other: &&HotNode<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &&Node<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &FrozenNode<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &FrozenNode<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &HotNode<U>) -> 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 and plain method.

Examples

See the documentation for Node::try_eq method.

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

This method tests for !=.

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

fn eq(&self, other: &HotNode<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &HotNode<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &HotNode<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &HotNode<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &Node<U>) -> 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.

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

This method tests for !=.

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

fn eq(&self, other: &Node<U>) -> 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.

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

This method tests for !=.

impl<T: Eq> Eq for HotNode<T>