tree-multimap-typed/dist/data-structures/binary-tree/red-black-tree.d.ts

Tree Multimap

/**
 * data-structure-typed
 *
 * @author Pablo Zeng
 * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
 * @license MIT License
 */
import type { BinaryTreeDeleteResult, BinaryTreeOptions, CRUD, EntryCallback, RBTNColor, RedBlackTreeOptions } from '../../types';
import { BST, BSTNode } from './bst';
import { IBinaryTree } from '../../interfaces';
export declare class RedBlackTreeNode<K = any, V = any> extends BSTNode<K, V> {
    parent?: RedBlackTreeNode<K, V>;
    /**
     * Create a Red-Black Tree and optionally bulk-insert items.
     * @remarks Time O(n log n), Space O(n)
     * @param key - See parameter type for details.
     * @param [value]- See parameter type for details.
     * @param color - See parameter type for details.
     * @returns New RedBlackTree instance.
     */
    constructor(key: K, value?: V, color?: RBTNColor);
    _left?: RedBlackTreeNode<K, V> | null | undefined;
    /**
     * Get the left child pointer.
     * @remarks Time O(1), Space O(1)
     * @returns Left child node, or null/undefined.
     */
    get left(): RedBlackTreeNode<K, V> | null | undefined;
    /**
     * Set the left child and update its parent pointer.
     * @remarks Time O(1), Space O(1)
     * @param v - New left node, or null/undefined.
     * @returns void
     */
    set left(v: RedBlackTreeNode<K, V> | null | undefined);
    _right?: RedBlackTreeNode<K, V> | null | undefined;
    /**
     * Get the right child pointer.
     * @remarks Time O(1), Space O(1)
     * @returns Right child node, or null/undefined.
     */
    get right(): RedBlackTreeNode<K, V> | null | undefined;
    /**
     * Set the right child and update its parent pointer.
     * @remarks Time O(1), Space O(1)
     * @param v - New right node, or null/undefined.
     * @returns void
     */
    set right(v: RedBlackTreeNode<K, V> | null | undefined);
}
/**
 * RRRRed-Black Tree (self-balancing BST) supporting map-like mode and stable O(log n) updates.
 * @remarks Time O(1), Space O(1)
 * @template K
 * @template V
 * @template R
 * 1. Efficient self-balancing, but not completely balanced. Compared with AVLTree, the addition and deletion efficiency is high but the query efficiency is slightly lower.
 * 2. It is BST itself. Compared with Heap which is not completely ordered, RedBlackTree is completely ordered.
 * @example
 * // using Red-Black Tree as a price-based index for stock data
 *     // Define the structure of individual stock records
 *     interface StockRecord {
 *       price: number; // Stock price (key for indexing)
 *       symbol: string; // Stock ticker symbol
 *       volume: number; // Trade volume
 *     }
 *
 *     // Simulate stock market data as it might come from an external feed
 *     const marketStockData: StockRecord[] = [
 *       { price: 142.5, symbol: 'AAPL', volume: 1000000 },
 *       { price: 335.2, symbol: 'MSFT', volume: 800000 },
 *       { price: 3285.04, symbol: 'AMZN', volume: 500000 },
 *       { price: 267.98, symbol: 'META', volume: 750000 },
 *       { price: 234.57, symbol: 'GOOGL', volume: 900000 }
 *     ];
 *
 *     // Extend the stock record type to include metadata for database usage
 *     type StockTableRecord = StockRecord & { lastUpdated: Date };
 *
 *     // Create a Red-Black Tree to index stock records by price
 *     // Simulates a database index with stock price as the key for quick lookups
 *     const priceIndex = new RedBlackTree<number, StockTableRecord, StockRecord>(marketStockData, {
 *       toEntryFn: stockRecord => [
 *         stockRecord.price, // Use stock price as the key
 *         {
 *           ...stockRecord,
 *           lastUpdated: new Date() // Add a timestamp for when the record was indexed
 *         }
 *       ]
 *     });
 *
 *     // Query the stock with the highest price
 *     const highestPricedStock = priceIndex.getRightMost();
 *     console.log(priceIndex.get(highestPricedStock)?.symbol); // 'AMZN' // Amazon has the highest price
 *
 *     // Query stocks within a specific price range (200 to 400)
 *     const stocksInRange = priceIndex.rangeSearch(
 *       [200, 400], // Price range
 *       node => priceIndex.get(node)?.symbol // Extract stock symbols for the result
 *     );
 *     console.log(stocksInRange); // ['GOOGL', 'META', 'MSFT']
 */
export declare class RedBlackTree<K = any, V = any, R extends object = object> extends BST<K, V, R> implements IBinaryTree<K, V, R> {
    constructor(keysNodesEntriesOrRaws?: Iterable<K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, options?: RedBlackTreeOptions<K, V, R>);
    protected _root: RedBlackTreeNode<K, V> | undefined;
    /**
     * Get the current root node.
     * @remarks Time O(1), Space O(1)
     * @returns Root node, or undefined.
     */
    get root(): RedBlackTreeNode<K, V> | undefined;
    /**
     * Create a red-black node for the given key/value (value ignored in map mode).
     * @remarks Time O(1), Space O(1)
     * @param key - See parameter type for details.
     * @param [value] - See parameter type for details.
     * @param color - See parameter type for details.
     * @returns A new RedBlackTreeNode instance.
     */
    _createNode(key: K, value?: V, color?: RBTNColor): RedBlackTreeNode<K, V>;
    /**
     * Type guard: check whether the input is a RedBlackTreeNode.
     * @remarks Time O(1), Space O(1)
     * @param keyNodeOrEntry - See parameter type for details.
     * @returns True if the value is a RedBlackTreeNode.
     */
    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).
     * @remarks Time O(n), Space O(1)
     * @returns void
     */
    clear(): void;
    /**
     * Insert or replace an entry using BST order and red-black fix-up.
     * @remarks Time O(log n), Space O(1)
     * @param keyNodeOrEntry - Key, node, or [key, value] entry to insert.
     * @param [value]- See parameter type for details.
     * @returns True if inserted or updated; false if ignored.
     */
    add(keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
    /**
     * Delete a node by key/node/entry and rebalance as needed.
     * @remarks Time O(log n), Space O(1)
     * @param keyNodeOrEntry - Key, node, or [key, value] entry identifying the node to delete.
     * @returns Array with deletion metadata (removed node, rebalancing hint if any).
     */
    delete(keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): BinaryTreeDeleteResult<RedBlackTreeNode<K, V>>[];
    /**
     * Transform entries into a like-kind red-black tree with possibly different key/value types.
     * @remarks Time O(n), Space O(n)
     * @template MK
     * @template MV
     * @template MR
     * @param callback - Mapping function from (key, value, index, tree) to a new [key, value].
     * @param [options] - See parameter type for details.
     * @param [thisArg] - See parameter type for details.
     * @returns A new RedBlackTree with mapped entries.
     */
    map<MK = K, MV = V, MR extends object = object>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<BinaryTreeOptions<MK, MV, MR>>, thisArg?: unknown): RedBlackTree<MK, MV, MR>;
    protected _createInstance<TK = K, TV = V, TR extends object = R>(options?: Partial<RedBlackTreeOptions<TK, TV, TR>>): this;
    protected _createLike<TK = K, TV = V, TR extends object = R>(iter?: Iterable<TK | RedBlackTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<RedBlackTreeOptions<TK, TV, TR>>): RedBlackTree<TK, TV, TR>;
    protected _setRoot(v: RedBlackTreeNode<K, V> | undefined): void;
    protected _replaceNode(oldNode: RedBlackTreeNode<K, V>, newNode: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V>;
    /**
     * (Protected) Standard BST insert followed by red-black fix-up.
     * @remarks Time O(log n), Space O(1)
     * @param node - Node to insert.
     * @returns Status string: 'CREATED' or 'UPDATED'.
     */
    protected _insert(node: RedBlackTreeNode<K, V>): CRUD;
    /**
     * (Protected) Transplant a subtree in place of another during deletion.
     * @remarks Time O(1), Space O(1)
     * @param u - Node to replace.
     * @param v - Replacement subtree root (may be undefined).
     * @returns void
     */
    protected _transplant(u: RedBlackTreeNode<K, V>, v: RedBlackTreeNode<K, V> | undefined): void;
    /**
     * (Protected) Restore red-black properties after insertion (recolor/rotate).
     * @remarks Time O(log n), Space O(1)
     * @param z - Recently inserted node.
     * @returns void
     */
    protected _insertFixup(z: RedBlackTreeNode<K, V> | undefined): void;
    /**
     * (Protected) Restore red-black properties after deletion (recolor/rotate).
     * @remarks Time O(log n), Space O(1)
     * @param node - Child that replaced the deleted node (may be undefined).
     * @returns void
     */
    protected _deleteFixup(node: RedBlackTreeNode<K, V> | undefined): void;
    /**
     * (Protected) Perform a left rotation around x.
     * @remarks Time O(1), Space O(1)
     * @param x - Pivot node to rotate around.
     * @returns void
     */
    protected _leftRotate(x: RedBlackTreeNode<K, V> | undefined): void;
    /**
     * (Protected) Perform a right rotation around y.
     * @remarks Time O(1), Space O(1)
     * @param y - Pivot node to rotate around.
     * @returns void
     */
    protected _rightRotate(y: RedBlackTreeNode<K, V> | undefined): void;
}