data-structure-typed 2.4.4 → 2.5.0

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

@@ -5,327 +5,397 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import { getMSB } from '../../utils';
+import { ERR } from '../../common';
 
 /**
+ * Binary Indexed Tree (Fenwick Tree).
  *
+ * Efficient prefix sums and point updates in O(log n).
+ * Standard array-based implementation per C++ competitive programming conventions.
+ *
+ * All indices are 0-based externally; internally converted to 1-based for BIT arithmetic.
+ *
+ * @example
+ * ```ts
+ * const bit = new BinaryIndexedTree(6);
+ * bit.update(0, 3);   // index 0 += 3
+ * bit.update(1, 2);   // index 1 += 2
+ * bit.update(2, 7);   // index 2 += 7
+ *
+ * bit.query(2);       // prefix sum [0..2] = 12
+ * bit.queryRange(1, 2); // range sum [1..2] = 9
+ * bit.get(1);         // point value at index 1 = 2
+ * ```
  */
-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>;
-
-  /**
-   * The function returns the frequency map of numbers.
-   * @returns The `_freqMap` property, which is a record with number keys and number values, is being
-   * returned.
-   */
-  get freqMap(): Record<number, number> {
-    return this._freqMap;
-  }
-
-  protected _msb: number;
-
-  /**
-   * The function returns the value of the _msb property.
-   * @returns The `_msb` property of the object.
-   */
-  get msb(): number {
-    return this._msb;
-  }
-
-  protected _negativeCount: number;
+export class BinaryIndexedTree implements Iterable<number> {
+  protected readonly _size: number;
+  protected _tree: number[];  // 1-indexed BIT array
 
   /**
-   * The function returns the value of the _negativeCount property.
-   * @returns The method is returning the value of the variable `_negativeCount`, which is of type
-   * `number`.
+   * Construct a BIT of given size (all zeros), or from an initial values array.
+   * @param sizeOrElements - number of elements, or an array of initial values
    */
-  get negativeCount(): number {
-    return this._negativeCount;
+  constructor(sizeOrElements: number | number[]) {
+    if (Array.isArray(sizeOrElements)) {
+      this._size = sizeOrElements.length;
+      this._tree = new Array(this._size + 1).fill(0);
+      for (let i = 0; i < this._size; i++) {
+        this._pointUpdate(i + 1, sizeOrElements[i]);
+      }
+    } else {
+      if (!Number.isInteger(sizeOrElements) || sizeOrElements < 0) {
+        throw new RangeError(ERR.invalidArgument('size must be a non-negative integer', 'BinaryIndexedTree'));
+      }
+      this._size = sizeOrElements;
+      this._tree = new Array(this._size + 1).fill(0);
+    }
   }
 
-  /**
-   * The above function returns the value of the protected variable `_freq`.
-   * @returns The frequency value stored in the protected variable `_freq`.
-   */
-  get freq(): number {
-    return this._freq;
-  }
+  // ─── Core operations ──────────────────────────────────────────
 
   /**
-   * The above function returns the maximum value.
-   * @returns The maximum value stored in the variable `_max`.
+   * Point update: add delta to the value at index (0-based).
+   * Time: O(log n)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Add delta at index
+ *  const bit = new BinaryIndexedTree([1, 2, 3, 4, 5]);
+ *     bit.update(2, 7);
+ *     console.log(bit.get(2)); // 10;
    */
-  get max(): number {
-    return this._max;
+  update(index: number, delta: number): void {
+    this._checkIndex(index);
+    this._pointUpdate(index + 1, delta);
   }
 
   /**
-   * 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.
+   * Point set: set the value at index to an absolute value (0-based).
+   * Time: O(log n)
+   
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Set value at index
+ *  const bit = new BinaryIndexedTree([1, 2, 3]);
+ *     bit.set(1, 10);
+ *     console.log(bit.get(1)); // 10;
    */
-  readSingle(index: number): number {
+  set(index: number, value: number): void {
     this._checkIndex(index);
-    return this._readSingle(index);
+    const current = this.get(index);
+    this._pointUpdate(index + 1, value - current);
   }
 
   /**
-   * 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.
+   * Get the point value at index (0-based).
+   * Time: O(log n)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get value at index
+ *  const bit = new BinaryIndexedTree([1, 2, 3]);
+ *     console.log(bit.get(0)); // 1;
+ *     console.log(bit.get(2)); // 3;
    */
-  update(position: number, change: number): void {
-    this._checkIndex(position);
-    const freqCur = this._readSingle(position);
-
-    this._update(position, change);
-    this._updateNegativeCount(freqCur, freqCur + change);
+  get(index: number): number {
+    this._checkIndex(index);
+    return this._pointQuery(index + 1);
   }
 
   /**
-   * 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.
+   * Prefix sum query: returns sum of elements [0..index] (inclusive, 0-based).
+   * Time: O(log n)
+   
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Prefix sum
+ *  const bit = new BinaryIndexedTree([1, 2, 3, 4]);
+ *     console.log(bit.query(2)); // 6;
    */
-  writeSingle(index: number, freq: number): void {
+  query(index: number): number {
     this._checkIndex(index);
-    this._writeSingle(index, freq);
+    return this._prefixSum(index + 1);
   }
 
   /**
-   * 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.
+   * Range sum query: returns sum of elements [start..end] (inclusive, 0-based).
+   * Time: O(log n)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Range sum
+ *  const bit = new BinaryIndexedTree([1, 2, 3, 4]);
+ *     console.log(bit.queryRange(1, 2)); // 5;
    */
-  read(count: number): number {
-    if (!Number.isInteger(count)) {
-      throw new Error('Invalid count');
-    }
-    return this._read(Math.max(Math.min(count, this.max), 0));
+  queryRange(start: number, end: number): number {
+    this._checkIndex(start);
+    this._checkIndex(end);
+    if (start > end) return 0;
+    if (start === 0) return this._prefixSum(end + 1);
+    return this._prefixSum(end + 1) - this._prefixSum(start);
   }
 
+  // ─── Binary search ───────────────────────────────────────────
+
   /**
-   * 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.
+   * Find the smallest index i such that prefix sum [0..i] >= sum.
+   * Requires all values to be non-negative (behavior undefined otherwise).
+   * Returns size if no such index exists.
+   * Time: O(log n)
+   
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find index with prefix sum ≥ target
+ *  const bit = new BinaryIndexedTree([1, 2, 3, 4]);
+ *     const idx = bit.lowerBound(4);
+ *     console.log(idx); // >= 0;
    */
   lowerBound(sum: number): number {
-    if (this.negativeCount > 0) {
-      throw new Error('Sequence is not non-descending');
+    let pos = 0;
+    let bitMask = this._highBit(this._size);
+
+    while (bitMask > 0) {
+      const next = pos + bitMask;
+      if (next <= this._size && this._tree[next] < sum) {
+        sum -= this._tree[next];
+        pos = next;
+      }
+      bitMask >>= 1;
     }
-    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);
+    return pos; // 0-based
   }
 
   /**
-   * 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`.
+   * Find the smallest index i such that prefix sum [0..i] > sum.
+   * Requires all values to be non-negative (behavior undefined otherwise).
+   * Returns size if no such index exists.
+   * Time: O(log n)
+   
+   
+   
+    * @example
+ * // Find index with prefix sum > target
+ *  const bit = new BinaryIndexedTree([1, 2, 3, 4]);
+ *     const idx = bit.upperBound(4);
+ *     console.log(idx); // >= 0;
    */
-  getPrefixSum(i: number): number {
-    this._checkIndex(i);
-    i++; // Convert to 1-based index
-
-    let sum = 0;
-    while (i > 0) {
-      sum += this._getFrequency(i);
-      i -= i & -i;
+  upperBound(sum: number): number {
+    let pos = 0;
+    let bitMask = this._highBit(this._size);
+
+    while (bitMask > 0) {
+      const next = pos + bitMask;
+      if (next <= this._size && this._tree[next] <= sum) {
+        sum -= this._tree[next];
+        pos = next;
+      }
+      bitMask >>= 1;
     }
 
-    return sum;
+    return pos; // 0-based
   }
 
-  /**
-   * 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];
-    }
+  // ─── Standard interface ──────────────────────────────────────
 
-    return this.freq * (index & -index);
+  get size(): number {
+    return this._size;
   }
 
-  /**
-   * 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;
+  isEmpty(): boolean {
+    return this._size === 0;
   }
 
-  /**
-   * 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).');
-    }
+  clear(): void {
+    this._tree.fill(0);
   }
 
-  /**
-   * 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;
+  clone(): BinaryIndexedTree {
+    return new BinaryIndexedTree(this.toArray());
   }
 
   /**
-   * 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.
+   * Returns the point values as a plain array.
+   * Time: O(n log n)
+   
+   
+   
+    * @example
+ * // Convert to array
+ *  const bit = new BinaryIndexedTree([1, 2, 3]);
+ *     console.log(bit.toArray()); // [1, 2, 3];
    */
-  protected _updateNegativeCount(freqCur: number, freqNew: number): void {
-    if (freqCur < 0 && freqNew >= 0) {
-      this._negativeCount--;
-    } else if (freqCur >= 0 && freqNew < 0) {
-      this._negativeCount++;
+  toArray(): number[] {
+    const result: number[] = [];
+    for (let i = 0; i < this._size; i++) {
+      result.push(this._pointQuery(i + 1));
     }
+    return result;
   }
 
   /**
-   * 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.
+   * Iterate over point values in index order.
    */
-  protected _update(index: number, delta: number): void {
-    index = index + 1;
+  [Symbol.iterator](): IterableIterator<number> {
+    const size = this._size;
+    let i = 0;
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this;
+    return {
+      [Symbol.iterator]() {
+        return this;
+      },
+      next(): IteratorResult<number> {
+        if (i < size) {
+          return { value: self._pointQuery(i++ + 1), done: false };
+        }
+        return { value: undefined as any, done: true };
+      }
+    };
+  }
 
-    while (index <= this.max) {
-      this._updateFrequency(index, delta);
-      index += index & -index;
+  forEach(callback: (value: number, index: number) => void): void {
+    for (let i = 0; i < this._size; i++) {
+      callback(this._pointQuery(i + 1), i);
     }
   }
 
-  /**
-   * 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);
+  print(): void {
+    console.log(this.toArray());
   }
 
-  /**
-   * 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;
+  // ─── Internal helpers ─────────────────────────────────────────
+
+  /** 1-based prefix sum up to pos (inclusive). */
+  protected _prefixSum(pos: number): number {
     let sum = 0;
-    while (index) {
-      sum += this._getFrequency(index);
-      index -= index & -index;
+    while (pos > 0) {
+      sum += this._tree[pos];
+      pos -= pos & -pos;
     }
-
     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;
+  /** 1-based point update: add delta to position pos. */
+  protected _pointUpdate(pos: number, delta: number): void {
+    while (pos <= this._size) {
+      this._tree[pos] += delta;
+      pos += pos & -pos;
+    }
+  }
 
-    while (right > left + 1) {
-      const middle = (left + right) >> 1;
-      const sumM = this._getFrequency(middle);
+  /** 1-based point query: get exact value at pos. */
+  protected _pointQuery(pos: number): number {
+    let val = this._tree[pos];
+    const lca = pos - (pos & -pos);  // parent in prefix-sum sense
+    pos--;
+    while (pos > lca) {
+      val -= this._tree[pos];
+      pos -= pos & -pos;
+    }
+    return val;
+  }
 
-      if (middle <= this.max && before(sumM, sumT)) {
-        sumT -= sumM;
-        left = middle;
-      } else {
-        right = middle;
-      }
+  protected _checkIndex(index: number): void {
+    if (!Number.isInteger(index)) {
+      throw new TypeError(ERR.invalidIndex('BinaryIndexedTree'));
+    }
+    if (index < 0 || index >= this._size) {
+      throw new RangeError(ERR.indexOutOfRange(index, 0, this._size - 1, 'BinaryIndexedTree'));
     }
-    return left;
+  }
+
+  /** Returns highest power of 2 <= n. */
+  protected _highBit(n: number): number {
+    let bit = 1;
+    while (bit <= n) bit <<= 1;
+    return bit >> 1;
   }
 }