doubly-linked-list-typed 1.54.3 → 2.0.1

package/dist/data-structures/linked-list/singly-linked-list.d.ts

@@ -6,75 +6,102 @@
  * @license MIT License
  */
 import type { ElementCallback, SinglyLinkedListOptions } from '../../types';
-import { IterableElementBase } from '../base';
-export declare class SinglyLinkedListNode<E = any> {
+import { LinearLinkedBase, LinkedListNode } from '../base/linear-base';
+export declare class SinglyLinkedListNode<E = any> extends LinkedListNode<E> {
     /**
      * 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: E);
-    protected _value: E;
-    /**
-     * The function returns the value of a protected variable.
-     * @returns The value of the variable `_value` is being returned.
-     */
-    get value(): E;
-    /**
-     * 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: E);
     protected _next: SinglyLinkedListNode<E> | undefined;
-    /**
-     * 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(): SinglyLinkedListNode<E> | undefined;
-    /**
-     * 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: SinglyLinkedListNode<E> | undefined);
 }
 /**
+ * 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 declare class SinglyLinkedList<E = any, R = any> extends IterableElementBase<E, R, SinglyLinkedList<E, R>> {
+export declare class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, SinglyLinkedListNode<E>> {
     constructor(elements?: Iterable<E> | Iterable<R> | Iterable<SinglyLinkedListNode<E>>, options?: SinglyLinkedListOptions<E, R>);
     protected _head: SinglyLinkedListNode<E> | undefined;
-    /**
-     * 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(): SinglyLinkedListNode<E> | undefined;
     protected _tail: SinglyLinkedListNode<E> | undefined;
-    /**
-     * 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(): SinglyLinkedListNode<E> | undefined;
-    /**
-     * 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(): E | undefined;
-    /**
-     * 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(): E | undefined;
-    protected _size: number;
-    /**
-     * The function returns the size of an object.
-     * @returns The size of the object, which is a number.
-     */
-    get size(): number;
+    protected _length: number;
+    get length(): number;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -210,7 +237,7 @@ export declare class SinglyLinkedList<E = any, R = any> extends IterableElementB
      * @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): boolean;
+    deleteAt(index: number): E | undefined;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -238,6 +265,21 @@ export declare class SinglyLinkedList<E = any, R = any> extends IterableElementB
      * successfully added at the specified index, and `false` if the index is out of bounds.
      */
     addAt(index: number, newElementOrNode: E | SinglyLinkedListNode<E>): boolean;
+    /**
+     * 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: number, value: E): boolean;
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -254,14 +296,6 @@ export declare class SinglyLinkedList<E = any, R = any> extends IterableElementB
      * The `clear` function resets the linked list by setting the head, tail, and length to undefined and 0 respectively.
      */
     clear(): void;
-    /**
-     * 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(): E[];
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -270,20 +304,6 @@ export declare class SinglyLinkedList<E = any, R = any> extends IterableElementB
      * @returns The reverse() method does not return anything. It has a return type of void.
      */
     reverse(): 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: E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<E>) => boolean)): number;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -332,6 +352,26 @@ export declare class SinglyLinkedList<E = any, R = any> extends IterableElementB
      * was not found.
      */
     addAfter(existingElementOrNode: E | SinglyLinkedListNode<E>, newElementOrNode: E | SinglyLinkedListNode<E>): boolean;
+    /**
+     * 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: number, deleteCount?: number, ...items: E[]): this;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
@@ -353,7 +393,7 @@ export declare class SinglyLinkedList<E = any, R = any> extends IterableElementB
      * @returns The `clone()` method is returning a new instance of the `SinglyLinkedList` class, which
      * is a clone of the original list.
      */
-    clone(): SinglyLinkedList<E, R>;
+    clone(): this;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -371,7 +411,7 @@ export declare class SinglyLinkedList<E = any, R = any> extends IterableElementB
      * @returns The `filter` method is returning a new `SinglyLinkedList` object that contains the
      * elements that pass the filter condition specified by the `callback` function.
      */
-    filter(callback: ElementCallback<E, R, boolean, SinglyLinkedList<E, R>>, thisArg?: any): SinglyLinkedList<E, R>;
+    filter(callback: ElementCallback<E, R, boolean>, thisArg?: any): SinglyLinkedList<E, R>;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -392,11 +432,31 @@ export declare class SinglyLinkedList<E = any, R = any> extends IterableElementB
      * value of
      * @returns a new instance of the `SinglyLinkedList` class with the mapped elements.
      */
-    map<EM, RM>(callback: ElementCallback<E, R, EM, SinglyLinkedList<E, R>>, toElementFn?: (rawElement: RM) => EM, thisArg?: any): SinglyLinkedList<EM, RM>;
+    map<EM, RM>(callback: ElementCallback<E, R, EM>, toElementFn?: (rawElement: RM) => EM, thisArg?: any): SinglyLinkedList<EM, RM>;
+    /**
+     * 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.
+     */
+    protected _createInstance(options?: SinglyLinkedListOptions<E, R>): this;
     /**
      * The function `_getIterator` returns an iterable iterator that yields the values of a linked list.
      */
     protected _getIterator(): IterableIterator<E>;
+    /**
+     * The function returns an iterator that iterates over the elements of a collection in reverse order.
+     */
+    protected _getReverseIterator(): IterableIterator<E>;
+    /**
+     * The function `_getNodeIterator` returns an iterator that iterates over the nodes of a singly
+     * linked list.
+     */
+    protected _getNodeIterator(): IterableIterator<SinglyLinkedListNode<E>>;
     /**
      * The _isPredicate function in TypeScript checks if the input is a function that takes a
      * SinglyLinkedListNode as an argument and returns a boolean.
@@ -427,4 +487,14 @@ export declare class SinglyLinkedList<E = any, R = any> extends IterableElementB
      * a function is returned that checks if a given node's value is equal to the input
      */
     protected _ensurePredicate(elementNodeOrPredicate: E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<E>) => boolean)): (node: SinglyLinkedListNode<E>) => boolean;
+    /**
+     * 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.
+     */
+    protected _getPrevNode(node: SinglyLinkedListNode<E>): SinglyLinkedListNode<E> | undefined;
 }