binary-tree-typed 2.4.4 → 2.5.0

package/dist/types/data-structures/binary-tree/segment-tree.d.ts

@@ -5,156 +5,222 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { SegmentTreeNodeVal } from '../../types';
-export declare class SegmentTreeNode {
-    /**
-     * 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);
-    protected _start: number;
-    /**
-     * The function returns the value of the protected variable _start.
-     * @returns The start value, which is of type number.
-     */
-    get start(): number;
-    /**
-     * The above function sets the value of the "start" property.
-     * @param {number} value - The value parameter is of type number.
-     */
-    set start(value: number);
-    protected _end: number;
-    /**
-     * The function returns the value of the protected variable `_end`.
-     * @returns The value of the protected property `_end`.
-     */
-    get end(): number;
-    /**
-     * 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);
-    protected _value: SegmentTreeNodeVal | 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;
-    /**
-     * 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);
-    protected _sum: number;
-    /**
-     * The function returns the value of the sum property.
-     * @returns The method is returning the value of the variable `_sum`.
-     */
-    get sum(): number;
-    /**
-     * The above function sets the value of the sum property.
-     * @param {number} value - The parameter "value" is of type "number".
-     */
-    set sum(value: number);
-    protected _left: SegmentTreeNode | 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;
-    /**
-     * 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);
-    protected _right: SegmentTreeNode | 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;
-    /**
-     * 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);
-}
-export declare class SegmentTree {
-    /**
-     * The constructor initializes the values, start, end, and root properties of an object.
-     * @param {number[]} values - An array of numbers that will be used to build a binary search tree.
-     * @param {number} [start] - The `start` parameter is the index of the first element in the `values` array that should
-     * be included in the range. If no value is provided for `start`, it defaults to 0, which means the range starts from
-     * the beginning of the array.
-     * @param {number} [end] - The "end" parameter is the index of the last element in the "values" array that should be
-     * included in the range. If not provided, it defaults to the index of the last element in the "values" array.
-     */
-    constructor(values: number[], start?: number, end?: number);
-    protected _values: number[];
-    /**
-     * The function returns an array of numbers.
-     * @returns An array of numbers is being returned.
-     */
-    get values(): number[];
-    protected _start: number;
-    /**
-     * The function returns the value of the protected variable _start.
-     * @returns The start value, which is of type number.
-     */
-    get start(): number;
-    protected _end: number;
-    /**
-     * The function returns the value of the protected variable `_end`.
-     * @returns The value of the protected property `_end`.
-     */
-    get end(): number;
-    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;
-    /**
-     * The build function creates a segment tree by recursively dividing the given range into smaller segments and assigning
-     * the sum of values to each segment.
-     * @param {number} start - The `start` parameter represents the starting index of the segment or range for which we are
-     * building the segment tree.
-     * @param {number} end - The "end" parameter represents the ending index of the segment or range for which we want to
-     * build a segment tree.
-     * @returns a SegmentTreeNode object.
-     */
-    build(start: number, end: number): SegmentTreeNode;
-    /**
-     * The function updates the value of a node in a segment tree and recalculates the sum of its children if they exist.
-     * @param {number} index - The index parameter represents the index of the node in the segment tree that needs to be
-     * updated.
-     * @param {number} sum - The `sum` parameter represents the new value that should be assigned to the `sum` property of
-     * the `SegmentTreeNode` at the specified `index`.
-     * @param {SegmentTreeNodeVal} [value] - The `value` parameter is an optional value that can be assigned to the `value`
-     * property of the `SegmentTreeNode` object. It is not currently used in the code, but you can uncomment the line `//
-     * cur.value = value;` and pass a value for `value` in the
-     * @returns The function does not return anything.
-     */
-    updateNode(index: number, sum: number, value?: SegmentTreeNodeVal): void;
-    /**
-     * The function `querySumByRange` calculates the sum of values within a given range in a segment tree.
-     * @param {number} indexA - The starting index of the range for which you want to calculate the sum.
-     * @param {number} indexB - The parameter `indexB` represents the ending index of the range for which you want to
-     * calculate the sum.
-     * @returns The function `querySumByRange` returns a number.
-     */
-    querySumByRange(indexA: number, indexB: number): number;
+export type SegmentTreeOptions<E> = {
+    merger: (a: E, b: E) => E;
+    identity: E;
+};
+/**
+ * Generic Segment Tree with flat array internals.
+ *
+ * Supports any associative merge operation (sum, min, max, gcd, etc.).
+ * Reference: AtCoder Library segtree<S, op, e>.
+ *
+ * @example
+ * ```ts
+ * const sumTree = SegmentTree.sum([1, 2, 3, 4, 5]);
+ * sumTree.query(1, 3);    // 9 (2+3+4)
+ * sumTree.update(2, 10);  // [1, 2, 10, 4, 5]
+ * sumTree.query(1, 3);    // 16 (2+10+4)
+ *
+ * const minTree = SegmentTree.min([5, 2, 8, 1, 9]);
+ * minTree.query(0, 4);    // 1
+ * ```
+ */
+export declare class SegmentTree<E = number> implements Iterable<E> {
+    protected readonly _merger: (a: E, b: E) => E;
+    protected readonly _identity: E;
+    protected _n: number;
+    protected _tree: E[];
+    protected _treeSize: number;
+    constructor(elements: E[], options: SegmentTreeOptions<E>);
+    /**
+     * Create a sum segment tree.
+     * @example
+     * ```ts
+     * const st = SegmentTree.sum([1, 2, 3, 4, 5]);
+     * st.query(0, 2); // 6 (1+2+3)
+     * st.update(1, 10);
+     * st.query(0, 2); // 14 (1+10+3)
+     * ```
+     */
+    static sum(elements: number[]): SegmentTree<number>;
+    /**
+     * 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;
+     */
+    static min(elements: number[]): SegmentTree<number>;
+    /**
+     * Create a max segment tree.
+     * @example
+     * ```ts
+     * const st = SegmentTree.max([3, 1, 4, 1, 5]);
+     * st.query(1, 4); // 5
+     * ```
+     */
+    static max(elements: number[]): SegmentTree<number>;
+    /**
+     * 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;
+     */
+    update(index: number, value: E): void;
+    /**
+     * 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;
+     */
+    query(start: number, end: number): E;
+    /**
+     * 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;
+     */
+    get(index: number): E;
+    /**
+     * 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;
+     */
+    maxRight(left: number, predicate: (segValue: E) => boolean): number;
+    /**
+     * Find the smallest l such that predicate(query(l, right)) is true.
+     * 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;
+     */
+    minLeft(right: number, predicate: (segValue: E) => boolean): number;
+    get size(): number;
+    isEmpty(): boolean;
+    clone(): SegmentTree<E>;
+    toArray(): E[];
+    /**
+     * Iterates over leaf values in index order.
+     */
+    [Symbol.iterator](): IterableIterator<E>;
+    forEach(callback: (value: E, index: number) => void): void;
+    print(): void;
 }