binary-tree-typed 2.5.1 → 2.5.3

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

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BinaryTreeDeleteResult, BSTNOptKeyOrNode, BSTOptions, BTNRep, Comparator, DFSOrderPattern, EntryCallback, FamilyPosition, IterationType, NodeCallback, NodePredicate, OptNode, RBTNColor } from '../../types';
+import type { BSTNOptKeyOrNode, BSTOptions, BTNRep, Comparator, DFSOrderPattern, EntryCallback, FamilyPosition, IterationType, NodeCallback, NodePredicate, OptNode, RBTNColor } from '../../types';
 import { BinaryTree } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 import { Range } from '../../common';
@@ -254,6 +254,7 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      */
     constructor(keysNodesEntriesOrRaws?: Iterable<K | BSTNode | [K | null | undefined, V | undefined] | null | undefined | R>, options?: BSTOptions<K, V, R>);
     protected _root?: BSTNode<K, V>;
+    protected _enableOrderStatistic: boolean;
     /**
      * Gets the root node of the tree.
      * @remarks Time O(1)
@@ -359,6 +360,20 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -425,6 +440,20 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -494,6 +523,20 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -513,7 +556,7 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
  * // Level-order grouping
  *  const bst = new BST<number>([5, 3, 7, 1, 4]);
  *     const levels = bst.listLevels(node => node.key);
- *     console.log(levels.length); // > 0;
+ *     console.log(levels); // toBeInstanceOf;
  *     console.log(levels[0].length); // 1; // root level has 1 node
  *     const allKeys = levels.flat().sort((a, b) => a - b);
  *     console.log(allKeys); // [1, 3, 4, 5, 7];
@@ -574,6 +617,20 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -638,6 +695,20 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -687,6 +758,13 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -702,6 +780,69 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    */
     rangeSearch(range: Range<K> | [K, K]): (K | undefined)[];
     rangeSearch<C extends NodeCallback<BSTNode<K, V>>>(range: Range<K> | [K, K], callback: C, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
+    /**
+     * Returns the element at the k-th position in tree order (0-indexed).
+     * @remarks Time O(log n), Space O(1) iterative / O(log n) recursive. Requires `enableOrderStatistic: true`.
+     * Tree order is defined by the comparator — ascending by default, but respects custom comparators (e.g. descending).
+     *
+     * @param k - The 0-based position in tree order (0 = first element).
+     * @returns The key at position k, or `undefined` if out of bounds.
+      * @example
+   * // Order-statistic on BST
+   *  const tree = new BST<number>([30, 10, 50, 20, 40], { enableOrderStatistic: true });
+   *       console.log(tree.getByRank(0)); // 10;
+   *       console.log(tree.getByRank(4)); // 50;
+   *       console.log(tree.getRank(30)); // 2;
+     */
+    getByRank(k: number): K | undefined;
+    /**
+     * Returns the element at the k-th position in tree order and applies a callback.
+     * @remarks Time O(log n), Space O(1) iterative / O(log n) recursive. Requires `enableOrderStatistic: true`.
+     *
+     * @param k - The 0-based position in tree order (0 = first element).
+     * @param callback - Callback to apply to the found node.
+     * @param iterationType - Iteration strategy ('ITERATIVE' or 'RECURSIVE').
+     * @returns The callback result, or `undefined` if out of bounds.
+     */
+    getByRank<C extends NodeCallback<BSTNode<K, V>>>(k: number, callback: C, iterationType?: IterationType): ReturnType<C> | undefined;
+    /**
+     * Returns the 0-based rank of a key (number of elements that precede it in tree order).
+     * @remarks Time O(log n), Space O(1) iterative / O(log n) recursive. Requires `enableOrderStatistic: true`.
+     * Tree order is defined by the comparator. When the key is not found, returns the insertion position.
+     *
+     * @param keyNodeEntryOrPredicate - The key, node, entry `[K, V]`, or predicate to find.
+     * @returns The rank (0-indexed), or -1 if the tree is empty or input is invalid.
+     */
+    getRank(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>): number;
+    /**
+     * Returns the 0-based rank (number of preceding elements in tree order) with explicit iteration type.
+     * @remarks Time O(log n), Space O(1) iterative / O(log n) recursive. Requires `enableOrderStatistic: true`.
+     *
+     * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate to find.
+     * @param iterationType - Iteration strategy ('ITERATIVE' or 'RECURSIVE').
+     * @returns The rank (0-indexed), or -1 if the tree is empty or input is invalid.
+     */
+    getRank(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>, iterationType: IterationType): number;
+    /**
+     * Returns elements by position range in tree order (0-indexed, inclusive on both ends).
+     * @remarks Time O(log n + k), Space O(k), where k = end - start + 1. Requires `enableOrderStatistic: true`.
+     *
+     * @param start - Start position (inclusive, 0-indexed). Clamped to 0 if negative.
+     * @param end - End position (inclusive, 0-indexed). Clamped to size-1 if too large.
+     * @returns Array of keys in tree order within the specified range.
+     */
+    rangeByRank(start: number, end: number): (K | undefined)[];
+    /**
+     * Returns elements by position range in tree order with callback and optional iteration type.
+     * @remarks Time O(log n + k), Space O(k), where k = end - start + 1. Requires `enableOrderStatistic: true`.
+     *
+     * @param start - Start rank (inclusive, 0-indexed).
+     * @param end - End rank (inclusive, 0-indexed).
+     * @param callback - Callback to apply to each node in the range.
+     * @param iterationType - Iteration strategy ('ITERATIVE' or 'RECURSIVE').
+     * @returns Array of callback results for nodes in the rank range.
+     */
+    rangeByRank<C extends NodeCallback<BSTNode<K, V>>>(start: number, end: number, callback: C, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Adds a new node to the BST based on key comparison.
      * @remarks Time O(log N), where H is tree height. O(N) worst-case (unbalanced tree), O(log N) average. Space O(1).
@@ -776,6 +917,27 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -854,6 +1016,20 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -906,6 +1082,13 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -957,6 +1140,13 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -1007,6 +1197,13 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -1058,6 +1255,13 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -1109,6 +1313,13 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -1155,6 +1366,13 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -1227,6 +1445,20 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -1285,7 +1517,7 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      *   - Value: true if the deletion succeeded, false if it failed (e.g., key not found during deletion phase).
      *   - If no nodes match the search criteria, the returned map is empty.
      */
-    deleteWhere(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>> | Range<K>, onlyOne?: boolean, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): BinaryTreeDeleteResult<BSTNode<K, V>>[];
+    deleteWhere(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>> | Range<K>, onlyOne?: boolean, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): boolean;
     /**
      * (Protected) Creates the default comparator function for keys that don't have a custom comparator.
      * @remarks Time O(1) Space O(1)
@@ -1412,6 +1644,41 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      *
      * @param v - The node to set as root.
      */
+    /**
+     * (Protected) Recalculates the subtree count for a single node.
+     * @remarks Time O(1). Only active when enableOrderStatistic is true.
+     */
+    protected _updateCount(node: BSTNode<K, V>): void;
+    /**
+     * (Protected) Updates subtree counts from a node up to the root.
+     * @remarks Time O(log n). Only active when enableOrderStatistic is true.
+     */
+    protected _updateCountAlongPath(node: OptNode<BSTNode<K, V>>): void;
+    /**
+     * (Protected) Finds the node at position k in tree order (iterative).
+     * @remarks Time O(log n), Space O(1)
+     */
+    protected _getByRankIterative(node: OptNode<BSTNode<K, V>>, k: number): BSTNode<K, V> | undefined;
+    /**
+     * (Protected) Finds the node at position k in tree order (recursive).
+     * @remarks Time O(log n), Space O(log n) call stack
+     */
+    protected _getByRankRecursive(node: OptNode<BSTNode<K, V>>, k: number): BSTNode<K, V> | undefined;
+    /**
+     * (Protected) Computes the rank of a key iteratively.
+     * @remarks Time O(log n), Space O(1)
+     */
+    protected _getRankIterative(node: OptNode<BSTNode<K, V>>, key: K): number;
+    /**
+     * (Protected) Computes the rank of a key recursively.
+     * @remarks Time O(log n), Space O(log n) call stack
+     */
+    protected _getRankRecursive(node: OptNode<BSTNode<K, V>>, key: K): number;
+    /**
+     * (Protected) Finds the in-order successor of a node.
+     * @remarks Time O(log n), Space O(1)
+     */
+    protected _next(node: BSTNode<K, V>): BSTNode<K, V> | undefined;
     protected _setRoot(v: OptNode<BSTNode<K, V>>): void;
     /**
      * (Protected) Compares two keys using the tree's comparator and reverse setting.

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

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BinaryTreeDeleteResult, BTNRep, CRUD, EntryCallback, FamilyPosition, NodePredicate, RBTNColor, IterationType, RedBlackTreeOptions } from '../../types';
+import type { BTNRep, CRUD, EntryCallback, FamilyPosition, NodePredicate, RBTNColor, IterationType, RedBlackTreeOptions } from '../../types';
 import { BST } from './bst';
 import { IBinaryTree } from '../../interfaces';
 export declare class RedBlackTreeNode<K = any, V = any> {
@@ -217,13 +217,36 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
      */
     isNode(keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is RedBlackTreeNode<K, V>;
     /**
-     * Remove all nodes and clear the key→value store (if in map mode).
+     * Remove all nodes, clear the key→value store (if in map mode) and internal caches.
      * @remarks Time O(n), Space O(1)
-     * @returns void
-     */
-    /**
-     * Remove all nodes and clear internal caches.
-     * @remarks Time O(n) average, Space O(1)
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -548,6 +571,34 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -694,6 +745,34 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -722,7 +801,7 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
    *     console.log(rbt.has(5)); // false;
    *     console.log(rbt.size); // 4;
      */
-    delete(keyNodeEntryRawOrPredicate: BTNRep<K, V, RedBlackTreeNode<K, V>> | NodePredicate<RedBlackTreeNode<K, V> | null>): BinaryTreeDeleteResult<RedBlackTreeNode<K, V>>[];
+    delete(keyNodeEntryRawOrPredicate: BTNRep<K, V, RedBlackTreeNode<K, V>> | NodePredicate<RedBlackTreeNode<K, V> | null>): boolean;
     /**
      * Transform entries into a like-kind red-black tree with possibly different key/value types.
      * @remarks Time O(n) average, Space O(n)
@@ -805,6 +884,27 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -933,6 +1033,34 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    

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

@@ -69,6 +69,13 @@ export declare class SegmentTree<E = number> implements Iterable<E> {
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -127,6 +134,13 @@ export declare class SegmentTree<E = number> implements Iterable<E> {
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -181,6 +195,13 @@ export declare class SegmentTree<E = number> implements Iterable<E> {
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -230,6 +251,13 @@ export declare class SegmentTree<E = number> implements Iterable<E> {
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -274,6 +302,13 @@ export declare class SegmentTree<E = number> implements Iterable<E> {
      
      
      
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -321,6 +356,13 @@ export declare class SegmentTree<E = number> implements Iterable<E> {
      
      
      
+     
+     
+     
+     
+     
+     
+