deque-typed
Version:
271 lines (270 loc) • 9.06 kB
TypeScript
/**
* TreeMultiSet (ordered multiset) — a restricted, native-like API backed by RedBlackTree.
*
* Design goals:
* - No node exposure
* - Strict default comparator (number/string/Date), otherwise require comparator
* - Default iteration is expanded (each element yielded `count(x)` times)
* - `delete(x)` removes one occurrence by default
*/
import type { Comparator, TreeMultiSetOptions } from '../../types';
export declare class TreeMultiSet<K = any, R = K> implements Iterable<K> {
#private;
private _size;
/**
* Creates a new TreeMultiSet.
* @param elements - Initial elements to add, or raw elements if `toElementFn` is provided.
* @param options - Configuration options including optional `toElementFn` to transform raw elements.
* @remarks Time O(m log m), Space O(m) where m is the number of initial elements
* @example
* // Standard usage with elements
* const mset = new TreeMultiSet([1, 2, 2, 3]);
*
* // Using toElementFn to transform raw objects
* const items = [{ score: 100 }, { score: 200 }, { score: 100 }];
* const mset = new TreeMultiSet<number, Item>(items, { toElementFn: item => item.score });
*/
constructor(elements?: Iterable<R> | Iterable<K>, options?: TreeMultiSetOptions<K, R>);
/**
* Validates the key against the default comparator rules.
* @remarks Time O(1), Space O(1)
*/
private _validateKey;
/**
* Validates that count is a non-negative safe integer.
* @remarks Time O(1), Space O(1)
*/
private _validateCount;
/**
* Total occurrences (sumCounts).
* @remarks Time O(1), Space O(1)
*/
get size(): number;
/**
* Number of distinct keys.
* @remarks Time O(1), Space O(1)
*/
get distinctSize(): number;
/**
* Whether the multiset is empty.
* @remarks Time O(1), Space O(1)
*/
isEmpty(): boolean;
/**
* Whether the multiset contains the given key.
* @remarks Time O(log n), Space O(1)
*/
has(key: K): boolean;
/**
* Returns the count of occurrences for the given key.
* @remarks Time O(log n), Space O(1)
*/
count(key: K): number;
/**
* Add `n` occurrences of `key`.
* @returns True if the multiset changed.
* @remarks Time O(log n), Space O(1)
*/
add(key: K, n?: number): boolean;
/**
* Set count for `key` to exactly `n`.
* @returns True if changed.
* @remarks Time O(log n), Space O(1)
*/
setCount(key: K, n: number): boolean;
/**
* Delete `n` occurrences of `key` (default 1).
* @returns True if any occurrence was removed.
* @remarks Time O(log n), Space O(1)
*/
delete(key: K, n?: number): boolean;
/**
* Delete all occurrences of the given key.
* @returns True if any occurrence was removed.
* @remarks Time O(log n), Space O(1)
*/
deleteAll(key: K): boolean;
/**
* Iterates over distinct keys (each key yielded once).
* @remarks Time O(n), Space O(1)
*/
keysDistinct(): IterableIterator<K>;
/**
* Iterates over entries as [key, count] pairs.
* @remarks Time O(n), Space O(1)
*/
entries(): IterableIterator<[K, number]>;
/**
* Expanded iteration (default). Each key is yielded `count(key)` times.
* @remarks Time O(size), Space O(1) where size is total occurrences
*/
[Symbol.iterator](): Iterator<K>;
/**
* Returns an array with all elements (expanded).
* @remarks Time O(size), Space O(size)
*/
toArray(): K[];
/**
* Returns an array with distinct keys only.
* @remarks Time O(n), Space O(n)
*/
toDistinctArray(): K[];
/**
* Returns an array of [key, count] entries.
* @remarks Time O(n), Space O(n)
*/
toEntries(): Array<[K, number]>;
/**
* Expose comparator for advanced usage/testing (read-only).
* @remarks Time O(1), Space O(1)
*/
get comparator(): Comparator<K>;
/**
* Remove all elements from the multiset.
* @remarks Time O(1), Space O(1)
* @example
* const ms = new TreeMultiSet([1, 2, 2, 3]);
* ms.clear();
* ms.size; // 0
*/
clear(): void;
/**
* Returns the smallest key, or undefined if empty.
* @remarks Time O(log n), Space O(1)
* @example
* const ms = new TreeMultiSet([3, 1, 4]);
* ms.first(); // 1
*/
first(): K | undefined;
/**
* Returns the largest key, or undefined if empty.
* @remarks Time O(log n), Space O(1)
* @example
* const ms = new TreeMultiSet([3, 1, 4]);
* ms.last(); // 4
*/
last(): K | undefined;
/**
* Removes all occurrences of the smallest key and returns it.
* @remarks Time O(log n), Space O(1)
* @example
* const ms = new TreeMultiSet([1, 1, 2, 3]);
* ms.pollFirst(); // 1
* ms.has(1); // false
*/
pollFirst(): K | undefined;
/**
* Removes all occurrences of the largest key and returns it.
* @remarks Time O(log n), Space O(1)
* @example
* const ms = new TreeMultiSet([1, 2, 3, 3]);
* ms.pollLast(); // 3
* ms.has(3); // false
*/
pollLast(): K | undefined;
/**
* Returns the smallest key >= given key, or undefined.
* @remarks Time O(log n), Space O(1)
* @example
* const ms = new TreeMultiSet([10, 20, 30]);
* ms.ceiling(15); // 20
* ms.ceiling(20); // 20
*/
ceiling(key: K): K | undefined;
/**
* Returns the largest key <= given key, or undefined.
* @remarks Time O(log n), Space O(1)
* @example
* const ms = new TreeMultiSet([10, 20, 30]);
* ms.floor(25); // 20
* ms.floor(20); // 20
*/
floor(key: K): K | undefined;
/**
* Returns the smallest key > given key, or undefined.
* @remarks Time O(log n), Space O(1)
* @example
* const ms = new TreeMultiSet([10, 20, 30]);
* ms.higher(10); // 20
* ms.higher(15); // 20
*/
higher(key: K): K | undefined;
/**
* Returns the largest key < given key, or undefined.
* @remarks Time O(log n), Space O(1)
* @example
* const ms = new TreeMultiSet([10, 20, 30]);
* ms.lower(20); // 10
* ms.lower(15); // 10
*/
lower(key: K): K | undefined;
/**
* Iterates over distinct keys with their counts.
* @remarks Time O(n), Space O(1)
* @example
* const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
* ms.forEach((key, count) => console.log(`${key}: ${count}`));
* // 1: 2, 2: 1, 3: 3
*/
forEach(callback: (key: K, count: number) => void): void;
/**
* Creates a new TreeMultiSet with entries that match the predicate.
* @remarks Time O(n log n), Space O(n)
* @example
* const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
* const filtered = ms.filter((key, count) => count >= 2);
* // TreeMultiSet { 1: 2, 3: 3 }
*/
filter(predicate: (key: K, count: number) => boolean): TreeMultiSet<K>;
/**
* Reduces the multiset to a single value.
* @remarks Time O(n), Space O(1)
* @example
* const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
* const total = ms.reduce((acc, key, count) => acc + count, 0); // 6
*/
reduce<U>(callback: (accumulator: U, key: K, count: number) => U, initialValue: U): U;
/**
* Maps keys and counts to a new TreeMultiSet.
* When multiple keys map to the same new key, counts are merged (added).
* @remarks Time O(n log n), Space O(n)
* @example
* const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
* const mapped = ms.map((key, count) => [key * 10, count]);
* // TreeMultiSet { 10: 2, 20: 1, 30: 3 }
* @example
* // Collision: counts merge
* const ms = new TreeMultiSet([1, 2, 3]);
* const merged = ms.map((key, count) => [key % 2, count]);
* // { 0: 1, 1: 2 } (1 and 3 both map to 1, counts add)
*/
map<K2>(mapper: (key: K, count: number) => [K2, number], options?: {
comparator?: Comparator<K2>;
}): TreeMultiSet<K2>;
/**
* Creates an independent copy of this multiset.
* @remarks Time O(n log n), Space O(n)
* @example
* const ms = new TreeMultiSet([1, 1, 2]);
* const copy = ms.clone();
* copy.add(3);
* ms.has(3); // false (original unchanged)
*/
clone(): TreeMultiSet<K>;
/**
* Returns keys within the given range.
* @remarks Time O(log n + k), Space O(k) where k is result size
* @example
* const ms = new TreeMultiSet([10, 20, 30, 40, 50]);
* ms.rangeSearch([15, 45]); // [20, 30, 40]
*/
rangeSearch<C extends (key: K) => any>(range: [K, K], callback?: C): (C extends undefined ? K : ReturnType<C>)[];
/**
* Prints the internal tree structure (for debugging).
* @remarks Time O(n), Space O(n)
* @example
* const ms = new TreeMultiSet([1, 2, 3]);
* ms.print();
*/
print(): void;
}