data-structure-typed 1.37.3 → 1.37.5

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

@@ -33,11 +33,12 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_swap` function swaps the location of two nodes in a binary tree.
-   * @param {N} srcNode - The source node that you want to _swap with the destination node.
-   * @param {N} destNode - The `destNode` parameter represents the destination node where the values from `srcNode` will
-   * be swapped to.
-   * @returns The `destNode` is being returned.
+   * The function swaps the key, value, and height properties between two nodes in a binary tree.
+   * @param {N} srcNode - The `srcNode` parameter represents the source node that needs to be swapped
+   * with the `destNode`.
+   * @param {N} destNode - The `destNode` parameter represents the destination node where the values
+   * from the source node (`srcNode`) will be swapped to.
+   * @returns The method is returning the `destNode` after swapping its properties with the `srcNode`.
    */
   protected override _swap(srcNode: N, destNode: N): N {
     const {key, val, height} = destNode;
@@ -59,11 +60,12 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The function creates a new AVL tree node with the given key and value.
-   * @param {BinaryTreeNodeKey} key - The `key` parameter is the identifier for the binary tree node. It is used to uniquely
-   * identify each node in the tree.
-   * @param [val] - The `val` parameter is an optional value that can be assigned to the node. It represents the value
-   * that will be stored in the node.
+   * The function creates a new AVL tree node with the specified key and value.
+   * @param {BinaryTreeNodeKey} key - The key parameter is the key value that will be associated with
+   * the new node. It is used to determine the position of the node in the binary search tree.
+   * @param [val] - The parameter `val` is an optional value that can be assigned to the node. It is of
+   * type `N['val']`, which means it can be any value that is assignable to the `val` property of the
+   * node type `N`.
    * @returns a new AVLTreeNode object with the specified key and value.
    */
   override createNode(key: BinaryTreeNodeKey, val?: N['val']): N {
@@ -71,11 +73,13 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The function overrides the add method of a binary tree node and balances the tree after inserting a new node.
-   * @param keyOrNode - The `keyOrNode` parameter is either a key or a node that needs to be added to the binary tree.
-   * @param [val] - The `val` parameter is an optional value that can be assigned to the node being added. It is of type
-   * `N['val']`, which means it should be of the same type as the `val` property of the nodes in the binary tree.
-   * @returns The method is returning the inserted node, or null or undefined if the insertion was not successful.
+   * The function overrides the add method of a binary tree node and balances the tree after inserting
+   * a new node.
+   * @param {BinaryTreeNodeKey | N | null} keyOrNode - The `keyOrNode` parameter can accept either a
+   * `BinaryTreeNodeKey` or a `N` (which represents a node in the binary tree) or `null`.
+   * @param [val] - The `val` parameter is the value that you want to assign to the new node that you
+   * are adding to the binary search tree.
+   * @returns The method is returning the inserted node (`N`), `null`, or `undefined`.
    */
   override add(keyOrNode: BinaryTreeNodeKey | N | null, val?: N['val']): N | null | undefined {
     // TODO support node as a param
@@ -85,9 +89,11 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The function overrides the delete method of a binary tree and performs additional operations to balance the tree after deletion.
+   * The function overrides the delete method of a binary tree and balances the tree after deleting a
+   * node if necessary.
+   * @param {N | BinaryTreeNodeKey} nodeOrKey - The `nodeOrKey` parameter can be either a node object
+   * (`N`) or a key value (`BinaryTreeNodeKey`).
    * @returns The method is returning an array of `BinaryTreeDeletedResult<N>` objects.
-   * @param nodeOrKey - The `nodeOrKey` parameter is either a node or a key that needs to be deleted from the binary tree.
    */
   override delete(nodeOrKey: N | BinaryTreeNodeKey): BinaryTreeDeletedResult<N>[] {
     const deletedResults = super.delete(nodeOrKey);
@@ -100,10 +106,10 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The balance factor of a given AVL tree node is calculated by subtracting the height of its left subtree from the
-   * height of its right subtree.
-   * @param node - The parameter "node" is of type N, which represents a node in an AVL tree.
-   * @returns The balance factor of the given AVL tree node.
+   * The function calculates the balance factor of a node in a binary tree.
+   * @param {N} node - The parameter "node" represents a node in a binary tree data structure.
+   * @returns the balance factor of a given node. The balance factor is calculated by subtracting the
+   * height of the left subtree from the height of the right subtree.
    */
   protected _balanceFactor(node: N): number {
     if (!node.right)
@@ -116,8 +122,9 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The function updates the height of a node in an AVL tree based on the heights of its left and right subtrees.
-   * @param node - The parameter `node` is an AVLTreeNode object, which represents a node in an AVL tree.
+   * The function updates the height of a node in a binary tree based on the heights of its left and
+   * right children.
+   * @param {N} node - The parameter "node" represents a node in a binary tree data structure.
    */
   protected _updateHeight(node: N): void {
     if (!node.left && !node.right) node.height = 0;
@@ -129,9 +136,10 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balancePath` function balances the AVL tree by performing appropriate rotations based on the balance factor of
-   * each node in the path from the given node to the root.
-   * @param node - The `node` parameter is an AVLTreeNode object, which represents a node in an AVL tree.
+   * The `_balancePath` function is used to update the heights of nodes and perform rotation operations
+   * to restore balance in an AVL tree after inserting a node.
+   * @param {N} node - The `node` parameter in the `_balancePath` function represents the node in the
+   * AVL tree that needs to be balanced.
    */
   protected _balancePath(node: N): void {
     const path = this.getPathToRoot(node, false); // first O(log n) + O(log n)
@@ -173,8 +181,8 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balanceLL` function performs a left-left rotation on an AVL tree to balance it.
-   * @param A - The parameter A is an AVLTreeNode object.
+   * The function `_balanceLL` performs a left-left rotation to balance a binary tree.
+   * @param {N} A - A is a node in a binary tree.
    */
   protected _balanceLL(A: N): void {
     const parentOfA = A.parent;
@@ -203,8 +211,8 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balanceLR` function performs a left-right rotation to balance an AVL tree.
-   * @param A - A is an AVLTreeNode object.
+   * The `_balanceLR` function performs a left-right rotation to balance a binary tree.
+   * @param {N} A - A is a node in a binary tree.
    */
   protected _balanceLR(A: N): void {
     const parentOfA = A.parent;
@@ -251,8 +259,8 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balanceRR` function performs a right-right rotation on an AVL tree to balance it.
-   * @param A - The parameter A is an AVLTreeNode object.
+   * The function `_balanceRR` performs a right-right rotation to balance a binary tree.
+   * @param {N} A - A is a node in a binary tree.
    */
   protected _balanceRR(A: N): void {
     const parentOfA = A.parent;
@@ -286,8 +294,8 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balanceRL` function performs a right-left rotation to balance an AVL tree.
-   * @param A - A is an AVLTreeNode object.
+   * The function `_balanceRL` performs a right-left rotation to balance a binary tree.
+   * @param {N} A - A is a node in a binary tree.
    */
   protected _balanceRL(A: N): void {
     const parentOfA = A.parent;

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

@@ -5,72 +5,294 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
+import {getMSB} from '../../utils';
+
 export class BinaryIndexedTree {
+  protected readonly _freq: number;
+  protected readonly _max: number;
+
+  /**
+   * The constructor initializes the properties of an object, including default frequency, maximum
+   * value, a freqMap data structure, the most significant bit, and the count of negative frequencies.
+   * @param  - - `frequency`: The default frequency value. It is optional and has a default
+   * value of 0.
+   */
+  constructor({frequency = 0, max}: {frequency?: number; max: number}) {
+    this._freq = frequency;
+    this._max = max;
+    this._freqMap = {0: 0};
+    this._msb = getMSB(max);
+    this._negativeCount = frequency < 0 ? max : 0;
+  }
+
+  protected _freqMap: Record<number, number>;
+
+  get freqMap(): Record<number, number> {
+    return this._freqMap;
+  }
+
+  set freqMap(value: Record<number, number>) {
+    this._freqMap = value;
+  }
+
+  protected _msb: number;
+
+  get msb(): number {
+    return this._msb;
+  }
+
+  set msb(value: number) {
+    this._msb = value;
+  }
+
+  protected _negativeCount: number;
+
+  get negativeCount(): number {
+    return this._negativeCount;
+  }
+
+  set negativeCount(value: number) {
+    this._negativeCount = value;
+  }
+
+  get freq(): number {
+    return this._freq;
+  }
+
+  get max(): number {
+    return this._max;
+  }
+
   /**
-   * The constructor initializes an array with a specified length and fills it with zeros.
-   * @param {number} n - The parameter `n` represents the size of the array that will be used to store the sum tree. The
-   * sum tree is a binary tree data structure used to efficiently calculate the sum of a range of elements in an array.
-   * The size of the sum tree array is `n + 1` because
+   * The function "readSingle" reads a single number from a specified index.
+   * @param {number} index - The `index` parameter is a number that represents the index of an element in a
+   * collection or array.
+   * @returns a number.
    */
-  constructor(n: number) {
-    this._sumTree = new Array<number>(n + 1).fill(0);
+  readSingle(index: number): number {
+    this._checkIndex(index);
+    return this._readSingle(index);
   }
 
-  private _sumTree: number[];
+  /**
+   * The "update" function updates the value at a given index by adding a delta and triggers a callback
+   * to notify of the change.
+   * @param {number} position - The `index` parameter represents the index of the element that needs to be
+   * updated in the data structure.
+   * @param {number} change - The "delta" parameter represents the change in value that needs to be
+   * applied to the frequency at the specified index.
+   */
+  update(position: number, change: number): void {
+    this._checkIndex(position);
+    const freqCur = this._readSingle(position);
 
-  get sumTree(): number[] {
-    return this._sumTree;
+    this._update(position, change);
+    this._updateNegativeCount(freqCur, freqCur + change);
   }
 
-  static lowBit(x: number) {
-    return x & -x;
+  /**
+   * The function "writeSingle" checks the index and writes a single value with a given frequency.
+   * @param {number} index - The `index` parameter is a number that represents the index of an element. It
+   * is used to identify the specific element that needs to be written.
+   * @param {number} freq - The `freq` parameter represents the frequency value that needs to be
+   * written.
+   */
+  writeSingle(index: number, freq: number): void {
+    this._checkIndex(index);
+    this._writeSingle(index, freq);
   }
 
   /**
-   * The update function updates the values in a binary indexed tree by adding a delta value to the specified index and
-   * its ancestors.
-   * @param {number} i - The parameter `i` represents the index of the element in the `_sumTree` array that needs to be
-   * updated.
-   * @param {number} delta - The "delta" parameter represents the change in value that needs to be added to the element
-   * at index "i" in the "_sumTree" array.
+   * The read function takes a count parameter, checks if it is an integer, and returns the result of
+   * calling the _read function with the count parameter clamped between 0 and the maximum value.
+   * @param {number} count - The `count` parameter is a number that represents the number of items to
+   * read.
+   * @returns a number.
    */
-  update(i: number, delta: number) {
-    while (i < this._sumTree.length) {
-      this._sumTree[i] += delta;
-      i += BinaryIndexedTree.lowBit(i);
+  read(count: number): number {
+    if (!Number.isInteger(count)) {
+      throw new Error('Invalid count');
     }
+    return this._read(Math.max(Math.min(count, this.max), 0));
   }
 
   /**
-   * The function calculates the prefix sum of an array using a binary indexed tree.
-   * @param {number} i - The parameter "i" in the function "getPrefixSum" represents the index of the element in the
-   * array for which we want to calculate the prefix sum.
-   * @returns The function `getPrefixSum` returns the prefix sum of the elements in the binary indexed tree up to index
-   * `i`.
+   * The function returns the lower bound of a non-descending sequence that sums up to a given number.
+   * @param {number} sum - The `sum` parameter is a number that represents the target sum that we want
+   * to find in the sequence.
+   * @returns The lowerBound function is returning a number.
    */
-  getPrefixSum(i: number) {
-    let sum = 0;
-    while (i > 0) {
-      sum += this._sumTree[i];
-      i -= BinaryIndexedTree.lowBit(i);
+  lowerBound(sum: number): number {
+    if (this.negativeCount > 0) {
+      throw new Error('Sequence is not non-descending');
+    }
+    return this._binarySearch(sum, (x, y) => x < y);
+  }
+
+  /**
+   * The upperBound function returns the index of the first element in a sequence that is greater than
+   * or equal to a given sum.
+   * @param {number} sum - The "sum" parameter is a number that represents the target sum that we want
+   * to find in the sequence.
+   * @returns The upperBound function is returning a number.
+   */
+  upperBound(sum: number): number {
+    if (this.negativeCount > 0) {
+      throw new Error('Must not be descending');
+    }
+    return this._binarySearch(sum, (x, y) => x <= y);
+  }
+
+  /**
+   * The function returns the value of a specific index in a freqMap data structure, or a default value if
+   * the index is not found.
+   * @param {number} index - The `index` parameter is a number that represents the index of a node in a
+   * freqMap data structure.
+   * @returns a number.
+   */
+  protected _getFrequency(index: number): number {
+    if (index in this.freqMap) {
+      return this.freqMap[index];
+    }
+
+    return this.freq * (index & -index);
+  }
+
+  /**
+   * The function _updateFrequency adds a delta value to the element at the specified index in the freqMap array.
+   * @param {number} index - The index parameter is a number that represents the index of the freqMap
+   * element that needs to be updated.
+   * @param {number} delta - The `delta` parameter represents the change in value that needs to be
+   * added to the freqMap at the specified `index`.
+   */
+  protected _updateFrequency(index: number, delta: number): void {
+    this.freqMap[index] = this._getFrequency(index) + delta;
+  }
+
+  /**
+   * The function checks if the given index is valid and within the range.
+   * @param {number} index - The parameter "index" is of type number and represents the index value
+   * that needs to be checked.
+   */
+  protected _checkIndex(index: number): void {
+    if (!Number.isInteger(index)) {
+      throw new Error('Invalid index: Index must be an integer.');
+    }
+    if (index < 0 || index >= this.max) {
+      throw new Error('Index out of range: Index must be within the range [0, this.max).');
     }
+  }
+
+  /**
+   * The function calculates the sum of elements in an array up to a given index using a binary indexed
+   * freqMap.
+   * @param {number} index - The `index` parameter is a number that represents the index of an element in a
+   * data structure.
+   * @returns a number.
+   */
+  protected _readSingle(index: number): number {
+    index = index + 1;
+    let sum = this._getFrequency(index);
+    const z = index - (index & -index);
+
+    index--;
+
+    while (index !== z) {
+      sum -= this._getFrequency(index);
+      index -= index & -index;
+    }
+
     return sum;
   }
 
   /**
-   * The function `getRangeSum` calculates the sum of a range of numbers in an array.
-   * @param {number} start - The start parameter is the starting index of the range for which we want to calculate the
-   * sum.
-   * @param {number} end - The "end" parameter represents the ending index of the range for which we want to calculate
-   * the sum.
-   * @returns the sum of the elements in the range specified by the start and end indices.
+   * The function `_updateNegativeCount` updates a counter based on changes in frequency values.
+   * @param {number} freqCur - The current frequency value.
+   * @param {number} freqNew - The freqNew parameter represents the new frequency value.
+   */
+  protected _updateNegativeCount(freqCur: number, freqNew: number): void {
+    if (freqCur < 0 && freqNew >= 0) {
+      this.negativeCount--;
+    } else if (freqCur >= 0 && freqNew < 0) {
+      this.negativeCount++;
+    }
+  }
+
+  /**
+   * The `_update` function updates the values in a binary indexed freqMap starting from a given index and
+   * propagating the changes to its parent nodes.
+   * @param {number} index - The `index` parameter is a number that represents the index of the element in
+   * the data structure that needs to be updated.
+   * @param {number} delta - The `delta` parameter represents the change in value that needs to be
+   * applied to the elements in the data structure.
    */
-  getRangeSum(start: number, end: number): number {
-    if (!(0 <= start && start <= end && end <= this._sumTree.length)) throw 'Index out of bounds';
-    return this.getPrefixSum(end) - this.getPrefixSum(start);
+  protected _update(index: number, delta: number): void {
+    index = index + 1;
+
+    while (index <= this.max) {
+      this._updateFrequency(index, delta);
+      index += index & -index;
+    }
   }
 
-  protected _setSumTree(value: number[]) {
-    this._sumTree = value;
+  /**
+   * The `_writeSingle` function updates the frequency at a specific index and triggers a callback if
+   * the frequency has changed.
+   * @param {number} index - The `index` parameter is a number that represents the index of the element
+   * being modified or accessed.
+   * @param {number} freq - The `freq` parameter represents the new frequency value that needs to be
+   * written to the specified index `index`.
+   */
+  protected _writeSingle(index: number, freq: number): void {
+    const freqCur = this._readSingle(index);
+
+    this._update(index, freq - freqCur);
+    this._updateNegativeCount(freqCur, freq);
+  }
+
+  /**
+   * The `_read` function calculates the sum of values in a binary freqMap up to a given count.
+   * @param {number} count - The `count` parameter is a number that represents the number of elements
+   * to read from the freqMap.
+   * @returns the sum of the values obtained from calling the `_getFrequency` method for each index in the
+   * range from `count` to 1.
+   */
+  protected _read(count: number): number {
+    let index = count;
+    let sum = 0;
+    while (index) {
+      sum += this._getFrequency(index);
+      index -= index & -index;
+    }
+
+    return sum;
+  }
+
+  /**
+   * The function `_binarySearch` performs a binary search to find the largest number that satisfies a given
+   * condition.
+   * @param {number} sum - The sum parameter is a number that represents the target sum value.
+   * @param before - The `before` parameter is a function that takes two numbers `x` and `y` as
+   * arguments and returns a boolean value. It is used to determine if `x` is less than or equal to
+   * `y`. The purpose of this function is to compare two numbers and determine their order.
+   * @returns the value of the variable "left".
+   */
+  protected _binarySearch(sum: number, before: (x: number, y: number) => boolean): number {
+    let left = 0;
+    let right = this.msb << 1;
+    let sumT = sum;
+
+    while (right > left + 1) {
+      const middle = (left + right) >> 1;
+      const sumM = this._getFrequency(middle);
+
+      if (middle <= this.max && before(sumM, sumT)) {
+        sumT -= sumM;
+        left = middle;
+      } else {
+        right = middle;
+      }
+    }
+    return left;
   }
 }