min-heap-typed 1.42.8 → 1.43.0

package/dist/data-structures/binary-tree/binary-tree.d.ts

@@ -87,24 +87,51 @@ export declare class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = Binary
      */
     createNode(key: BTNKey, value?: V): N;
     /**
-     * Add a node with the given key and value to the binary tree.
-     * @param {BTNKey | N | null} keyOrNode - The key or node to add to the binary tree.
-     * @param {V} value - The value for the new node (optional).
-     * @returns {N | null | undefined} - The inserted node, or null if nothing was inserted, or undefined if the operation failed.
+     * Time Complexity: O(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(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.
      */
     add(keyOrNode: BTNKey | N | null | undefined, value?: V): N | null | undefined;
     /**
-     * The `addMany` function takes an array of binary tree node IDs or nodes, and optionally an array of corresponding data
-     * values, and adds them to the binary tree.
-     * @param {(BTNKey | null)[] | (N | null)[]} keysOrNodes - An array of BTNKey or BinaryTreeNode
-     * objects, or null values.
-     * @param {V[]} [values] - The `values` parameter is an optional array of values (`V[]`) that corresponds to
-     * the nodes or node IDs being added. It is used to set the value of each node being added. If `values` is not provided,
-     * the value of the nodes will be `undefined`.
+     * 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)
+     */
+    /**
+     * 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 `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: (BTNKey | N | null | undefined)[], values?: (V | undefined)[]): (N | null | undefined)[];
     /**
+     * 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)
+     */
+    /**
+     * 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.
@@ -118,48 +145,76 @@ export declare class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = Binary
     delete<C extends BTNCallback<N, N>>(identifier: N | null | undefined, callback?: C): BiTreeDeleteResult<N>[];
     delete<C extends BTNCallback<N>>(identifier: ReturnType<C>, callback: C): BiTreeDeleteResult<N>[];
     /**
-     * The function `getDepth` calculates the depth of a given node in a binary tree relative to a
-     * specified root node.
-     * @param {BTNKey | N | null | undefined} distNode - The `distNode` parameter represents the node
-     * whose depth we want to find in the binary tree. It can be either a node object (`N`), a key value
-     * of the node (`BTNKey`), or `null`.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
-     * starting node from which we want to calculate the depth. It can be either a node object or the key
-     * of a node in the binary tree. If no value is provided for `beginRoot`, it defaults to the root
-     * node of the binary tree.
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The function calculates the depth of a given node in a binary tree.
+     * @param {BTNKey | N | null | undefined} distNode - The `distNode` parameter represents the node in
+     * the binary tree whose depth we want to find. It can be of type `BTNKey`, `N`, `null`, or
+     * `undefined`.
+     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
+     * from which we want to calculate the depth. It can be either a `BTNKey` (binary tree node key) or
+     * `N` (binary tree node) or `null` or `undefined`. If no value is provided for `beginRoot
      * @returns the depth of the `distNode` relative to the `beginRoot`.
      */
     getDepth(distNode: BTNKey | N | null | undefined, beginRoot?: BTNKey | N | null | undefined): number;
     /**
-     * The `getHeight` function calculates the maximum height of a binary tree using either recursive or
-     * iterative approach.
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
+     * Best Case - O(log n) (when using recursive iterationType), Worst Case - O(n) (when using iterative iterationType)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
+     *
+     * The function `getHeight` calculates the maximum height of a binary tree using either recursive or
+     * iterative traversal.
      * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
-     * starting node from which the height of the binary tree is calculated. It can be either a node
-     * object (`N`), a key value of a node in the tree (`BTNKey`), or `null` if no starting
-     * node is specified. If `
+     * starting node of the binary tree from which we want to calculate the height. It can be of type
+     * `BTNKey`, `N`, `null`, or `undefined`. If not provided, it defaults to `this.root`.
      * @param iterationType - The `iterationType` parameter is used to determine whether to calculate the
-     * height of the binary tree using a recursive approach or an iterative approach. It can have two
-     * possible values:
+     * height of the tree using a recursive approach or an iterative approach. It can have two possible
+     * values:
      * @returns the height of the binary tree.
      */
     getHeight(beginRoot?: BTNKey | N | null | undefined, iterationType?: IterationType): number;
     /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
+     * Best Case - O(log n) (when using recursive iterationType), Worst Case - O(n) (when using iterative iterationType)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
+     *
      * The `getMinHeight` function calculates the minimum height of a binary tree using either a
      * recursive or iterative approach.
-     * @param {N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node from which we want to
-     * calculate the minimum height of the tree. It is optional and defaults to the root of the tree if
-     * not provided.
+     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * starting node of the binary tree from which we want to calculate the minimum height. It can be of
+     * type `BTNKey`, `N`, `null`, or `undefined`. If no value is provided, it defaults to `this.root`.
      * @param iterationType - The `iterationType` parameter is used to determine the method of iteration
      * to calculate the minimum height of a binary tree. It can have two possible values:
      * @returns The function `getMinHeight` returns the minimum height of a binary tree.
      */
     getMinHeight(beginRoot?: BTNKey | N | null | undefined, iterationType?: IterationType): number;
     /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
+     *
      * The function checks if a binary tree is perfectly balanced by comparing the minimum height and the
      * height of the tree.
-     * @param {N | null | undefined} beginRoot - The parameter `beginRoot` is of type `N | null | undefined`, which means it can
-     * either be of type `N` (representing a node in a tree) or `null` (representing an empty tree).
-     * @returns The method is returning a boolean value.
+     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * for calculating the height and minimum height of a binary tree. It can be either a `BTNKey` (a key
+     * value of a binary tree node), `N` (a node of a binary tree), `null`, or `undefined`. If
+     * @returns a boolean value.
      */
     isPerfectlyBalanced(beginRoot?: BTNKey | N | null | undefined): boolean;
     getNodes<C extends BTNCallback<N, BTNKey>>(identifier: BTNKey, callback?: C, onlyOne?: boolean, beginRoot?: BTNKey | N | null | undefined, iterationType?: IterationType): N[];
@@ -172,6 +227,13 @@ export declare class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = Binary
     getNode<C extends BTNCallback<N, N>>(identifier: N | null | undefined, callback?: C, beginRoot?: BTNKey | N | null | undefined, iterationType?: IterationType): N | null | undefined;
     getNode<C extends BTNCallback<N>>(identifier: ReturnType<C>, callback: C, beginRoot?: BTNKey | N | null | undefined, iterationType?: IterationType): N | null | undefined;
     /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
+     *
      * The function `getNodeByKey` searches for a node in a binary tree by its key, using either
      * recursive or iterative iteration.
      * @param {BTNKey} key - The `key` parameter is the key value that we are searching for in the tree.
@@ -208,56 +270,93 @@ export declare class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = Binary
      */
     isEmpty(): boolean;
     /**
-     * The function `getPathToRoot` returns an array of nodes starting from a given node and traversing
-     * up to the root node, with the option to reverse the order of the nodes.
-     * @param {N} beginRoot - The `beginRoot` parameter represents the starting node from which you want
-     * to find the path to the root node.
+     * Time Complexity: O(log n)
+     * Space Complexity: O(log n)
+     */
+    /**
+     * Time Complexity: O(log n)
+     * Space Complexity: O(log n)
+     *
+     * The function `getPathToRoot` returns an array of nodes from a given node to the root of a tree
+     * structure, with the option to reverse the order of the nodes.
+     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * starting node from which you want to find the path to the root. It can be of type `BTNKey`, `N`,
+     * `null`, or `undefined`.
      * @param [isReverse=true] - The `isReverse` parameter is a boolean flag that determines whether the
      * resulting path should be reversed or not. If `isReverse` is set to `true`, the path will be
-     * reversed before returning it. If `isReverse` is set to `false` or not provided, the path will
-     * @returns The function `getPathToRoot` returns an array of type `N[]`.
+     * reversed before returning it. If `isReverse` is set to `false`, the path will be returned as is
+     * @returns The function `getPathToRoot` returns an array of nodes (`N[]`).
      */
     getPathToRoot(beginRoot: BTNKey | N | null | undefined, isReverse?: boolean): N[];
     /**
-     * The function `getLeftMost` returns the leftmost node in a binary tree, either using recursive or
-     * iterative traversal.
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     *
+     * The function `getLeftMost` returns the leftmost node in a binary tree, either recursively or
+     * iteratively.
      * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
-     * for finding the leftmost node in a binary tree. It can be either a node object (`N`), a key value
-     * of a node (`BTNKey`), or `null` if the tree is empty.
+     * for finding the leftmost node in a binary tree. It can be either a `BTNKey` (a key value), `N` (a
+     * node), `null`, or `undefined`. If not provided, it defaults to `this.root`,
      * @param iterationType - The `iterationType` parameter is used to determine the type of iteration to
      * be performed when finding the leftmost node in a binary tree. It can have two possible values:
-     * @returns The function `getLeftMost` returns the leftmost node (`N`) in a binary tree. If there is
-     * no leftmost node, it returns `null`.
+     * @returns The function `getLeftMost` returns the leftmost node (`N`) in the binary tree. If there
+     * is no leftmost node, it returns `null` or `undefined` depending on the input.
      */
     getLeftMost(beginRoot?: BTNKey | N | null | undefined, iterationType?: IterationType): N | null | undefined;
     /**
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     *
      * The function `getRightMost` returns the rightmost node in a binary tree, either recursively or
      * iteratively.
-     * @param {N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node from which we want to
-     * find the rightmost node. It is of type `N | null | undefined`, which means it can either be a node of type `N`
-     * or `null`. If it is `null`, it means there is no starting node
-     * @param iterationType - The `iterationType` parameter is used to determine the type of iteration to
-     * be performed when finding the rightmost node in a binary tree. It can have two possible values:
-     * @returns The function `getRightMost` returns the rightmost node (`N`) in a binary tree. If the
-     * `beginRoot` parameter is `null`, it returns `null`.
+     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * starting node from which we want to find the rightmost node. It can be of type `BTNKey`, `N`,
+     * `null`, or `undefined`. If not provided, it defaults to `this.root`, which is a property of the
+     * current object.
+     * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
+     * type of iteration to use when finding the rightmost node. It can have one of two values:
+     * @returns The function `getRightMost` returns the rightmost node (`N`) in a binary tree. If there
+     * is no rightmost node, it returns `null` or `undefined`, depending on the input.
      */
     getRightMost(beginRoot?: BTNKey | N | null | undefined, iterationType?: IterationType): N | null | undefined;
     /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
      * The function `isSubtreeBST` checks if a given binary tree is a valid binary search tree.
-     * @param {N} beginRoot - The `beginRoot` parameter is the root node of the binary tree that you want
-     * to check if it is a binary search tree (BST) subtree.
+     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the root
+     * node of the binary search tree (BST) that you want to check if it is a subtree of another BST.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
      * type of iteration to use when checking if a subtree is a binary search tree (BST). It can have two
      * possible values:
-     * @returns The function `isSubtreeBST` returns a boolean value.
+     * @returns a boolean value.
      */
     isSubtreeBST(beginRoot: BTNKey | N | null | undefined, iterationType?: IterationType): boolean;
     /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
      * The function checks if a binary tree is a binary search tree.
      * @param iterationType - The parameter "iterationType" is used to specify the type of iteration to
      * be used when checking if the binary tree is a binary search tree (BST). It is an optional
-     * parameter with a default value of "this.iterationType". The value of "this.iterationType" is not
-     * provided in
+     * parameter with a default value of "this.iterationType". The value of "this.iterationType" is
+     * expected to be
      * @returns a boolean value.
      */
     isBST(iterationType?: IterationType): boolean;
@@ -301,26 +400,33 @@ export declare class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = Binary
     listLevels<C extends BTNCallback<N | null | undefined>>(callback?: C, beginRoot?: BTNKey | N | null | undefined, iterationType?: IterationType, includeNull?: true): ReturnType<C>[][];
     getPredecessor(node: N): N;
     /**
-     * The function `getSuccessor` returns the next node in a binary tree given a node `x`, or `null` if
-     * `x` is the last node.
-     * @param {N} x - N - a node in a binary tree
-     * @returns The function `getSuccessor` returns a value of type `N` (the successor node), or `null`
-     * if there is no successor, or `undefined` if the input `x` is `undefined`.
+     * The function `getSuccessor` returns the next node in a binary tree given a current node.
+     * @param {BTNKey | N | null} [x] - The parameter `x` can be of type `BTNKey`, `N`, or `null`.
+     * @returns the successor of the given node or key. The successor is the node that comes immediately
+     * after the given node in the inorder traversal of the binary tree.
      */
     getSuccessor(x?: BTNKey | N | null): N | null | undefined;
     /**
-     * The `morris` function performs a depth-first traversal of a binary tree using the Morris traversal
-     * algorithm and returns an array of values obtained by applying a callback function to each node.
-     * @param callback - The `callback` parameter is a function that will be called on each node in the
-     * tree. It takes a node of type `N` as input and returns a value of type `ReturnType<BTNCallback<N>>`. The
-     * default value for this parameter is `this._defaultOneParamCallback`.
+     * Time complexity: O(n)
+     * Space complexity: O(1)
+     */
+    /**
+     * Time complexity: O(n)
+     * Space complexity: O(1)
+     * The `morris` function performs a depth-first traversal on a binary tree using the Morris traversal
+     * algorithm.
+     * @param {C} callback - The `callback` parameter is a function that will be called for each node in
+     * the tree. It takes a single parameter of type `N` (the type of the nodes in the tree) and returns
+     * a value of any type.
      * @param {DFSOrderPattern} [pattern=in] - The `pattern` parameter in the `morris` function
      * determines the order in which the nodes of a binary tree are traversed. It can have one of the
      * following values:
-     * @param {N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node for the Morris
-     * traversal. It specifies the root node of the tree from which the traversal should begin. If
-     * `beginRoot` is `null`, an empty array will be returned.
-     * @returns The `morris` function returns an array of `ReturnType<BTNCallback<N>>` values.
+     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
+     * for the traversal. It can be specified as a key, a node object, or `null`/`undefined` to indicate
+     * the root of the tree. If no value is provided, the default value is the root of the tree.
+     * @returns The function `morris` returns an array of values that are the result of invoking the
+     * `callback` function on each node in the binary tree. The type of the array elements is determined
+     * by the return type of the `callback` function.
      */
     morris<C extends BTNCallback<N>>(callback?: C, pattern?: DFSOrderPattern, beginRoot?: BTNKey | N | null | undefined): ReturnType<C>[];
     /**
@@ -362,9 +468,9 @@ export declare class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = Binary
     protected _setRoot(v: N | null | undefined): void;
     /**
      * The `print` function is used to display a binary tree structure in a visually appealing way.
-     * @param {N | null | undefined} root - The `root` parameter in the `print` function represents the
-     * root node of a binary tree. It can have one of the following types: `BTNKey`, `N`, `null`, or
-     * `undefined`. The default value is `this.root`, which suggests that `this.root` is the
+     * @param {N | null | undefined} root - The `root` parameter is of type `BTNKey | N | null |
+     * undefined`. It represents the root node of a binary tree. The root node can have one of the
+     * following types:
      */
     print(beginRoot?: BTNKey | N | null | undefined): void;
 }