bst-typed 1.49.0 → 1.49.2

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

@@ -1,6 +1,3 @@
-import { IterableElementBase } from "../base";
-import { ElementCallback } from "../../types";
-
 /**
  * data-structure-typed
  *
@@ -8,6 +5,9 @@ import { ElementCallback } from "../../types";
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
+import type { ElementCallback } from '../../types';
+import { IterableElementBase } from '../base';
+
 export class DoublyLinkedListNode<E = any> {
   value: E;
   next: DoublyLinkedListNode<E> | undefined;
@@ -25,15 +25,21 @@ export class DoublyLinkedListNode<E = any> {
   }
 }
 
+/**
+ * 1. Node Structure: Each node contains three parts: a data field, a pointer (or reference) to the previous node, and a pointer to the next node. This structure allows traversal of the linked list in both directions.
+ * 2. Bidirectional Traversal: Unlike singly linked lists, doubly linked lists can be easily traversed forwards or backwards. This makes insertions and deletions in the list more flexible and efficient.
+ * 3. No Centralized Index: Unlike arrays, elements in a linked list are not stored contiguously, so there is no centralized index. Accessing elements in a linked list typically requires traversing from the head or tail node.
+ * 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.
+ */
 export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
   /**
-   * The constructor initializes the linked list with an empty head, tail, and length.
+   * The constructor initializes the linked list with an empty head, tail, and size.
    */
   constructor(elements?: Iterable<E>) {
     super();
     this._head = undefined;
     this._tail = undefined;
-    this._length = 0;
+    this._size = 0;
     if (elements) {
       for (const el of elements) {
         this.push(el);
@@ -53,23 +59,19 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
     return this._tail;
   }
 
-  protected _length: number;
-
-  get length(): number {
-    return this._length;
-  }
+  protected _size: number;
 
   get size(): number {
-    return this.length;
+    return this._size;
   }
 
   /**
-   * Time Complexity: O(n), where n is the length of the input array.
+   * Time Complexity: O(n), where n is the size of the input array.
    * Space Complexity: O(n)
    */
 
   /**
-   * Time Complexity: O(n), where n is the length of the input array.
+   * Time Complexity: O(n), where n is the size of the input array.
    * Space Complexity: O(n)
    *
    * The `fromArray` function creates a new instance of a DoublyLinkedList and populates it with the elements from the
@@ -97,7 +99,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * The push function adds a new node with the given value to the end of the doubly linked list.
    * @param {E} value - The value to be added to the linked list.
    */
-  push(value: E): void {
+  push(value: E): boolean {
     const newNode = new DoublyLinkedListNode(value);
     if (!this.head) {
       this._head = newNode;
@@ -107,23 +109,8 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
       this.tail!.next = newNode;
       this._tail = newNode;
     }
-    this._length++;
-  }
-
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The addLast function adds a new node with the given value to the end of the doubly linked list.
-   * @param {E} value - The value to be added to the linked list.
-   */
-  addLast(value: E): void {
-    this.push(value);
+    this._size++;
+    return true;
   }
 
   /**
@@ -149,27 +136,10 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
       this._tail = removedNode.prev;
       this.tail!.next = undefined;
     }
-    this._length--;
+    this._size--;
     return removedNode.value;
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The `pollLast()` function removes and returns the value of the last node in a doubly linked list.
-   * @returns The method is returning the value of the removed node (removedNode.value) if the list is not empty. If the
-   * list is empty, it returns undefined.
-   */
-  pollLast(): E | undefined {
-    return this.pop();
-  }
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -193,27 +163,10 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
       this._head = removedNode.next;
       this.head!.prev = undefined;
     }
-    this._length--;
+    this._size--;
     return removedNode.value;
   }
 
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The `pollFirst()` function removes and returns the value of the first node in a doubly linked list.
-   * @returns The method `shift()` returns the value of the node that is removed from the beginning of the doubly linked
-   * list.
-   */
-  pollFirst(): E | undefined {
-    return this.shift();
-  }
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -227,7 +180,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * @param {E} value - The `value` parameter represents the value of the new node that will be added to the beginning of the
    * doubly linked list.
    */
-  unshift(value: E): void {
+  unshift(value: E): boolean {
     const newNode = new DoublyLinkedListNode(value);
     if (!this.head) {
       this._head = newNode;
@@ -237,56 +190,8 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
       this.head!.prev = newNode;
       this._head = newNode;
     }
-    this._length++;
-  }
-
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
-   *
-   * The addFirst function adds a new node with the given value to the beginning of a doubly linked list.
-   * @param {E} value - The `value` parameter represents the value of the new node that will be added to the beginning of the
-   * doubly linked list.
-   */
-  addFirst(value: E): void {
-    this.unshift(value);
-  }
-
-  /**
-   * Time Complexity: O(n), where n is the number of elements in the linked list.
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(n), where n is the number of elements in the linked list.
-   * Space Complexity: O(1)
-   *
-   * The `getFirst` function returns the first node in a doubly linked list, or undefined if the list is empty.
-   * @returns The method `getFirst()` returns the first node of the doubly linked list, or `undefined` if the list is empty.
-   */
-  getFirst(): E | undefined {
-    return this.head?.value;
-  }
-
-  /**
-   * Time Complexity: O(n), where n is the number of elements in the linked list.
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(n), where n is the number of elements in the linked list.
-   * Space Complexity: O(1)
-   *
-   * The `getLast` function returns the last node in a doubly linked list, or undefined if the list is empty.
-   * @returns The method `getLast()` returns the last node of the doubly linked list, or `undefined` if the list is empty.
-   */
-  getLast(): E | undefined {
-    return this.tail?.value;
+    this._size++;
+    return true;
   }
 
   /**
@@ -305,7 +210,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * or the linked list is empty, it will return undefined.
    */
   getAt(index: number): E | undefined {
-    if (index < 0 || index >= this.length) return undefined;
+    if (index < 0 || index >= this.size) return undefined;
     let current = this.head;
     for (let i = 0; i < index; i++) {
       current = current!.next;
@@ -330,7 +235,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * valid range of the linked list, otherwise it returns `undefined`.
    */
   getNodeAt(index: number): DoublyLinkedListNode<E> | undefined {
-    if (index < 0 || index >= this.length) return undefined;
+    if (index < 0 || index >= this.size) return undefined;
     let current = this.head;
     for (let i = 0; i < index; i++) {
       current = current!.next;
@@ -383,13 +288,13 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * @returns The `insert` method returns a boolean value. It returns `true` if the insertion is successful, and `false`
    * if the index is out of bounds.
    */
-  insertAt(index: number, value: E): boolean {
-    if (index < 0 || index > this.length) return false;
+  addAt(index: number, value: E): boolean {
+    if (index < 0 || index > this.size) return false;
     if (index === 0) {
       this.unshift(value);
       return true;
     }
-    if (index === this.length) {
+    if (index === this.size) {
       this.push(value);
       return true;
     }
@@ -401,7 +306,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
     newNode.next = nextNode;
     prevNode!.next = newNode;
     nextNode!.prev = newNode;
-    this._length++;
+    this._size++;
     return true;
   }
 
@@ -414,7 +319,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * Time Complexity: O(n), where n is the number of elements in the linked list.
    * Space Complexity: O(1)
    *
-   * The `insertBefore` function inserts a new value before an existing value or node in a doubly linked list.
+   * The `addBefore` function inserts a new value before an existing value or node in a doubly linked list.
    * @param {E | DoublyLinkedListNode<E>} existingValueOrNode - The existing value or node in the doubly linked list
    * before which the new value will be inserted. It can be either the value of the existing node or the existing node
    * itself.
@@ -423,7 +328,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * @returns The method returns a boolean value. It returns `true` if the insertion is successful, and `false` if the
    * insertion fails.
    */
-  insertBefore(existingValueOrNode: E | DoublyLinkedListNode<E>, newValue: E): boolean {
+  addBefore(existingValueOrNode: E | DoublyLinkedListNode<E>, newValue: E): boolean {
     let existingNode;
 
     if (existingValueOrNode instanceof DoublyLinkedListNode) {
@@ -443,7 +348,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
       if (existingNode === this.head) {
         this._head = newNode;
       }
-      this._length++;
+      this._size++;
       return true;
     }
 
@@ -459,7 +364,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * Time Complexity: O(n), where n is the number of elements in the linked list.
    * Space Complexity: O(1)
    *
-   * The `insertAfter` function inserts a new node with a given value after an existing node in a doubly linked list.
+   * The `addAfter` function inserts a new node with a given value after an existing node in a doubly linked list.
    * @param {E | DoublyLinkedListNode<E>} existingValueOrNode - The existing value or node in the doubly linked list
    * after which the new value will be inserted. It can be either the value of the existing node or the existing node
    * itself.
@@ -467,7 +372,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * @returns The method returns a boolean value. It returns true if the insertion is successful, and false if the
    * existing value or node is not found in the doubly linked list.
    */
-  insertAfter(existingValueOrNode: E | DoublyLinkedListNode<E>, newValue: E): boolean {
+  addAfter(existingValueOrNode: E | DoublyLinkedListNode<E>, newValue: E): boolean {
     let existingNode;
 
     if (existingValueOrNode instanceof DoublyLinkedListNode) {
@@ -487,7 +392,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
       if (existingNode === this.tail) {
         this._tail = newNode;
       }
-      this._length++;
+      this._size++;
       return true;
     }
 
@@ -509,18 +414,24 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    * @returns The method `deleteAt` returns the value of the node that was deleted, or `undefined` if the index is out of
    * bounds.
    */
-  deleteAt(index: number): E | undefined {
-    if (index < 0 || index >= this.length) return undefined;
-    if (index === 0) return this.shift();
-    if (index === this.length - 1) return this.pop();
+  deleteAt(index: number): boolean {
+    if (index < 0 || index >= this.size) return false;
+    if (index === 0) {
+      this.shift();
+      return true;
+    }
+    if (index === this.size - 1) {
+      this.pop();
+      return true;
+    }
 
     const removedNode = this.getNodeAt(index);
     const prevNode = removedNode!.prev;
     const nextNode = removedNode!.next;
     prevNode!.next = nextNode;
     nextNode!.prev = prevNode;
-    this._length--;
-    return removedNode!.value;
+    this._size--;
+    return true;
   }
 
   /**
@@ -557,7 +468,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
         const nextNode = node.next;
         prevNode!.next = nextNode;
         nextNode!.prev = prevNode;
-        this._length--;
+        this._size--;
       }
       return true;
     }
@@ -565,20 +476,20 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * The function checks if a variable has a length greater than zero and returns a boolean value.
+   * The function checks if a variable has a size greater than zero and returns a boolean value.
    * @returns A boolean value is being returned.
    */
   isEmpty(): boolean {
-    return this.length === 0;
+    return this.size === 0;
   }
 
   /**
-   * The `clear` function resets the linked list by setting the head, tail, and length to undefined and 0 respectively.
+   * The `clear` function resets the linked list by setting the head, tail, and size to undefined and 0 respectively.
    */
   clear(): void {
     this._head = undefined;
     this._tail = undefined;
-    this._length = 0;
+    this._size = 0;
   }
 
   /**
@@ -673,7 +584,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
    *
    * The `reverse` function reverses the order of the elements in a doubly linked list.
    */
-  reverse(): void {
+  reverse(): this {
     let current = this.head;
     [this._head, this._tail] = [this.tail, this.head];
     while (current) {
@@ -681,6 +592,7 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
       [current.prev, current.next] = [current.next, current.prev];
       current = next;
     }
+    return this;
   }
 
   /**
@@ -794,13 +706,103 @@ export class DoublyLinkedList<E = any> extends IterableElementBase<E> {
     return mappedList;
   }
 
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The addLast function adds a new node with the given value to the end of the doubly linked list.
+   * @param {E} value - The value to be added to the linked list.
+   */
+  addLast(value: E): boolean {
+    return this.push(value);
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `pollLast()` function removes and returns the value of the last node in a doubly linked list.
+   * @returns The method is returning the value of the removed node (removedNode.value) if the list is not empty. If the
+   * list is empty, it returns undefined.
+   */
+  pollLast(): E | undefined {
+    return this.pop();
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `pollFirst()` function removes and returns the value of the first node in a doubly linked list.
+   * @returns The method `shift()` returns the value of the node that is removed from the beginning of the doubly linked
+   * list.
+   */
+  pollFirst(): E | undefined {
+    return this.shift();
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The addFirst function adds a new node with the given value to the beginning of a doubly linked list.
+   * @param {E} value - The `value` parameter represents the value of the new node that will be added to the beginning of the
+   * doubly linked list.
+   */
+  addFirst(value: E): void {
+    this.unshift(value);
+  }
+
   /**
    * Time Complexity: O(n), where n is the number of elements in the linked list.
-   * Space Complexity: O(n)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(n), where n is the number of elements in the linked list.
+   * Space Complexity: O(1)
+   *
+   * The `get first` function returns the first node in a doubly linked list, or undefined if the list is empty.
+   * @returns The method `get first()` returns the first node of the doubly linked list, or `undefined` if the list is empty.
    */
+  get first(): E | undefined {
+    return this.head?.value;
+  }
 
-  print(): void {
-    console.log([...this]);
+  /**
+   * Time Complexity: O(n), where n is the number of elements in the linked list.
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(n), where n is the number of elements in the linked list.
+   * Space Complexity: O(1)
+   *
+   * The `get last` function returns the last node in a doubly linked list, or undefined if the list is empty.
+   * @returns The method `get last()` returns the last node of the doubly linked list, or `undefined` if the list is empty.
+   */
+  get last(): E | undefined {
+    return this.tail?.value;
   }
 
   /**