tree-multimap-typed 2.4.5 → 2.5.0

package/dist/types/data-structures/base/iterable-element-base.d.ts

@@ -27,7 +27,7 @@ export declare abstract class IterableElementBase<E, R> implements Iterable<E> {
      * @remarks
      * Time O(1), Space O(1).
      */
-    protected readonly _toElementFn?: (rawElement: R) => E;
+    protected _toElementFn?: (rawElement: R) => E;
     /**
      * Exposes the current `toElementFn`, if configured.
      *

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

@@ -80,12 +80,6 @@ export declare class AVLTreeNode<K = any, V = any> {
      * @returns The node's color.
      */
     get color(): RBTNColor;
-    /**
-     * Sets the color of the node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new color.
-     */
     set color(value: RBTNColor);
     _count: number;
     /**
@@ -95,12 +89,6 @@ export declare class AVLTreeNode<K = any, V = any> {
      * @returns The subtree node count.
      */
     get count(): number;
-    /**
-     * Sets the count of nodes in the subtree.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new count.
-     */
     set count(value: number);
     /**
      * Gets the position of the node relative to its parent.
@@ -127,28 +115,6 @@ export declare class AVLTreeNode<K = any, V = any> {
  * 7. Path Length: The path length from the root to any leaf is longer compared to an unbalanced BST, but shorter than a linear chain of nodes.
  *
  * @example
- * // basic AVLTree creation and add operation
- *  // Create a simple AVLTree with initial values
- *     const tree = new AVLTree([5, 2, 8, 1, 9]);
- *
- *     tree.print();
- *     //   _2___
- *     //  /     \
- *     //  1    _8_
- *     //      /   \
- *     //      5   9
- *
- *     // Verify the tree maintains sorted order
- *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
- *
- *     // Check size
- *     console.log(tree.size); // 5;
- *
- *     // Add a new element
- *     tree.set(3);
- *     console.log(tree.size); // 6;
- *     console.log([...tree.keys()]); // [1, 2, 3, 5, 8, 9];
- * @example
  * // AVLTree has and get operations
  *  const tree = new AVLTree<number>([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
  *
@@ -163,23 +129,6 @@ export declare class AVLTreeNode<K = any, V = any> {
  *     // Verify tree is balanced
  *     console.log(tree.isAVLBalanced()); // true;
  * @example
- * // AVLTree delete and balance verification
- *  const tree = new AVLTree([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
- *
- *     // Delete an element
- *     tree.delete(10);
- *     console.log(tree.has(10)); // false;
- *
- *     // Tree should remain balanced after deletion
- *     console.log(tree.isAVLBalanced()); // true;
- *
- *     // Size decreased
- *     console.log(tree.size); // 15;
- *
- *     // Remaining elements are still sorted
- *     const keys = [...tree.keys()];
- *     console.log(keys); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16];
- * @example
  * // AVLTree for university ranking system with strict balance
  *  interface University {
  *       name: string;
@@ -318,6 +267,48 @@ export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> imp
      * @param keyNodeOrEntry - The key, node, or entry to set.
      * @param [value] - The value, if providing just a key.
      * @returns True if the addition was successful, false otherwise.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Set a key-value pair
+   *  const avl = new AVLTree<number, string>();
+   *     avl.set(1, 'one');
+   *     avl.set(2, 'two');
+   *     console.log(avl.get(1)); // 'one';
      */
     set(keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
@@ -326,6 +317,45 @@ export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> imp
      *
      * @param keyNodeOrEntry - The node to delete.
      * @returns An array containing deletion results.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove nodes and verify structure
+   *  const avl = new AVLTree<number>([5, 3, 7, 1, 4, 6, 8]);
+   *     avl.delete(3);
+   *     console.log(avl.has(3)); // false;
+   *     console.log(avl.size); // 6;
      */
     delete(keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): BinaryTreeDeleteResult<AVLTreeNode<K, V>>[];
     /**
@@ -335,6 +365,26 @@ export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> imp
      *
      * @param [iterationType=this.iterationType] - The traversal method for the initial node export.
      * @returns True if successful, false if the tree was empty.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Rebalance the tree
+   *  const avl = new AVLTree<number>();
+   *     // Insert in sorted order (worst case for BST)
+   *     for (let i = 1; i <= 7; i++) avl.add(i);
+   *     console.log(avl.isAVLBalanced()); // false;
+   *     avl.perfectlyBalance();
+   *     console.log(avl.isAVLBalanced()); // true;
      */
     perfectlyBalance(iterationType?: IterationType): boolean;
     /**
@@ -348,6 +398,33 @@ export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> imp
      * @param [options] - Options for the new AVLTree.
      * @param [thisArg] - `this` context for the callback.
      * @returns A new, mapped AVLTree.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Transform to new tree
+   *  const avl = new AVLTree<number, number>([[1, 10], [2, 20], [3, 30]]);
+   *     const doubled = avl.map((value, key) => [key, (value ?? 0) * 2] as [number, number]);
+   *     console.log([...doubled.values()]); // [20, 40, 60];
      */
     map<MK = K, MV = V, MR = any>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<BinaryTreeOptions<MK, MV, MR>>, thisArg?: unknown): AVLTree<MK, MV, MR>;
     /**

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

@@ -1,174 +1,220 @@
 /**
+ * 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 declare 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, max }: {
-        frequency?: number;
-        max: number;
-    });
-    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>;
-    protected _msb: number;
-    /**
-     * The function returns the value of the _msb property.
-     * @returns The `_msb` property of the object.
-     */
-    get msb(): number;
-    protected _negativeCount: number;
-    /**
-     * 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`.
-     */
-    get negativeCount(): number;
-    /**
-     * The above function returns the value of the protected variable `_freq`.
-     * @returns The frequency value stored in the protected variable `_freq`.
-     */
-    get freq(): number;
-    /**
-     * The above function returns the maximum value.
-     * @returns The maximum value stored in the variable `_max`.
-     */
-    get max(): number;
-    /**
-     * 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.
-     */
-    readSingle(index: number): 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;
-    /**
-     * 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;
-    /**
-     * 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.
-     */
-    read(count: number): number;
-    /**
-     * 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.
+export declare class BinaryIndexedTree implements Iterable<number> {
+    protected readonly _size: number;
+    protected _tree: 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
+     */
+    constructor(sizeOrElements: number | number[]);
+    /**
+     * 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;
+     */
+    update(index: number, delta: number): void;
+    /**
+     * 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;
+     */
+    set(index: number, value: number): void;
+    /**
+     * 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;
+     */
+    get(index: number): number;
+    /**
+     * 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;
+     */
+    query(index: number): 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;
+     */
+    queryRange(start: number, end: number): 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;
     /**
-     * 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.
+     * 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;
      */
     upperBound(sum: number): number;
-    /**
-     * 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`.
-     */
-    getPrefixSum(i: number): number;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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.
-     */
+    get size(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    clone(): BinaryIndexedTree;
+    /**
+     * 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];
+     */
+    toArray(): number[];
+    /**
+     * Iterate over point values in index order.
+     */
+    [Symbol.iterator](): IterableIterator<number>;
+    forEach(callback: (value: number, index: number) => void): void;
+    print(): void;
+    /** 1-based prefix sum up to pos (inclusive). */
+    protected _prefixSum(pos: number): number;
+    /** 1-based point update: add delta to position pos. */
+    protected _pointUpdate(pos: number, delta: number): void;
+    /** 1-based point query: get exact value at pos. */
+    protected _pointQuery(pos: number): number;
     protected _checkIndex(index: number): void;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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.
-     */
-    protected _update(index: number, delta: number): void;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
+    /** Returns highest power of 2 <= n. */
+    protected _highBit(n: number): number;
 }