data-structure-typed 1.47.5 → 1.47.7

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

@@ -44,30 +44,41 @@ export class BSTNode extends BinaryTreeNode {
         this._right = v;
     }
 }
+/**
+ * 1. Node Order: Each node's left child has a lesser value, and the right child has a greater value.
+ * 2. Unique Keys: No duplicate keys in a standard BST.
+ * 3. Efficient Search: Enables quick search, minimum, and maximum operations.
+ * 4. Inorder Traversal: Yields nodes in ascending order.
+ * 5. Logarithmic Operations: Ideal operations like insertion, deletion, and searching are O(log n) time-efficient.
+ * 6. Balance Variability: Can become unbalanced; special types maintain balance.
+ * 7. No Auto-Balancing: Standard BSTs don't automatically balance themselves.
+ */
 export class BST extends BinaryTree {
-    options;
     /**
-     * The constructor function initializes a binary search tree with an optional comparator function.
-     * @param {BSTOptions} [options] - An optional object that contains additional configuration options
-     * for the binary search tree.
+     * This is the constructor function for a binary search tree class in TypeScript, which initializes
+     * the tree with optional elements and options.
+     * @param [elements] - An optional iterable of BTNodeExemplar objects that will be added to the
+     * binary search tree.
+     * @param [options] - The `options` parameter is an optional object that can contain additional
+     * configuration options for the binary search tree. It can have the following properties:
      */
-    constructor(options) {
-        super(options);
+    constructor(elements, options) {
+        super([], options);
         if (options) {
-            this.options = { iterationType: IterationType.ITERATIVE, comparator: (a, b) => a - b, ...options };
-        }
-        else {
-            this.options = { iterationType: IterationType.ITERATIVE, comparator: (a, b) => a - b };
+            const { comparator } = options;
+            if (comparator) {
+                this.comparator = comparator;
+            }
         }
         this._root = undefined;
+        if (elements)
+            this.addMany(elements);
     }
     _root;
-    /**
-     * Get the root node of the binary tree.
-     */
     get root() {
         return this._root;
     }
+    comparator = (a, b) => a - b;
     /**
      * The function creates a new binary search tree node with the given key and value.
      * @param {BTNKey} key - The key parameter is the key value that will be associated with
@@ -79,8 +90,18 @@ export class BST extends BinaryTree {
     createNode(key, value) {
         return new BSTNode(key, value);
     }
+    /**
+     * The function creates a new binary search tree with the specified options.
+     * @param [options] - The `options` parameter is an optional object that allows you to customize the
+     * behavior of the `createTree` method. It accepts a partial `BSTOptions` object, which is a type
+     * that defines various options for creating a binary search tree.
+     * @returns a new instance of the BST class with the specified options.
+     */
     createTree(options) {
-        return new BST({ ...this.options, ...options });
+        return new BST([], {
+            iterationType: this.iterationType,
+            comparator: this.comparator, ...options
+        });
     }
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree. In the worst case (unbalanced tree), it can be O(n).
@@ -90,158 +111,138 @@ export class BST extends BinaryTree {
      * Time Complexity: O(log n) - Average case for a balanced tree. In the worst case (unbalanced tree), it can be O(n).
      * Space Complexity: O(1) - Constant space is used.
      *
-     * The `add` function adds a new node to a binary search tree based on the provided key and value.
-     * @param {BTNKey | N | null | undefined} keyOrNode - The `keyOrNode` parameter can be one of the
-     * following types:
-     * @param {V} [value] - The `value` parameter is an optional value that can be associated with the
-     * key or node being added to the binary search tree.
-     * @returns The method `add` returns a node (`N`) that was inserted into the binary search tree. If
-     * no node was inserted, it returns `undefined`.
+     * The `add` function adds a new node to a binary search tree, either by key or by providing a node
+     * object.
+     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be one of the following:
+     * @returns The method returns either the newly added node (`newNode`) or `undefined` if the input
+     * (`keyOrNodeOrEntry`) is null, undefined, or does not match any of the expected types.
      */
-    add(keyOrNode, value) {
-        if (keyOrNode === null)
+    add(keyOrNodeOrEntry) {
+        if (keyOrNodeOrEntry === null || keyOrNodeOrEntry === undefined) {
             return undefined;
-        // TODO support node as a parameter
-        let inserted;
+        }
         let newNode;
-        if (keyOrNode instanceof BSTNode) {
-            newNode = keyOrNode;
+        if (keyOrNodeOrEntry instanceof BSTNode) {
+            newNode = keyOrNodeOrEntry;
         }
-        else if (this.isNodeKey(keyOrNode)) {
-            newNode = this.createNode(keyOrNode, value);
+        else if (this.isNodeKey(keyOrNodeOrEntry)) {
+            newNode = this.createNode(keyOrNodeOrEntry);
+        }
+        else if (this.isEntry(keyOrNodeOrEntry)) {
+            const [key, value] = keyOrNodeOrEntry;
+            if (key === undefined || key === null) {
+                return;
+            }
+            else {
+                newNode = this.createNode(key, value);
+            }
         }
         else {
-            newNode = undefined;
+            return;
         }
         if (this.root === undefined) {
             this._setRoot(newNode);
-            this._size = this.size + 1;
-            inserted = this.root;
+            this._size++;
+            return this.root;
         }
-        else {
-            let cur = this.root;
-            let traversing = true;
-            while (traversing) {
-                if (cur !== undefined && newNode !== undefined) {
-                    if (this._compare(cur.key, newNode.key) === CP.eq) {
-                        if (newNode) {
-                            cur.value = newNode.value;
-                        }
-                        //Duplicates are not accepted.
-                        traversing = false;
-                        inserted = cur;
-                    }
-                    else if (this._compare(cur.key, newNode.key) === CP.gt) {
-                        // Traverse left of the node
-                        if (cur.left === undefined) {
-                            if (newNode) {
-                                newNode.parent = cur;
-                            }
-                            //Add to the left of the current node
-                            cur.left = newNode;
-                            this._size = this.size + 1;
-                            traversing = false;
-                            inserted = cur.left;
-                        }
-                        else {
-                            //Traverse the left of the current node
-                            if (cur.left)
-                                cur = cur.left;
-                        }
-                    }
-                    else if (this._compare(cur.key, newNode.key) === CP.lt) {
-                        // Traverse right of the node
-                        if (cur.right === undefined) {
-                            if (newNode) {
-                                newNode.parent = cur;
-                            }
-                            //Add to the right of the current node
-                            cur.right = newNode;
-                            this._size = this.size + 1;
-                            traversing = false;
-                            inserted = cur.right;
-                        }
-                        else {
-                            //Traverse the left of the current node
-                            if (cur.right)
-                                cur = cur.right;
-                        }
-                    }
+        let current = this.root;
+        while (current !== undefined) {
+            if (this._compare(current.key, newNode.key) === CP.eq) {
+                // if (current !== newNode) {
+                // The key value is the same but the reference is different, update the value of the existing node
+                this._replaceNode(current, newNode);
+                return newNode;
+                // } else {
+                // The key value is the same and the reference is the same, replace the entire node
+                // this._replaceNode(current, newNode);
+                //   return;
+                // }
+            }
+            else if (this._compare(current.key, newNode.key) === CP.gt) {
+                if (current.left === undefined) {
+                    current.left = newNode;
+                    newNode.parent = current;
+                    this._size++;
+                    return newNode;
                 }
-                else {
-                    traversing = false;
+                current = current.left;
+            }
+            else {
+                if (current.right === undefined) {
+                    current.right = newNode;
+                    newNode.parent = current;
+                    this._size++;
+                    return newNode;
                 }
+                current = current.right;
             }
         }
-        return inserted;
+        return undefined;
     }
     /**
-     * Time Complexity: O(n log n) - Adding each element individually in a balanced tree.
-     * Space Complexity: O(n) - Additional space is required for the sorted array.
+     * Time Complexity: O(k log n) - Adding each element individually in a balanced tree.
+     * Space Complexity: O(k) - Additional space is required for the sorted array.
      */
     /**
-     * Time Complexity: O(n log n) - Adding each element individually in a balanced tree.
-     * Space Complexity: O(n) - Additional space is required for the sorted array.
+     * Time Complexity: O(k log n) - Adding each element individually in a balanced tree.
+     * Space Complexity: O(k) - Additional space is required for the sorted array.
      *
-     * The `addMany` function is used to efficiently add multiple keys or nodes with corresponding data
-     * to a binary search tree.
-     * @param {(BTNKey | N | undefined)[]} keysOrNodes - An array of keys or nodes to be added to the
-     * binary search tree. Each element can be of type `BTNKey` (binary tree node key), `N` (binary tree
-     * node), or `undefined`.
-     * @param {(V | undefined)[]} [data] - An optional array of values to associate with the keys or
-     * nodes being added. If provided, the length of the `data` array must be the same as the length of
-     * the `keysOrNodes` array.
+     * The `addMany` function in TypeScript adds multiple nodes to a binary tree, either in a balanced or
+     * unbalanced manner, and returns an array of the inserted nodes.
+     * @param keysOrNodesOrEntries - An iterable containing keys, nodes, or entries to be added to the
+     * binary tree.
      * @param [isBalanceAdd=true] - A boolean flag indicating whether the tree should be balanced after
-     * adding the nodes. The default value is `true`.
+     * adding the nodes. The default value is true.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
-     * type of iteration to use when adding multiple keys or nodes to the binary search tree. It has a
-     * default value of `this.iterationType`, which means it will use the iteration type specified in the
-     * current instance of the binary search tree
-     * @returns The function `addMany` returns an array of nodes (`N`) or `undefined` values.
+     * type of iteration to use when adding multiple keys or nodes to the binary tree. It has a default
+     * value of `this.iterationType`, which means it will use the iteration type specified by the binary
+     * tree instance.
+     * @returns The `addMany` function returns an array of `N` or `undefined` values.
      */
-    addMany(keysOrNodes, data, isBalanceAdd = true, iterationType = this.options.iterationType) {
-        // TODO this addMany function is inefficient, it should be optimized
-        function hasNoUndefined(arr) {
-            return arr.indexOf(undefined) === -1;
-        }
-        if (!isBalanceAdd || !hasNoUndefined(keysOrNodes)) {
-            return super.addMany(keysOrNodes, data).map(n => n ?? undefined);
-        }
+    addMany(keysOrNodesOrEntries, isBalanceAdd = true, iterationType = this.iterationType) {
         const inserted = [];
-        const combinedArr = keysOrNodes.map((value, index) => [value, data?.[index]]);
-        let sorted = [];
-        function _isNodeOrUndefinedTuple(arr) {
-            for (const [keyOrNode] of arr)
-                if (keyOrNode instanceof BSTNode)
-                    return true;
-            return false;
+        if (!isBalanceAdd) {
+            for (const kve of keysOrNodesOrEntries) {
+                const nn = this.add(kve);
+                inserted.push(nn);
+            }
+            return inserted;
         }
-        const _isBinaryTreeKeyOrNullTuple = (arr) => {
-            for (const [keyOrNode] of arr)
-                if (this.isNodeKey(keyOrNode))
-                    return true;
-            return false;
+        const realBTNExemplars = [];
+        const isRealBTNExemplar = (kve) => {
+            if (kve === undefined || kve === null)
+                return false;
+            return !(this.isEntry(kve) && (kve[0] === undefined || kve[0] === null));
         };
-        let sortedKeysOrNodes = [], sortedData = [];
-        if (_isNodeOrUndefinedTuple(combinedArr)) {
-            sorted = combinedArr.sort((a, b) => a[0].key - b[0].key);
+        for (const kve of keysOrNodesOrEntries) {
+            isRealBTNExemplar(kve) && realBTNExemplars.push(kve);
         }
-        else if (_isBinaryTreeKeyOrNullTuple(combinedArr)) {
-            sorted = combinedArr.sort((a, b) => a[0] - b[0]);
-        }
-        else {
-            throw new Error('Invalid input keysOrNodes');
-        }
-        sortedKeysOrNodes = sorted.map(([keyOrNode]) => keyOrNode);
-        sortedData = sorted.map(([, value]) => value);
-        const _dfs = (arr, data) => {
+        // TODO this addMany function is inefficient, it should be optimized
+        let sorted = [];
+        sorted = realBTNExemplars.sort((a, b) => {
+            let aR, bR;
+            if (this.isEntry(a))
+                aR = a[0];
+            else if (this.isRealNode(a))
+                aR = a.key;
+            else
+                aR = a;
+            if (this.isEntry(b))
+                bR = b[0];
+            else if (this.isRealNode(b))
+                bR = b.key;
+            else
+                bR = b;
+            return aR - bR;
+        });
+        const _dfs = (arr) => {
             if (arr.length === 0)
                 return;
             const mid = Math.floor((arr.length - 1) / 2);
-            const newNode = this.add(arr[mid], data?.[mid]);
+            const newNode = this.add(arr[mid]);
             inserted.push(newNode);
-            _dfs(arr.slice(0, mid), data?.slice(0, mid));
-            _dfs(arr.slice(mid + 1), data?.slice(mid + 1));
+            _dfs(arr.slice(0, mid));
+            _dfs(arr.slice(mid + 1));
         };
         const _iterate = () => {
             const n = sorted.length;
@@ -252,7 +253,7 @@ export class BST extends BinaryTree {
                     const [l, r] = popped;
                     if (l <= r) {
                         const m = l + Math.floor((r - l) / 2);
-                        const newNode = this.add(sortedKeysOrNodes[m], sortedData?.[m]);
+                        const newNode = this.add(sorted[m]);
                         inserted.push(newNode);
                         stack.push([m + 1, r]);
                         stack.push([l, m - 1]);
@@ -261,7 +262,7 @@ export class BST extends BinaryTree {
             }
         };
         if (iterationType === IterationType.RECURSIVE) {
-            _dfs(sortedKeysOrNodes, sortedData);
+            _dfs(sorted);
         }
         else {
             _iterate();
@@ -269,8 +270,8 @@ export class BST extends BinaryTree {
         return inserted;
     }
     /**
-     * Time Complexity: O(log n) - Average case for a balanced tree.
-     * Space Complexity: O(1) - Constant space is used.
+     * Time Complexity: O(n log n) - Adding each element individually in a balanced tree.
+     * Space Complexity: O(n) - Additional space is required for the sorted array.
      */
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree.
@@ -287,7 +288,7 @@ export class BST extends BinaryTree {
      * the key of the leftmost node if the comparison result is greater than, and the key of the
      * rightmost node otherwise. If no node is found, it returns 0.
      */
-    lastKey(beginRoot = this.root, iterationType = this.options.iterationType) {
+    lastKey(beginRoot = this.root, iterationType = this.iterationType) {
         if (this._compare(0, 1) === CP.lt)
             return this.getRightMost(beginRoot, iterationType)?.key ?? 0;
         else if (this._compare(0, 1) === CP.gt)
@@ -297,7 +298,7 @@ export class BST extends BinaryTree {
     }
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree.
-     * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
+     * Space Complexity: O(1) - Constant space is used.
      */
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree.
@@ -345,7 +346,11 @@ export class BST extends BinaryTree {
         }
     }
     /**
-     * The function `ensureNotKey` returns the node corresponding to the given key if it is a node key,
+     * Time Complexity: O(log n) - Average case for a balanced tree.
+     * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
+     */
+    /**
+     * The function `ensureNode` returns the node corresponding to the given key if it is a node key,
      * otherwise it returns the key itself.
      * @param {BTNKey | N | undefined} key - The `key` parameter can be of type `BTNKey`, `N`, or
      * `undefined`.
@@ -353,13 +358,9 @@ export class BST extends BinaryTree {
      * type of iteration to be performed. It has a default value of `IterationType.ITERATIVE`.
      * @returns either a node object (N) or undefined.
      */
-    ensureNotKey(key, iterationType = IterationType.ITERATIVE) {
+    ensureNode(key, iterationType = IterationType.ITERATIVE) {
         return this.isNodeKey(key) ? this.getNodeByKey(key, iterationType) : key;
     }
-    /**
-     * Time Complexity: O(log n) - Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key.
-     * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
-     */
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key.
      * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
@@ -383,8 +384,8 @@ export class BST extends BinaryTree {
      * performed on the binary tree. It can have two possible values:
      * @returns The method returns an array of nodes (`N[]`).
      */
-    getNodes(identifier, callback = this._defaultOneParamCallback, onlyOne = false, beginRoot = this.root, iterationType = this.options.iterationType) {
-        beginRoot = this.ensureNotKey(beginRoot);
+    getNodes(identifier, callback = this._defaultOneParamCallback, onlyOne = false, beginRoot = this.root, iterationType = this.iterationType) {
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
         const ans = [];
@@ -464,8 +465,8 @@ export class BST extends BinaryTree {
      * @returns The function `lesserOrGreaterTraverse` returns an array of values of type
      * `ReturnType<C>`, which is the return type of the callback function passed as an argument.
      */
-    lesserOrGreaterTraverse(callback = this._defaultOneParamCallback, lesserOrGreater = CP.lt, targetNode = this.root, iterationType = this.options.iterationType) {
-        targetNode = this.ensureNotKey(targetNode);
+    lesserOrGreaterTraverse(callback = this._defaultOneParamCallback, lesserOrGreater = CP.lt, targetNode = this.root, iterationType = this.iterationType) {
+        targetNode = this.ensureNode(targetNode);
         const ans = [];
         if (!targetNode)
             return ans;
@@ -505,17 +506,8 @@ export class BST extends BinaryTree {
         }
     }
     /**
-     * Balancing Adjustment:
-     * Perfectly Balanced Binary Tree: Since the balance of a perfectly balanced binary tree is already fixed, no additional balancing adjustment is needed. Any insertion or deletion operation will disrupt the perfect balance, often requiring a complete reconstruction of the tree.
-     * AVL Tree: After insertion or deletion operations, an AVL tree performs rotation adjustments based on the balance factor of nodes to restore the tree's balance. These rotations can be left rotations, right rotations, left-right rotations, or right-left rotations, performed as needed.
-     *
-     * Use Cases and Efficiency:
-     * Perfectly Balanced Binary Tree: Perfectly balanced binary trees are typically used in specific scenarios such as complete binary heaps in heap sort or certain types of Huffman trees. However, they are not suitable for dynamic operations requiring frequent insertions and deletions, as these operations often necessitate full tree reconstruction.
-     * AVL Tree: AVL trees are well-suited for scenarios involving frequent searching, insertion, and deletion operations. Through rotation adjustments, AVL trees maintain their balance, ensuring average and worst-case time complexity of O(log n).
-     */
-    /**
-     * Time Complexity: O(n) - Building a balanced tree from a sorted array.
-     * Space Complexity: O(n) - Additional space is required for the sorted array.
+     * Time Complexity: O(log n) - Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key.
+     * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
      */
     /**
      * Time Complexity: O(n) - Building a balanced tree from a sorted array.
@@ -528,7 +520,7 @@ export class BST extends BinaryTree {
      * values:
      * @returns The function `perfectlyBalance` returns a boolean value.
      */
-    perfectlyBalance(iterationType = this.options.iterationType) {
+    perfectlyBalance(iterationType = this.iterationType) {
         const sorted = this.dfs(node => node, 'in'), n = sorted.length;
         this.clear();
         if (sorted.length < 1)
@@ -539,7 +531,7 @@ export class BST extends BinaryTree {
                     return;
                 const m = l + Math.floor((r - l) / 2);
                 const midNode = sorted[m];
-                this.add(midNode.key, midNode.value);
+                this.add([midNode.key, midNode.value]);
                 buildBalanceBST(l, m - 1);
                 buildBalanceBST(m + 1, r);
             };
@@ -556,7 +548,7 @@ export class BST extends BinaryTree {
                         const m = l + Math.floor((r - l) / 2);
                         const midNode = sorted[m];
                         debugger;
-                        this.add(midNode.key, midNode.value);
+                        this.add([midNode.key, midNode.value]);
                         stack.push([m + 1, r]);
                         stack.push([l, m - 1]);
                     }
@@ -566,8 +558,17 @@ export class BST extends BinaryTree {
         }
     }
     /**
-     * Time Complexity: O(n) - Visiting each node once.
-     * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
+     * Balancing Adjustment:
+     * Perfectly Balanced Binary Tree: Since the balance of a perfectly balanced binary tree is already fixed, no additional balancing adjustment is needed. Any insertion or deletion operation will disrupt the perfect balance, often requiring a complete reconstruction of the tree.
+     * AVL Tree: After insertion or deletion operations, an AVL tree performs rotation adjustments based on the balance factor of nodes to restore the tree's balance. These rotations can be left rotations, right rotations, left-right rotations, or right-left rotations, performed as needed.
+     *
+     * Use Cases and Efficiency:
+     * Perfectly Balanced Binary Tree: Perfectly balanced binary trees are typically used in specific scenarios such as complete binary heaps in heap sort or certain types of Huffman trees. However, they are not suitable for dynamic operations requiring frequent insertions and deletions, as these operations often necessitate full tree reconstruction.
+     * AVL Tree: AVL trees are well-suited for scenarios involving frequent searching, insertion, and deletion operations. Through rotation adjustments, AVL trees maintain their balance, ensuring average and worst-case time complexity of O(log n).
+     */
+    /**
+     * Time Complexity: O(n) - Building a balanced tree from a sorted array.
+     * Space Complexity: O(n) - Additional space is required for the sorted array.
      */
     /**
      * Time Complexity: O(n) - Visiting each node once.
@@ -578,7 +579,7 @@ export class BST extends BinaryTree {
      * to check if the AVL tree is balanced. It can have two possible values:
      * @returns a boolean value.
      */
-    isAVLBalanced(iterationType = this.options.iterationType) {
+    isAVLBalanced(iterationType = this.iterationType) {
         if (!this.root)
             return true;
         let balanced = true;
@@ -638,7 +639,7 @@ export class BST extends BinaryTree {
      * than), CP.lt (less than), or CP.eq (equal).
      */
     _compare(a, b) {
-        const compared = this.options.comparator(a, b);
+        const compared = this.comparator(a, b);
         if (compared > 0)
             return CP.gt;
         else if (compared < 0)

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

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import { BiTreeDeleteResult, BTNCallback, BTNKey, IterationType, RBTNColor, RBTreeOptions, RedBlackTreeNested, RedBlackTreeNodeNested } from '../../types';
+import { BiTreeDeleteResult, BTNCallback, BTNKey, BTNodeExemplar, IterationType, RBTNColor, RBTreeOptions, RedBlackTreeNested, RedBlackTreeNodeNested } from '../../types';
 import { BST, BSTNode } from './bst';
 import { IBinaryTree } from '../../interfaces';
 export declare class RedBlackTreeNode<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTreeNodeNested<V>> extends BSTNode<V, N> {
@@ -21,35 +21,54 @@ export declare class RedBlackTreeNode<V = any, N extends RedBlackTreeNode<V, N>
  */
 export declare class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTreeNode<V, RedBlackTreeNodeNested<V>>, TREE extends RedBlackTree<V, N, TREE> = RedBlackTree<V, N, RedBlackTreeNested<V, N>>> extends BST<V, N, TREE> implements IBinaryTree<V, N, TREE> {
     Sentinel: N;
-    options: RBTreeOptions;
     /**
-     * The constructor function initializes a Red-Black Tree with an optional set of options.
-     * @param {RBTreeOptions} [options] - The `options` parameter is an optional object that can be
-     * passed to the constructor. It is used to configure the RBTree object with specific options.
-     */
-    constructor(options?: RBTreeOptions);
+     * This is the constructor function for a Red-Black Tree data structure in TypeScript, which
+     * initializes the tree with optional elements and options.
+     * @param [elements] - The `elements` parameter is an optional iterable of `BTNodeExemplar<V, N>`
+     * objects. It represents the initial elements that will be added to the RBTree during its
+     * construction. If this parameter is provided, the `addMany` method is called to add all the
+     * elements 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.
+     */
+    constructor(elements?: Iterable<BTNodeExemplar<V, N>>, options?: Partial<RBTreeOptions>);
     protected _root: N;
     get root(): N;
     protected _size: number;
     get size(): number;
+    /**
+     * The function creates a new Red-Black Tree node with the specified key, value, and color.
+     * @param {BTNKey} 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 {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.
+     * @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".
+     * @returns The method is returning a new instance of a RedBlackTreeNode with the specified key,
+     * value, and color.
+     */
     createNode(key: BTNKey, value?: V, color?: RBTNColor): N;
+    /**
+     * 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.
+     * @returns a new instance of a RedBlackTree object.
+     */
     createTree(options?: RBTreeOptions): TREE;
     /**
      * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
-     * Space Complexity: O(1)
-     *
-     * The `add` function adds a new node to a Red-Black Tree data structure.
-     * @param {BTNKey | N | null | undefined} keyOrNode - The `keyOrNode` parameter can be one of the
-     * following types:
-     * @param {V} [value] - The `value` parameter is an optional value that can be associated with the
-     * key in the node being added to the Red-Black Tree.
-     * @returns The method returns either a node (`N`) or `undefined`.
+     * The function adds a node to a Red-Black Tree data structure.
+     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be one of the following:
+     * @returns The method `add` returns either an instance of `N` (the node that was added) or
+     * `undefined`.
      */
-    add(keyOrNode: BTNKey | N | null | undefined, value?: V): N | undefined;
+    add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined;
     /**
      * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
      * Space Complexity: O(1)
@@ -70,6 +89,10 @@ export declare class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = Re
      * @returns an array of `BiTreeDeleteResult<N>`.
      */
     delete<C extends BTNCallback<N>>(identifier: ReturnType<C> | null | undefined, callback?: C): BiTreeDeleteResult<N>[];
+    /**
+     * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
+     * Space Complexity: O(1)
+     */
     isRealNode(node: N | undefined): node is N;
     getNode<C extends BTNCallback<N, BTNKey>>(identifier: BTNKey, callback?: C, beginRoot?: N | undefined, iterationType?: IterationType): N | undefined;
     getNode<C extends BTNCallback<N, N>>(identifier: N | undefined, callback?: C, beginRoot?: N | undefined, iterationType?: IterationType): N | undefined;
@@ -101,6 +124,10 @@ export declare class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = Re
      * @returns the predecessor of the given RedBlackTreeNode 'x'.
      */
     getPredecessor(x: N): N;
+    /**
+     * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
+     * Space Complexity: O(1)
+     */
     clear(): void;
     protected _setRoot(v: N): void;
     /**
@@ -166,4 +193,14 @@ export declare class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = Re
      * red-black tree.
      */
     protected _fixInsert(k: N): void;
+    /**
+     * The function replaces an old node with a new node while preserving the color of the old node.
+     * @param {N} oldNode - The `oldNode` parameter represents the node that needs to be replaced in a
+     * data structure. It is of type `N`, which is the type of the nodes in the data structure.
+     * @param {N} 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.
+     */
+    protected _replaceNode(oldNode: N, newNode: N): N;
 }