data-structure-typed 2.4.4 → 2.5.0

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

@@ -63,71 +63,6 @@ export class SinglyLinkedListNode<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 SinglyLinkedList creation and push operation
- *  // Create a simple SinglyLinkedList with initial values
- *     const list = new SinglyLinkedList([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
- * // SinglyLinkedList pop and shift operations
- *  const list = new SinglyLinkedList<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
- * // SinglyLinkedList unshift and forward traversal
- *  const list = new SinglyLinkedList<number>([20, 30, 40]);
- *
- *     // Unshift adds to the beginning
- *     list.unshift(10);
- *     console.log([...list]); // [10, 20, 30, 40];
- *
- *     // Access elements (forward traversal only for singly linked)
- *     const second = list.at(1);
- *     console.log(second); // 20;
- *
- *     // SinglyLinkedList allows forward iteration only
- *     const elements: number[] = [];
- *     for (const item of list) {
- *       elements.push(item);
- *     }
- *     console.log(elements); // [10, 20, 30, 40];
- *
- *     console.log(list.length); // 4;
- * @example
- * // SinglyLinkedList filter and map operations
- *  const list = new SinglyLinkedList<number>([1, 2, 3, 4, 5]);
- *
- *     // Filter even numbers
- *     const filtered = list.filter(value => value % 2 === 0);
- *     console.log(filtered.length); // 2;
- *
- *     // Map to double values
- *     const doubled = list.map(value => value * 2);
- *     console.log(doubled.length); // 5;
- *
- *     // Use reduce to sum
- *     const sum = list.reduce((acc, value) => acc + value, 0);
- *     console.log(sum); // 15;
- * @example
  * // SinglyLinkedList for sequentially processed data stream
  *  interface LogEntry {
  *       timestamp: number;
@@ -244,6 +179,17 @@ export class SinglyLinkedListNode<E = any> extends LinkedListNode<E> {
  *     editor.moveCursor(1);
  *     editor.insert('a');
  *     console.log(editor.getText()); // 'Haello';
+ * @example
+ * // Find first matching element
+ *  const list = new SinglyLinkedList<number>([1, 2, 3, 4, 5]);
+ *     console.log(list.find(n => n > 3)); // 4;
+ *     console.log(list.find(n => n > 10)); // undefined;
+ * @example
+ * // Iterate over elements
+ *  const list = new SinglyLinkedList<number>([10, 20, 30]);
+ *     const result: number[] = [];
+ *     list.forEach(n => result.push(n));
+ *     console.log(result); // [10, 20, 30];
  */
 export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, SinglyLinkedListNode<E>> {
   protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);
@@ -350,6 +296,33 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * @remarks Time O(1), Space O(1)
    * @param elementOrNode - Element or node to append.
    * @returns True when appended.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // basic SinglyLinkedList creation and push operation
+ *  // Create a simple SinglyLinkedList with initial values
+ *     const list = new SinglyLinkedList([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 | SinglyLinkedListNode<E>): boolean {
@@ -369,6 +342,33 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * Remove and return the tail element.
    * @remarks Time O(N), Space O(1)
    * @returns Removed element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // SinglyLinkedList pop and shift operations
+ *  const list = new SinglyLinkedList<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 {
@@ -393,6 +393,23 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * 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 SinglyLinkedList<number>([10, 20, 30]);
+ *     console.log(list.shift()); // 10;
+ *     console.log(list.length); // 2;
    */
 
   shift(): E | undefined {
@@ -409,6 +426,38 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * @remarks Time O(1), Space O(1)
    * @param elementOrNode - Element or node to prepend.
    * @returns True when prepended.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // SinglyLinkedList unshift and forward traversal
+ *  const list = new SinglyLinkedList<number>([20, 30, 40]);
+ *
+ *     // Unshift adds to the beginning
+ *     list.unshift(10);
+ *     console.log([...list]); // [10, 20, 30, 40];
+ *
+ *     // Access elements (forward traversal only for singly linked)
+ *     const second = list.at(1);
+ *     console.log(second); // 20;
+ *
+ *     // SinglyLinkedList allows forward iteration only
+ *     const elements: number[] = [];
+ *     for (const item of list) {
+ *       elements.push(item);
+ *     }
+ *     console.log(elements); // [10, 20, 30, 40];
+ *
+ *     console.log(list.length); // 4;
    */
 
   unshift(elementOrNode: E | SinglyLinkedListNode<E>): boolean {
@@ -479,6 +528,24 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * @remarks Time O(N), Space O(1)
    * @param index - Zero-based index.
    * @returns Element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Access element by index
+ *  const list = new SinglyLinkedList<string>(['a', 'b', 'c', 'd']);
+ *     console.log(list.at(0)); // 'a';
+ *     console.log(list.at(2)); // 'c';
+ *     console.log(list.at(3)); // 'd';
    */
 
   at(index: number): E | undefined {
@@ -506,6 +573,19 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * @remarks Time O(N), Space O(1)
    * @param index - Zero-based index.
    * @returns Node or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get node at index
+ *  const list = new SinglyLinkedList<string>(['a', 'b', 'c']);
+ *     console.log(list.getNodeAt(1)?.value); // 'b';
    */
 
   getNodeAt(index: number): SinglyLinkedListNode<E> | undefined {
@@ -520,6 +600,20 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * @remarks Time O(N), Space O(1)
    * @param index - Zero-based index.
    * @returns Removed element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove by index
+ *  const list = new SinglyLinkedList<string>(['a', 'b', 'c']);
+ *     list.deleteAt(1);
+ *     console.log(list.toArray()); // ['a', 'c'];
    */
 
   deleteAt(index: number): E | undefined {
@@ -539,6 +633,20 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * @remarks Time O(N), Space O(1)
    * @param [elementOrNode] - Element or node to remove; if omitted/undefined, nothing happens.
    * @returns True if removed.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove first occurrence
+ *  const list = new SinglyLinkedList<number>([1, 2, 3, 2]);
+ *     list.delete(2);
+ *     console.log(list.toArray()); // [1, 3, 2];
    */
 
   delete(elementOrNode: E | SinglyLinkedListNode<E> | undefined): boolean {
@@ -564,6 +672,20 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * @param index - Zero-based index.
    * @param newElementOrNode - Element or node to insert.
    * @returns True if inserted.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Insert at index
+ *  const list = new SinglyLinkedList<number>([1, 3]);
+ *     list.addAt(1, 2);
+ *     console.log(list.toArray()); // [1, 2, 3];
    */
 
   addAt(index: number, newElementOrNode: E | SinglyLinkedListNode<E>): boolean {
@@ -597,6 +719,19 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * 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 SinglyLinkedList().isEmpty()); // true;
    */
 
   isEmpty(): boolean {
@@ -607,6 +742,21 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * Remove all nodes and reset length.
    * @remarks Time O(N), Space O(1)
    * @returns void
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all
+ *  const list = new SinglyLinkedList<number>([1, 2, 3]);
+ *     list.clear();
+ *     console.log(list.isEmpty()); // true;
    */
 
   clear(): void {
@@ -619,6 +769,23 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * Reverse the list in place.
    * @remarks Time O(N), Space O(1)
    * @returns This list.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Reverse the list in-place
+ *  const list = new SinglyLinkedList<number>([1, 2, 3, 4]);
+ *     list.reverse();
+ *     console.log([...list]); // [4, 3, 2, 1];
    */
 
   reverse(): this {
@@ -827,6 +994,23 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * 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 SinglyLinkedList<number>([1, 2, 3]);
+ *     const copy = list.clone();
+ *     copy.pop();
+ *     console.log(list.length); // 3;
+ *     console.log(copy.length); // 2;
    */
 
   clone(): this {
@@ -841,6 +1025,33 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * @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
+ * // SinglyLinkedList filter and map operations
+ *  const list = new SinglyLinkedList<number>([1, 2, 3, 4, 5]);
+ *
+ *     // Filter even numbers
+ *     const filtered = list.filter(value => value % 2 === 0);
+ *     console.log(filtered.length); // 2;
+ *
+ *     // Map to double values
+ *     const doubled = list.map(value => value * 2);
+ *     console.log(doubled.length); // 5;
+ *
+ *     // Use reduce to sum
+ *     const sum = list.reduce((acc, value) => acc + value, 0);
+ *     console.log(sum); // 15;
    */
 
   filter(callback: ElementCallback<E, R, boolean>, thisArg?: any): this {
@@ -877,6 +1088,23 @@ export class SinglyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, S
    * @param [options] - Options for the output list (e.g., maxLen, toElementFn).
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new SinglyLinkedList with mapped values.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform elements
+ *  const list = new SinglyLinkedList<number>([1, 2, 3]);
+ *     const doubled = list.map(n => n * 2);
+ *     console.log([...doubled]); // [2, 4, 6];
    */
 
   map<EM, RM = any>(