linked-list-typed 1.47.6 → 1.47.8

package/dist/data-structures/binary-tree/binary-tree.js

@@ -17,41 +17,22 @@ const queue_1 = require("../queue");
  * @template N - The type of the family relationship in the binary tree.
  */
 class BinaryTreeNode {
-    /**
-     * Creates a new instance of BinaryTreeNode.
-     * @param {BTNKey} key - The key associated with the node.
-     * @param {V} value - The value stored in the node.
-     */
     constructor(key, value) {
         this.key = key;
         this.value = value;
     }
-    /**
-     * Get the left child node.
-     */
     get left() {
         return this._left;
     }
-    /**
-     * Set the left child node.
-     * @param {N | null | undefined} v - The left child node.
-     */
     set left(v) {
         if (v) {
             v.parent = this;
         }
         this._left = v;
     }
-    /**
-     * Get the right child node.
-     */
     get right() {
         return this._right;
     }
-    /**
-     * Set the right child node.
-     * @param {N | null | undefined} v - The right child node.
-     */
     set right(v) {
         if (v) {
             v.parent = this;
@@ -78,13 +59,25 @@ class BinaryTreeNode {
 }
 exports.BinaryTreeNode = BinaryTreeNode;
 /**
- * Represents a binary tree data structure.
- * @template N - The type of the binary tree's nodes.
+ * 1. Two Children Maximum: Each node has at most two children.
+ * 2. Left and Right Children: Nodes have distinct left and right children.
+ * 3. Depth and Height: Depth is the number of edges from the root to a node; height is the maximum depth in the tree.
+ * 4. Subtrees: Each child of a node forms the root of a subtree.
+ * 5. Leaf Nodes: Nodes without children are leaves.
+ * 6. Internal Nodes: Nodes with at least one child are internal.
+ * 7. Balanced Trees: The heights of the left and right subtrees of any node differ by no more than one.
+ * 8. Full Trees: Every node has either 0 or 2 children.
+ * 9. Complete Trees: All levels are fully filled except possibly the last, filled from left to right.
  */
 class BinaryTree {
     /**
-     * Creates a new instance of BinaryTree.
-     * @param {BinaryTreeOptions} [options] - The options for the binary tree.
+     * The constructor function initializes a binary tree object with optional elements and options.
+     * @param [elements] - An optional iterable of BTNodeExemplar objects. These objects represent the
+     * elements to be added to the binary tree.
+     * @param [options] - The `options` parameter is an optional object that can contain additional
+     * configuration options for the binary tree. In this case, it is of type
+     * `Partial<BinaryTreeOptions>`, which means that not all properties of `BinaryTreeOptions` are
+     * required.
      */
     constructor(elements, options) {
         this.iterationType = types_1.IterationType.ITERATIVE;
@@ -97,17 +90,11 @@ class BinaryTree {
         }
         this._size = 0;
         if (elements)
-            this.init(elements);
+            this.addMany(elements);
     }
-    /**
-     * Get the root node of the binary tree.
-     */
     get root() {
         return this._root;
     }
-    /**
-     * Get the number of nodes in the binary tree.
-     */
     get size() {
         return this._size;
     }
@@ -120,30 +107,46 @@ class BinaryTree {
     createNode(key, value) {
         return new BinaryTreeNode(key, value);
     }
+    /**
+     * The function creates a binary tree with the given options.
+     * @param [options] - The `options` parameter is an optional object that allows you to customize the
+     * behavior of the `BinaryTree` class. It is of type `Partial<BinaryTreeOptions>`, which means that
+     * you can provide only a subset of the properties defined in the `BinaryTreeOptions` interface.
+     * @returns a new instance of a binary tree.
+     */
     createTree(options) {
         return new BinaryTree([], Object.assign({ iterationType: this.iterationType }, options));
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
+     * The function checks if a given value is an entry in a binary tree node.
+     * @param kne - BTNodeExemplar<V, N> - A generic type representing a node in a binary tree. It has
+     * two type parameters V and N, representing the value and node type respectively.
+     * @returns a boolean value.
+     */
+    isEntry(kne) {
+        return Array.isArray(kne) && kne.length === 2;
+    }
+    /**
+     * Time Complexity O(log n) - O(n)
+     * Space Complexity O(1)
+     */
+    /**
+     * Time Complexity O(log n) - O(n)
+     * Space Complexity O(1)
      *
-     * The `add` function adds a new node with a key and value to a binary tree, or updates the value of
-     * an existing node with the same key.
-     * @param {BTNKey | N | null | undefined} keyOrNode - The `keyOrNode` parameter can be one of the
-     * following types:
-     * @param {V} [value] - The value to be associated with the key or node being added to the binary
-     * tree.
-     * @returns The function `add` returns a node (`N`) if it was successfully inserted into the binary
-     * tree, or `null` or `undefined` if the insertion was not successful.
+     * The `add` function adds a new node to a binary tree, either by key or by providing a node object.
+     * @param keyOrNodeOrEntry - The parameter `keyOrNodeOrEntry` can be one of the following:
+     * @returns The function `add` returns the inserted node (`N`), `null`, or `undefined`.
      */
-    add(keyOrNode, value) {
+    add(keyOrNodeOrEntry) {
+        let inserted, needInsert;
         const _bfs = (root, newNode) => {
             const queue = new queue_1.Queue([root]);
             while (queue.size > 0) {
                 const cur = queue.shift();
                 if (newNode && cur.key === newNode.key) {
-                    cur.value = newNode.value;
-                    return;
+                    this._replaceNode(cur, newNode);
+                    return newNode;
                 }
                 const inserted = this._addTo(newNode, cur);
                 if (inserted !== undefined)
@@ -154,15 +157,26 @@ class BinaryTree {
                     queue.push(cur.right);
             }
         };
-        let inserted, needInsert;
-        if (keyOrNode === null) {
+        if (keyOrNodeOrEntry === null) {
             needInsert = null;
         }
-        else if (this.isNodeKey(keyOrNode)) {
-            needInsert = this.createNode(keyOrNode, value);
+        else if (this.isNodeKey(keyOrNodeOrEntry)) {
+            needInsert = this.createNode(keyOrNodeOrEntry);
         }
-        else if (keyOrNode instanceof BinaryTreeNode) {
-            needInsert = keyOrNode;
+        else if (keyOrNodeOrEntry instanceof BinaryTreeNode) {
+            needInsert = keyOrNodeOrEntry;
+        }
+        else if (this.isEntry(keyOrNodeOrEntry)) {
+            const [key, value] = keyOrNodeOrEntry;
+            if (key === undefined) {
+                return;
+            }
+            else if (key === null) {
+                needInsert = null;
+            }
+            else {
+                needInsert = this.createNode(key, value);
+            }
         }
         else {
             return;
@@ -183,36 +197,28 @@ class BinaryTree {
         return inserted;
     }
     /**
-     * Time Complexity: O(n)
+     * Time Complexity: O(k log n) - O(k * n)
      * Space Complexity: O(1)
      * Comments: The time complexity for adding a node depends on the depth of the tree. In the best case (when the tree is empty), it's O(1). In the worst case (when the tree is a degenerate tree), it's O(n). The space complexity is constant.
      */
     /**
-     * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
+     * Time Complexity: O(k log n) - O(k * n)
      * Space Complexity: O(1)
      *
-     * The `addMany` function takes an array of keys or nodes and an optional array of values, and adds
-     * each key-value pair to a data structure.
-     * @param {(BTNKey | N |null | undefined)[]} keysOrNodes - An array of keys or nodes to be added to
-     * the binary search tree. Each element can be of type `BTNKey` (a key value), `N` (a node), `null`,
-     * or `undefined`.
-     * @param {(V | undefined)[]} [values] - The `values` parameter is an optional array of values that
-     * correspond to the keys or nodes being added. If provided, the values will be associated with the
-     * keys or nodes during the add operation.
-     * @returns The function `addMany` returns an array of `N`, `null`, or `undefined` values.
-     */
-    addMany(keysOrNodes, values) {
+     * The function `addMany` takes in an iterable of `BTNodeExemplar` objects, adds each object to the
+     * current instance, and returns an array of the inserted nodes.
+     * @param nodes - The `nodes` parameter is an iterable (such as an array or a set) of
+     * `BTNodeExemplar<V, N>` objects.
+     * @returns The function `addMany` returns an array of values, where each value is either of type
+     * `N`, `null`, or `undefined`.
+     */
+    addMany(nodes) {
         // TODO not sure addMany not be run multi times
-        return keysOrNodes.map((keyOrNode, i) => {
-            if (keyOrNode instanceof BinaryTreeNode) {
-                return this.add(keyOrNode.key, keyOrNode.value);
-            }
-            if (keyOrNode === null) {
-                return this.add(null);
-            }
-            const value = values === null || values === void 0 ? void 0 : values[i];
-            return this.add(keyOrNode, value);
-        });
+        const inserted = [];
+        for (const kne of nodes) {
+            inserted.push(this.add(kne));
+        }
+        return inserted;
     }
     /**
      * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
@@ -222,17 +228,13 @@ class BinaryTree {
      * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
      * Space Complexity: O(1)
      *
-     * The `refill` function clears the binary tree and adds multiple nodes with the given IDs or nodes and optional data.
-     * @param {(BTNKey | N)[]} keysOrNodes - The `keysOrNodes` parameter is an array that can contain either
-     * `BTNKey` or `N` values.
-     * @param {N[] | Array<V>} [values] - The `data` parameter is an optional array of values that will be assigned to
-     * the nodes being added. If provided, the length of the `data` array should be equal to the length of the `keysOrNodes`
-     * array. Each value in the `data` array will be assigned to the
-     * @returns The method is returning a boolean value.
+     * The `refill` function clears the current collection and adds new nodes, keys, or entries to it.
+     * @param nodesOrKeysOrEntries - The parameter `nodesOrKeysOrEntries` is an iterable object that can
+     * contain either `BTNodeExemplar` objects, keys, or entries.
      */
-    refill(keysOrNodes, values) {
+    refill(nodesOrKeysOrEntries) {
         this.clear();
-        return keysOrNodes.length === this.addMany(keysOrNodes, values).length;
+        this.addMany(nodesOrKeysOrEntries);
     }
     /**
      * Time Complexity: O(n)
@@ -282,7 +284,7 @@ class BinaryTree {
                 const leftSubTreeRightMost = this.getRightMost(curr.left);
                 if (leftSubTreeRightMost) {
                     const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
-                    orgCurrent = this._swap(curr, leftSubTreeRightMost);
+                    orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
                     if (parentOfLeftSubTreeMax) {
                         if (parentOfLeftSubTreeMax.right === leftSubTreeRightMost)
                             parentOfLeftSubTreeMax.right = leftSubTreeRightMost.left;
@@ -315,8 +317,8 @@ class BinaryTree {
      * @returns the depth of the `distNode` relative to the `beginRoot`.
      */
     getDepth(distNode, beginRoot = this.root) {
-        distNode = this.ensureNotKey(distNode);
-        beginRoot = this.ensureNotKey(beginRoot);
+        distNode = this.ensureNode(distNode);
+        beginRoot = this.ensureNode(beginRoot);
         let depth = 0;
         while (distNode === null || distNode === void 0 ? void 0 : distNode.parent) {
             if (distNode === beginRoot) {
@@ -346,7 +348,7 @@ class BinaryTree {
      * @returns the height of the binary tree.
      */
     getHeight(beginRoot = this.root, iterationType = this.iterationType) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return -1;
         if (iterationType === types_1.IterationType.RECURSIVE) {
@@ -393,7 +395,7 @@ class BinaryTree {
      */
     getMinHeight(beginRoot = this.root, iterationType = this.iterationType) {
         var _a, _b, _c;
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return -1;
         if (iterationType === types_1.IterationType.RECURSIVE) {
@@ -483,7 +485,7 @@ class BinaryTree {
     getNodes(identifier, callback = this._defaultOneParamCallback, onlyOne = false, beginRoot = this.root, iterationType = this.iterationType) {
         if ((!callback || callback === this._defaultOneParamCallback) && identifier instanceof BinaryTreeNode)
             callback = (node => node);
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
         const ans = [];
@@ -622,7 +624,7 @@ class BinaryTree {
      * Space Complexity: O(log n)
      */
     /**
-     * The function `ensureNotKey` returns the node corresponding to the given key if it is a valid node
+     * The function `ensureNode` returns the node corresponding to the given key if it is a valid node
      * key, otherwise it returns the key itself.
      * @param {BTNKey | N | null | undefined} key - The `key` parameter can be of type `BTNKey`, `N`,
      * `null`, or `undefined`. It represents a key used to identify a node in a binary tree.
@@ -632,7 +634,7 @@ class BinaryTree {
      * @returns either the node corresponding to the given key if it is a valid node key, or the key
      * itself if it is not a valid node key.
      */
-    ensureNotKey(key, iterationType = types_1.IterationType.ITERATIVE) {
+    ensureNode(key, iterationType = types_1.IterationType.ITERATIVE) {
         return this.isNodeKey(key) ? this.getNodeByKey(key, iterationType) : key;
     }
     /**
@@ -698,7 +700,7 @@ class BinaryTree {
     getPathToRoot(beginRoot, isReverse = true) {
         // TODO to support get path through passing key
         const result = [];
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return result;
         while (beginRoot.parent) {
@@ -729,7 +731,7 @@ class BinaryTree {
      * is no leftmost node, it returns `null` or `undefined` depending on the input.
      */
     getLeftMost(beginRoot = this.root, iterationType = this.iterationType) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return beginRoot;
         if (iterationType === types_1.IterationType.RECURSIVE) {
@@ -771,7 +773,7 @@ class BinaryTree {
      */
     getRightMost(beginRoot = this.root, iterationType = this.iterationType) {
         // TODO support get right most by passing key in
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return beginRoot;
         if (iterationType === types_1.IterationType.RECURSIVE) {
@@ -810,7 +812,7 @@ class BinaryTree {
      */
     isSubtreeBST(beginRoot, iterationType = this.iterationType) {
         // TODO there is a bug
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return true;
         if (iterationType === types_1.IterationType.RECURSIVE) {
@@ -883,7 +885,7 @@ class BinaryTree {
      * by the return type of the `callback` function.
      */
     subTreeTraverse(callback = this._defaultOneParamCallback, beginRoot = this.root, iterationType = this.iterationType, includeNull = false) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         const ans = [];
         if (!beginRoot)
             return ans;
@@ -984,7 +986,7 @@ class BinaryTree {
      * @returns an array of values that are the return values of the callback function.
      */
     dfs(callback = this._defaultOneParamCallback, pattern = 'in', beginRoot = this.root, iterationType = types_1.IterationType.ITERATIVE, includeNull = false) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
         const ans = [];
@@ -1111,7 +1113,7 @@ class BinaryTree {
      * the breadth-first traversal of a binary tree.
      */
     bfs(callback = this._defaultOneParamCallback, beginRoot = this.root, iterationType = this.iterationType, includeNull = false) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
         const ans = [];
@@ -1184,7 +1186,7 @@ class BinaryTree {
      * @returns The function `listLevels` returns a two-dimensional array of type `ReturnType<C>[][]`.
      */
     listLevels(callback = this._defaultOneParamCallback, beginRoot = this.root, iterationType = this.iterationType, includeNull = false) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         const levelsNodes = [];
         if (!beginRoot)
             return levelsNodes;
@@ -1239,7 +1241,7 @@ class BinaryTree {
      * @returns The function `getPredecessor` returns a value of type `N | undefined`.
      */
     getPredecessor(node) {
-        node = this.ensureNotKey(node);
+        node = this.ensureNode(node);
         if (!this.isRealNode(node))
             return undefined;
         if (node.left) {
@@ -1262,7 +1264,7 @@ class BinaryTree {
      * after the given node in the inorder traversal of the binary tree.
      */
     getSuccessor(x) {
-        x = this.ensureNotKey(x);
+        x = this.ensureNode(x);
         if (!x)
             return undefined;
         if (x.right) {
@@ -1294,7 +1296,7 @@ class BinaryTree {
      * by the return type of the `callback` function.
      */
     morris(callback = this._defaultOneParamCallback, pattern = 'in', beginRoot = this.root) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (beginRoot === null)
             return [];
         const ans = [];
@@ -1405,7 +1407,7 @@ class BinaryTree {
         const newTree = this.createTree();
         for (const [key, value] of this) {
             if (predicate([key, value], this)) {
-                newTree.add(key, value);
+                newTree.add([key, value]);
             }
         }
         return newTree;
@@ -1419,7 +1421,7 @@ class BinaryTree {
     map(callback) {
         const newTree = this.createTree();
         for (const [key, value] of this) {
-            newTree.add(key, callback([key, value], this));
+            newTree.add([key, callback([key, value], this)]);
         }
         return newTree;
     }
@@ -1496,7 +1498,7 @@ class BinaryTree {
      */
     print(beginRoot = this.root, options) {
         const opts = Object.assign({ isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false }, options);
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return;
         if (opts.isShowUndefined)
@@ -1516,19 +1518,6 @@ class BinaryTree {
         };
         display(beginRoot);
     }
-    init(elements) {
-        if (elements) {
-            for (const entryOrKey of elements) {
-                if (Array.isArray(entryOrKey)) {
-                    const [key, value] = entryOrKey;
-                    this.add(key, value);
-                }
-                else {
-                    this.add(entryOrKey);
-                }
-            }
-        }
-    }
     _displayAux(node, options) {
         const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
         const emptyDisplayLayout = [['─'], 1, 0, 0];
@@ -1578,9 +1567,9 @@ class BinaryTree {
      * @param {N} destNode - The destination node to swap.
      * @returns {N} - The destination node after the swap.
      */
-    _swap(srcNode, destNode) {
-        srcNode = this.ensureNotKey(srcNode);
-        destNode = this.ensureNotKey(destNode);
+    _swapProperties(srcNode, destNode) {
+        srcNode = this.ensureNode(srcNode);
+        destNode = this.ensureNode(destNode);
         if (srcNode && destNode) {
             const { key, value } = destNode;
             const tempNode = this.createNode(key, value);
@@ -1594,6 +1583,31 @@ class BinaryTree {
         }
         return undefined;
     }
+    /**
+     * The function replaces an old node with a new node in a binary tree.
+     * @param {N} oldNode - The oldNode parameter represents the node that needs to be replaced in the
+     * tree.
+     * @param {N} newNode - The `newNode` parameter is the node that will replace the `oldNode` in the
+     * tree.
+     * @returns The method is returning the newNode.
+     */
+    _replaceNode(oldNode, newNode) {
+        if (oldNode.parent) {
+            if (oldNode.parent.left === oldNode) {
+                oldNode.parent.left = newNode;
+            }
+            else if (oldNode.parent.right === oldNode) {
+                oldNode.parent.right = newNode;
+            }
+        }
+        newNode.left = oldNode.left;
+        newNode.right = oldNode.right;
+        newNode.parent = oldNode.parent;
+        if (this.root === oldNode) {
+            this._root = newNode;
+        }
+        return newNode;
+    }
     /**
      * The function `_addTo` adds a new node to a binary tree if there is an available position.
      * @param {N | null | undefined} newNode - The `newNode` parameter represents the node that you want to add to