red-black-tree-typed 1.53.6 → 1.54.1

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

@@ -59,18 +59,16 @@ export class SinglyLinkedListNode<E = any> {
   }
 }
 
+/**
+ *
+ */
 export class SinglyLinkedList<E = any, R = any> extends IterableElementBase<E, R, SinglyLinkedList<E, R>> {
-  constructor(elements: Iterable<E> | Iterable<R> = [], options?: SinglyLinkedListOptions<E, R>) {
+  constructor(
+    elements: Iterable<E> | Iterable<R> | Iterable<SinglyLinkedListNode<E>> = [],
+    options?: SinglyLinkedListOptions<E, R>
+  ) {
     super(options);
-    if (elements) {
-      for (const el of elements) {
-        if (this.toElementFn) {
-          this.push(this.toElementFn(el as R));
-        } else {
-          this.push(el as E);
-        }
-      }
-    }
+    this.pushMany(elements);
   }
 
   protected _head: SinglyLinkedListNode<E> | undefined;
@@ -121,6 +119,23 @@ export class SinglyLinkedList<E = any, R = any> extends IterableElementBase<E, R
     return this._size;
   }
 
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `fromArray` function creates a new SinglyLinkedList instance and populates it with the elements from the given
+   * array.
+   * @param {E[]} data - The `data` parameter is an array of elements of type `E`.
+   * @returns The `fromArray` function returns a `SinglyLinkedList` object.
+   */
+  static fromArray<E>(data: E[]) {
+    const singlyLinkedList = new SinglyLinkedList<E>();
+    for (const item of data) {
+      singlyLinkedList.push(item);
+    }
+    return singlyLinkedList;
+  }
+
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -211,6 +226,55 @@ export class SinglyLinkedList<E = any, R = any> extends IterableElementBase<E, R
     return true;
   }
 
+  /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
+   * The function `pushMany` iterates over elements and pushes them into a data structure, applying a
+   * transformation function if provided.
+   * @param {Iterable<E> | Iterable<R> | Iterable<SinglyLinkedListNode<E>>} elements - The `elements`
+   * parameter in the `pushMany` function can accept an iterable containing elements of type `E`, `R`,
+   * or `SinglyLinkedListNode<E>`.
+   * @returns The `pushMany` function returns an array of boolean values indicating whether each
+   * element was successfully pushed into the data structure.
+   */
+  pushMany(elements: Iterable<E> | Iterable<R> | Iterable<SinglyLinkedListNode<E>>) {
+    const ans: boolean[] = [];
+    for (const el of elements) {
+      if (this.toElementFn) {
+        ans.push(this.push(this.toElementFn(el as R)));
+        continue;
+      }
+      ans.push(this.push(el as E | SinglyLinkedListNode<E>));
+    }
+    return ans;
+  }
+
+  /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
+   * The function `unshiftMany` iterates over elements and adds them to a data structure, optionally
+   * converting them using a provided function.
+   * @param {Iterable<E> | Iterable<R> | Iterable<SinglyLinkedListNode<E>>} elements - The `elements`
+   * parameter in the `unshiftMany` function can accept an iterable containing elements of type `E`,
+   * `R`, or `SinglyLinkedListNode<E>`. The function iterates over each element in the iterable and
+   * performs an `unshift` operation on the linked list for each
+   * @returns The `unshiftMany` function is returning an array of boolean values, where each value
+   * represents the result of calling the `unshift` method on the current instance of the class.
+   */
+  unshiftMany(elements: Iterable<E> | Iterable<R> | Iterable<SinglyLinkedListNode<E>>) {
+    const ans: boolean[] = [];
+    for (const el of elements) {
+      if (this.toElementFn) {
+        ans.push(this.unshift(this.toElementFn(el as R)));
+        continue;
+      }
+      ans.push(this.unshift(el as E | SinglyLinkedListNode<E>));
+    }
+    return ans;
+  }
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -223,7 +287,7 @@ export class SinglyLinkedList<E = any, R = any> extends IterableElementBase<E, R
    * @returns The `get` method returns the value of the first node in the singly linked list that
    * satisfies the provided predicate function. If no such node is found, it returns `undefined`.
    */
-  get(
+  search(
     elementNodeOrPredicate: E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<E>) => boolean)
   ): E | undefined {
     const predicate = this._ensurePredicate(elementNodeOrPredicate);
@@ -399,6 +463,9 @@ export class SinglyLinkedList<E = any, R = any> extends IterableElementBase<E, R
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if the length of a data structure is equal to zero and returns a boolean value indicating
    * whether it is empty or not.
    * @returns A boolean value indicating whether the length of the object is equal to 0.
@@ -408,6 +475,9 @@ export class SinglyLinkedList<E = any, R = any> extends IterableElementBase<E, R
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The `clear` function resets the linked list by setting the head, tail, and length to undefined and 0 respectively.
    */
   clear(): void {
@@ -713,23 +783,6 @@ export class SinglyLinkedList<E = any, R = any> extends IterableElementBase<E, R
     }
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   *
-   * The `fromArray` function creates a new SinglyLinkedList instance and populates it with the elements from the given
-   * array.
-   * @param {E[]} data - The `data` parameter is an array of elements of type `E`.
-   * @returns The `fromArray` function returns a `SinglyLinkedList` object.
-   */
-  static fromArray<E>(data: E[]) {
-    const singlyLinkedList = new SinglyLinkedList<E>();
-    for (const item of data) {
-      singlyLinkedList.push(item);
-    }
-    return singlyLinkedList;
-  }
-
   /**
    * The _isPredicate function in TypeScript checks if the input is a function that takes a
    * SinglyLinkedListNode as an argument and returns a boolean.

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

@@ -19,6 +19,9 @@ export class SkipListNode<K, V> {
   }
 }
 
+/**
+ *
+ */
 export class SkipList<K, V> {
   /**
    * The constructor function initializes a SkipLinkedList object with optional options and elements.

package/src/data-structures/matrix/matrix.ts

@@ -7,6 +7,9 @@
  */
 import type { MatrixOptions } from '../../types';
 
+/**
+ *
+ */
 export class Matrix {
   /**
    * The constructor function initializes a matrix object with the provided data and options, or with

package/src/data-structures/matrix/navigator.ts

@@ -25,6 +25,9 @@ export class Character {
   }
 }
 
+/**
+ *
+ */
 export class Navigator<T = number> {
   onMove: (cur: [number, number]) => void;
   protected readonly _matrix: T[][];

package/src/data-structures/priority-queue/max-priority-queue.ts

@@ -8,6 +8,9 @@
 import type { Comparator, ElementCallback, PriorityQueueOptions } from '../../types';
 import { PriorityQueue } from './priority-queue';
 
+/**
+ *
+ */
 export class MaxPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
   /**
    * The constructor initializes a PriorityQueue with optional elements and options, including a

package/src/data-structures/priority-queue/min-priority-queue.ts

@@ -8,6 +8,9 @@
 import type { Comparator, ElementCallback, PriorityQueueOptions } from '../../types';
 import { PriorityQueue } from './priority-queue';
 
+/**
+ *
+ */
 export class MinPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
   /**
    * The constructor initializes a PriorityQueue with optional elements and options, including a

package/src/data-structures/queue/deque.ts

@@ -53,14 +53,7 @@ export class Deque<E = any, R = any> extends IterableElementBase<E, R, Deque<E,
     const needBucketNum = calcMinUnitsRequired(_size, this._bucketSize);
     this._bucketFirst = this._bucketLast = (this._bucketCount >> 1) - (needBucketNum >> 1);
     this._firstInBucket = this._lastInBucket = (this._bucketSize - (_size % this._bucketSize)) >> 1;
-
-    for (const el of elements) {
-      if (this.toElementFn) {
-        this.push(this.toElementFn(el as R));
-      } else {
-        this.push(el as E);
-      }
-    }
+    this.pushMany(elements);
   }
 
   protected _bucketSize: number = 1 << 12;
@@ -230,6 +223,33 @@ export class Deque<E = any, R = any> extends IterableElementBase<E, R, Deque<E,
     return element;
   }
 
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `shift()` function removes and returns the first element from a data structure, updating the
+   * internal state variables accordingly.
+   * @returns The element that is being removed from the beginning of the data structure is being
+   * returned.
+   */
+  shift(): E | undefined {
+    if (this._size === 0) return;
+    const element = this._buckets[this._bucketFirst][this._firstInBucket];
+    if (this._size !== 1) {
+      if (this._firstInBucket < this._bucketSize - 1) {
+        this._firstInBucket += 1;
+      } else if (this._bucketFirst < this._bucketCount - 1) {
+        this._bucketFirst += 1;
+        this._firstInBucket = 0;
+      } else {
+        this._bucketFirst = 0;
+        this._firstInBucket = 0;
+      }
+    }
+    this._size -= 1;
+    return element;
+  }
+
   /**
    * Time Complexity: Amortized O(1)
    * Space Complexity: O(n)
@@ -260,30 +280,54 @@ export class Deque<E = any, R = any> extends IterableElementBase<E, R, Deque<E,
   }
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(1)
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
    *
-   * The `shift()` function removes and returns the first element from a data structure, updating the
-   * internal state variables accordingly.
-   * @returns The element that is being removed from the beginning of the data structure is being
-   * returned.
-   */
-  shift(): E | undefined {
-    if (this._size === 0) return;
-    const element = this._buckets[this._bucketFirst][this._firstInBucket];
-    if (this._size !== 1) {
-      if (this._firstInBucket < this._bucketSize - 1) {
-        this._firstInBucket += 1;
-      } else if (this._bucketFirst < this._bucketCount - 1) {
-        this._bucketFirst += 1;
-        this._firstInBucket = 0;
+   * The function `pushMany` iterates over elements and pushes them into an array after applying a
+   * transformation function if provided.
+   * @param {IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R>} elements - The `elements`
+   * parameter in the `pushMany` function is expected to be an iterable containing elements of type `E`
+   * or `R`. It can be either an `IterableWithSizeOrLength<E>` or an `IterableWithSizeOrLength<R>`. The
+   * function iterates over each element
+   * @returns The `pushMany` function is returning an array of boolean values, where each value
+   * represents the result of calling the `push` method on the current object instance with the
+   * corresponding element from the input `elements` iterable.
+   */
+  pushMany(elements: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R>) {
+    const ans: boolean[] = [];
+    for (const el of elements) {
+      if (this.toElementFn) {
+        ans.push(this.push(this.toElementFn(el as R)));
       } else {
-        this._bucketFirst = 0;
-        this._firstInBucket = 0;
+        ans.push(this.push(el as E));
       }
     }
-    this._size -= 1;
-    return element;
+    return ans;
+  }
+
+  /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
+   * The `unshiftMany` function in TypeScript iterates over elements and adds them to the beginning of
+   * an array, optionally converting them using a provided function.
+   * @param {IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R>} elements - The `elements`
+   * parameter in the `unshiftMany` function is an iterable containing elements of type `E` or `R`. It
+   * can be an array or any other iterable data structure that has a known size or length. The function
+   * iterates over each element in the `elements` iterable and
+   * @returns The `unshiftMany` function returns an array of boolean values indicating whether each
+   * element was successfully added to the beginning of the array.
+   */
+  unshiftMany(elements: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R> = []) {
+    const ans: boolean[] = [];
+    for (const el of elements) {
+      if (this.toElementFn) {
+        ans.push(this.unshift(this.toElementFn(el as R)));
+      } else {
+        ans.push(this.unshift(el as E));
+      }
+    }
+    return ans;
   }
 
   /**

package/src/data-structures/queue/queue.ts

@@ -25,12 +25,7 @@ export class Queue<E = any, R = any> extends IterableElementBase<E, R, Queue<E,
       this._autoCompactRatio = autoCompactRatio;
     }
 
-    if (elements) {
-      for (const el of elements) {
-        if (this.toElementFn) this.push(this.toElementFn(el as R));
-        else this.push(el as E);
-      }
-    }
+    this.pushMany(elements);
   }
 
   protected _elements: E[] = [];
@@ -131,6 +126,26 @@ export class Queue<E = any, R = any> extends IterableElementBase<E, R, Queue<E,
     return true;
   }
 
+  /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
+   * The `pushMany` function iterates over elements and pushes them into an array after applying a
+   * transformation function if provided.
+   * @param {Iterable<E> | Iterable<R>} elements - The `elements` parameter in the `pushMany` function
+   * is an iterable containing elements of type `E` or `R`.
+   * @returns The `pushMany` function is returning an array of boolean values indicating whether each
+   * element was successfully pushed into the data structure.
+   */
+  pushMany(elements: Iterable<E> | Iterable<R>) {
+    const ans: boolean[] = [];
+    for (const el of elements) {
+      if (this.toElementFn) ans.push(this.push(this.toElementFn(el as R)));
+      else ans.push(this.push(el as E));
+    }
+    return ans;
+  }
+
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -150,6 +165,9 @@ export class Queue<E = any, R = any> extends IterableElementBase<E, R, Queue<E,
   }
 
   /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
    * The delete function removes an element from the list.
    * @param {E} element - Specify the element to be deleted
    * @return A boolean value indicating whether the element was successfully deleted or not
@@ -160,6 +178,9 @@ export class Queue<E = any, R = any> extends IterableElementBase<E, R, Queue<E,
   }
 
   /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
    * The deleteAt function deletes the element at a given index.
    * @param {number} index - Determine the index of the element to be deleted
    * @return A boolean value
@@ -173,7 +194,12 @@ export class Queue<E = any, R = any> extends IterableElementBase<E, R, Queue<E,
    * Time Complexity: O(1)
    * Space Complexity: O(1)
    *
-   * @param index
+   * The `at` function returns the element at a specified index adjusted by an offset, or `undefined`
+   * if the index is out of bounds.
+   * @param {number} index - The `index` parameter represents the position of the element you want to
+   * retrieve from the data structure.
+   * @returns The `at` method is returning the element at the specified index adjusted by the offset
+   * `_offset`.
    */
   at(index: number): E | undefined {
     return this.elements[index + this._offset];
@@ -213,6 +239,9 @@ export class Queue<E = any, R = any> extends IterableElementBase<E, R, Queue<E,
   }
 
   /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
    * The `compact` function in TypeScript slices the elements array based on the offset and resets the
    * offset to zero.
    * @returns The `compact()` method is returning a boolean value of `true`.
@@ -265,6 +294,20 @@ export class Queue<E = any, R = any> extends IterableElementBase<E, R, Queue<E,
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
+   *
+   * The `map` function in TypeScript creates a new Queue by applying a callback function to each
+   * element in the original Queue.
+   * @param callback - The `callback` parameter is a function that will be applied to each element in
+   * the queue. It takes the current element, its index, and the queue itself as arguments, and returns
+   * a new element.
+   * @param [toElementFn] - The `toElementFn` parameter is an optional function that can be provided to
+   * convert a raw element of type `RM` to a new element of type `EM`. This function is used within the
+   * `map` method to transform each raw element before passing it to the `callback` function. If
+   * @param {any} [thisArg] - The `thisArg` parameter in the `map` function is used to specify the
+   * value of `this` when executing the `callback` function. It allows you to set the context (the
+   * value of `this`) within the callback function. If `thisArg` is provided, it will be
+   * @returns A new Queue object containing elements of type EM, which are the result of applying the
+   * callback function to each element in the original Queue object.
    */
   map<EM, RM>(
     callback: ElementCallback<E, R, EM, Queue<E, R>>,

package/src/data-structures/stack/stack.ts

@@ -19,15 +19,7 @@ import { IterableElementBase } from '../base';
 export class Stack<E = any, R = any> extends IterableElementBase<E, R, Stack<E, R>> {
   constructor(elements: Iterable<E> | Iterable<R> = [], options?: StackOptions<E, R>) {
     super(options);
-    if (elements) {
-      for (const el of elements) {
-        if (this.toElementFn) {
-          this.push(this.toElementFn(el as R));
-        } else {
-          this.push(el as E);
-        }
-      }
-    }
+    this.pushMany(elements);
   }
 
   protected _elements: E[] = [];
@@ -48,11 +40,6 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R, Stack<E,
     return this.elements.length;
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -67,6 +54,9 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R, Stack<E,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if an array is empty and returns a boolean value.
    * @returns A boolean value indicating whether the `_elements` array is empty or not.
    */
@@ -115,9 +105,36 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R, Stack<E,
   }
 
   /**
-   * The delete function removes an element from the stack.
-   * @param element: E Specify the element to be deleted
-   * @return A boolean value indicating whether the element was successfully deleted or not
+   * Time Complexity: O(k)
+   * Space Complexity: O(1)
+   *
+   * The function `pushMany` iterates over elements and pushes them into an array after applying a
+   * transformation function if provided.
+   * @param {Iterable<E> | Iterable<R>} elements - The `elements` parameter in the `pushMany` function
+   * is an iterable containing elements of type `E` or `R`. The function iterates over each element in
+   * the iterable and pushes it into the data structure. If a transformation function `toElementFn` is
+   * provided, it is used to
+   * @returns The `pushMany` function is returning an array of boolean values indicating whether each
+   * element was successfully pushed into the data structure.
+   */
+  pushMany(elements: Iterable<E> | Iterable<R>) {
+    const ans: boolean[] = [];
+    for (const el of elements) {
+      if (this.toElementFn) {
+        ans.push(this.push(this.toElementFn(el as R)));
+      } else {
+        ans.push(this.push(el as E));
+      }
+    }
+    return ans;
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The toArray function returns a copy of the elements in an array.
+   * @returns An array of type E.
    */
   delete(element: E): boolean {
     const index = this.elements.indexOf(element);
@@ -125,9 +142,11 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R, Stack<E,
   }
 
   /**
-   * The deleteAt function deletes the element at a given index.
-   * @param index: number Determine the index of the element to be deleted
-   * @return A boolean value
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The toArray function returns a copy of the elements in an array.
+   * @returns An array of type E.
    */
   deleteAt(index: number): boolean {
     const spliced = this.elements.splice(index, 1);