data-structure-typed 2.4.4 → 2.5.0

package/src/data-structures/linked-list/doubly-linked-list.ts

@@ -87,50 +87,6 @@ export class DoublyLinkedListNode<E = any> extends LinkedListNode<E> {
  * 4. High Efficiency in Insertion and Deletion: Adding or removing elements in a linked list does not require moving other elements, making these operations more efficient than in arrays.
  * Caution: Although our linked list classes provide methods such as at, setAt, addAt, and indexOf that are based on array indices, their time complexity, like that of the native Array.lastIndexOf, is 𝑂(𝑛). If you need to use these methods frequently, you might want to consider other data structures, such as Deque or Queue (designed for random access). Similarly, since the native Array.shift method has a time complexity of 𝑂(𝑛), using an array to simulate a queue can be inefficient. In such cases, you should use Queue or Deque, as these data structures leverage deferred array rearrangement, effectively reducing the average time complexity to 𝑂(1).
  * @example
- * // basic DoublyLinkedList creation and push operation
- *  // Create a simple DoublyLinkedList with initial values
- *     const list = new DoublyLinkedList([1, 2, 3, 4, 5]);
- *
- *     // Verify the list maintains insertion order
- *     console.log([...list]); // [1, 2, 3, 4, 5];
- *
- *     // Check length
- *     console.log(list.length); // 5;
- *
- *     // Push a new element to the end
- *     list.push(6);
- *     console.log(list.length); // 6;
- *     console.log([...list]); // [1, 2, 3, 4, 5, 6];
- * @example
- * // DoublyLinkedList pop and shift operations
- *  const list = new DoublyLinkedList<number>([10, 20, 30, 40, 50]);
- *
- *     // Pop removes from the end
- *     const last = list.pop();
- *     console.log(last); // 50;
- *
- *     // Shift removes from the beginning
- *     const first = list.shift();
- *     console.log(first); // 10;
- *
- *     // Verify remaining elements
- *     console.log([...list]); // [20, 30, 40];
- *     console.log(list.length); // 3;
- * @example
- * // DoublyLinkedList for...of iteration and map operation
- *  const list = new DoublyLinkedList<number>([1, 2, 3, 4, 5]);
- *
- *     // Iterate through list
- *     const doubled = list.map(value => value * 2);
- *     console.log(doubled.length); // 5;
- *
- *     // Use for...of loop
- *     const result: number[] = [];
- *     for (const item of list) {
- *       result.push(item);
- *     }
- *     console.log(result); // [1, 2, 3, 4, 5];
- * @example
  * // Browser history
  *  const browserHistory = new DoublyLinkedList<string>();
  *
@@ -180,6 +136,16 @@ export class DoublyLinkedListNode<E = any> extends LinkedListNode<E> {
  *     // Access entry (in real LRU, this would move it to end)
  *     const foundEntry = [...cacheList].find(entry => entry.key === 'user:2');
  *     console.log(foundEntry?.value); // 'Bob';
+ * @example
+ * // Find first matching element
+ *  const list = new DoublyLinkedList<number>([5, 10, 15, 20]);
+ *     console.log(list.find(n => n >= 12)); // 15;
+ * @example
+ * // Iterate over elements
+ *  const list = new DoublyLinkedList<number>([1, 2, 3]);
+ *     const sum: number[] = [];
+ *     list.forEach(n => sum.push(n));
+ *     console.log(sum); // [1, 2, 3];
  */
 export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, DoublyLinkedListNode<E>> {
   protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);
@@ -302,6 +268,33 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @remarks Time O(1), Space O(1)
    * @param elementOrNode - Element or node to append.
    * @returns True when appended.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // basic DoublyLinkedList creation and push operation
+ *  // Create a simple DoublyLinkedList with initial values
+ *     const list = new DoublyLinkedList([1, 2, 3, 4, 5]);
+ *
+ *     // Verify the list maintains insertion order
+ *     console.log([...list]); // [1, 2, 3, 4, 5];
+ *
+ *     // Check length
+ *     console.log(list.length); // 5;
+ *
+ *     // Push a new element to the end
+ *     list.push(6);
+ *     console.log(list.length); // 6;
+ *     console.log([...list]); // [1, 2, 3, 4, 5, 6];
    */
 
   push(elementOrNode: E | DoublyLinkedListNode<E>): boolean {
@@ -323,6 +316,33 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * Remove and return the tail element.
    * @remarks Time O(1), Space O(1)
    * @returns Removed element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // DoublyLinkedList pop and shift operations
+ *  const list = new DoublyLinkedList<number>([10, 20, 30, 40, 50]);
+ *
+ *     // Pop removes from the end
+ *     const last = list.pop();
+ *     console.log(last); // 50;
+ *
+ *     // Shift removes from the beginning
+ *     const first = list.shift();
+ *     console.log(first); // 10;
+ *
+ *     // Verify remaining elements
+ *     console.log([...list]); // [20, 30, 40];
+ *     console.log(list.length); // 3;
    */
 
   pop(): E | undefined {
@@ -343,6 +363,23 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * Remove and return the head element.
    * @remarks Time O(1), Space O(1)
    * @returns Removed element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove from the front
+ *  const list = new DoublyLinkedList<number>([10, 20, 30]);
+ *     console.log(list.shift()); // 10;
+ *     console.log(list.first); // 20;
    */
 
   shift(): E | undefined {
@@ -364,6 +401,23 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @remarks Time O(1), Space O(1)
    * @param elementOrNode - Element or node to prepend.
    * @returns True when prepended.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Add to the front
+ *  const list = new DoublyLinkedList<number>([2, 3]);
+ *     list.unshift(1);
+ *     console.log([...list]); // [1, 2, 3];
    */
 
   unshift(elementOrNode: E | DoublyLinkedListNode<E>): boolean {
@@ -418,6 +472,23 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @remarks Time O(N), Space O(1)
    * @param index - Zero-based index.
    * @returns Element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Access by index
+ *  const list = new DoublyLinkedList<string>(['a', 'b', 'c']);
+ *     console.log(list.at(1)); // 'b';
+ *     console.log(list.at(2)); // 'c';
    */
 
   at(index: number): E | undefined {
@@ -432,6 +503,19 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @remarks Time O(N), Space O(1)
    * @param index - Zero-based index.
    * @returns Node or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get node at index
+ *  const list = new DoublyLinkedList<string>(['a', 'b', 'c']);
+ *     console.log(list.getNodeAt(1)?.value); // 'b';
    */
 
   getNodeAt(index: number): DoublyLinkedListNode<E> | undefined {
@@ -486,6 +570,20 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @param index - Zero-based index.
    * @param newElementOrNode - Element or node to insert.
    * @returns True if inserted.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Insert at position
+ *  const list = new DoublyLinkedList<number>([1, 3]);
+ *     list.addAt(1, 2);
+ *     console.log(list.toArray()); // [1, 2, 3];
    */
 
   addAt(index: number, newElementOrNode: E | DoublyLinkedListNode<E>): boolean {
@@ -575,6 +673,20 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @remarks Time O(N), Space O(1)
    * @param index - Zero-based index.
    * @returns Removed element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove by index
+ *  const list = new DoublyLinkedList<string>(['a', 'b', 'c']);
+ *     list.deleteAt(1);
+ *     console.log(list.toArray()); // ['a', 'c'];
    */
 
   deleteAt(index: number): E | undefined {
@@ -596,6 +708,20 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @remarks Time O(N), Space O(1)
    * @param [elementOrNode] - Element or node to remove.
    * @returns True if removed.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove first occurrence
+ *  const list = new DoublyLinkedList<number>([1, 2, 3, 2]);
+ *     list.delete(2);
+ *     console.log(list.toArray()); // [1, 3, 2];
    */
 
   delete(elementOrNode: E | DoublyLinkedListNode<E> | undefined): boolean {
@@ -618,6 +744,19 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * Check whether the list is empty.
    * @remarks Time O(1), Space O(1)
    * @returns True if length is 0.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check empty
+ *  console.log(new DoublyLinkedList().isEmpty()); // true;
    */
 
   isEmpty(): boolean {
@@ -628,6 +767,21 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * Remove all nodes and reset length.
    * @remarks Time O(N), Space O(1)
    * @returns void
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all
+ *  const list = new DoublyLinkedList<number>([1, 2]);
+ *     list.clear();
+ *     console.log(list.isEmpty()); // true;
    */
 
   clear(): void {
@@ -641,6 +795,20 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @remarks Time O(N), Space O(1)
    * @param elementNodeOrPredicate - Element, node, or predicate to match.
    * @returns Matched value or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Search with predicate
+ *  const list = new DoublyLinkedList<number>([10, 20, 30]);
+ *     const found = list.search(node => node.value > 15);
+ *     console.log(found); // 20;
    */
 
   search(
@@ -660,6 +828,21 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @remarks Time O(N), Space O(1)
    * @param elementNodeOrPredicate - Element, node, or predicate to match.
    * @returns Matched value or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find value scanning from tail
+ *  const list = new DoublyLinkedList<number>([1, 2, 3, 4]);
+ *     // getBackward scans from tail to head, returns first match
+ *     const found = list.getBackward(node => node.value < 4);
+ *     console.log(found); // 3;
    */
 
   getBackward(
@@ -678,6 +861,23 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * Reverse the list in place.
    * @remarks Time O(N), Space O(1)
    * @returns This list.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Reverse in-place
+ *  const list = new DoublyLinkedList<number>([1, 2, 3]);
+ *     list.reverse();
+ *     console.log([...list]); // [3, 2, 1];
    */
 
   reverse(): this {
@@ -707,6 +907,22 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * Deep clone this list (values are copied by reference).
    * @remarks Time O(N), Space O(N)
    * @returns A new list with the same element sequence.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Deep copy
+ *  const list = new DoublyLinkedList<number>([1, 2, 3]);
+ *     const copy = list.clone();
+ *     copy.pop();
+ *     console.log(list.length); // 3;
    */
 
   clone(): this {
@@ -721,6 +937,23 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @param callback - Predicate (value, index, list) → boolean to keep value.
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new list with kept values.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Filter elements
+ *  const list = new DoublyLinkedList<number>([1, 2, 3, 4, 5]);
+ *     const evens = list.filter(n => n % 2 === 0);
+ *     console.log([...evens]); // [2, 4];
    */
 
   filter(callback: ElementCallback<E, R, boolean>, thisArg?: any): this {
@@ -757,6 +990,32 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    * @param [options] - Options for the output list (e.g., maxLen, toElementFn).
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new DoublyLinkedList with mapped values.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // DoublyLinkedList for...of iteration and map operation
+ *  const list = new DoublyLinkedList<number>([1, 2, 3, 4, 5]);
+ *
+ *     // Iterate through list
+ *     const doubled = list.map(value => value * 2);
+ *     console.log(doubled.length); // 5;
+ *
+ *     // Use for...of loop
+ *     const result: number[] = [];
+ *     for (const item of list) {
+ *       result.push(item);
+ *     }
+ *     console.log(result); // [1, 2, 3, 4, 5];
    */
 
   map<EM, RM>(