Struct Node

pub struct Node<T> {
    pub content: T,
    /* private fields */
}

A Node has 1 parent and multiple children. It also stores content of type T.

A Node is heap-allocated and pinned to allow storing a reference to the parent (Node is a self referential struct) without the data of said parent being moved. The pointer to the parent must be valid for the lifetime of the Node that holds the pointer.

Therefore, in theory, a stack-allocated unpinned Node should not exist, but that is ok as long as the Node has no children. The current implementation of the methods allows asserting that such Node has no children because adding children (i.e. using a mutable Node) requires it to be Pinned. A user can still use std::pin::pin! on a stack-allocated Node and add children to it, but the Node can’t be moved, and its children are dropped along with it, so the pointer it’s children hold remains valid for their lifetimes.

This allows the Node struct to implement traits that require returning a stack-allocated Node (e.g. Default and Clone). However, it is recommended to convert the returned Node into a Tree using Tree::from() or Node::into() as an “ez mode” for getting rid of compiler errors that are caused by trying to use &mut Node or trying to move it.

Fields

content: T

Implementations

impl<T> Node<T>

pub fn builder(content: T) -> NodeBuilder<T>

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

Get an immutable reference to the parent Node of self. To get a mutable reference, call crate::Tree::borrow_descendant() from the owner Tree with self.parent().ptr().

pub fn children(&self) -> Box<[&Self]>

Holds references to each child. /// To get a mutable reference to one of the children, call crate::Tree::borrow_descendant() from the owner Tree with self.parent().ptr().

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

Returns the Node immediately following this one in the parent’s children. Otherwise returns None if self has no parent, or if it is the last child of the parent.

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

Returns the Node immediately preceeding this one in the parent’s children. Otherwise returns None if self has no parent, or if it is the first child of the parent.

pub fn append_child(self: Pin<&mut Self>, child: Tree<T>)

Pushes the child to the end of self’s children. Also see Self::insert_child().

pub fn insert_child(self: Pin<&mut Self>, child: Tree<T>, index: usize)

Inserts the child to self’s children at some index. Also see Self::append_child().

pub fn iter_bfs(&self) -> IterBFS<'_, T>

Iterate over all the Nodes of the subtree (including self) using Breadth-First Search.

pub fn iter_dfs(&self) -> IterDFS<'_, T>

Iterate over all the Nodes of the subtree (including self) using Depth-First Search.

pub fn is_same_as(&self, other: impl AsPtr<Raw = Self>) -> bool

Whether two Nodes are the same (that is, they reference the same object).

pub fn ptr(&self) -> NonNull<Self>

Get a NonNull pointer for self, which should only be treated as a *const Self. Useful for Tree::detach_descendant and Tree::borrow_descendant.

impl<T: Clone> Node<T>

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

Copies the Node’s content and its children recursively. The resulting cloned Node will have no parent.

For a method that clones the Node but not its subtree, see Node::clone.

impl<T: Debug> Node<T>

pub fn debug_tree(&self) -> DebugTree<'_, T>

Debug the entire subtree (self and its children).

Trait Implementations

impl<T: Clone> Clone for Node<T>

fn clone(&self) -> Self

Copies the Node’s content, but not its children. The resulting cloned Node will have no parent or children.

Converting the returned Node to a Tree is recommended.

For a method that clones the Node and its subtree, see Node::clone_deep.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<T: Default> Default for Node<T>

fn default() -> Self

Creates a Node with the Default content. Converting the returned Node to a Tree is recommended.

impl<T: PartialEq> PartialEq for Node<T>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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