From 5077c0d291513cb7ed62b4b007c08bde7c238822 Mon Sep 17 00:00:00 2001
From: Revone <zrwusa@gmail.com>
Date: Sat, 23 Nov 2024 21:57:13 +1300
Subject: [PATCH] docs: Improve the documentation for pushMany, addMany, and
 similar methods.

---
 src/data-structures/hash/hash-map.ts          | 30 ++++++++++++++
 src/data-structures/heap/heap.ts              | 20 ++++++++-
 .../linked-list/doubly-linked-list.ts         | 33 +++++++++++++++
 .../linked-list/singly-linked-list.ts         | 31 ++++++++++++++
 src/data-structures/queue/deque.ts            | 27 ++++++++++++
 src/data-structures/queue/queue.ts            | 41 ++++++++++++++++++-
 src/data-structures/stack/stack.ts            |  9 +++-
 src/data-structures/trie/trie.ts              |  9 +++-
 8 files changed, 195 insertions(+), 5 deletions(-)

diff --git a/src/data-structures/hash/hash-map.ts b/src/data-structures/hash/hash-map.ts
index 580deee..5d5858b 100644
--- a/src/data-structures/hash/hash-map.ts
+++ b/src/data-structures/hash/hash-map.ts
@@ -97,6 +97,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if a given element is an array with exactly two elements.
    * @param {any} rawElement - The `rawElement` parameter is of type `any`, which means it can be any
    * data type.
@@ -107,6 +110,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if the size of an object is equal to zero and returns a boolean value.
    * @returns A boolean value indicating whether the size of the object is 0 or not.
    */
@@ -115,6 +121,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The clear() function resets the state of an object by clearing its internal store, object map, and
    * size.
    */
@@ -125,6 +134,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The `set` function adds a key-value pair to a map-like data structure, incrementing the size if
    * the key is not already present.
    * @param {K} key - The key parameter is the key used to identify the value in the data structure. It
@@ -150,6 +162,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
    * The function `setMany` takes an iterable collection of objects, maps each object to a key-value
    * pair using a mapping function, and sets each key-value pair in the current object.
    * @param entryOrRawElements - The `entryOrRawElements` parameter is an iterable collection of elements of a type
@@ -175,6 +190,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The `get` function retrieves a value from a map based on a given key, either from an object map or
    * a string map.
    * @param {K} key - The `key` parameter is the key used to retrieve a value from the map. It can be
@@ -192,6 +210,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The `has` function checks if a given key exists in the `_objMap` or `_store` based on whether it
    * is an object key or not.
    * @param {K} key - The parameter "key" is of type K, which means it can be any type.
@@ -207,6 +228,9 @@ export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K,
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The `delete` function removes an element from a map-like data structure based on the provided key.
    * @param {K} key - The `key` parameter is the key of the element that you want to delete from the
    * data structure.
@@ -579,6 +603,9 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
   }
 
   /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
    * The function `setMany` takes an iterable collection, converts each element into a key-value pair
    * using a provided function, and sets each key-value pair in the current object, returning an array
    * of booleans indicating the success of each set operation.
@@ -605,6 +632,9 @@ export class LinkedHashMap<K = any, V = any, R = [K, V]> extends IterableEntryBa
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The function checks if a given key exists in a map, using different logic depending on whether the
    * key is a weak key or not.
    * @param {K} key - The `key` parameter is the key that is being checked for existence in the map.
diff --git a/src/data-structures/heap/heap.ts b/src/data-structures/heap/heap.ts
index e11d95f..c52f88f 100644
--- a/src/data-structures/heap/heap.ts
+++ b/src/data-structures/heap/heap.ts
@@ -249,12 +249,30 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R, Heap<E, R>
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
+   * The add function pushes an element into an array and then triggers a bubble-up operation.
+   * @param {E} element - The `element` parameter represents the element that you want to add to the
+   * data structure.
+   * @returns The `add` method is returning a boolean value, which is the result of calling the
+   * `_bubbleUp` method with the index `this.elements.length - 1` as an argument.
    */
   add(element: E): boolean {
     this._elements.push(element as E);
     return this._bubbleUp(this.elements.length - 1);
   }
 
+  /**
+   * Time Complexity: O(k log n)
+   * Space Complexity: O(1)
+   *
+   * The `addMany` function iterates over elements and adds them to a collection, returning an array of
+   * boolean values indicating success or failure.
+   * @param {Iterable<E> | Iterable<R>} elements - The `elements` parameter in the `addMany` method is
+   * an iterable containing elements of type `E` or `R`. The method iterates over each element in the
+   * iterable and adds them to the data structure. If a transformation function `_toElementFn` is
+   * provided, it transforms the element
+   * @returns The `addMany` method returns an array of boolean values indicating whether each element
+   * in the input iterable was successfully added to the data structure.
+   */
   addMany(elements: Iterable<E> | Iterable<R>): boolean[] {
     const ans: boolean[] = [];
     for (const el of elements) {
@@ -478,7 +496,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R, Heap<E, R>
   }
 
   /**
-   * Time Complexity: O(n log n)
+   * Time Complexity: O(n)
    * Space Complexity: O(n)
    *
    * The `map` function creates a new heap by applying a callback function to each element of the
diff --git a/src/data-structures/linked-list/doubly-linked-list.ts b/src/data-structures/linked-list/doubly-linked-list.ts
index 0110125..2dc15e2 100644
--- a/src/data-structures/linked-list/doubly-linked-list.ts
+++ b/src/data-structures/linked-list/doubly-linked-list.ts
@@ -697,6 +697,19 @@ export class DoublyLinkedList<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<DoublyLinkedListNode<E>>} elements - The `elements`
+   * parameter in the `pushMany` function can accept an iterable containing elements of type `E`, `R`,
+   * or `DoublyLinkedListNode<E>`. The function iterates over each element in the iterable and pushes
+   * it onto the linked list. If a transformation function `to
+   * @returns The `pushMany` function is returning an array of boolean values (`ans`) which indicate
+   * the success or failure of pushing each element into the data structure.
+   */
   pushMany(elements: Iterable<E> | Iterable<R> | Iterable<DoublyLinkedListNode<E>>) {
     const ans: boolean[] = [];
     for (const el of elements) {
@@ -709,6 +722,20 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
     return ans;
   }
 
+  /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
+   * The function `unshiftMany` iterates through a collection of elements and adds them to the
+   * beginning of a Doubly Linked List, returning an array of boolean values indicating the success of
+   * each insertion.
+   * @param {Iterable<E> | Iterable<R> | Iterable<DoublyLinkedListNode<E>>} elements - The `elements`
+   * parameter in the `unshiftMany` function can accept an iterable containing elements of type `E`,
+   * `R`, or `DoublyLinkedListNode<E>`. The function iterates over each element in the iterable and
+   * performs an `unshift` operation on the doubly linked list
+   * @returns The `unshiftMany` function returns an array of boolean values indicating the success of
+   * each unshift operation performed on the elements passed as input.
+   */
   unshiftMany(elements: Iterable<E> | Iterable<R> | Iterable<DoublyLinkedListNode<E>>) {
     const ans: boolean[] = [];
     for (const el of elements) {
@@ -1203,6 +1230,12 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
    * Time Complexity: O(n)
    * Space Complexity: O(1)
    *
+   * The function `countOccurrences` iterates through a doubly linked list and counts the occurrences
+   * of a specified element or nodes that satisfy a given predicate.
+   * @param {E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)} elementOrNode
+   * - The `elementOrNode` parameter in the `countOccurrences` method can accept three types of values:
+   * @returns The `countOccurrences` method returns the number of occurrences of the specified element,
+   * node, or predicate function in the doubly linked list.
    */
   countOccurrences(elementOrNode: E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)): number {
     const predicate = this._ensurePredicate(elementOrNode);
diff --git a/src/data-structures/linked-list/singly-linked-list.ts b/src/data-structures/linked-list/singly-linked-list.ts
index a6d4b7e..5776faf 100644
--- a/src/data-structures/linked-list/singly-linked-list.ts
+++ b/src/data-structures/linked-list/singly-linked-list.ts
@@ -206,6 +206,18 @@ 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) {
@@ -218,6 +230,19 @@ export class SinglyLinkedList<E = any, R = any> extends IterableElementBase<E, R
     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) {
@@ -418,6 +443,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.
@@ -427,6 +455,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 {
diff --git a/src/data-structures/queue/deque.ts b/src/data-structures/queue/deque.ts
index 037ef6b..66b43de 100644
--- a/src/data-structures/queue/deque.ts
+++ b/src/data-structures/queue/deque.ts
@@ -279,6 +279,20 @@ export class Deque<E = any, R = any> extends IterableElementBase<E, R, Deque<E,
     return true;
   }
 
+  /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
+   * 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) {
@@ -291,6 +305,19 @@ export class Deque<E = any, R = any> extends IterableElementBase<E, R, Deque<E,
     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) {
diff --git a/src/data-structures/queue/queue.ts b/src/data-structures/queue/queue.ts
index 49aa52c..fd12a37 100644
--- a/src/data-structures/queue/queue.ts
+++ b/src/data-structures/queue/queue.ts
@@ -126,6 +126,17 @@ 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) {
@@ -154,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
@@ -164,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
@@ -177,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];
@@ -217,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`.
@@ -269,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>>,
diff --git a/src/data-structures/stack/stack.ts b/src/data-structures/stack/stack.ts
index b508fc3..59ede59 100644
--- a/src/data-structures/stack/stack.ts
+++ b/src/data-structures/stack/stack.ts
@@ -108,7 +108,14 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R, Stack<E,
    * 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[] = [];
diff --git a/src/data-structures/trie/trie.ts b/src/data-structures/trie/trie.ts
index 424d475..f177764 100644
--- a/src/data-structures/trie/trie.ts
+++ b/src/data-structures/trie/trie.ts
@@ -366,9 +366,14 @@ export class Trie<R = any> extends IterableElementBase<string, R, Trie<R>> {
   }
 
   /**
-   * Time Complexity: O(n), where n is the total number of nodes in the trie.
-   * Space Complexity: O(1) - Constant space.
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
    *
+   * The function `getHeight` calculates the height of a trie data structure starting from the root
+   * node.
+   * @returns The `getHeight` method returns the maximum depth or height of the trie tree starting from
+   * the root node. It calculates the depth using a breadth-first search (BFS) traversal of the trie
+   * tree and returns the maximum depth found.
    */
   getHeight(): number {
     const startNode = this.root;