min-heap-typed 1.50.5 → 1.50.7

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

@@ -1,11 +1,5 @@
-/**
- * data-structure-typed
- *
- * @author Tyler Zeng
- * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
- * @license MIT License
- */
-import { BinaryTreeDeleteResult, BSTNKeyOrNode, BTNCallback, KeyOrNodeOrEntry, RBTNColor, RBTreeOptions, RedBlackTreeNested, RedBlackTreeNodeNested } from '../../types';
+import type { BinaryTreeDeleteResult, BSTNKeyOrNode, BTNCallback, KeyOrNodeOrEntry, RBTreeOptions, RedBlackTreeNested, RedBlackTreeNodeNested } from '../../types';
+import { CRUD, RBTNColor } from '../../types';
 import { BST, BSTNode } from './bst';
 import { IBinaryTree } from '../../interfaces';
 export declare class RedBlackTreeNode<K = any, V = any, NODE extends RedBlackTreeNode<K, V, NODE> = RedBlackTreeNodeNested<K, V>> extends BSTNode<K, V, NODE> {
@@ -24,7 +18,7 @@ export declare class RedBlackTreeNode<K = any, V = any, NODE extends RedBlackTre
     protected _color: RBTNColor;
     /**
      * The function returns the color value of a variable.
-     * @returns The color value stored in the protected variable `_color`.
+     * @returns The color value stored in the private variable `_color`.
      */
     get color(): RBTNColor;
     /**
@@ -33,82 +27,88 @@ export declare class RedBlackTreeNode<K = any, V = any, NODE extends RedBlackTre
      */
     set color(value: RBTNColor);
 }
-/**
- * 1. Each node is either red or black.
- * 2. The root node is always black.
- * 3. Leaf nodes are typically Sentinel nodes and are considered black.
- * 4. Red nodes must have black children.
- * 5. Black balance: Every path from any node to each of its leaf nodes contains the same number of black nodes.
- */
 export declare class RedBlackTree<K = any, V = any, NODE extends RedBlackTreeNode<K, V, NODE> = RedBlackTreeNode<K, V, RedBlackTreeNodeNested<K, V>>, TREE extends RedBlackTree<K, V, NODE, TREE> = RedBlackTree<K, V, NODE, RedBlackTreeNested<K, V, NODE>>> extends BST<K, V, NODE, TREE> implements IBinaryTree<K, V, NODE, TREE> {
     /**
-     * This is the constructor function for a Red-Black Tree data structure in TypeScript, which
-     * initializes the tree with optional nodes and options.
-     * @param [keysOrNodesOrEntries] - The `keysOrNodesOrEntries` parameter is an optional iterable of `KeyOrNodeOrEntry<K, V, NODE>`
-     * objects. It represents the initial nodes that will be added to the RBTree during its
-     * construction. If this parameter is provided, the `addMany` method is called to add all the
-     * nodes to the
-     * @param [options] - The `options` parameter is an optional object that allows you to customize the
-     * behavior of the RBTree. It is of type `Partial<RBTreeOptions>`, which means that you can provide
-     * only a subset of the properties defined in the `RBTreeOptions` interface.
+     * This is the constructor function for a Red-Black Tree data structure in TypeScript.
+     * @param keysOrNodesOrEntries - The `keysOrNodesOrEntries` parameter is an iterable object that can
+     * contain keys, nodes, or entries. It is used to initialize the RBTree with the provided keys,
+     * nodes, or entries.
+     * @param [options] - The `options` parameter is an optional object that can be passed to the
+     * constructor. It allows you to customize the behavior of the RBTree. It can include properties such
+     * as `compareKeys`, `compareValues`, `allowDuplicates`, etc. These properties define how the RBTree
+     * should compare keys and
      */
     constructor(keysOrNodesOrEntries?: Iterable<KeyOrNodeOrEntry<K, V, NODE>>, options?: RBTreeOptions<K>);
-    protected _Sentinel: NODE;
+    protected _SENTINEL: NODE;
     /**
-     * The function returns the value of the `_Sentinel` property.
-     * @returns The method is returning the value of the `_Sentinel` property.
+     * The function returns the value of the _SENTINEL property.
+     * @returns The method is returning the value of the `_SENTINEL` property.
      */
-    get Sentinel(): NODE;
-    protected _root: NODE;
+    get SENTINEL(): NODE;
+    protected _root: NODE | undefined;
     /**
-     * The function returns the root node.
-     * @returns The root node of the data structure.
+     * The function returns the root node of a tree or undefined if there is no root.
+     * @returns The root node of the tree structure, or undefined if there is no root node.
      */
-    get root(): NODE;
-    protected _size: number;
-    /**
-     * The function returns the size of an object.
-     * @returns The size of the object, which is a number.
-     */
-    get size(): number;
+    get root(): NODE | undefined;
     /**
      * The function creates a new Red-Black Tree node with the specified key, value, and color.
-     * @param {K} key - The key parameter is the key value associated with the node. It is used to
-     * identify and compare nodes in the Red-Black Tree.
+     * @param {K} key - The key parameter represents the key of the node being created. It is of type K,
+     * which is a generic type representing the key's data type.
      * @param {V} [value] - The `value` parameter is an optional parameter that represents the value
-     * associated with the node. It is of type `V`, which is a generic type that can be replaced with any
-     * specific type when using the `createNode` method.
+     * associated with the key in the node. It is not required and can be omitted if not needed.
      * @param {RBTNColor} color - The "color" parameter is used to specify the color of the node in a
-     * Red-Black Tree. It can be either "RED" or "BLACK". By default, the color is set to "BLACK".
+     * Red-Black Tree. It is an optional parameter with a default value of "RBTNColor.BLACK". The color
+     * can be either "RBTNColor.RED" or "RBTNColor.BLACK".
      * @returns The method is returning a new instance of a RedBlackTreeNode with the specified key,
      * value, and color.
      */
     createNode(key: K, value?: V, color?: RBTNColor): NODE;
     /**
-     * The function creates a Red-Black Tree with the specified options and returns it.
-     * @param {RBTreeOptions} [options] - The `options` parameter is an optional object that can be
-     * passed to the `createTree` function. It is used to customize the behavior of the `RedBlackTree`
-     * class.
+     * The function creates a Red-Black Tree with the given options and returns it.
+     * @param [options] - The `options` parameter is an optional object that contains configuration
+     * options for creating the Red-Black Tree. It is of type `RBTreeOptions<K>`, where `K` represents
+     * the type of keys in the tree.
      * @returns a new instance of a RedBlackTree object.
      */
     createTree(options?: RBTreeOptions<K>): TREE;
     /**
-     * The function `keyValueOrEntryToNode` takes an keyOrNodeOrEntry and converts it into a node object if possible.
-     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`, where:
-     * @param {V} [value] - The `value` parameter is an optional value that can be passed to the
-     * `keyValueOrEntryToNode` function. It represents the value associated with the keyOrNodeOrEntry node. If a value
-     * is provided, it will be used when creating the new node. If no value is provided, the new node
-     * @returns a node of type NODE or undefined.
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The function `keyValueOrEntryToNode` takes a key, value, or entry and returns a node if it is
+     * valid, otherwise it returns undefined.
+     * @param {KeyOrNodeOrEntry<K, V, NODE>} keyOrNodeOrEntry - The key, value, or entry to convert.
+     * @param {V} [value] - The value associated with the key (if `keyOrNodeOrEntry` is a key).
+     * @returns {NODE | undefined} - The corresponding Red-Black Tree node, or `undefined` if conversion fails.
      */
     keyValueOrEntryToNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V): NODE | undefined;
     /**
-     * The function checks if an keyOrNodeOrEntry is an instance of the RedBlackTreeNode class.
-     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`.
-     * @returns a boolean value indicating whether the keyOrNodeOrEntry is an instance of the RedBlackTreeNode
-     * class.
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     * /
+  
+     /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The function checks if the input is an instance of the RedBlackTreeNode class.
+     * @param {KeyOrNodeOrEntry<K, V, NODE>} keyOrNodeOrEntry - The object to check.
+     * @returns {boolean} - `true` if the object is a Red-Black Tree node, `false` otherwise.
      */
     isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>): keyOrNodeOrEntry is NODE;
     /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
      * The function checks if a given node is a real node in a Red-Black Tree.
      * @param {NODE | undefined} node - The `node` parameter is of type `NODE | undefined`, which means
      * it can either be of type `NODE` or `undefined`.
@@ -118,21 +118,41 @@ export declare class RedBlackTree<K = any, V = any, NODE extends RedBlackTreeNod
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
-     * On average (where n is the number of nodes in the tree)
      */
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * The `add` function adds a new node to a binary search tree and performs necessary rotations and
-     * color changes to maintain the red-black tree properties.
-     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be either a key, a node, or an
-     * entry.
-     * @param {V} [value] - The `value` parameter represents the value associated with the key that is
-     * being added to the binary search tree.
-     * @returns The method `add` returns either the newly added node (`NODE`) or `undefined`.
+     * The `getNode` function retrieves a node from a Red-Black Tree based on the provided identifier and
+     * callback function.
+     * @param {ReturnType<C> | undefined} identifier - The `identifier` parameter is the value or key
+     * that you want to search for in the binary search tree. It can be of any type that is compatible
+     * with the type of nodes in the tree.
+     * @param {C} callback - The `callback` parameter is a function that will be called for each node in
+     * the tree. It is used to determine whether a node matches the given identifier. The `callback`
+     * function should take a node as its parameter and return a value that can be compared to the
+     * `identifier` parameter.
+     * @param beginRoot - The `beginRoot` parameter is the starting point for the search in the binary
+     * search tree. It can be either a key or a node. If it is a key, it will be converted to a node
+     * using the `ensureNode` method. If it is not provided, the `root`
+     * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
+     * be performed when searching for nodes in the binary search tree. It is an optional parameter and
+     * its default value is taken from the `iterationType` property of the class.
+     * @returns The method is returning a value of type `NODE | null | undefined`.
+     */
+    getNode<C extends BTNCallback<NODE>>(identifier: ReturnType<C> | undefined, callback?: C, beginRoot?: BSTNKeyOrNode<K, NODE>, iterationType?: import("../../types").IterationType): NODE | null | undefined;
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
      */
-    add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V): boolean;
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The "clear" function sets the root node of a data structure to a sentinel value and resets the
+     * size counter to zero.
+     */
+    clear(): void;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -141,18 +161,16 @@ export declare class RedBlackTree<K = any, V = any, NODE extends RedBlackTreeNod
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * The `delete` function removes a node from a binary tree based on a given identifier and updates
-     * the tree accordingly.
-     * @param {ReturnType<C> | null | undefined} identifier - The `identifier` parameter is the value
-     * that you want to use to identify the node that you want to delete from the binary tree. It can be
-     * of any type that is returned by the callback function `C`. It can also be `null` or `undefined` if
-     * you don't want to
-     * @param {C} callback - The `callback` parameter is a function that takes a node of type `NODE` and
-     * returns a value of type `ReturnType<C>`. It is used to determine if a node should be deleted based
-     * on its identifier. The `callback` function is optional and defaults to `this._defaultOneParam
-     * @returns an array of `BinaryTreeDeleteResult<NODE>`.
+     * The function adds a new node to a Red-Black Tree data structure and returns a boolean indicating
+     * whether the operation was successful.
+     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be either a key, a node, or an
+     * entry.
+     * @param {V} [value] - The `value` parameter is the value associated with the key that is being
+     * added to the tree.
+     * @returns The method is returning a boolean value. It returns true if the node was successfully
+     * added or updated, and false otherwise.
      */
-    delete<C extends BTNCallback<NODE>>(identifier: ReturnType<C> | null | undefined, callback?: C): BinaryTreeDeleteResult<NODE>[];
+    add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V): boolean;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -161,24 +179,25 @@ export declare class RedBlackTree<K = any, V = any, NODE extends RedBlackTreeNod
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * The function `getNode` retrieves a single node from a binary tree based on a given identifier and
-     * callback function.
-     * @param {ReturnType<C> | undefined} identifier - The `identifier` parameter is the value used to
-     * identify the node you want to retrieve. It can be of any type that is the return type of the `C`
-     * callback function. If the `identifier` is `undefined`, it means you want to retrieve the first
-     * node that matches the other criteria
-     * @param {C} callback - The `callback` parameter is a function that will be called for each node in
-     * the binary tree. It is used to determine if a node matches the given identifier. The `callback`
-     * function should take a single parameter of type `NODE` (the type of the nodes in the binary tree) and
-     * @param {K | NODE | undefined} beginRoot - The `beginRoot` parameter is the starting point for
-     * searching for a node in a binary tree. It can be either a key value or a node object. If it is not
-     * provided, the search will start from the root of the binary tree.
-     * @param iterationType - The `iterationType` parameter is a variable that determines the type of
-     * iteration to be performed when searching for nodes in the binary tree. It is used in the
-     * `getNodes` method, which is called within the `getNode` method.
-     * @returns a value of type `NODE`, `null`, or `undefined`.
+     * The function `delete` in a binary tree class deletes a node from the tree and fixes the tree if
+     * necessary.
+     * @param {ReturnType<C> | null | undefined} identifier - The `identifier` parameter is the
+     * identifier of the node that needs to be deleted from the binary tree. It can be of any type that
+     * is returned by the callback function `C`. It can also be `null` or `undefined` if the node to be
+     * deleted is not found.
+     * @param {C} callback - The `callback` parameter is a function that is used to retrieve a node from
+     * the binary tree based on its identifier. It is an optional parameter and if not provided, the
+     * `_defaultOneParamCallback` function is used as the default callback. The callback function should
+     * return the identifier of the node to
+     * @returns an array of BinaryTreeDeleteResult<NODE> objects.
      */
-    getNode<C extends BTNCallback<NODE>>(identifier: ReturnType<C> | undefined, callback?: C, beginRoot?: BSTNKeyOrNode<K, NODE>, iterationType?: import("../../types").IterationType): NODE | null | undefined;
+    delete<C extends BTNCallback<NODE>>(identifier: ReturnType<C> | null | undefined, callback?: C): BinaryTreeDeleteResult<NODE>[];
+    /**
+     * The function sets the root of a tree-like structure and updates the parent property of the new
+     * root.
+     * @param {NODE | undefined} v - v is a parameter of type NODE or undefined.
+     */
+    protected _setRoot(v: NODE | undefined): void;
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -187,9 +206,15 @@ export declare class RedBlackTree<K = any, V = any, NODE extends RedBlackTreeNod
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * The "clear" function sets the root node to the sentinel node and resets the size to 0.
+     * The function replaces an old node with a new node while preserving the color of the old node.
+     * @param {NODE} oldNode - The `oldNode` parameter represents the node that needs to be replaced in
+     * the data structure.
+     * @param {NODE} newNode - The `newNode` parameter is the new node that will replace the old node in
+     * the data structure.
+     * @returns The method is returning the result of calling the `_replaceNode` method from the
+     * superclass, with the `oldNode` and `newNode` parameters.
      */
-    clear(): void;
+    protected _replaceNode(oldNode: NODE, newNode: NODE): NODE;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -198,19 +223,14 @@ export declare class RedBlackTree<K = any, V = any, NODE extends RedBlackTreeNod
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * The function returns the predecessor of a given node in a red-black tree.
-     * @param {RedBlackTreeNode} x - The parameter `x` is of type `RedBlackTreeNode`, which represents a node in a
-     * Red-Black Tree.
-     * @returns the predecessor of the given RedBlackTreeNode 'x'.
-     */
-    getPredecessor(x: NODE): NODE;
-    /**
-     * The function sets the root node of a tree structure and updates the parent property of the new
-     * root node.
-     * @param {NODE} v - The parameter "v" is of type "NODE", which represents a node in a data
-     * structure.
+     * The `_insert` function inserts or updates a node in a binary search tree and performs necessary
+     * fix-ups to maintain the red-black tree properties.
+     * @param {NODE} node - The `node` parameter represents the node that needs to be inserted into a
+     * binary search tree. It contains a `key` property that is used to determine the position of the
+     * node in the tree.
+     * @returns {'inserted' | 'updated'} - The result of the insertion.
      */
-    protected _setRoot(v: NODE): void;
+    protected _insert(node: NODE): CRUD;
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -219,23 +239,25 @@ export declare class RedBlackTree<K = any, V = any, NODE extends RedBlackTreeNod
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * The function performs a left rotation on a binary tree node.
-     * @param {RedBlackTreeNode} x - The parameter `x` is of type `NODE`, which likely represents a node in a binary tree.
+     * The function `_transplant` is used to replace a node `u` with another node `v` in a binary tree.
+     * @param {NODE} u - The parameter "u" represents a node in a binary tree.
+     * @param {NODE | undefined} v - The parameter `v` is of type `NODE | undefined`, which means it can
+     * either be a `NODE` object or `undefined`.
      */
-    protected _leftRotate(x: NODE): void;
+    protected _transplant(u: NODE, v: NODE | undefined): void;
     /**
-     * Time Complexity: O(1)
+     * Time Complexity: O(log n)
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(1)
+     * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * The function performs a right rotation on a red-black tree node.
-     * @param {RedBlackTreeNode} x - x is a RedBlackTreeNode, which represents the node that needs to be right
-     * rotated.
+     * The `_insertFixup` function is used to fix the Red-Black Tree after inserting a new node.
+     * @param {NODE | undefined} z - The parameter `z` represents a node in the Red-Black Tree. It can
+     * either be a valid node object or `undefined`.
      */
-    protected _rightRotate(x: NODE): void;
+    protected _insertFixup(z: NODE | undefined): void;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -244,23 +266,27 @@ export declare class RedBlackTree<K = any, V = any, NODE extends RedBlackTreeNod
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * The `_fixInsert` function is used to fix the red-black tree after an insertion operation.
-     * @param {RedBlackTreeNode} k - The parameter `k` is a RedBlackTreeNode object, which represents a node in a
-     * red-black tree.
+     * The `_deleteFixup` function is used to fix the red-black tree after a node deletion by adjusting
+     * the colors and performing rotations.
+     * @param {NODE | undefined} node - The `node` parameter represents a node in a Red-Black Tree data
+     * structure. It can be either a valid node object or `undefined`.
+     * @returns The function does not return any value. It has a return type of `void`.
      */
-    protected _fixInsert(k: NODE): void;
+    protected _deleteFixup(node: NODE | undefined): void;
     /**
-     * Time Complexity: O(log n)
+     * Time Complexity: O(1)
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(log n)
+     * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * The function `_fixDelete` is used to fix the red-black tree after a node deletion.
-     * @param {RedBlackTreeNode} x - The parameter `x` represents a node in a Red-Black Tree (RBT).
+     * The `_leftRotate` function performs a left rotation on a given node in a binary tree.
+     * @param {NODE | undefined} x - The parameter `x` is of type `NODE | undefined`. It represents a
+     * node in a binary tree or `undefined` if there is no node.
+     * @returns void, which means it does not return any value.
      */
-    protected _fixDelete(x: NODE): void;
+    protected _leftRotate(x: NODE | undefined): void;
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -269,19 +295,10 @@ export declare class RedBlackTree<K = any, V = any, NODE extends RedBlackTreeNod
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * The function `_rbTransplant` replaces one node in a red-black tree with another node.
-     * @param {RedBlackTreeNode} u - The parameter "u" represents a RedBlackTreeNode object.
-     * @param {RedBlackTreeNode} v - The parameter "v" is a RedBlackTreeNode object.
-     */
-    protected _rbTransplant(u: NODE, v: NODE): void;
-    /**
-     * The function replaces an old node with a new node while preserving the color of the old node.
-     * @param {NODE} oldNode - The `oldNode` parameter represents the node that needs to be replaced in a
-     * data structure. It is of type `NODE`, which is the type of the nodes in the data structure.
-     * @param {NODE} newNode - The `newNode` parameter is the node that will replace the `oldNode` in the
-     * data structure.
-     * @returns The method is returning the result of calling the `_replaceNode` method from the
-     * superclass, passing in the `oldNode` and `newNode` as arguments.
+     * The `_rightRotate` function performs a right rotation on a given node in a binary tree.
+     * @param {NODE | undefined} y - The parameter `y` is of type `NODE | undefined`. It represents a
+     * node in a binary tree or `undefined` if there is no node.
+     * @returns void, which means it does not return any value.
      */
-    protected _replaceNode(oldNode: NODE, newNode: NODE): NODE;
+    protected _rightRotate(y: NODE | undefined): void;
 }