data-structure-typed 2.6.0 → 2.6.1

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

@@ -4,7 +4,6 @@
  * @author Pablo Zeng
  * @license MIT License
  */
-
 export type SegmentTreeOptions<E> = {
   merger: (a: E, b: E) => E;
   identity: E;
@@ -30,27 +29,22 @@ export type SegmentTreeOptions<E> = {
 export class SegmentTree<E = number> implements Iterable<E> {
   protected readonly _merger: (a: E, b: E) => E;
   protected readonly _identity: E;
-  protected _n: number;         // number of leaf elements
-  protected _tree: E[];         // flat array, 1-indexed, size 2*_size
-  protected _treeSize: number;  // internal tree size (next power of 2 >= _n)
-
+  protected _n: number; // number of leaf elements
+  protected _tree: E[]; // flat array, 1-indexed, size 2*_size
+  protected _treeSize: number; // internal tree size (next power of 2 >= _n)
   constructor(elements: E[], options: SegmentTreeOptions<E>) {
     this._merger = options.merger;
     this._identity = options.identity;
     this._n = elements.length;
-
     // Round up to next power of 2
     this._treeSize = 1;
     while (this._treeSize < this._n) this._treeSize <<= 1;
-
     // Allocate and fill with identity
     this._tree = new Array(2 * this._treeSize).fill(this._identity);
-
     // Place elements in leaves
     for (let i = 0; i < this._n; i++) {
       this._tree[this._treeSize + i] = elements[i];
     }
-
     // Build internal nodes bottom-up
     for (let i = this._treeSize - 1; i >= 1; i--) {
       this._tree[i] = this._merger(this._tree[2 * i], this._tree[2 * i + 1]);
@@ -59,6 +53,11 @@ export class SegmentTree<E = number> implements Iterable<E> {
 
   // ─── Convenience factories ─────────────────────────────────
 
+  // ─── Standard interface ────────────────────────────────────
+  get size(): number {
+    return this._n;
+  }
+
   /**
    * Create a sum segment tree.
    * @example
@@ -78,60 +77,18 @@ export class SegmentTree<E = number> implements Iterable<E> {
 
   /**
    * Create a min segment tree.
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Temperature monitoring with range queries
- *  // Hourly temperatures for a day (24 readings)
- *     const temps = [18, 17, 16, 15, 16, 18, 21, 24, 27, 29, 31, 32, 33, 32, 31, 29, 27, 25, 23, 21, 20, 19, 18, 17];
- *     const tree = SegmentTree.sum(temps);
- *
- *     // Average temperature during work hours (9-17)
- *     const workSum = tree.query(9, 17);
- *     console.log(workSum / 9); // toBeCloseTo;
- *
- *     // Sum of morning temps (6-11)
- *     console.log(tree.query(6, 11)); // 164;
+   * @example
+   * // Temperature monitoring with range queries
+   *  // Hourly temperatures for a day (24 readings)
+   *     const temps = [18, 17, 16, 15, 16, 18, 21, 24, 27, 29, 31, 32, 33, 32, 31, 29, 27, 25, 23, 21, 20, 19, 18, 17];
+   *     const tree = SegmentTree.sum(temps);
+   *
+   *     // Average temperature during work hours (9-17)
+   *     const workSum = tree.query(9, 17);
+   *     console.log(workSum / 9); // toBeCloseTo;
+   *
+   *     // Sum of morning temps (6-11)
+   *     console.log(tree.query(6, 11)); // 164;
    */
   static min(elements: number[]): SegmentTree<number> {
     return new SegmentTree<number>(elements, {
@@ -140,6 +97,8 @@ export class SegmentTree<E = number> implements Iterable<E> {
     });
   }
 
+  // ─── Core operations ───────────────────────────────────────
+
   /**
    * Create a max segment tree.
    * @example
@@ -155,77 +114,31 @@ export class SegmentTree<E = number> implements Iterable<E> {
     });
   }
 
-  // ─── Core operations ───────────────────────────────────────
-
   /**
    * Point update: set element at index to value.
    * Time: O(log n)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Dynamic range sum with updates
- *  // Monthly revenue data (in thousands)
- *     const revenue = [120, 95, 140, 110, 85, 130, 150, 100, 160, 125, 90, 175];
- *     const tree = SegmentTree.sum(revenue);
- *
- *     // Q1 revenue (Jan-Mar)
- *     console.log(tree.query(0, 2)); // 355;
- *
- *     // Update March revenue from 140 to 200
- *     tree.update(2, 200);
- *
- *     // Q1 revenue after update
- *     console.log(tree.query(0, 2)); // 415;
- *
- *     // H1 revenue (Jan-Jun)
- *     console.log(tree.query(0, 5)); // 740;
+   * @example
+   * // Dynamic range sum with updates
+   *  // Monthly revenue data (in thousands)
+   *     const revenue = [120, 95, 140, 110, 85, 130, 150, 100, 160, 125, 90, 175];
+   *     const tree = SegmentTree.sum(revenue);
+   *
+   *     // Q1 revenue (Jan-Mar)
+   *     console.log(tree.query(0, 2)); // 355;
+   *
+   *     // Update March revenue from 140 to 200
+   *     tree.update(2, 200);
+   *
+   *     // Q1 revenue after update
+   *     console.log(tree.query(0, 2)); // 415;
+   *
+   *     // H1 revenue (Jan-Jun)
+   *     console.log(tree.query(0, 5)); // 740;
    */
   update(index: number, value: E): void {
     if (index < 0 || index >= this._n) return;
-
     let pos = this._treeSize + index;
     this._tree[pos] = value;
-
     // Propagate up
     pos >>= 1;
     while (pos >= 1) {
@@ -237,71 +150,27 @@ export class SegmentTree<E = number> implements Iterable<E> {
   /**
    * Range query: returns merger result over [start, end] (inclusive).
    * Time: O(log n)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Range sum query on an array
- *  const tree = SegmentTree.sum([1, 3, 5, 7, 9, 11]);
- *
- *     // Query sum of range [1, 3] → 3 + 5 + 7 = 15
- *     console.log(tree.query(1, 3)); // 15;
- *
- *     // Query entire range
- *     console.log(tree.query(0, 5)); // 36;
- *
- *     // Query single element
- *     console.log(tree.query(2, 2)); // 5;
+   * @example
+   * // Range sum query on an array
+   *  const tree = SegmentTree.sum([1, 3, 5, 7, 9, 11]);
+   *
+   *     // Query sum of range [1, 3] → 3 + 5 + 7 = 15
+   *     console.log(tree.query(1, 3)); // 15;
+   *
+   *     // Query entire range
+   *     console.log(tree.query(0, 5)); // 36;
+   *
+   *     // Query single element
+   *     console.log(tree.query(2, 2)); // 5;
    */
   query(start: number, end: number): E {
     if (start < 0) start = 0;
     if (end >= this._n) end = this._n - 1;
     if (start > end) return this._identity;
-
     let resultLeft = this._identity;
     let resultRight = this._identity;
     let left = this._treeSize + start;
     let right = this._treeSize + end + 1; // exclusive
-
     while (left < right) {
       if (left & 1) {
         resultLeft = this._merger(resultLeft, this._tree[left]);
@@ -314,132 +183,44 @@ export class SegmentTree<E = number> implements Iterable<E> {
       left >>= 1;
       right >>= 1;
     }
-
     return this._merger(resultLeft, resultRight);
   }
 
+  // ─── Binary search on tree (ACL-style) ─────────────────────
+
   /**
    * Get element at index.
    * Time: O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Point access on segment tree
- *  const st = SegmentTree.sum([10, 20, 30, 40]);
- *     console.log(st.get(0)); // 10;
- *     console.log(st.get(2)); // 30;
+   * @example
+   * // Point access on segment tree
+   *  const st = SegmentTree.sum([10, 20, 30, 40]);
+   *     console.log(st.get(0)); // 10;
+   *     console.log(st.get(2)); // 30;
    */
   get(index: number): E {
     if (index < 0 || index >= this._n) return this._identity;
     return this._tree[this._treeSize + index];
   }
 
-  // ─── Binary search on tree (ACL-style) ─────────────────────
-
   /**
    * Find the largest r such that predicate(query(left, r)) is true.
    * Returns left-1 if predicate(identity) is false.
    * Returns n-1 if predicate holds for the entire range [left, n-1].
    * Time: O(log n)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Find rightmost position where predicate holds
- *  // Prefix sums: find the rightmost index where prefix sum < 10
- *     const st = SegmentTree.sum([3, 1, 4, 1, 5]);
- *     // maxRight(0, sum => sum < 10) — prefix [3,4,8,9,14]
- *     // sum < 10 holds through index 3 (prefix=9), fails at 4 (prefix=14)
- *     const result = st.maxRight(0, sum => sum < 10);
- *     console.log(result); // 3;
+   * @example
+   * // Find rightmost position where predicate holds
+   *  // Prefix sums: find the rightmost index where prefix sum < 10
+   *     const st = SegmentTree.sum([3, 1, 4, 1, 5]);
+   *     // maxRight(0, sum => sum < 10) — prefix [3,4,8,9,14]
+   *     // sum < 10 holds through index 3 (prefix=9), fails at 4 (prefix=14)
+   *     const result = st.maxRight(0, sum => sum < 10);
+   *     console.log(result); // 3;
    */
   maxRight(left: number, predicate: (segValue: E) => boolean): number {
     if (left >= this._n) return this._n - 1;
-
     let acc = this._identity;
     if (!predicate(acc)) return left - 1;
-
     let pos = this._treeSize + left;
-
     // Go up while we're a right child or predicate still holds
     while (true) {
       // Find the lowest relevant node
@@ -453,19 +234,16 @@ export class SegmentTree<E = number> implements Iterable<E> {
           pos = 2 * pos; // go left (dig deeper)
         }
       }
-
       // At leaf level
       const combined = this._merger(acc, this._tree[pos]);
       if (!predicate(combined)) {
         return pos - this._treeSize - 1;
       }
       acc = combined;
-
       // Move to next segment
       pos++;
       // Check if we've gone past the end
       if (pos - this._treeSize >= this._n) return this._n - 1;
-
       // Go up while we're a right child
       while (pos > 1 && (pos & 1) === 0) {
         pos >>= 1;
@@ -480,65 +258,20 @@ export class SegmentTree<E = number> implements Iterable<E> {
    * Returns right+1 if predicate(identity) is false.
    * Returns 0 if predicate holds for the entire range [0, right].
    * Time: O(log n)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Find leftmost position where predicate holds
- *  const st = SegmentTree.sum([3, 1, 4, 1, 5]);
- *     // minLeft(5, sum => sum < 7) — suffix sums from right
- *     // From right: [5]=5 < 7, [1,5]=6 < 7, [4,1,5]=10 ≥ 7
- *     const result = st.minLeft(5, sum => sum < 7);
- *     console.log(result); // 3;
+   * @example
+   * // Find leftmost position where predicate holds
+   *  const st = SegmentTree.sum([3, 1, 4, 1, 5]);
+   *     // minLeft(5, sum => sum < 7) — suffix sums from right
+   *     // From right: [5]=5 < 7, [1,5]=6 < 7, [4,1,5]=10 ≥ 7
+   *     const result = st.minLeft(5, sum => sum < 7);
+   *     console.log(result); // 3;
    */
   minLeft(right: number, predicate: (segValue: E) => boolean): number {
     if (right < 0) return 0;
     if (right >= this._n) right = this._n - 1;
-
     let acc = this._identity;
     if (!predicate(acc)) return right + 1;
-
     let pos = this._treeSize + right;
-
     while (true) {
       while (pos < this._treeSize) {
         const combined = this._merger(this._tree[2 * pos + 1], acc);
@@ -549,17 +282,14 @@ export class SegmentTree<E = number> implements Iterable<E> {
           pos = 2 * pos + 1; // go right (dig deeper)
         }
       }
-
       const combined = this._merger(this._tree[pos], acc);
       if (!predicate(combined)) {
         return pos - this._treeSize + 1;
       }
       acc = combined;
-
       // Move to previous segment
       if (pos === this._treeSize) return 0;
       pos--;
-
       // Go up while we're a left child
       while (pos > 1 && (pos & 1) === 1) {
         pos >>= 1;
@@ -569,12 +299,6 @@ export class SegmentTree<E = number> implements Iterable<E> {
     }
   }
 
-  // ─── Standard interface ────────────────────────────────────
-
-  get size(): number {
-    return this._n;
-  }
-
   isEmpty(): boolean {
     return this._n === 0;
   }
@@ -629,5 +353,3 @@ export class SegmentTree<E = number> implements Iterable<E> {
     console.log(this.toArray());
   }
 }
-
-