data-structure-typed 1.54.3 → 2.0.1

package/dist/esm/data-structures/linked-list/singly-linked-list.js

@@ -1,95 +1,121 @@
-import { IterableElementBase } from '../base';
-export class SinglyLinkedListNode {
+import { LinearLinkedBase, LinkedListNode } from '../base/linear-base';
+export class SinglyLinkedListNode extends LinkedListNode {
     /**
      * The constructor function initializes an instance of a class with a given value and sets the next property to undefined.
      * @param {E} value - The "value" parameter is of type E, which means it can be any data type. It represents the value that
      * will be stored in the node of a linked list.
      */
     constructor(value) {
+        super(value);
         this._value = value;
         this._next = undefined;
     }
-    _value;
-    /**
-     * The function returns the value of a protected variable.
-     * @returns The value of the variable `_value` is being returned.
-     */
-    get value() {
-        return this._value;
-    }
-    /**
-     * The above function sets the value of a variable.
-     * @param {E} value - The parameter "value" is of type E, which means it can be any type.
-     */
-    set value(value) {
-        this._value = value;
-    }
     _next;
-    /**
-     * The `next` function returns the next node in a singly linked list.
-     * @returns The `next` property is being returned. It can be either a `SinglyLinkedListNode<E>`
-     * object or `undefined`.
-     */
     get next() {
         return this._next;
     }
-    /**
-     * The "next" property of a SinglyLinkedListNode is set to the provided value.
-     * @param {SinglyLinkedListNode<E> | undefined} value - The `value` parameter is of type
-     * `SinglyLinkedListNode<E> | undefined`. This means that it can accept either a
-     * `SinglyLinkedListNode` object or `undefined` as its value.
-     */
     set next(value) {
         this._next = value;
     }
 }
 /**
+ * 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 doubly linked lists, singly linked lists can be easily traversed forwards but not backwards.
+ * 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.
+ * 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
+ * // implementation of a basic text editor
+ *     class TextEditor {
+ *       private content: SinglyLinkedList<string>;
+ *       private cursorIndex: number;
+ *       private undoStack: Stack<{ operation: string; data?: any }>;
+ *
+ *       constructor() {
+ *         this.content = new SinglyLinkedList<string>();
+ *         this.cursorIndex = 0; // Cursor starts at the beginning
+ *         this.undoStack = new Stack<{ operation: string; data?: any }>(); // Stack to keep track of operations for undo
+ *       }
+ *
+ *       insert(char: string) {
+ *         this.content.addAt(this.cursorIndex, char);
+ *         this.cursorIndex++;
+ *         this.undoStack.push({ operation: 'insert', data: { index: this.cursorIndex - 1 } });
+ *       }
+ *
+ *       delete() {
+ *         if (this.cursorIndex === 0) return; // Nothing to delete
+ *         const deleted = this.content.deleteAt(this.cursorIndex - 1);
+ *         this.cursorIndex--;
+ *         this.undoStack.push({ operation: 'delete', data: { index: this.cursorIndex, char: deleted } });
+ *       }
+ *
+ *       moveCursor(index: number) {
+ *         this.cursorIndex = Math.max(0, Math.min(index, this.content.length));
+ *       }
+ *
+ *       undo() {
+ *         if (this.undoStack.size === 0) return; // No operations to undo
+ *         const lastAction = this.undoStack.pop();
+ *
+ *         if (lastAction!.operation === 'insert') {
+ *           this.content.deleteAt(lastAction!.data.index);
+ *           this.cursorIndex = lastAction!.data.index;
+ *         } else if (lastAction!.operation === 'delete') {
+ *           this.content.addAt(lastAction!.data.index, lastAction!.data.char);
+ *           this.cursorIndex = lastAction!.data.index + 1;
+ *         }
+ *       }
  *
+ *       getText(): string {
+ *         return [...this.content].join('');
+ *       }
+ *     }
+ *
+ *     // Example Usage
+ *     const editor = new TextEditor();
+ *     editor.insert('H');
+ *     editor.insert('e');
+ *     editor.insert('l');
+ *     editor.insert('l');
+ *     editor.insert('o');
+ *     console.log(editor.getText()); // 'Hello' // Output: "Hello"
+ *
+ *     editor.delete();
+ *     console.log(editor.getText()); // 'Hell' // Output: "Hell"
+ *
+ *     editor.undo();
+ *     console.log(editor.getText()); // 'Hello' // Output: "Hello"
+ *
+ *     editor.moveCursor(1);
+ *     editor.insert('a');
+ *     console.log(editor.getText()); // 'Haello'
  */
-export class SinglyLinkedList extends IterableElementBase {
+export class SinglyLinkedList extends LinearLinkedBase {
     constructor(elements = [], options) {
         super(options);
+        if (options) {
+        }
         this.pushMany(elements);
     }
     _head;
-    /**
-     * The `head` function returns the first node of a singly linked list.
-     * @returns The method is returning either a SinglyLinkedListNode object or undefined.
-     */
     get head() {
         return this._head;
     }
     _tail;
-    /**
-     * The `tail` function returns the last node of a singly linked list.
-     * @returns The method is returning either a SinglyLinkedListNode object or undefined.
-     */
     get tail() {
         return this._tail;
     }
-    /**
-     * The above function returns the value of the first element in a linked list, or undefined if the
-     * list is empty.
-     * @returns The value of the first node in the linked list, or undefined if the linked list is empty.
-     */
     get first() {
         return this.head?.value;
     }
-    /**
-     * The function returns the value of the last element in a linked list, or undefined if the list is
-     * empty.
-     * @returns The value of the last node in the linked list, or undefined if the linked list is empty.
-     */
     get last() {
         return this.tail?.value;
     }
-    _size = 0;
-    /**
-     * The function returns the size of an object.
-     * @returns The size of the object, which is a number.
-     */
-    get size() {
-        return this._size;
+    _length = 0;
+    get length() {
+        return this._length;
     }
     /**
      * Time Complexity: O(n)
@@ -126,7 +152,9 @@ export class SinglyLinkedList extends IterableElementBase {
             this.tail.next = newNode;
             this._tail = newNode;
         }
-        this._size++;
+        this._length++;
+        if (this._maxLen > 0 && this.length > this._maxLen)
+            this.shift();
         return true;
     }
     /**
@@ -144,7 +172,7 @@ export class SinglyLinkedList extends IterableElementBase {
             const value = this.head.value;
             this._head = undefined;
             this._tail = undefined;
-            this._size--;
+            this._length--;
             return value;
         }
         let current = this.head;
@@ -154,7 +182,7 @@ export class SinglyLinkedList extends IterableElementBase {
         const value = this.tail.value;
         current.next = undefined;
         this._tail = current;
-        this._size--;
+        this._length--;
         return value;
     }
     /**
@@ -169,7 +197,7 @@ export class SinglyLinkedList extends IterableElementBase {
             return undefined;
         const removedNode = this.head;
         this._head = this.head.next;
-        this._size--;
+        this._length--;
         return removedNode.value;
     }
     /**
@@ -193,7 +221,7 @@ export class SinglyLinkedList extends IterableElementBase {
             newNode.next = this.head;
             this._head = newNode;
         }
-        this._size++;
+        this._length++;
         return true;
     }
     /**
@@ -276,7 +304,7 @@ export class SinglyLinkedList extends IterableElementBase {
      * `undefined` if the index is out of bounds.
      */
     at(index) {
-        if (index < 0 || index >= this._size)
+        if (index < 0 || index >= this._length)
             return undefined;
         let current = this.head;
         for (let i = 0; i < index; i++) {
@@ -328,21 +356,25 @@ export class SinglyLinkedList extends IterableElementBase {
      * bounds.
      */
     deleteAt(index) {
-        if (index < 0 || index >= this._size)
-            return false;
+        if (index < 0 || index >= this._length)
+            return;
+        let deleted;
         if (index === 0) {
+            deleted = this.first;
             this.shift();
-            return true;
+            return deleted;
         }
-        if (index === this._size - 1) {
-            this.pop();
-            return true;
+        const targetNode = this.getNodeAt(index);
+        const prevNode = this._getPrevNode(targetNode);
+        if (prevNode && targetNode) {
+            deleted = targetNode.value;
+            prevNode.next = targetNode.next;
+            if (targetNode === this.tail)
+                this._tail = prevNode;
+            this._length--;
+            return deleted;
         }
-        const prevNode = this.getNodeAt(index - 1);
-        const removedNode = prevNode.next;
-        prevNode.next = removedNode.next;
-        this._size--;
-        return true;
+        return;
     }
     /**
      * Time Complexity: O(n)
@@ -355,37 +387,25 @@ export class SinglyLinkedList extends IterableElementBase {
      * successfully deleted from the linked list, and `false` if the value or node is not found in the linked list.
      */
     delete(elementOrNode) {
-        if (elementOrNode === undefined)
+        if (elementOrNode === undefined || !this.head)
             return false;
-        let value;
-        if (elementOrNode instanceof SinglyLinkedListNode) {
-            value = elementOrNode.value;
+        const node = this.isNode(elementOrNode) ? elementOrNode : this.getNode(elementOrNode);
+        if (!node)
+            return false;
+        const prevNode = this._getPrevNode(node);
+        if (!prevNode) {
+            // The node is the head
+            this._head = node.next;
+            if (node === this.tail)
+                this._tail = undefined;
         }
         else {
-            value = elementOrNode;
+            prevNode.next = node.next;
+            if (node === this.tail)
+                this._tail = prevNode;
         }
-        let current = this.head, prev = undefined;
-        while (current) {
-            if (current.value === value) {
-                if (prev === undefined) {
-                    this._head = current.next;
-                    if (current === this.tail) {
-                        this._tail = undefined;
-                    }
-                }
-                else {
-                    prev.next = current.next;
-                    if (current === this.tail) {
-                        this._tail = prev;
-                    }
-                }
-                this._size--;
-                return true;
-            }
-            prev = current;
-            current = current.next;
-        }
-        return false;
+        this._length--;
+        return true;
     }
     /**
      * Time Complexity: O(n)
@@ -403,13 +423,13 @@ export class SinglyLinkedList extends IterableElementBase {
      * successfully added at the specified index, and `false` if the index is out of bounds.
      */
     addAt(index, newElementOrNode) {
-        if (index < 0 || index > this._size)
+        if (index < 0 || index > this._length)
             return false;
         if (index === 0) {
             this.unshift(newElementOrNode);
             return true;
         }
-        if (index === this._size) {
+        if (index === this._length) {
             this.push(newElementOrNode);
             return true;
         }
@@ -417,9 +437,31 @@ export class SinglyLinkedList extends IterableElementBase {
         const prevNode = this.getNodeAt(index - 1);
         newNode.next = prevNode.next;
         prevNode.next = newNode;
-        this._size++;
+        this._length++;
         return true;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The function setAt(index, value) updates the value at a specified index in a data structure if the
+     * index exists.
+     * @param {number} index - The `index` parameter in the `setAt` method refers to the position in the
+     * data structure where you want to set a new value.
+     * @param {E} value - The `value` parameter in the `setAt` method represents the new value that you
+     * want to set at the specified index in the data structure.
+     * @returns The `setAt` method returns a boolean value - `true` if the value at the specified index
+     * is successfully updated, and `false` if the index is out of bounds (i.e., the node at that index
+     * does not exist).
+     */
+    setAt(index, value) {
+        const node = this.getNodeAt(index);
+        if (node) {
+            node.value = value;
+            return true;
+        }
+        return false;
+    }
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -429,7 +471,7 @@ export class SinglyLinkedList extends IterableElementBase {
      * @returns A boolean value indicating whether the length of the object is equal to 0.
      */
     isEmpty() {
-        return this._size === 0;
+        return this._length === 0;
     }
     /**
      * Time Complexity: O(1)
@@ -440,23 +482,7 @@ export class SinglyLinkedList extends IterableElementBase {
     clear() {
         this._head = undefined;
         this._tail = undefined;
-        this._size = 0;
-    }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The `toArray` function converts a linked list into an array.
-     * @returns The `toArray()` method is returning an array of type `E[]`.
-     */
-    toArray() {
-        const array = [];
-        let current = this.head;
-        while (current) {
-            array.push(current.value);
-            current = current.next;
-        }
-        return array;
+        this._length = 0;
     }
     /**
      * Time Complexity: O(n)
@@ -480,32 +506,6 @@ export class SinglyLinkedList extends IterableElementBase {
         [this._head, this._tail] = [this.tail, this.head];
         return this;
     }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `indexOf` function in TypeScript searches for a specific element or node in a singly linked
-     * list and returns its index if found.
-     * @param {E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<E>) => boolean)} elementNodeOrPredicate
-     * elementNodeOrPredicate - The `elementNodeOrPredicate` parameter in the `indexOf` method can be one
-     * of the following types:
-     * @returns The `indexOf` method returns the index of the first occurrence of the element that
-     * matches the provided predicate in the singly linked list. If no matching element is found, it
-     * returns -1.
-     */
-    indexOf(elementNodeOrPredicate) {
-        const predicate = this._ensurePredicate(elementNodeOrPredicate);
-        let index = 0;
-        let current = this.head;
-        while (current) {
-            if (predicate(current)) {
-                return index;
-            }
-            index++;
-            current = current.next;
-        }
-        return -1;
-    }
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -522,6 +522,8 @@ export class SinglyLinkedList extends IterableElementBase {
     getNode(elementNodeOrPredicate) {
         if (elementNodeOrPredicate === undefined)
             return;
+        if (this.isNode(elementNodeOrPredicate))
+            return elementNodeOrPredicate;
         const predicate = this._ensurePredicate(elementNodeOrPredicate);
         let current = this.head;
         while (current) {
@@ -549,31 +551,21 @@ export class SinglyLinkedList extends IterableElementBase {
      * unsuccessful.
      */
     addBefore(existingElementOrNode, newElementOrNode) {
-        if (!this.head)
+        const existingNode = this.getNode(existingElementOrNode);
+        if (!existingNode)
             return false;
-        let existingValue;
-        if (this.isNode(existingElementOrNode)) {
-            existingValue = existingElementOrNode.value;
+        const prevNode = this._getPrevNode(existingNode);
+        const newNode = this._ensureNode(newElementOrNode);
+        if (!prevNode) {
+            // Add at the head
+            this.unshift(newNode);
         }
         else {
-            existingValue = existingElementOrNode;
+            prevNode.next = newNode;
+            newNode.next = existingNode;
+            this._length++;
         }
-        if (this.head.value === existingValue) {
-            this.unshift(newElementOrNode);
-            return true;
-        }
-        let current = this.head;
-        while (current.next) {
-            if (current.next.value === existingValue) {
-                const newNode = this._ensureNode(newElementOrNode);
-                newNode.next = current.next;
-                current.next = newNode;
-                this._size++;
-                return true;
-            }
-            current = current.next;
-        }
-        return false;
+        return true;
     }
     /**
      * Time Complexity: O(n)
@@ -600,11 +592,74 @@ export class SinglyLinkedList extends IterableElementBase {
             if (existingNode === this.tail) {
                 this._tail = newNode;
             }
-            this._size++;
+            this._length++;
             return true;
         }
         return false;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The function `splice` in TypeScript overrides the default behavior to remove and insert elements
+     * in a singly linked list while handling boundary cases.
+     * @param {number} start - The `start` parameter in the `splice` method indicates the index at which
+     * to start modifying the list. It specifies the position where elements will be added or removed.
+     * @param {number} [deleteCount=0] - The `deleteCount` parameter in the `splice` method specifies the
+     * number of elements to remove from the array starting at the specified `start` index. If
+     * `deleteCount` is not provided, it defaults to 0, meaning no elements will be removed but new
+     * elements can still be inserted at
+     * @param {E[]} items - The `items` parameter in the `splice` method represents the elements to be
+     * inserted into the list at the specified `start` index. These elements will be inserted in place of
+     * the elements that are removed from the list. The `splice` method allows you to add new elements to
+     * the list while
+     * @returns The `splice` method is returning a `SinglyLinkedList` containing the elements that were
+     * removed from the original list during the splice operation.
+     */
+    splice(start, deleteCount = 0, ...items) {
+        const removedList = this._createInstance({ toElementFn: this._toElementFn, maxLen: this._maxLen });
+        // If `start` is out of range, perform boundary processing
+        start = Math.max(0, Math.min(start, this.length));
+        deleteCount = Math.max(0, deleteCount);
+        // Find the predecessor node of `start`
+        const prevNode = start === 0 ? undefined : this.getNodeAt(start - 1);
+        const startNode = prevNode ? prevNode.next : this.head;
+        let current = startNode;
+        for (let i = 0; i < deleteCount && current; i++) {
+            removedList.push(current.value);
+            current = current.next;
+        }
+        const nextNode = current;
+        let lastInsertedNode = undefined;
+        for (const item of items) {
+            const newNode = this._ensureNode(item);
+            if (!lastInsertedNode) {
+                if (prevNode) {
+                    prevNode.next = newNode;
+                }
+                else {
+                    this._head = newNode;
+                }
+            }
+            else {
+                lastInsertedNode.next = newNode;
+            }
+            lastInsertedNode = newNode;
+        }
+        // Connect new node to `nextNode`
+        if (lastInsertedNode) {
+            lastInsertedNode.next = nextNode;
+        }
+        else if (prevNode) {
+            prevNode.next = nextNode;
+        }
+        // Update tail node and length
+        if (!nextNode) {
+            this._tail = lastInsertedNode || prevNode;
+        }
+        this._length += items.length - removedList.length;
+        return removedList;
+    }
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -638,7 +693,7 @@ export class SinglyLinkedList extends IterableElementBase {
      * is a clone of the original list.
      */
     clone() {
-        return new SinglyLinkedList(this, { toElementFn: this.toElementFn });
+        return new SinglyLinkedList(this, { toElementFn: this.toElementFn, maxLen: this._maxLen });
     }
     /**
      * Time Complexity: O(n)
@@ -658,7 +713,7 @@ export class SinglyLinkedList extends IterableElementBase {
      * elements that pass the filter condition specified by the `callback` function.
      */
     filter(callback, thisArg) {
-        const filteredList = new SinglyLinkedList([], { toElementFn: this.toElementFn });
+        const filteredList = this._createInstance({ toElementFn: this.toElementFn, maxLen: this._maxLen });
         let index = 0;
         for (const current of this) {
             if (callback.call(thisArg, current, index, this)) {
@@ -689,7 +744,7 @@ export class SinglyLinkedList extends IterableElementBase {
      * @returns a new instance of the `SinglyLinkedList` class with the mapped elements.
      */
     map(callback, toElementFn, thisArg) {
-        const mappedList = new SinglyLinkedList([], { toElementFn });
+        const mappedList = new SinglyLinkedList([], { toElementFn, maxLen: this._maxLen });
         let index = 0;
         for (const current of this) {
             mappedList.push(callback.call(thisArg, current, index, this));
@@ -697,6 +752,19 @@ export class SinglyLinkedList extends IterableElementBase {
         }
         return mappedList;
     }
+    /**
+     * The function `_createInstance` returns a new instance of `SinglyLinkedList` with the specified
+     * options.
+     * @param [options] - The `options` parameter in the `_createInstance` method is of type
+     * `SinglyLinkedListOptions<E, R>`, which is used to configure the behavior of the `SinglyLinkedList`
+     * instance being created. It is an optional parameter, meaning it can be omitted when calling the
+     * method.
+     * @returns An instance of the `SinglyLinkedList` class with an empty array and the provided options
+     * is being returned.
+     */
+    _createInstance(options) {
+        return new SinglyLinkedList([], options);
+    }
     /**
      * The function `_getIterator` returns an iterable iterator that yields the values of a linked list.
      */
@@ -707,6 +775,33 @@ export class SinglyLinkedList extends IterableElementBase {
             current = current.next;
         }
     }
+    /**
+     * The function returns an iterator that iterates over the elements of a collection in reverse order.
+     */
+    *_getReverseIterator() {
+        const reversedArr = [...this].reverse();
+        for (const item of reversedArr) {
+            yield item;
+        }
+    }
+    /**
+     * The function `_getNodeIterator` returns an iterator that iterates over the nodes of a singly
+     * linked list.
+     */
+    *_getNodeIterator() {
+        let current = this.head;
+        while (current) {
+            yield current;
+            current = current.next;
+        }
+    }
+    // protected *_getReverseNodeIterator(): IterableIterator<SinglyLinkedListNode<E>> {
+    //   const reversedArr = [...this._getNodeIterator()].reverse();
+    //
+    //   for (const item of reversedArr) {
+    //     yield item;
+    //   }
+    // }
     /**
      * The _isPredicate function in TypeScript checks if the input is a function that takes a
      * SinglyLinkedListNode as an argument and returns a boolean.
@@ -749,5 +844,23 @@ export class SinglyLinkedList extends IterableElementBase {
             return elementNodeOrPredicate;
         return (node) => node.value === elementNodeOrPredicate;
     }
+    /**
+     * The function `_getPrevNode` returns the node before a given node in a singly linked list.
+     * @param node - The `node` parameter in the `_getPrevNode` method is a reference to a node in a
+     * singly linked list. The method is used to find the node that comes before the given node in the
+     * linked list.
+     * @returns The `_getPrevNode` method returns either the previous node of the input node in a singly
+     * linked list or `undefined` if the input node is the head of the list or if the input node is not
+     * found in the list.
+     */
+    _getPrevNode(node) {
+        if (!this.head || this.head === node)
+            return undefined;
+        let current = this.head;
+        while (current.next && current.next !== node) {
+            current = current.next;
+        }
+        return current.next === node ? current : undefined;
+    }
 }
 //# sourceMappingURL=singly-linked-list.js.map