Merge branch 'master' of github.com:mgechev/javascript-algorithms

* 'master' of github.com:mgechev/javascript-algorithms:
  more doc fixes.
  Added more docs for datastructures.
  Added linked list spec.
  added new line.
  Basic heap specs. typo in heap.
  BST remove root with children bug fix.
  AVL Tree balance on removal. Added remove specs.

Author: mgechev

src/data-structures/avl-tree.js

@@ -93,6 +93,94 @@
     return true;
   };
 
+  /**
+   * Gets the nodes to be restructured during an AVL restructure
+   * after a remove/delete takes place.
+   *
+   * @public
+   * @method
+   * @param {Array} traveledNodes Array of previously traveled nodes
+   * that are used to help determine the nodes to be restructured.
+   */
+  exports.AVLTree.prototype._getNodesToRestructureRemove =
+    function (traveledNodes) {
+    // z is last traveled node - imbalance found at z
+    var zIndex = traveledNodes.length;
+    zIndex -= 1;
+    var z = traveledNodes[zIndex];
+    // y should be child of z with larger height
+    // (cannot be ancestor of removed node)
+    var y;
+    if (z._left !== null && z._right !== null){
+      y = (z._left === y) ? z._right : z._left;
+    }else if (z._left !== null && z._right === null){
+      y = z._left;
+    }else if (z._right !== null && z._left === null){
+      y = z._right;
+    }
+    // x should be tallest child of y.
+    // If children same height, x should be child of y
+    // that has same orientation as z to y.
+    var x;
+    if (y._left !== null && y._right !== null){
+      if (y._left._height > y._right._height){
+        x = y._left;
+      }else if (y._left._height < y._right._height){
+        x = y._right;
+      }else if (y._left._height === y._right._height){
+        x = (z._left === y) ? y._left : y._right;
+      }
+    }else if (y._left !== null && y._right === null){
+      x = y._left;
+    }else if (y._right !== null && y._left === null){
+      x = y._right;
+    }
+    return [x, y, z];
+  };
+
+  /**
+   * Gets the nodes to be restructured during an AVL restructure
+   * after an insert takes place.
+   *
+   * @public
+   * @method
+   * @param {Array} traveledNodes Array of previously traveled nodes
+   * that are used to help determine the nodes to be restructured.
+   */
+  exports.AVLTree.prototype._getNodesToRestructureInsert =
+    function (traveledNodes) {
+    // z is last traveled node - imbalance found at z
+    var zIndex = traveledNodes.length;
+    zIndex -= 1;
+    var z = traveledNodes[zIndex];
+    // y should be child of z with larger height
+    // (must be ancestor of inserted node)
+    // therefore, last traveled node is correct.
+    var yIndex = traveledNodes.length;
+    yIndex -= 2;
+    var y = traveledNodes[yIndex];
+    // x should be tallest child of y.
+    // If children same height, x should be ancestor
+    // of inserted node (in traveled path).
+    var x;
+    if (y._left !== null && y._right !== null){
+      if (y._left._height > y._right._height){
+        x = y._left;
+      }else if (y._left._height < y._right._height){
+        x = y._right;
+      }else if (y._left._height === y._right._height){
+        var xIndex = traveledNodes.length;
+        xIndex -= 3;
+        x = traveledNodes[xIndex];
+      }
+    }else if (y._left !== null && y._right === null){
+      x = y._left;
+    }else if (y._right !== null && y._left === null){
+      x = y._right;
+    }
+    return [x, y, z];
+  };
+
   /**
    * Maintains the height balance property by
    * walking to root and checking for invalid height
@@ -102,21 +190,20 @@
    * @public
    * @method
    * @param {Node} node Started node.
+   * @param {Boolean} isRemove Represents if method was called after remove.
    */
-  exports.AVLTree.prototype._maintainHeightBalanceProperty = function (node) {
+  exports.AVLTree.prototype._maintainHeightBalanceProperty =
+    function (node, isRemove) {
     var current = node;
-    var path = []; //During restructure, use last 3 nodes traveled.
+    var traveledNodes = [];
     while (current !== null){
-      path.push(current);
+      traveledNodes.push(current);
       current._height = this._getHeightAtNode(current);
       if (!this._isBalancedAtNode(current)){
-        if (path.length >= 3){
-          var nodesToRestructure = path.slice(0, 3);
-          var x = nodesToRestructure[0];
-          var y = nodesToRestructure[1];
-          var z = nodesToRestructure[2];
-          this._restructure(x, y, z);
-        }
+        var nodesToBeRestructured = (isRemove)
+          ? this._getNodesToRestructureRemove(traveledNodes)
+          : this._getNodesToRestructureInsert(traveledNodes);
+        this._restructure(nodesToBeRestructured);
       }
       current = current._parent;
     }
@@ -128,11 +215,13 @@
    *
    * @public
    * @method
-   * @param {Node} x node with lowest height to be restructured.
-   * @param {Node} y parent of x parameter.
-   * @param {Node} z grandparent of x, largest height.
+   * @param {Array} nodesToBeRestructured
+   * array of nodes, in format, [x, y, z], to be restructured
    */
-  exports.AVLTree.prototype._restructure = function (x, y, z) {
+  exports.AVLTree.prototype._restructure = function (nodesToBeRestructured) {
+    var x = nodesToBeRestructured[0];
+    var y = nodesToBeRestructured[1];
+    var z = nodesToBeRestructured[2];
     //Determine Rotation Pattern
     if (z._right === y && y._right === x){
       this._rightRight(x, y, z);
@@ -337,7 +426,7 @@
     }
     if (!current[insertKey]) {
       current[insertKey] = new exports.Node(value, null, null, current);
-      this._maintainHeightBalanceProperty(current[insertKey]);
+      this._maintainHeightBalanceProperty(current[insertKey], false);
     } else {
       this.insert(value, current[insertKey]);
     }
@@ -481,9 +570,11 @@
    */
   exports.AVLTree.prototype._replaceChild =
    function (parent, oldChild, newChild) {
-    if (!parent) {
+    if (parent === null) {
       this._root = newChild;
-      this._root._parent = null;
+      if (this._root !== null){
+        this._root._parent = null;
+      }
     } else {
       if (parent._left === oldChild) {
         parent._left = newChild;
@@ -501,33 +592,31 @@
    * Average runtime complexity: O(log N).
    *
    * @public
-   * @param {Node} node to be removed
+   * @param {Number|String} value of node to be removed
    * @returns {Boolean} True/false depending
    *    on whether the given node is removed.
    */
-  exports.AVLTree.prototype.remove = function (node) {
+  exports.AVLTree.prototype.remove = function (value) {
+    var node = this.find(value);
     if (!node) {
       return false;
     }
-
     if (node._left && node._right) {
       var min = this._findMin(node._right);
       var temp = node.value;
-
       node.value = min.value;
       min.value = temp;
       return this.remove(min);
     } else {
-      if (node._parent !== null) {
-        if (node._left) {
-          this._replaceChild(node._parent, node, node._left);
-        } else if (node._right) {
-          this._replaceChild(node._parent, node, node._right);
-        } else {
-          this._replaceChild(node._parent, node, null);
-        }
-      }else {
-        this._root = null;
+      if (node._left) {
+        this._replaceChild(node._parent, node, node._left);
+        this._maintainHeightBalanceProperty(node._left, true);
+      } else if (node._right) {
+        this._replaceChild(node._parent, node, node._right);
+        this._maintainHeightBalanceProperty(node._right, true);
+      } else {
+        this._replaceChild(node._parent, node, null);
+        this._maintainHeightBalanceProperty(node._parent, true);
       }
       return true;
     }
@@ -656,12 +745,12 @@
    * @returns {Node} The lowest common ancestor of the two nodes or null.
    */
   exports.AVLTree.prototype.lowestCommonAncestor =
-   function (firstNode, secondNode) {
+    function (firstNode, secondNode) {
     return this._lowestCommonAncestor(firstNode, secondNode, this._root);
   };
 
   exports.AVLTree.prototype._lowestCommonAncestor =
-   function (firstNode, secondNode, current) {
+    function (firstNode, secondNode, current) {
     var firstNodeInLeft = this._existsInSubtree(firstNode, current._left);
     var secondNodeInLeft = this._existsInSubtree(secondNode, current._left);
     var firstNodeInRight = this._existsInSubtree(firstNode, current._right);

src/data-structures/binary-search-tree.js

@@ -225,7 +225,9 @@
    function (parent, oldChild, newChild) {
     if (!parent) {
       this._root = newChild;
-      this._root._parent = null;
+      if (this._root !== null){
+        this._root._parent = null;
+      }
     } else {
       if (parent._left === oldChild) {
         parent._left = newChild;
@@ -251,25 +253,19 @@
     if (!node) {
       return false;
     }
-
     if (node._left && node._right) {
       var min = this._findMin(node._right);
       var temp = node.value;
-
       node.value = min.value;
       min.value = temp;
       return this.remove(min);
     } else {
-      if (node._parent !== null) {
-        if (node._left) {
-          this._replaceChild(node._parent, node, node._left);
-        } else if (node._right) {
-          this._replaceChild(node._parent, node, node._right);
-        } else {
-          this._replaceChild(node._parent, node, null);
-        }
-      }else {
-        this._root = null;
+      if (node._left) {
+        this._replaceChild(node._parent, node, node._left);
+      } else if (node._right) {
+        this._replaceChild(node._parent, node, node._right);
+      } else {
+        this._replaceChild(node._parent, node, null);
       }
       return true;
     }
@@ -334,6 +330,13 @@
     return this._findMax(this._root);
   };
 
+  /**
+   * Checks if a given node is balanced.
+   *
+   * @private
+   * @param {Node} current Node to have balance checked.
+   * @returns {Boolean} Boolean of whether or not provided node is balanced.
+   */
   exports.BinaryTree.prototype._isBalanced = function (current) {
     if (!current) {
       return true;
@@ -383,6 +386,13 @@
     return this._getHeight(this._root);
   };
 
+  /**
+   * Recursive worker function for getHeight()
+   *
+   * @private
+   * @param {Node} node Node at current recursive frame.
+   * @returns {Number} Height of the Node in the parameter.
+   */
   exports.BinaryTree.prototype._getHeight = function (node) {
     if (!node) {
       return 0;
@@ -395,13 +405,28 @@
    * Finds the lowest common ancestor of two nodes.
    *
    * @public
+   * @param {Node} firstNode First node to be considered when checking
+   * for ancestor.
+   * @param {Node} secondNode Second node to be considered when checking
+   * for ancestor.
    * @returns {Node} The lowest common ancestor of the two nodes or null.
    */
   exports.BinaryTree.prototype.lowestCommonAncestor =
    function (firstNode, secondNode) {
     return this._lowestCommonAncestor(firstNode, secondNode, this._root);
   };
 
+  /**
+   * Obtains the lowest common ancestor for the given nodes.
+   *
+   * @private
+   * @param {Node} firstNode First node to be considered when checking
+   * for ancestor.
+   * @param {Node} secondNode Second node to be considered when checking
+   * for ancestor.
+   * @param {Node} current Current node.
+   * @returns {Node} The lowest common ancestor of the two nodes or null.
+   */
   exports.BinaryTree.prototype._lowestCommonAncestor =
    function (firstNode, secondNode, current) {
     var firstNodeInLeft = this._existsInSubtree(firstNode, current._left);
@@ -421,6 +446,14 @@
     return null;
   };
 
+  /**
+   * Checks if a given node exists in a subtree.
+   *
+   * @private
+   * @param {Node} node Node to check for.
+   * @param {Node} root Root node of a given subtree.
+   * @returns {Node} The lowest common ancestor of the two nodes or null.
+   */
   exports.BinaryTree.prototype._existsInSubtree = function (node, root) {
     if (!root) {
       return false;

src/data-structures/heap.js

@@ -47,7 +47,7 @@
    *
    * @public
    * @constructor
-   * @param {Function} cmp Function used for comparition between the elements.
+   * @param {Function} cmp Function used for comparison between the elements.
    */
   exports.Heap = function (cmp) {
     this._heap = [];

src/data-structures/linked-list.js

@@ -165,7 +165,7 @@
   };
 
   /**
-   * Check or linked list contains cycle.
+   * Check if linked list contains cycle.
    *
    * @public
    * @method
@@ -222,6 +222,12 @@
     return temp;
   };
 
+  /**
+   * Reverses the linked list recursively
+   *
+   * @public
+   * @method
+   */
   exports.LinkedList.prototype.recursiveReverse = function () {
 
     function inverse(current, next) {
@@ -242,6 +248,12 @@
     this.last = temp;
   };
 
+  /**
+   * Reverses the linked list iteratively
+   *
+   * @public
+   * @method
+   */
   exports.LinkedList.prototype.reverse = function () {
     if (!this.first || !this.first.next) {
       return;