Struct dendron::tree::Tree

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

A reference to the tree, with shared ownership.

Tree cannot exist without the root node, so you should create tree by creating a new root node. See Node::new_tree and HotNode::new_tree.

There are convenience macro to create a tree (tree!) or a root node (tree_node!).

Implementations

impl<T> Tree<T>

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

Returns the root node.

Examples

use dendron::{Tree, tree};

let tree = tree! {
    "root", ["0"]
};
//  root
//  `-- 0

assert_eq!(*tree.root().borrow_data(), "root");

pub fn prohibit_hierarchy_edit(
    &self
) -> Result<HierarchyEditProhibition<T>, HierarchyEditProhibitionError>

Prohibits the tree hierarchy edit.

Examples

use dendron::{Tree, tree};

let tree = tree! {
    "root", ["0"]
};
//  root
//  `-- 0

let prohibition = tree
    .prohibit_hierarchy_edit()
    .expect("hierarchy edit should not yet be granted");

assert!(prohibition.is_valid_for_node(&tree.root()));

pub fn grant_hierarchy_edit(
    &self
) -> Result<HierarchyEditGrant<T>, HierarchyEditGrantError>

Grants the tree hierarchy edit.

Examples

use dendron::{Tree, tree};

let tree = tree! {
    "root", ["0"]
};
//  root
//  `-- 0

let grant = tree
    .grant_hierarchy_edit()
    .expect("hierarchy edit should not yet be prohibition");

assert!(grant.is_valid_for_node(&tree.root()));

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

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

Examples

use dendron::tree;

let tree1 = tree!("root");
let tree2 = tree!("root");

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

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

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

Compares two trees.

Returns Ok(true) if the two trees 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, Tree};

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

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

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

let tree1_first_child_of_root = tree1.root()
    .first_child()
    .expect("the root of `tree1` has a child");
assert!(
    tree1_first_child_of_root
        .try_eq(&tree2.root())
        .expect("data are not borrowed"),
    "the first child of the root of tree1 and tree2 are equal"
);

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

Creates a new tree that a clone of the tree.

Tree type is a reference-conuted handle to the actual tree object, so Tree::clone (that is <Tree as Clone>::clone) does not duplicate the tree. Use this method to make an independent tree with the identical structure and content.

Failures

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

Examples

use dendron::tree;

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

let cloned = tree.try_clone_tree()
    .expect("data are currently not borrowed");

// Different allocation.
assert!(!tree.ptr_eq(&cloned));
// Identical content.
assert_eq!(tree, cloned);

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

Creates a new tree that a clone of the tree.

See try_clone_tree for detail.

Panics

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

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

Downgrades the reference to a weak one.

use dendron::tree;

let tree = tree!("root");
let tree_weak = tree.downgrade();
assert!(tree_weak.upgrade().is_some());

drop(tree);
assert!(tree_weak.upgrade().is_none());

impl<T> Tree<T>

Debug printing.

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

Returns the pretty-printable proxy object to the tree.

(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;

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

let printable = tree.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) -> DebugPrintTreeLocal<'_, T>

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

pub fn debug_print(&self) -> DebugPrintTree<'_, T>where
    T: Debug,

Returns a debug-printable proxy that dumps nodes.

Trait Implementations

impl<T> Clone for Tree<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 for Tree<T>

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

Formats the value using the given formatter.

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

fn eq(&self, other: &Tree<U>) -> bool

Compares two trees.

Returns Ok(true) if the two trees 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.

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.

impl<T: Eq> Eq for Tree<T>