deque-typed
Version:
192 lines (191 loc) • 6.31 kB
TypeScript
/**
* TreeSet (ordered set) — a restricted, native-like API backed by RedBlackTree.
*
* Design goals:
* - No node exposure (no node inputs/outputs)
* - Native Set-like surface + Java NavigableSet-like helpers
* - Strict default comparator (number/string/Date), otherwise require comparator
*/
import type { Comparator } from '../../types';
import type { TreeSetElementCallback, TreeSetOptions, TreeSetRangeOptions, TreeSetReduceCallback } from '../../types';
/**
* An ordered Set backed by a red-black tree.
*
* - Iteration order is ascending by key.
* - No node exposure: all APIs use keys only.
*/
export declare class TreeSet<K = any, R = K> implements Iterable<K> {
#private;
/**
* Create a TreeSet from an iterable of keys or raw elements.
*
* @param elements - Iterable of keys, or raw elements if `toElementFn` is provided.
* @param options - Configuration options including optional `toElementFn` to transform raw elements.
* @throws {TypeError} When using the default comparator and encountering unsupported key types,
* or invalid keys (e.g. `NaN`, invalid `Date`).
* @example
* // Standard usage with keys
* const set = new TreeSet([3, 1, 2]);
*
* // Using toElementFn to transform raw objects
* const users = [{ id: 3, name: 'Alice' }, { id: 1, name: 'Bob' }];
* const set = new TreeSet<number, User>(users, { toElementFn: u => u.id });
*/
constructor(elements?: Iterable<R> | Iterable<K>, options?: TreeSetOptions<K, R>);
/**
* Create the strict default comparator.
*
* Supports:
* - `number` (rejects `NaN`; treats `-0` and `0` as equal)
* - `string`
* - `Date` (orders by `getTime()`, rejects invalid dates)
*
* For other key types, a custom comparator must be provided.
*/
static createDefaultComparator<K>(): Comparator<K>;
/**
* Number of elements in the set.
*/
get size(): number;
/**
* Whether the set is empty.
*/
isEmpty(): boolean;
private _validateKey;
/**
* Add a key to the set (no-op if already present).
* @remarks Expected time O(log n)
*/
add(key: K): this;
/**
* Test whether a key exists.
* @remarks Expected time O(log n)
*/
has(key: K): boolean;
/**
* Delete a key.
* @returns `true` if the key existed; otherwise `false`.
* @remarks Expected time O(log n)
*/
delete(key: K): boolean;
/**
* Remove all keys.
*/
clear(): void;
/**
* Iterate over keys in ascending order.
*/
keys(): IterableIterator<K>;
/**
* Iterate over values in ascending order.
*
* Note: for Set-like containers, `values()` is the same as `keys()`.
*/
values(): IterableIterator<K>;
/**
* Iterate over `[value, value]` pairs (native Set convention).
*
* Note: TreeSet stores only keys internally; `[k, k]` is created on-the-fly during iteration.
*/
entries(): IterableIterator<[K, K]>;
[Symbol.iterator](): IterableIterator<K>;
/**
* Visit each value in ascending order.
*
* Callback follows native Set convention: `(value, value2, set)`.
*/
forEach(cb: (value: K, value2: K, set: TreeSet<K>) => void, thisArg?: any): void;
/**
* Create a new TreeSet by mapping each value to a new key.
*
* This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
* @remarks Time O(n log n) expected, Space O(n)
*/
map<MK>(callbackfn: TreeSetElementCallback<K, MK, TreeSet<K>>, options?: Omit<TreeSetOptions<MK>, 'toElementFn'> & {
comparator?: (a: MK, b: MK) => number;
}, thisArg?: unknown): TreeSet<MK>;
/**
* Create a new TreeSet containing only values that satisfy the predicate.
* @remarks Time O(n log n) expected, Space O(n)
*/
filter(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): TreeSet<K>;
/**
* Reduce values into a single accumulator.
* @remarks Time O(n), Space O(1)
*/
reduce<A>(callbackfn: TreeSetReduceCallback<K, A, TreeSet<K>>, initialValue: A): A;
/**
* Test whether all values satisfy a predicate.
* @remarks Time O(n), Space O(1)
*/
every(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): boolean;
/**
* Test whether any value satisfies a predicate.
* @remarks Time O(n), Space O(1)
*/
some(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): boolean;
/**
* Find the first value that satisfies a predicate.
* @remarks Time O(n), Space O(1)
*/
find(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): K | undefined;
/**
* Materialize the set into an array of keys.
* @remarks Time O(n), Space O(n)
*/
toArray(): K[];
/**
* Print a human-friendly representation.
* @remarks Time O(n), Space O(n)
*/
print(): void;
/**
* Smallest key in the set.
*/
first(): K | undefined;
/**
* Largest key in the set.
*/
last(): K | undefined;
/**
* Remove and return the smallest key.
*/
pollFirst(): K | undefined;
/**
* Remove and return the largest key.
*/
pollLast(): K | undefined;
/**
* Smallest key that is >= the given key.
*/
ceiling(key: K): K | undefined;
/**
* Largest key that is <= the given key.
*/
floor(key: K): K | undefined;
/**
* Smallest key that is > the given key.
*/
higher(key: K): K | undefined;
/**
* Largest key that is < the given key.
*/
lower(key: K): K | undefined;
/**
* Return all keys in a given range.
*
* @param range `[low, high]`
* @param options Inclusive/exclusive bounds (defaults to inclusive).
*/
rangeSearch(range: [K, K], options?: TreeSetRangeOptions): K[];
/**
* Creates a shallow clone of this set.
* @remarks Time O(n log n), Space O(n)
* @example
* const original = new TreeSet([1, 2, 3]);
* const copy = original.clone();
* copy.add(4);
* original.has(4); // false (original unchanged)
*/
clone(): TreeSet<K>;
}