Merge branch 'master' into traversals

Author: spearman

examples/formatted.rs

@@ -0,0 +1,34 @@
+extern crate slab_tree;
+
+use slab_tree::*;
+
+fn main() {
+    let mut tree = TreeBuilder::new().with_root(0).build();
+    let mut root = tree.root_mut().unwrap();
+    {
+        let mut one = root.append(1);
+        let mut two = one.append(2);
+        two.append(3);
+        two.append(4);
+    }
+    {
+        let mut five = root.append(5);
+        five.append(6).append(7);
+        five.append(8);
+    }
+    root.append(9);
+
+    let mut s = String::new();
+    // 0
+    // ├── 1
+    // │   └── 2
+    // │       ├── 3
+    // │       └── 4
+    // ├── 5
+    // │   ├── 6
+    // │   │   └── 7
+    // │   └── 8
+    // └── 9
+    tree.write_formatted(&mut s).unwrap();
+    print!("{}", s);
+}

src/tree.rs

@@ -376,6 +376,89 @@ impl<T> Default for Tree<T> {
     }
 }
 
+impl<T: std::fmt::Debug> Tree<T> {
+    /// Write formatted tree representation and nodes with debug formatting.
+    ///
+    /// Example:
+    ///
+    /// ```
+    /// use slab_tree::tree::TreeBuilder;
+    ///
+    /// let mut tree = TreeBuilder::new().with_root(0).build();
+    /// let mut root = tree.root_mut().unwrap();
+    /// root.append(1)
+    ///     .append(2);
+    /// root.append(3);
+    /// let mut s = String::new();
+    /// tree.write_formatted(&mut s).unwrap();
+    /// assert_eq!(&s, "\
+    /// 0
+    /// ├── 1
+    /// │   └── 2
+    /// └── 3
+    /// ");
+    /// ```
+    ///
+    /// Writes nothing if the tree is empty.
+    ///
+    /// ```
+    /// use slab_tree::tree::TreeBuilder;
+    ///
+    /// let tree = TreeBuilder::<i32>::new().build();
+    /// let mut s = String::new();
+    /// tree.write_formatted(&mut s).unwrap();
+    /// assert_eq!(&s, "");
+    /// ```
+    pub fn write_formatted<W: std::fmt::Write>(&self, w: &mut W) -> std::fmt::Result {
+        if let Some(root) = self.root() {
+            let node_id = root.node_id();
+            let childn = 0;
+            let level = 0;
+            let last = vec![];
+            let mut stack = vec![(node_id, childn, level, last)];
+            while let Some((node_id, childn, level, last)) = stack.pop() {
+                debug_assert_eq!(
+                    last.len(),
+                    level,
+                    "each previous level should indicate whether it has reached the last node"
+                );
+                let node = self
+                    .get(node_id)
+                    .expect("getting node of existing node ref id");
+                if childn == 0 {
+                    for i in 1..level {
+                        if last[i - 1] {
+                            write!(w, "    ")?;
+                        } else {
+                            write!(w, "│   ")?;
+                        }
+                    }
+                    if level > 0 {
+                        if last[level - 1] {
+                            write!(w, "└── ")?;
+                        } else {
+                            write!(w, "├── ")?;
+                        }
+                    }
+                    writeln!(w, "{:?}", node.data())?;
+                }
+                let mut children = node.children().skip(childn);
+                if let Some(child) = children.next() {
+                    let mut next_last = last.clone();
+                    if children.next().is_some() {
+                        stack.push((node_id, childn + 1, level, last));
+                        next_last.push(false);
+                    } else {
+                        next_last.push(true);
+                    }
+                    stack.push((child.node_id(), 0, level + 1, next_last));
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
 #[cfg_attr(tarpaulin, skip)]
 #[cfg(test)]
 mod tree_tests {