min-heap-typed 1.50.1 → 1.50.3

package/src/data-structures/binary-tree/segment-tree.ts

@@ -9,18 +9,136 @@
 import type { SegmentTreeNodeVal } from '../../types';
 
 export class SegmentTreeNode {
-  start = 0;
-  end = 0;
-  value: SegmentTreeNodeVal | undefined = undefined;
-  sum = 0;
-  left: SegmentTreeNode | undefined = undefined;
-  right: SegmentTreeNode | undefined = undefined;
-
+  /**
+   * The constructor initializes the properties of a SegmentTreeNode object.
+   * @param {number} start - The `start` parameter represents the starting index of the segment covered
+   * by this node in a segment tree.
+   * @param {number} end - The `end` parameter represents the end index of the segment covered by this
+   * node in a segment tree.
+   * @param {number} sum - The `sum` parameter represents the sum of the values in the range covered by
+   * the segment tree node.
+   * @param {SegmentTreeNodeVal | undefined} [value] - The `value` parameter is an optional parameter
+   * of type `SegmentTreeNodeVal`. It represents the value associated with the segment tree node.
+   */
   constructor(start: number, end: number, sum: number, value?: SegmentTreeNodeVal | undefined) {
-    this.start = start;
-    this.end = end;
-    this.sum = sum;
-    this.value = value || undefined;
+    this._start = start;
+    this._end = end;
+    this._sum = sum;
+    this._value = value || undefined;
+  }
+
+  protected _start = 0;
+
+  /**
+   * The function returns the value of the protected variable _start.
+   * @returns The start value, which is of type number.
+   */
+  get start(): number {
+    return this._start;
+  }
+
+  /**
+   * The above function sets the value of the "start" property.
+   * @param {number} value - The value parameter is of type number.
+   */
+  set start(value: number) {
+    this._start = value;
+  }
+
+  protected _end = 0;
+
+  /**
+   * The function returns the value of the protected variable `_end`.
+   * @returns The value of the protected property `_end`.
+   */
+  get end(): number {
+    return this._end;
+  }
+
+  /**
+   * The above function sets the value of the "end" property.
+   * @param {number} value - The value parameter is a number that represents the new value for the end
+   * property.
+   */
+  set end(value: number) {
+    this._end = value;
+  }
+
+  protected _value: SegmentTreeNodeVal | undefined = undefined;
+
+  /**
+   * The function returns the value of a segment tree node.
+   * @returns The value being returned is either a `SegmentTreeNodeVal` object or `undefined`.
+   */
+  get value(): SegmentTreeNodeVal | undefined {
+    return this._value;
+  }
+
+  /**
+   * The function sets the value of a segment tree node.
+   * @param {SegmentTreeNodeVal | undefined} value - The `value` parameter is of type
+   * `SegmentTreeNodeVal` or `undefined`.
+   */
+  set value(value: SegmentTreeNodeVal | undefined) {
+    this._value = value;
+  }
+
+  protected _sum = 0;
+
+  /**
+   * The function returns the value of the sum property.
+   * @returns The method is returning the value of the variable `_sum`.
+   */
+  get sum(): number {
+    return this._sum;
+  }
+
+  /**
+   * The above function sets the value of the sum property.
+   * @param {number} value - The parameter "value" is of type "number".
+   */
+  set sum(value: number) {
+    this._sum = value;
+  }
+
+  protected _left: SegmentTreeNode | undefined = undefined;
+
+  /**
+   * The function returns the left child of a segment tree node.
+   * @returns The `left` property of the `SegmentTreeNode` object is being returned. It is of type
+   * `SegmentTreeNode` or `undefined`.
+   */
+  get left(): SegmentTreeNode | undefined {
+    return this._left;
+  }
+
+  /**
+   * The function sets the value of the left property of a SegmentTreeNode object.
+   * @param {SegmentTreeNode | undefined} value - The value parameter is of type SegmentTreeNode or
+   * undefined.
+   */
+  set left(value: SegmentTreeNode | undefined) {
+    this._left = value;
+  }
+
+  protected _right: SegmentTreeNode | undefined = undefined;
+
+  /**
+   * The function returns the right child of a segment tree node.
+   * @returns The `getRight()` method is returning a value of type `SegmentTreeNode` or `undefined`.
+   */
+  get right(): SegmentTreeNode | undefined {
+    return this._right;
+  }
+
+  /**
+   * The function sets the right child of a segment tree node.
+   * @param {SegmentTreeNode | undefined} value - The `value` parameter is of type `SegmentTreeNode |
+   * undefined`. This means that it can accept either a `SegmentTreeNode` object or `undefined` as its
+   * value.
+   */
+  set right(value: SegmentTreeNode | undefined) {
+    this._right = value;
   }
 }
 
@@ -51,24 +169,40 @@ export class SegmentTree {
 
   protected _values: number[] = [];
 
+  /**
+   * The function returns an array of numbers.
+   * @returns An array of numbers is being returned.
+   */
   get values(): number[] {
     return this._values;
   }
 
   protected _start = 0;
 
+  /**
+   * The function returns the value of the protected variable _start.
+   * @returns The start value, which is of type number.
+   */
   get start(): number {
     return this._start;
   }
 
   protected _end: number;
 
+  /**
+   * The function returns the value of the protected variable `_end`.
+   * @returns The value of the protected property `_end`.
+   */
   get end(): number {
     return this._end;
   }
 
   protected _root: SegmentTreeNode | undefined;
 
+  /**
+   * The function returns the root node of a segment tree.
+   * @returns The `root` property of the class `SegmentTreeNode` or `undefined` if it is not defined.
+   */
   get root(): SegmentTreeNode | undefined {
     return this._root;
   }

package/src/data-structures/binary-tree/tree-multimap.ts

@@ -21,10 +21,8 @@ import { AVLTree, AVLTreeNode } from './avl-tree';
 export class TreeMultimapNode<
   K = any,
   V = any,
-  N extends TreeMultimapNode<K, V, N> = TreeMultimapNodeNested<K, V>
-> extends AVLTreeNode<K, V, N> {
-  count: number;
-
+  NODE extends TreeMultimapNode<K, V, NODE> = TreeMultimapNodeNested<K, V>
+> extends AVLTreeNode<K, V, NODE> {
   /**
    * The constructor function initializes a BinaryTreeNode object with a key, value, and count.
    * @param {K} key - The `key` parameter is of type `K` and represents the unique identifier
@@ -39,6 +37,25 @@ export class TreeMultimapNode<
     super(key, value);
     this.count = count;
   }
+
+  protected _count: number = 1;
+
+  /**
+   * The function returns the value of the protected variable _count.
+   * @returns The count property of the object, which is of type number.
+   */
+  get count(): number {
+    return this._count;
+  }
+
+  /**
+   * The above function sets the value of the count property.
+   * @param {number} value - The value parameter is of type number, which means it can accept any
+   * numeric value.
+   */
+  set count(value: number) {
+    this._count = value;
+  }
 }
 
 /**
@@ -47,19 +64,24 @@ export class TreeMultimapNode<
 export class TreeMultimap<
   K = any,
   V = any,
-  N extends TreeMultimapNode<K, V, N> = TreeMultimapNode<K, V, TreeMultimapNodeNested<K, V>>,
-  TREE extends TreeMultimap<K, V, N, TREE> = TreeMultimap<K, V, N, TreeMultimapNested<K, V, N>>
+  NODE extends TreeMultimapNode<K, V, NODE> = TreeMultimapNode<K, V, TreeMultimapNodeNested<K, V>>,
+  TREE extends TreeMultimap<K, V, NODE, TREE> = TreeMultimap<K, V, NODE, TreeMultimapNested<K, V, NODE>>
 >
-  extends AVLTree<K, V, N, TREE>
-  implements IBinaryTree<K, V, N, TREE> {
-  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, N>> = [], options?: TreeMultimapOptions<K>) {
+  extends AVLTree<K, V, NODE, TREE>
+  implements IBinaryTree<K, V, NODE, TREE> {
+  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: TreeMultimapOptions<K>) {
     super([], options);
     if (keysOrNodesOrEntries) this.addMany(keysOrNodesOrEntries);
   }
 
-  private _count = 0;
+  protected _count = 0;
 
   // TODO the _count is not accurate after nodes count modified
+  /**
+   * The function calculates the sum of the count property of all nodes in a tree using depth-first
+   * search.
+   * @returns the sum of the count property of all nodes in the tree.
+   */
   get count(): number {
     let sum = 0;
     this.dfs(node => (sum += node.count));
@@ -70,17 +92,26 @@ export class TreeMultimap<
    * The function creates a new BSTNode with the given key, value, and count.
    * @param {K} key - The key parameter is the unique identifier for the binary tree node. It is used to
    * distinguish one node from another in the tree.
-   * @param {N} value - The `value` parameter represents the value that will be stored in the binary search tree node.
+   * @param {NODE} value - The `value` parameter represents the value that will be stored in the binary search tree node.
    * @param {number} [count] - The "count" parameter is an optional parameter of type number. It represents the number of
    * occurrences of the value in the binary search tree node. If not provided, the count will default to 1.
    * @returns A new instance of the BSTNode class with the specified key, value, and count (if provided).
    */
-  override createNode(key: K, value?: V, count?: number): N {
-    return new TreeMultimapNode(key, value, count) as N;
+  override createNode(key: K, value?: V, count?: number): NODE {
+    return new TreeMultimapNode(key, value, count) as NODE;
   }
 
+  /**
+   * The function creates a new TreeMultimap object with the specified options and returns it.
+   * @param [options] - The `options` parameter is an optional object that contains additional
+   * configuration options for creating the `TreeMultimap` object. It can include properties such as
+   * `iterationType` and `variant`, which are used to specify the type of iteration and the variant of
+   * the tree, respectively. These properties can be
+   * @returns a new instance of the `TreeMultimap` class, with the provided options merged with the
+   * default options. The returned value is casted as `TREE`.
+   */
   override createTree(options?: TreeMultimapOptions<K>): TREE {
-    return new TreeMultimap<K, V, N, TREE>([], {
+    return new TreeMultimap<K, V, NODE, TREE>([], {
       iterationType: this.iterationType,
       variant: this.variant,
       ...options
@@ -88,18 +119,22 @@ export class TreeMultimap<
   }
 
   /**
-   * The function `exemplarToNode` converts an keyOrNodeOrEntry object into a node object.
-   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, N>`, which means it
+   * The function `keyValueOrEntryToNode` converts an keyOrNodeOrEntry object into a node object.
+   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`, which means it
    * can be one of the following:
    * @param {V} [value] - The `value` parameter is an optional argument that represents the value
    * associated with the node. It is of type `V`, which can be any data type. If no value is provided,
    * it defaults to `undefined`.
    * @param [count=1] - The `count` parameter is an optional parameter that specifies the number of
    * times the value should be added to the node. If not provided, it defaults to 1.
-   * @returns a node of type `N` or `undefined`.
+   * @returns a node of type `NODE` or `undefined`.
    */
-  override exemplarToNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, N>, value?: V, count = 1): N | undefined {
-    let node: N | undefined;
+  override keyValueOrEntryToNode(
+    keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>,
+    value?: V,
+    count = 1
+  ): NODE | undefined {
+    let node: NODE | undefined;
     if (keyOrNodeOrEntry === undefined || keyOrNodeOrEntry === null) {
       return;
     } else if (this.isNode(keyOrNodeOrEntry)) {
@@ -121,18 +156,17 @@ export class TreeMultimap<
 
   /**
    * The function checks if an keyOrNodeOrEntry is an instance of the TreeMultimapNode class.
-   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, N>`.
+   * @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 TreeMultimapNode
    * class.
    */
-  override isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, N>): keyOrNodeOrEntry is N {
+  override isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>): keyOrNodeOrEntry is NODE {
     return keyOrNodeOrEntry instanceof TreeMultimapNode;
   }
 
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
-   * logarithmic time, where "n" is the number of nodes in the tree. The add method of the superclass (AVLTree) has logarithmic time complexity. constant space, as it doesn't use additional data structures that scale with input size.
    */
 
   /**
@@ -151,8 +185,8 @@ export class TreeMultimap<
    * @returns The method is returning either the newly inserted node or `undefined` if the insertion
    * was not successful.
    */
-  override add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, N>, value?: V, count = 1): boolean {
-    const newNode = this.exemplarToNode(keyOrNodeOrEntry, value, count);
+  override add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V, count = 1): boolean {
+    const newNode = this.keyValueOrEntryToNode(keyOrNodeOrEntry, value, count);
     if (newNode === undefined) return false;
 
     const orgNodeCount = newNode?.count || 0;
@@ -164,88 +198,12 @@ export class TreeMultimap<
   }
 
   /**
-   * Time Complexity: O(k log n)
-   * Space Complexity: O(1)
-   * logarithmic time, where "n" is the number of nodes in the tree. The add method of the superclass (AVLTree) has logarithmic time complexity. constant space, as it doesn't use additional data structures that scale with input size.
-   */
-
-  /**
-   * Time Complexity: O(k log n)
-   * Space Complexity: O(1)
-   *
-   * The function overrides the addMany method to add multiple keys, nodes, or entries to a data
-   * structure.
-   * @param keysOrNodesOrEntries - The parameter `keysOrNodesOrEntries` is an iterable that can contain
-   * either keys, nodes, or entries.
-   * @returns The method is returning an array of type `N | undefined`.
-   */
-  override addMany(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, N>>): boolean[] {
-    return super.addMany(keysOrNodesOrEntries);
-  }
-
-  /**
-   * Time Complexity: O(n log n)
-   * Space Complexity: O(n)
-   * logarithmic time for each insertion, where "n" is the number of nodes in the tree. This is because the method calls the add method for each node. linear space, as it creates an array to store the sorted nodes.
-   */
-
-  /**
-   * Time Complexity: O(n log n)
-   * Space Complexity: O(n)
-   *
-   * The `perfectlyBalance` function takes a sorted array of nodes and builds a balanced binary search
-   * tree using either a recursive or iterative approach.
-   * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
-   * type of iteration to use when building the balanced binary search tree. It can have two possible
-   * values:
-   * @returns a boolean value.
-   */
-  override perfectlyBalance(iterationType = this.iterationType): boolean {
-    const sorted = this.dfs(node => node, 'in'),
-      n = sorted.length;
-    if (sorted.length < 1) return false;
-
-    this.clear();
-
-    if (iterationType === IterationType.RECURSIVE) {
-      const buildBalanceBST = (l: number, r: number) => {
-        if (l > r) return;
-        const m = l + Math.floor((r - l) / 2);
-        const midNode = sorted[m];
-        this.add(midNode.key, midNode.value, midNode.count);
-        buildBalanceBST(l, m - 1);
-        buildBalanceBST(m + 1, r);
-      };
-
-      buildBalanceBST(0, n - 1);
-      return true;
-    } else {
-      const stack: [[number, number]] = [[0, n - 1]];
-      while (stack.length > 0) {
-        const popped = stack.pop();
-        if (popped) {
-          const [l, r] = popped;
-          if (l <= r) {
-            const m = l + Math.floor((r - l) / 2);
-            const midNode = sorted[m];
-            this.add(midNode.key, midNode.value, midNode.count);
-            stack.push([m + 1, r]);
-            stack.push([l, m - 1]);
-          }
-        }
-      }
-      return true;
-    }
-  }
-
-  /**
-   * Time Complexity: O(k log n)
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
-   * logarithmic time for each insertion, where "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted. This is because the method iterates through the keys and calls the add method for each. constant space, as it doesn't use additional data structures that scale with input size.
    */
 
   /**
-   * Time Complexity: O(k log n)
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
    * The `delete` function in TypeScript is used to remove a node from a binary tree, taking into
@@ -261,22 +219,22 @@ export class TreeMultimap<
    * being deleted. If set to true, the count of the node will not be considered and the node will be
    * deleted regardless of its count. If set to false (default), the count of the node will be
    * decremented by 1 and
-   * @returns an array of `BinaryTreeDeleteResult<N>`.
+   * @returns an array of `BinaryTreeDeleteResult<NODE>`.
    */
-  override delete<C extends BTNCallback<N>>(
+  override delete<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C>,
     callback: C = this._defaultOneParamCallback as C,
     ignoreCount = false
-  ): BinaryTreeDeleteResult<N>[] {
-    const deletedResult: BinaryTreeDeleteResult<N>[] = [];
+  ): BinaryTreeDeleteResult<NODE>[] {
+    const deletedResult: BinaryTreeDeleteResult<NODE>[] = [];
     if (!this.root) return deletedResult;
 
-    const curr: N | undefined = this.getNode(identifier, callback) ?? undefined;
+    const curr: NODE | undefined = this.getNode(identifier, callback) ?? undefined;
     if (!curr) return deletedResult;
 
-    const parent: N | undefined = curr?.parent ? curr.parent : undefined;
-    let needBalanced: N | undefined = undefined,
-      orgCurrent: N | undefined = curr;
+    const parent: NODE | undefined = curr?.parent ? curr.parent : undefined;
+    let needBalanced: NODE | undefined = undefined,
+      orgCurrent: NODE | undefined = curr;
 
     if (curr.count > 1 && !ignoreCount) {
       curr.count--;
@@ -339,6 +297,60 @@ export class TreeMultimap<
     this._count = 0;
   }
 
+  /**
+   * Time Complexity: O(n log n)
+   * Space Complexity: O(log n)
+   */
+
+  /**
+   * Time Complexity: O(n log n)
+   * Space Complexity: O(log n)
+   *
+   * The `perfectlyBalance` function takes a sorted array of nodes and builds a balanced binary search
+   * tree using either a recursive or iterative approach.
+   * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
+   * type of iteration to use when building the balanced binary search tree. It can have two possible
+   * values:
+   * @returns a boolean value.
+   */
+  override perfectlyBalance(iterationType = this.iterationType): boolean {
+    const sorted = this.dfs(node => node, 'in'),
+      n = sorted.length;
+    if (sorted.length < 1) return false;
+
+    this.clear();
+
+    if (iterationType === IterationType.RECURSIVE) {
+      const buildBalanceBST = (l: number, r: number) => {
+        if (l > r) return;
+        const m = l + Math.floor((r - l) / 2);
+        const midNode = sorted[m];
+        this.add(midNode.key, midNode.value, midNode.count);
+        buildBalanceBST(l, m - 1);
+        buildBalanceBST(m + 1, r);
+      };
+
+      buildBalanceBST(0, n - 1);
+      return true;
+    } else {
+      const stack: [[number, number]] = [[0, n - 1]];
+      while (stack.length > 0) {
+        const popped = stack.pop();
+        if (popped) {
+          const [l, r] = popped;
+          if (l <= r) {
+            const m = l + Math.floor((r - l) / 2);
+            const midNode = sorted[m];
+            this.add(midNode.key, midNode.value, midNode.count);
+            stack.push([m + 1, r]);
+            stack.push([l, m - 1]);
+          }
+        }
+      }
+      return true;
+    }
+  }
+
   /**
    * Time complexity: O(n)
    * Space complexity: O(n)
@@ -359,14 +371,17 @@ export class TreeMultimap<
 
   /**
    * The `_swapProperties` function swaps the key, value, count, and height properties between two nodes.
-   * @param {K | N | undefined} srcNode - The `srcNode` parameter represents the source node from
-   * which the values will be swapped. It can be of type `K`, `N`, or `undefined`.
-   * @param {K | N | undefined} destNode - The `destNode` parameter represents the destination
+   * @param {K | NODE | undefined} srcNode - The `srcNode` parameter represents the source node from
+   * which the values will be swapped. It can be of type `K`, `NODE`, or `undefined`.
+   * @param {K | NODE | undefined} destNode - The `destNode` parameter represents the destination
    * node where the values from the source node will be swapped to.
    * @returns either the `destNode` object if both `srcNode` and `destNode` are defined, or `undefined`
    * if either `srcNode` or `destNode` is undefined.
    */
-  protected override _swapProperties(srcNode: BSTNKeyOrNode<K, N>, destNode: BSTNKeyOrNode<K, N>): N | undefined {
+  protected override _swapProperties(
+    srcNode: BSTNKeyOrNode<K, NODE>,
+    destNode: BSTNKeyOrNode<K, NODE>
+  ): NODE | undefined {
     srcNode = this.ensureNode(srcNode);
     destNode = this.ensureNode(destNode);
     if (srcNode && destNode) {
@@ -391,7 +406,15 @@ export class TreeMultimap<
     return undefined;
   }
 
-  protected _replaceNode(oldNode: N, newNode: N): N {
+  /**
+   * The function replaces an old node with a new node and updates the count property of the new node.
+   * @param {NODE} oldNode - The `oldNode` parameter is of type `NODE` and represents the node that
+   * needs to be replaced in a data structure.
+   * @param {NODE} newNode - The `newNode` parameter is an object of type `NODE`.
+   * @returns The method is returning the result of calling the `_replaceNode` method from the
+   * superclass, after updating the `count` property of the `newNode` object.
+   */
+  protected _replaceNode(oldNode: NODE, newNode: NODE): NODE {
     newNode.count = oldNode.count + newNode.count;
     return super._replaceNode(oldNode, newNode);
   }