child function is now returning TreeNode

Develop

README.md

@@ -1,47 +1,73 @@
 # Tree (Data Structure)
-[![maven](https://img.shields.io/maven-central/v/com.github.adriankuta/tree-structure?style=plastic)](https://search.maven.org/artifact/com.github.adriankuta/tree-structure)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=plastic)](https://github.com/AdrianKuta/Design-Patterns-Kotlin/blob/master/LICENSE)
-[![CircleCI](https://img.shields.io/circleci/build/github/AdrianKuta/Tree-Data-Structure/master?label=CircleCI&style=plastic)](https://circleci.com/gh/AdrianKuta/Tree-Data-Structure)
+[![maven](https://img.shields.io/maven-central/v/com.github.adriankuta/tree-structure?style=plastic)](https://mvnrepository.com/artifact/com.github.adriankuta/tree-structure)
+[![License: MIT](https://img.shields.io/github/license/AdrianKuta/Tree-Data-Structure?style=plastic)](https://github.com/AdrianKuta/Design-Patterns-Kotlin/blob/master/LICENSE)
+[![CircleCI](https://img.shields.io/circleci/build/github/AdrianKuta/Tree-Data-Structure/master?label=CircleCI&style=plastic&logo=circleci)](https://circleci.com/gh/AdrianKuta/Tree-Data-Structure)
 
 Simple implementation to store object in tree structure. Method `toString()` is overrided to provide nice tree view in logs.
 
 ## Usage
 
+**Kotlin**
 ```kotlin
-val root = TreeNode<String>("Root")
-val beveragesNode = TreeNode<String>("Beverages")
-val curdNode = TreeNode<String>("Curd")
-root.addChild(beveragesNode)
-root.addChild(curdNode)
+val root = TreeNode("World")
+val northA = TreeNode("North America")
+val europe = TreeNode("Europe")
+root.addChild(northA)
+root.addChild(europe)
 
-val teaNode = TreeNode<String>("tea")
-val coffeeNode = TreeNode<String>("coffee")
-val milkShakeNode = TreeNode<String>("Milk Shake")
-beveragesNode.addChild(teaNode)
-beveragesNode.addChild(coffeeNode)
-beveragesNode.addChild(milkShakeNode)
+val usa = TreeNode("USA")
+northA.addChild(usa)
 
-val gingerTeaNode = TreeNode<String>("ginger tea")
-val normalTeaNode = TreeNode<String>("normal tea")
-teaNode.addChild(gingerTeaNode)
-teaNode.addChild(normalTeaNode)
+val poland = TreeNode("Poland")
+val france = TreeNode("France")
+europe.addChild(poland)
+europe.addChild(france)
+println(root.prettyString())
+```
 
-val yogurtNode = TreeNode<String>("yogurt")
-val lassiNode = TreeNode<String>("lassi")
-curdNode.addChild(yogurtNode)
-curdNode.addChild(lassiNode)
+**Pretty Kotlin**
 
-println(root)
-System.out.println("Remove: ${curdNode.value}")
-root.removeChild(curdNode)
-System.out.println("Remove: ${gingerTeaNode.value}")
-root.removeChild(gingerTeaNode)
-println(root)
+```kotlin
+val root =
+    tree("World") {
+        child("North America") {
+            child("USA")
+        }
+        child("Europe") {
+            child("Poland")
+            child("Germany")
+        }
+    }
+```
+
+**Java**
+```java
+TreeNode<String> root = new TreeNode<>("World");
+TreeNode<String> northA = new TreeNode<>("North America");
+TreeNode<String> europe = new TreeNode<>("Europe");
+root.addChild(northA);
+root.addChild(europe);
+
+TreeNode<String> usa = new TreeNode<>("USA");
+northA.addChild(usa);
+
+TreeNode<String> poland = new TreeNode<>("Poland");
+TreeNode<String> france = new TreeNode<>("France");
+europe.addChild(poland);
+europe.addChild(france);
+System.out.println(root.prettyString());
 ```
 
 *Output:*
 
-<img src="https://github.com/AdrianKuta/Tree-Collection/blob/master/images/console_output.png" width=400>
+```
+World
+├── North America
+│   └── USA
+└── Europe
+    ├── Poland
+    └── France
+```
 
 
 ## Download

_config.yml

@@ -0,0 +1,3 @@
+theme: jekyll-theme-minimal
+title: Tree Data Structure
+logo: images/console_output.png

treedatastructure/build.gradle

@@ -15,7 +15,7 @@ android {
         minSdkVersion 15
         targetSdkVersion 29
         versionCode 1
-        versionName "1.0.5"
+        versionName "1.2.3"
 
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
         consumerProguardFiles 'consumer-rules.pro'

treedatastructure/src/main/java/com/github/adriankuta/datastructure/tree/ChildDeclarationInterface.kt

@@ -0,0 +1,22 @@
+package com.github.adriankuta.datastructure.tree
+
+interface ChildDeclarationInterface<T> {
+
+    /**
+     * This method is used to easily create child in node.
+     * ```
+     * val root = tree("World") {
+     *     child("North America") {
+     *         child("USA")
+     *     }
+     *     child("Europe") {
+     *         child("Poland")
+     *         child("Germany")
+     *     }
+     * }
+     * ```
+     * @return New created TreeNode.
+     */
+    @JvmSynthetic
+    fun child(value: T, childDeclaration: ChildDeclaration<T>? = null): TreeNode<T>
+}

treedatastructure/src/main/java/com/github/adriankuta/datastructure/tree/TreeNode.kt

@@ -1,46 +1,101 @@
 package com.github.adriankuta.datastructure.tree
 
-class TreeNode<T>(val value: T) {
+open class TreeNode<T>(val value: T) : Iterable<TreeNode<T>>, ChildDeclarationInterface<T> {
 
-    private var parent: TreeNode<T>? = null
-    private val children = mutableListOf<TreeNode<T>>()
+    private var _parent: TreeNode<T>? = null
+    /**
+     * The converse notion of a child, an immediate ancestor.
+     */
+    val parent: TreeNode<T>?
+        get() = _parent
 
+    private val _children = mutableListOf<TreeNode<T>>()
+    /**
+     * A group of nodes with the same parent.
+     */
+    val children: List<TreeNode<T>>
+        get() = _children
+
+    /**
+     * Add new child to current node or root.
+     *
+     * @param child A node which will be directly connected to current node.
+     */
     fun addChild(child: TreeNode<T>) {
-        child.parent = this
-        children += child
+        child._parent = this
+        _children.add(child)
     }
 
+    @JvmSynthetic
+    override fun child(value: T, childDeclaration: ChildDeclaration<T>?): TreeNode<T> {
+        val newChild = TreeNode(value)
+        if(childDeclaration != null)
+            newChild.childDeclaration()
+        _children.add(newChild)
+        return newChild
+    }
+
+    /**
+     * Removes a single instance of the specified node from this tree, if it is present.
+     *
+     * @return `true` if the node has been successfully removed; `false` if it was not present in the tree.
+     */
     fun removeChild(child: TreeNode<T>): Boolean {
-        if (children.isEmpty()) {
-            return false
+        val removed = child._parent?._children?.remove(child)
+        child._parent = null
+        return removed ?: false
     }
 
-        val nestedChildRemoved = children.map {
-            it.removeChild(child)
-        }.reduce { acc, b -> acc or b }
-
-        return children.remove(child) or nestedChildRemoved
-    }
-
-    fun getParent(): TreeNode<T>? = parent
-
-    fun getChildren(): List<TreeNode<T>> = children
-
-    fun size(): Int {
-        if (children.isEmpty())
+    /**
+     * This function go through tree and counts children. Root element is not counted.
+     * @return All child and nested child count.
+     */
+    fun nodeCount(): Int {
+        if (_children.isEmpty())
             return 0
-        return children.size +
-                children.sumBy { it.size() }
-
+        return _children.size +
+                _children.sumBy { it.nodeCount() }
     }
 
-    fun depth(): Int {
-
-        val childrenMaxDepth = children.map { it.depth() }.max() ?: 0
+    /**
+     * @return The number of edges on the longest path between current node and a descendant leaf.
+     */
+    fun height(): Int {
+        val childrenMaxDepth = _children.map { it.height() }
+            .max()
+            ?: -1 // -1 because this method counts nodes, and edges are always one less then nodes.
         return childrenMaxDepth + 1
     }
 
+    /**
+     * Distance is the number of edges along the shortest path between two nodes.
+     * @return The distance between current node and the root.
+     */
+    fun depth(): Int {
+        var _depth = 0
+        var tempParent = parent
+
+        while (tempParent != null) {
+            _depth++
+            tempParent = tempParent.parent
+        }
+        return _depth
+    }
+
+    /**
+     * Remove all children from root and every node in tree.
+     */
+    fun clear() {
+        _parent = null
+        _children.forEach { it.clear() }
+        _children.clear()
+    }
+
     override fun toString(): String {
+        return value.toString()
+    }
+
+    fun prettyString(): String {
         val stringBuilder = StringBuilder()
         print(stringBuilder, "", "")
         return stringBuilder.toString()
@@ -50,14 +105,36 @@ class TreeNode<T>(val value: T) {
         stringBuilder.append(prefix)
         stringBuilder.append(value)
         stringBuilder.append('\n')
-        val childIterator = children.iterator()
+        val childIterator = _children.iterator()
         while (childIterator.hasNext()) {
             val node = childIterator.next()
-            if(childIterator.hasNext()) {
+            if (childIterator.hasNext()) {
                 node.print(stringBuilder, "$childrenPrefix├── ", "$childrenPrefix│   ")
             } else {
                 node.print(stringBuilder, "$childrenPrefix└── ", "$childrenPrefix    ")
             }
         }
     }
+
+    /**
+     * Tree is iterated by using `Pre-order Traversal Algorithm"
+     *  1. Check if the current node is empty or null.
+     *  2. Display the data part of the root (or current node).
+     *  3. Traverse the left subtree by recursively calling the pre-order function.
+     *  4. Traverse the right subtree by recursively calling the pre-order function.
+     * ```
+     * E.g.
+     *                    1
+     *                  / | \
+     *                 /  |   \
+     *               2    3     4
+     *              / \       / | \
+     *             5    6    7  8  9
+     *            /   / | \
+     *           10  11 12 13
+     *
+     * Output: 1 2 5 10 6 11 12 13 3 4 7 8 9
+     * ```
+     */
+    override fun iterator(): Iterator<TreeNode<T>> = TreeNodeIterator(this)
 }

treedatastructure/src/main/java/com/github/adriankuta/datastructure/tree/TreeNodeExt.kt

@@ -0,0 +1,18 @@
+package com.github.adriankuta.datastructure.tree
+
+typealias ChildDeclaration<T> = ChildDeclarationInterface<T>.() -> Unit
+
+/**
+ * This method can be used to initialize new tree.
+ * ```
+ * val root = tree("World") { ... }
+ * ```
+ * @param root Root element of new tree.
+ * @see [ChildDeclarationInterface.child]
+ */
+@JvmSynthetic
+inline fun<reified T> tree(root: T, childDeclaration: ChildDeclaration<T>): TreeNode<T> {
+    val treeNode = TreeNode(root)
+    treeNode.childDeclaration()
+    return treeNode
+}

treedatastructure/src/main/java/com/github/adriankuta/datastructure/tree/TreeNodeIterator.kt

@@ -0,0 +1,22 @@
+package com.github.adriankuta.datastructure.tree
+
+import java.util.*
+
+class TreeNodeIterator<T>(root: TreeNode<T>) : Iterator<TreeNode<T>> {
+
+    private val stack = Stack<TreeNode<T>>()
+
+    init {
+        stack.push(root)
+    }
+
+    override fun hasNext(): Boolean = !stack.empty()
+
+    override fun next(): TreeNode<T> {
+        val node = stack.pop()
+        node.children
+            .asReversed()
+            .forEach { stack.push(it) }
+        return node
+    }
+}

treedatastructure/src/test/java/com/github/adriankuta/datastructure/tree/TreeNodeTest.kt

@@ -0,0 +1,142 @@
+package com.github.adriankuta.datastructure.tree
+
+import org.hamcrest.CoreMatchers.`is`
+import org.hamcrest.CoreMatchers.nullValue
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertThat
+import org.junit.Test
+
+class TreeNodeTest {
+
+    @Test
+    fun removeNodeTest() {
+        val root = TreeNode<String>("Root")
+        val beveragesNode = TreeNode<String>("Beverages")
+        val curdNode = TreeNode<String>("Curd")
+        root.addChild(beveragesNode)
+        root.addChild(curdNode)
+
+        val teaNode = TreeNode<String>("tea")
+        val coffeeNode = TreeNode<String>("coffee")
+        val milkShakeNode = TreeNode<String>("Milk Shake")
+        beveragesNode.addChild(teaNode)
+        beveragesNode.addChild(coffeeNode)
+        beveragesNode.addChild(milkShakeNode)
+
+        val gingerTeaNode = TreeNode<String>("ginger tea")
+        val normalTeaNode = TreeNode<String>("normal tea")
+        teaNode.addChild(gingerTeaNode)
+        teaNode.addChild(normalTeaNode)
+
+        val yogurtNode = TreeNode<String>("yogurt")
+        val lassiNode = TreeNode<String>("lassi")
+        curdNode.addChild(yogurtNode)
+        curdNode.addChild(lassiNode)
+
+        assertEquals(
+            "Root\n" +
+                    "├── Beverages\n" +
+                    "│   ├── tea\n" +
+                    "│   │   ├── ginger tea\n" +
+                    "│   │   └── normal tea\n" +
+                    "│   ├── coffee\n" +
+                    "│   └── Milk Shake\n" +
+                    "└── Curd\n" +
+                    "    ├── yogurt\n" +
+                    "    └── lassi\n", root.toString()
+        )
+
+        System.out.println("Remove: ${curdNode.value}")
+        root.removeChild(curdNode)
+        System.out.println("Remove: ${gingerTeaNode.value}")
+        root.removeChild(gingerTeaNode)
+        assertEquals(
+            "Root\n" +
+                    "└── Beverages\n" +
+                    "    ├── tea\n" +
+                    "    │   └── normal tea\n" +
+                    "    ├── coffee\n" +
+                    "    └── Milk Shake\n", root.toString()
+        )
+    }
+
+    @Test
+    fun clearTest() {
+        val root = TreeNode<String>("Root")
+        val beveragesNode = TreeNode<String>("Beverages")
+        val curdNode = TreeNode<String>("Curd")
+        root.addChild(beveragesNode)
+        root.addChild(curdNode)
+
+        val teaNode = TreeNode<String>("tea")
+        val coffeeNode = TreeNode<String>("coffee")
+        val milkShakeNode = TreeNode<String>("Milk Shake")
+        beveragesNode.addChild(teaNode)
+        beveragesNode.addChild(coffeeNode)
+        beveragesNode.addChild(milkShakeNode)
+
+        val gingerTeaNode = TreeNode<String>("ginger tea")
+        val normalTeaNode = TreeNode<String>("normal tea")
+        teaNode.addChild(gingerTeaNode)
+        teaNode.addChild(normalTeaNode)
+
+        val yogurtNode = TreeNode<String>("yogurt")
+        val lassiNode = TreeNode<String>("lassi")
+        curdNode.addChild(yogurtNode)
+        curdNode.addChild(lassiNode)
+
+        println(root.toString())
+        println(curdNode.height())
+
+        root.clear()
+        assertThat(root.children, `is`(emptyList()))
+        assertThat(beveragesNode.children, `is`(emptyList()))
+        assertThat(curdNode.children, `is`(emptyList()))
+        assertThat(teaNode.children, `is`(emptyList()))
+        assertThat(coffeeNode.children, `is`(emptyList()))
+        assertThat(milkShakeNode.children, `is`(emptyList()))
+        assertThat(gingerTeaNode.children, `is`(emptyList()))
+        assertThat(normalTeaNode.children, `is`(emptyList()))
+        assertThat(yogurtNode.children, `is`(emptyList()))
+        assertThat(lassiNode.children, `is`(emptyList()))
+
+        assertThat(root.parent, `is`(nullValue()))
+        assertThat(beveragesNode.parent, `is`(nullValue()))
+        assertThat(curdNode.parent, `is`(nullValue()))
+        assertThat(teaNode.parent, `is`(nullValue()))
+        assertThat(coffeeNode.parent, `is`(nullValue()))
+        assertThat(milkShakeNode.parent, `is`(nullValue()))
+        assertThat(gingerTeaNode.parent, `is`(nullValue()))
+        assertThat(normalTeaNode.parent, `is`(nullValue()))
+        assertThat(yogurtNode.parent, `is`(nullValue()))
+        assertThat(lassiNode.parent, `is`(nullValue()))
+    }
+
+    @Test
+    fun kotlinExtTest() {
+        val root = TreeNode("World")
+        val northA = TreeNode("North America")
+        val europe = TreeNode("Europe")
+        root.addChild(northA)
+        root.addChild(europe)
+
+        val usa = TreeNode("USA")
+        northA.addChild(usa)
+
+        val poland = TreeNode("Poland")
+        val france = TreeNode("France")
+        europe.addChild(poland)
+        europe.addChild(france)
+
+        val rootExt = tree("World") {
+            child("North America") {
+                child("USA")
+            }
+            child("Europe") {
+                child("Poland")
+                child("France")
+            }
+        }
+        assertEquals(root.prettyString(), rootExt.prettyString())
+    }
+}