data-structure-typed 2.5.0 → 2.5.1

package/docs-site-docusaurus/docs/api/classes/IterableElementBase.md

@@ -0,0 +1,800 @@
+[**data-structure-typed**](../README.md)
+
+***
+
+[data-structure-typed](../README.md) / IterableElementBase
+
+# Abstract Class: IterableElementBase\<E, R\>
+
+Defined in: [data-structures/base/iterable-element-base.ts:14](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L14)
+
+Base class that makes a data structure iterable and provides common
+element-wise utilities (e.g., map/filter/reduce/find).
+
+## Remarks
+
+This class implements the JavaScript iteration protocol (via `Symbol.iterator`)
+and offers array-like helpers with predictable time/space complexity.
+
+## Extended by
+
+- [`Stack`](Stack.md)
+- [`Heap`](Heap.md)
+- [`Trie`](Trie.md)
+- [`LinearBase`](LinearBase.md)
+
+## Type Parameters
+
+### E
+
+`E`
+
+The public element type yielded by the structure.
+
+### R
+
+`R`
+
+The underlying "raw" element type used internally or by converters.
+
+## Implements
+
+- `Iterable`\<`E`\>
+
+## Constructors
+
+### toElementFn
+
+#### Get Signature
+
+```ts
+get toElementFn(): ((rawElement) => E) | undefined;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:47](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L47)
+
+Exposes the current `toElementFn`, if configured.
+
+##### Remarks
+
+Time O(1), Space O(1).
+
+##### Returns
+
+((`rawElement`) => `E`) \| `undefined`
+
+The converter function or `undefined` when not set.
+
+## Methods
+
+### \[iterator\]()
+
+```ts
+iterator: IterableIterator<E>;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:60](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L60)
+
+Returns an iterator over the structure's elements.
+
+#### Parameters
+
+##### args
+
+...`unknown`[]
+
+Optional iterator arguments forwarded to the internal iterator.
+
+#### Returns
+
+`IterableIterator`\<`E`\>
+
+An `IterableIterator<E>` that yields the elements in traversal order.
+
+#### Remarks
+
+Producing the iterator is O(1); consuming the entire iterator is Time O(n) with O(1) extra space.
+
+#### Implementation of
+
+```ts
+Iterable.[iterator]
+```
+
+***
+
+### clear()
+
+```ts
+abstract clear(): void;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:288](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L288)
+
+Removes all elements from the structure.
+
+#### Returns
+
+`void`
+
+`void`.
+
+#### Remarks
+
+Expected Time O(1) or O(n) depending on the implementation; Space O(1).
+
+***
+
+### clone()
+
+```ts
+abstract clone(): this;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:297](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L297)
+
+Creates a structural copy with the same element values and configuration.
+
+#### Returns
+
+`this`
+
+A clone of the current instance (same concrete type).
+
+#### Remarks
+
+Expected Time O(n) to copy elements; Space O(n).
+
+***
+
+### every()
+
+```ts
+every(predicate, thisArg?): boolean;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:86](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L86)
+
+Tests whether all elements satisfy the predicate.
+
+#### Parameters
+
+##### predicate
+
+`ElementCallback`\<`E`, `R`, `boolean`\>
+
+Function invoked for each element with signature `(value, index, self)`.
+
+##### thisArg?
+
+`unknown`
+
+Optional `this` binding for the predicate.
+
+#### Returns
+
+`boolean`
+
+`true` if every element passes; otherwise `false`.
+
+#### Remarks
+
+Time O(n) in the worst case; may exit early when the first failure is found. Space O(1).
+
+***
+
+### filter()
+
+```ts
+abstract filter(predicate, thisArg?): this;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:340](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L340)
+
+Filters elements using the provided predicate and returns the same concrete structure type.
+
+#### Parameters
+
+##### predicate
+
+`ElementCallback`\<`E`, `R`, `boolean`\>
+
+Function with signature `(value, index, self) => boolean`.
+
+##### thisArg?
+
+`unknown`
+
+Optional `this` binding for the predicate.
+
+#### Returns
+
+`this`
+
+A new instance of the same concrete type containing only elements that pass the predicate.
+
+#### Remarks
+
+Time O(n), Space O(k) where `k` is the number of kept elements.
+
+***
+
+### find()
+
+#### Call Signature
+
+```ts
+find<S>(predicate, thisArg?): S | undefined;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:162](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L162)
+
+Finds the first element that satisfies the predicate and returns it.
+
+Finds the first element of type `S` (a subtype of `E`) that satisfies the predicate and returns it.
+
+##### Type Parameters
+
+###### S
+
+`S`
+
+##### Parameters
+
+###### predicate
+
+`ElementCallback`\<`E`, `R`, `S`\>
+
+Type-guard predicate: `(value, index, self) => value is S`.
+
+###### thisArg?
+
+`unknown`
+
+Optional `this` binding for the predicate.
+
+##### Returns
+
+`S` \| `undefined`
+
+The matched element typed as `S`, or `undefined` if not found.
+
+##### Remarks
+
+Time O(n) in the worst case; may exit early on the first match. Space O(1).
+
+#### Call Signature
+
+```ts
+find(predicate, thisArg?): E | undefined;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:163](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L163)
+
+Finds the first element that satisfies the predicate and returns it.
+
+Finds the first element of type `S` (a subtype of `E`) that satisfies the predicate and returns it.
+
+##### Parameters
+
+###### predicate
+
+`ElementCallback`\<`E`, `R`, `unknown`\>
+
+Type-guard predicate: `(value, index, self) => value is S`.
+
+###### thisArg?
+
+`unknown`
+
+Optional `this` binding for the predicate.
+
+##### Returns
+
+`E` \| `undefined`
+
+The matched element typed as `S`, or `undefined` if not found.
+
+##### Remarks
+
+Time O(n) in the worst case; may exit early on the first match. Space O(1).
+
+***
+
+### forEach()
+
+```ts
+forEach(callbackfn, thisArg?): void;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:132](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L132)
+
+Invokes a callback for each element in iteration order.
+
+#### Parameters
+
+##### callbackfn
+
+`ElementCallback`\<`E`, `R`, `void`\>
+
+Function invoked per element with signature `(value, index, self)`.
+
+##### thisArg?
+
+`unknown`
+
+Optional `this` binding for the callback.
+
+#### Returns
+
+`void`
+
+`void`.
+
+#### Remarks
+
+Time O(n), Space O(1).
+
+***
+
+### has()
+
+```ts
+has(element): boolean;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:188](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L188)
+
+Checks whether a strictly-equal element exists in the structure.
+
+#### Parameters
+
+##### element
+
+`E`
+
+The element to test with `===` equality.
+
+#### Returns
+
+`boolean`
+
+`true` if an equal element is found; otherwise `false`.
+
+#### Remarks
+
+Time O(n) in the worst case. Space O(1).
+
+***
+
+### isEmpty()
+
+```ts
+abstract isEmpty(): boolean;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:279](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L279)
+
+Indicates whether the structure currently contains no elements.
+
+#### Returns
+
+`boolean`
+
+`true` if empty; otherwise `false`.
+
+#### Remarks
+
+Expected Time O(1), Space O(1) for most implementations.
+
+***
+
+### map()
+
+```ts
+abstract map<EM, RM>(
+   callback, 
+   options?, 
+thisArg?): IterableElementBase<EM, RM>;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:312](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L312)
+
+Maps each element to a new element and returns a new iterable structure.
+
+#### Type Parameters
+
+##### EM
+
+`EM`
+
+The mapped element type.
+
+##### RM
+
+`RM`
+
+The mapped raw element type used internally by the target structure.
+
+#### Parameters
+
+##### callback
+
+`ElementCallback`\<`E`, `R`, `EM`\>
+
+Function with signature `(value, index, self) => mapped`.
+
+##### options?
+
+`IterableElementBaseOptions`\<`EM`, `RM`\>
+
+Optional options for the returned structure, including its `toElementFn`.
+
+##### thisArg?
+
+`unknown`
+
+Optional `this` binding for the callback.
+
+#### Returns
+
+`IterableElementBase`\<`EM`, `RM`\>
+
+A new `IterableElementBase<EM, RM>` containing mapped elements.
+
+#### Remarks
+
+Time O(n), Space O(n).
+
+***
+
+### mapSame()
+
+```ts
+abstract mapSame(callback, thisArg?): this;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:328](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L328)
+
+Maps each element to the same element type and returns the same concrete structure type.
+
+#### Parameters
+
+##### callback
+
+`ElementCallback`\<`E`, `R`, `E`\>
+
+Function with signature `(value, index, self) => mappedValue`.
+
+##### thisArg?
+
+`unknown`
+
+Optional `this` binding for the callback.
+
+#### Returns
+
+`this`
+
+A new instance of the same concrete type with mapped elements.
+
+#### Remarks
+
+Time O(n), Space O(n).
+
+***
+
+### print()
+
+```ts
+print(): void;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:268](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L268)
+
+Prints `toVisual()` to the console. Intended for quick debugging.
+
+#### Returns
+
+`void`
+
+`void`.
+
+#### Remarks
+
+Time O(n) due to materialization, Space O(n) for the intermediate representation.
+
+***
+
+### reduce()
+
+Reduces all elements to a single accumulated value.
+
+#### Param
+
+Reducer of signature `(acc, value, index, self) => nextAcc`. The first element is used as the initial accumulator.
+
+#### Param
+
+Reducer of signature `(acc, value, index, self) => nextAcc`.
+
+#### Param
+
+The initial accumulator value of type `E`.
+
+#### Template
+
+The accumulator type when it differs from `E`.
+
+#### Param
+
+Reducer of signature `(acc: U, value, index, self) => U`.
+
+#### Param
+
+The initial accumulator value of type `U`.
+
+#### Remarks
+
+Time O(n), Space O(1). Throws if called on an empty structure without `initialValue`.
+
+#### Call Signature
+
+```ts
+reduce(callbackfn): E;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:193](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L193)
+
+##### Parameters
+
+###### callbackfn
+
+`ReduceElementCallback`\<`E`, `R`\>
+
+##### Returns
+
+`E`
+
+#### Call Signature
+
+```ts
+reduce(callbackfn, initialValue): E;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:194](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L194)
+
+##### Parameters
+
+###### callbackfn
+
+`ReduceElementCallback`\<`E`, `R`\>
+
+###### initialValue
+
+`E`
+
+##### Returns
+
+`E`
+
+#### Call Signature
+
+```ts
+reduce<U>(callbackfn, initialValue): U;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:195](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L195)
+
+##### Type Parameters
+
+###### U
+
+`U`
+
+##### Parameters
+
+###### callbackfn
+
+`ReduceElementCallback`\<`E`, `R`, `U`\>
+
+###### initialValue
+
+`U`
+
+##### Returns
+
+`U`
+
+***
+
+### some()
+
+```ts
+some(predicate, thisArg?): boolean;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:109](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L109)
+
+Tests whether at least one element satisfies the predicate.
+
+#### Parameters
+
+##### predicate
+
+`ElementCallback`\<`E`, `R`, `boolean`\>
+
+Function invoked for each element with signature `(value, index, self)`.
+
+##### thisArg?
+
+`unknown`
+
+Optional `this` binding for the predicate.
+
+#### Returns
+
+`boolean`
+
+`true` if any element passes; otherwise `false`.
+
+#### Remarks
+
+Time O(n) in the worst case; may exit early on first success. Space O(1).
+
+***
+
+### toArray()
+
+```ts
+toArray(): E[];
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:245](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L245)
+
+Materializes the elements into a new array.
+
+#### Returns
+
+`E`[]
+
+A shallow array copy of the iteration order.
+
+#### Remarks
+
+Time O(n), Space O(n).
+
+***
+
+### toVisual()
+
+```ts
+toVisual(): E[];
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:257](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L257)
+
+Returns a representation of the structure suitable for quick visualization.
+Defaults to an array of elements; subclasses may override to provide richer visuals.
+
+#### Returns
+
+`E`[]
+
+A visual representation (array by default).
+
+#### Remarks
+
+Time O(n), Space O(n).
+
+***
+
+### values()
+
+```ts
+values(): IterableIterator<E>;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:71](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L71)
+
+Returns an iterator over the values (alias of the default iterator).
+
+#### Returns
+
+`IterableIterator`\<`E`\>
+
+An `IterableIterator<E>` over all elements.
+
+#### Remarks
+
+Creating the iterator is O(1); full iteration is Time O(n), Space O(1).
+
+
+---
+
+## Protected Members
+
+### Constructor
+
+```ts
+protected new IterableElementBase<E, R>(options?): IterableElementBase<E, R>;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:24](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L24)
+
+Create a new iterable base.
+
+#### Parameters
+
+##### options?
+
+`IterableElementBaseOptions`\<`E`, `R`\>
+
+Optional behavior overrides. When provided, a `toElementFn`
+is used to convert a raw element (`R`) into a public element (`E`).
+
+#### Returns
+
+`IterableElementBase`\<`E`, `R`\>
+
+#### Remarks
+
+Time O(1), Space O(1).
+
+## Properties
+
+### \_toElementFn?
+
+```ts
+protected optional _toElementFn?: (rawElement) => E;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:38](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L38)
+
+The converter used to transform a raw element (`R`) into a public element (`E`).
+
+#### Parameters
+
+##### rawElement
+
+`R`
+
+#### Returns
+
+`E`
+
+#### Remarks
+
+Time O(1), Space O(1).
+
+## Accessors
+
+### \_getIterator()
+
+```ts
+abstract protected _getIterator(...args): IterableIterator<E>;
+```
+
+Defined in: [data-structures/base/iterable-element-base.ts:351](https://github.com/zrwusa/data-structure-typed/blob/2f6ceb3aee852228efc88b111e19c0809753e805/src/data-structures/base/iterable-element-base.ts#L351)
+
+Internal iterator factory used by the default iterator.
+
+#### Parameters
+
+##### args
+
+...`unknown`[]
+
+Optional iterator arguments.
+
+#### Returns
+
+`IterableIterator`\<`E`\>
+
+An iterator over elements.
+
+#### Remarks
+
+Implementations should yield in O(1) per element with O(1) extra space when possible.
+
+***