Add BinarySearchTree exercise. (#550)

config.json

@@ -893,6 +893,14 @@
         "practices": [],
         "prerequisites": [],
         "difficulty": 5
+      },
+      {
+        "slug": "binary-search-tree",
+        "name": "Binary Search Tree",
+        "uuid": "e13c2b59-75c1-4415-a439-b548721ebdbc",
+        "practices": [],
+        "prerequisites": [],
+        "difficulty": 3
       }
     ]
   },

exercises/practice/binary-search-tree/.docs/instructions.md

@@ -0,0 +1,47 @@
+# Instructions
+
+Insert and search for numbers in a binary tree.
+
+When we need to represent sorted data, an array does not make a good data structure.
+
+Say we have the array `[1, 3, 4, 5]`, and we add 2 to it so it becomes `[1, 3, 4, 5, 2]`.
+Now we must sort the entire array again!
+We can improve on this by realizing that we only need to make space for the new item `[1, nil, 3, 4, 5]`, and then adding the item in the space we added.
+But this still requires us to shift many elements down by one.
+
+Binary Search Trees, however, can operate on sorted data much more efficiently.
+
+A binary search tree consists of a series of connected nodes.
+Each node contains a piece of data (e.g. the number 3), a variable named `left`, and a variable named `right`.
+The `left` and `right` variables point at `nil`, or other nodes.
+Since these other nodes in turn have other nodes beneath them, we say that the left and right variables are pointing at subtrees.
+All data in the left subtree is less than or equal to the current node's data, and all data in the right subtree is greater than the current node's data.
+
+For example, if we had a node containing the data 4, and we added the data 2, our tree would look like this:
+
+      4
+     /
+    2
+
+If we then added 6, it would look like this:
+
+      4
+     / \
+    2   6
+
+If we then added 3, it would look like this
+
+       4
+     /   \
+    2     6
+     \
+      3
+
+And if we then added 1, 5, and 7, it would look like this
+
+          4
+        /   \
+       /     \
+      2       6
+     / \     / \
+    1   3   5   7

exercises/practice/binary-search-tree/.meta/config.json

@@ -0,0 +1,10 @@
+{
+  "blurb": "Insert and search for numbers in a binary tree.",
+  "authors": ["MichaelBunker"],
+  "contributors": [],
+  "files": {
+    "solution": ["BinarySearchTree.php"],
+    "test": ["BinarySearchTreeTest.php"],
+    "example": [".meta/example.php"]
+  }
+}

exercises/practice/binary-search-tree/.meta/example.php

@@ -0,0 +1,71 @@
+<?php
+
+/*
+ * By adding type hints and enabling strict type checking, code can become
+ * easier to read, self-documenting and reduce the number of potential bugs.
+ * By default, type declarations are non-strict, which means they will attempt
+ * to change the original type to match the type specified by the
+ * type-declaration.
+ *
+ * In other words, if you pass a string to a function requiring a float,
+ * it will attempt to convert the string value to a float.
+ *
+ * To enable strict mode, a single declare directive must be placed at the top
+ * of the file.
+ * This means that the strictness of typing is configured on a per-file basis.
+ * This directive not only affects the type declarations of parameters, but also
+ * a function's return type.
+ *
+ * For more info review the Concept on strict type checking in the PHP track
+ * <link>.
+ *
+ * To disable strict typing, comment out the directive below.
+ */
+
+declare(strict_types=1);
+
+class BinarySearchTree
+{
+    public ?BinarySearchTree $left;
+    public ?BinarySearchTree $right;
+    public int $data;
+
+    public function __construct(int $data)
+    {
+        $this->data  = $data;
+        $this->left  = null;
+        $this->right = null;
+    }
+
+    public function insert(int $data): self
+    {
+        $data <= $this->data ? $this->addLeftNode($data) : $this->addRightNode($data);
+
+        return $this;
+    }
+
+    public function getSortedData(): array
+    {
+        $data[] = $this->data;
+
+        if ($this->left) {
+            $data = array_merge($this->left->getSortedData(), $data);
+        }
+
+        if ($this->right) {
+            $data = array_merge($data, $this->right->getSortedData());
+        }
+
+        return $data;
+    }
+
+    private function addLeftNode(int $data): void
+    {
+        $this->left = $this->left ? $this->left->insert($data) : new BinarySearchTree($data);
+    }
+
+    private function addRightNode(int $data): void
+    {
+        $this->right = $this->right ? $this->right->insert($data) : new BinarySearchTree($data);
+    }
+}

exercises/practice/binary-search-tree/BinarySearchTree.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * By adding type hints and enabling strict type checking, code can become
+ * easier to read, self-documenting and reduce the number of potential bugs.
+ * By default, type declarations are non-strict, which means they will attempt
+ * to change the original type to match the type specified by the
+ * type-declaration.
+ *
+ * In other words, if you pass a string to a function requiring a float,
+ * it will attempt to convert the string value to a float.
+ *
+ * To enable strict mode, a single declare directive must be placed at the top
+ * of the file.
+ * This means that the strictness of typing is configured on a per-file basis.
+ * This directive not only affects the type declarations of parameters, but also
+ * a function's return type.
+ *
+ * For more info review the Concept on strict type checking in the PHP track
+ * <link>.
+ *
+ * To disable strict typing, comment out the directive below.
+ */
+
+declare(strict_types=1);
+
+class BinarySearchTree
+{
+    public ?BinarySearchTree $left;
+    public ?BinarySearchTree $right;
+    public int $data;
+
+    public function insert(int $data)
+    {
+        throw new \BadMethodCallException(sprintf('Implement the %s method', __FUNCTION__));
+    }
+
+    public function getSortedData(): array
+    {
+        throw new \BadMethodCallException(sprintf('Implement the %s method', __FUNCTION__));
+    }
+}

exercises/practice/binary-search-tree/BinarySearchTreeTest.php

@@ -0,0 +1,128 @@
+<?php
+
+/*
+ * By adding type hints and enabling strict type checking, code can become
+ * easier to read, self-documenting and reduce the number of potential bugs.
+ * By default, type declarations are non-strict, which means they will attempt
+ * to change the original type to match the type specified by the
+ * type-declaration.
+ *
+ * In other words, if you pass a string to a function requiring a float,
+ * it will attempt to convert the string value to a float.
+ *
+ * To enable strict mode, a single declare directive must be placed at the top
+ * of the file.
+ * This means that the strictness of typing is configured on a per-file basis.
+ * This directive not only affects the type declarations of parameters, but also
+ * a function's return type.
+ *
+ * For more info review the Concept on strict type checking in the PHP track
+ * <link>.
+ *
+ * To disable strict typing, comment out the directive below.
+ */
+
+declare(strict_types=1);
+
+class BinarySearchTreeTest extends PHPUnit\Framework\TestCase
+{
+    public static function setUpBeforeClass(): void
+    {
+        require_once 'BinarySearchTree.php';
+    }
+
+    public function testDataIsRetained(): void
+    {
+        $tree = new BinarySearchTree(4);
+        $this->assertEquals(4, $tree->data);
+    }
+
+    public function testSmallNumberAtLeftNode(): void
+    {
+        $tree = new BinarySearchTree(4);
+        $tree->insert(2);
+
+        $this->assertEquals(4, $tree->data);
+        $this->assertEquals(2, $tree->left->data);
+    }
+
+    public function testSameNumberLeftNodes(): void
+    {
+        $tree = new BinarySearchTree(4);
+        $tree->insert(4);
+
+        $this->assertEquals(4, $tree->data);
+        $this->assertEquals(4, $tree->left->data);
+    }
+
+    public function testGreaterNumberRightNode(): void
+    {
+        $tree = new BinarySearchTree(4);
+        $tree->insert(5);
+
+        $this->assertEquals(4, $tree->data);
+        $this->assertEquals(5, $tree->right->data);
+    }
+
+    public function testCreateComplexTree(): void
+    {
+        $tree = new BinarySearchTree(4);
+        $tree->insert(2);
+        $tree->insert(6);
+        $tree->insert(1);
+        $tree->insert(3);
+        $tree->insert(5);
+        $tree->insert(7);
+
+        $this->assertEquals(4, $tree->data);
+        $this->assertEquals(2, $tree->left->data);
+        $this->assertEquals(1, $tree->left->left->data);
+        $this->assertEquals(3, $tree->left->right->data);
+        $this->assertEquals(6, $tree->right->data);
+        $this->assertEquals(5, $tree->right->left->data);
+        $this->assertEquals(7, $tree->right->right->data);
+    }
+
+    public function testCanSortSingleNode(): void
+    {
+        $tree = new BinarySearchTree(2);
+
+        $this->assertEquals([2], $tree->getSortedData());
+    }
+
+    public function testCanSortSmallerSecondNumber(): void
+    {
+        $tree = new BinarySearchTree(2);
+        $tree->insert(1);
+
+        $this->assertEquals([1, 2], $tree->getSortedData());
+    }
+
+    public function testCanSortSameNumbers(): void
+    {
+        $tree = new BinarySearchTree(2);
+        $tree->insert(2);
+
+        $this->assertEquals([2, 2], $tree->getSortedData());
+    }
+
+    public function testCanSortGreaterSecondNumber(): void
+    {
+        $tree = new BinarySearchTree(2);
+        $tree->insert(3);
+
+        $this->assertEquals([2, 3], $tree->getSortedData());
+    }
+
+    public function testCanSortComplexTree(): void
+    {
+        $tree = new BinarySearchTree(2);
+        $tree->insert(1);
+        $tree->insert(3);
+        $tree->insert(6);
+        $tree->insert(7);
+        $tree->insert(5);
+
+        $this->assertEquals([1, 2, 3, 5, 6, 7], $tree->getSortedData());
+    }
+}