Merge pull request #8 from CrimsonNynja/Binary-Heap

Binary heap

Author: CrimsonNynja

README.md

@@ -4,9 +4,9 @@
 
 This repo is designed to have all common trees used in an easy to use php way
 
-Current included are implementations of a Binary Search Tree, Rope and a Generic Tree, with more to come!
+Current included are implementations of a Binary Search Tree, Rope, Binary Heap, and a Generic Tree, with more to come!
 
-All tests are written in PHP Unit, and all code is written in the PSR-4 standards. Php Trees also requires PHP 7.2 or above
+All tests are written in PHP Unit, and all code is written in the PSR-4 standards. Php Trees also requires PHP 7.4 or above
 
 PHP Trees can be installed through composer with
 
@@ -23,23 +23,31 @@ To use the binary search tree, include the correct file and create it as such
 ```php
 use PhpTrees\BinarySearchTree;
 
-$b = new PhpTrees\BinarySearchTree(5);
+$b = new BinarySearchTree(5);
 ```
 
 To use the Rope
 
 ```php
 use PhpTrees\Rope;
 
-$r = new PhpTrees\Rope("This is a Rope!");
+$r = new Rope("This is a Rope!");
+```
+
+To use the Binary Heap
+
+```php
+use PhpTrees\BinaryHeap;
+
+$h = new BinaryHeap();
 ```
 
 To use the Generic Tree
 
 ```php
 use PhpTrees\GenericTree;
 
-$g = new PhpTrees\GenericTree(4.1);
+$g = new GenericTree(4.1);
 ```
 
 This will create a binary search tree with a root of the value 5\
@@ -50,6 +58,5 @@ For a more detailed description of the features of PHP Trees, check out the wiki
 
 tree balancing options\
 2-3 tree\
-Heep\
 B-Tree\
 search/traversal types (depth first search breadth first search, etc)

composer.json

@@ -2,7 +2,7 @@
     "name": "crimson-nynja/php-trees",
     "description": "PHP implementation of various Trees",
     "license": "GPL-3.0-or-later",
-    "keywords": ["PHP", "Trees", "Tree", "Binary Search Tree", "BST", "Rope"],
+    "keywords": ["PHP", "Trees", "Tree", "Binary Search Tree", "BST", "Rope", "Binary Heap", "Heap", "Generic Tree"],
     "authors": [
         {
             "name": "Hudson Cassidy",

composer.lock

@@ -0,0 +1,192 @@
+<?php
+
+namespace PhpTrees;
+
+/**
+ * implementation of a binary heap (currently just a Min Heap)
+ * this is an array implementation, and as such stores everything in an array internally
+ */
+class BinaryHeap
+{
+    /* internal array to store the heap in */
+    private array $heap = [];
+
+    /**
+     * constructs the heap with the initial root, if given
+     * as this is a heap the root value may not remain consistent
+     *
+     * @param mixed|null $root the initial root of the heap
+     */
+    public function __construct($root = null)
+    {
+        if ($root !== null) {
+            $this->insert($root);
+        }
+    }
+
+    /**
+     * constructs a heap from an array
+     * this function will be much faster then inserting each element from that array individually
+     * Note that if any values in the heap already exists, they will be replaced here
+     *
+     * @param array<mixed> $values the array to build the heap on
+     */
+    public function constructFromArray(array $values) : void
+    {
+        $this->heap = $values;
+        $this->heapify();
+    }
+
+    /**
+     * inserts a value into the heap
+     *
+     * @param mixed $value the value to add
+     */
+    public function insert($value) : void
+    {
+        $this->heap[] = $value;
+        $this->bubbleUp(sizeof($this->heap) - 1);
+    }
+
+    /**
+     * inserts multiple values into the heap
+     *
+     * @param mixed ...$values the variatic values to add, can be of differing types
+     */
+    public function insertMultiple(...$values) : void
+    {
+        foreach($values as $value) {
+            $this->insert($value);
+        }
+    }
+
+    /**
+     * deletes the minimum value from the heap
+     *
+     * @return mixed returns teh element removed
+     */
+    public function deleteMin()
+    {
+        if ($this->heap !== []) {
+            $ret = $this->heap[0];
+            $this->heap[0] = array_pop($this->heap);
+            $this->bubbleDown(0);
+            return $ret;
+        }
+    }
+
+    /**
+     * gets the smallest value in the heap, if it exists
+     *
+     * @return mixed|null the smallest value in the heap
+     */
+    public function getMinValue()
+    {
+        if ($this->heap !== []) {
+            return $this->heap[0];
+        }
+        return null;
+    }
+
+    /**
+     * gets the max element in the heap, if it exists
+     *
+     * @return mixed|null the maximum element in the heap
+     */
+    public function getMaxValue()
+    {
+        if ($this->heap !== []) {
+            $max = $this->heap[(int)sizeof($this->heap) / 2];
+            for ($i = 1 + (sizeof($this->heap) / 2); $i < sizeof($this->heap); ++$i) {
+                $max = max($max, $this->heap[$i]);
+            }
+            return $max;
+        }
+        return null;
+    }
+
+    /**
+     * gets the internal representation of the heap
+     *
+     * @return array the heap representation in the array
+     */
+    public function getInternalArray() : array
+    {
+        return $this->heap;
+    }
+
+    /**
+     * gets the amount of elements in the heap
+     *
+     * @return int the size of the heap
+     */
+    public function getSize() : int
+    {
+        return sizeof($this->heap);
+    }
+
+    /**
+     * rebuilds the heap. This is useful if you want a heap from an array
+     */
+    private function heapify() : void
+    {
+        for ($i = sizeof($this->heap) - 1; $i >= 0; --$i) {
+            $this->bubbleDown($i);
+        }
+    }
+
+    /**
+     * bubbles up the value in the heap, if it needs to
+     *
+     * @param int $index the index to start bubbling up from
+     */
+    private function bubbleUp(int $index) : void
+    {
+        if ($index === 0) {
+            return;
+        }
+
+        $parentIndex = (int)($index - 1) / 2;
+
+        if ($this->heap[$parentIndex] > $this->heap[$index]) {
+            $dummy = $this->heap[$parentIndex];
+            $this->heap[$parentIndex] = $this->heap[$index];
+            $this->heap[$index] = $dummy;
+            $this->bubbleUp($parentIndex);
+        }
+    }
+
+    /**
+     * turns an array into a heap
+     * more efficient then inserting each element individually if an array is already created
+     *
+     * @param int $index the index to bubble down on
+     */
+    private function bubbleDown(int $index) : void
+    {
+        $length = sizeof($this->heap);
+        $leftIndex = (2 * $index) + 1;
+        $rightIndex = (2 * $index) + 2;
+
+        if ($leftIndex >= $length) {
+            return;
+        }
+
+        $minIndex = $index;
+
+        if ($this->heap[$index] > $this->heap[$leftIndex]) {
+            $minIndex = $leftIndex;
+        }
+
+        if (($rightIndex < $length) && ($this->heap[$minIndex] > $this->heap[$rightIndex])) {
+            $minIndex = $rightIndex;
+        }
+
+        if ($minIndex !== $index) {
+            $dummy = $this->heap[$index];
+            $this->heap[$index] = $this->heap[$minIndex];
+            $this->heap[$minIndex] = $dummy;
+            $this->bubbleDown($minIndex);
+        }
+    }
+}