graph-typed 1.54.2 → 1.54.3

package/dist/data-structures/binary-tree/bst.d.ts

@@ -5,11 +5,12 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BSTNOptKeyOrNode, BSTOptions, BTNRep, Comparable, Comparator, CP, DFSOrderPattern, EntryCallback, IterationType, NodeCallback, NodePredicate, OptNode, OptNodeOrNull } from '../../types';
+import type { BSTNOptKeyOrNode, BSTOptions, BTNRep, Comparable, Comparator, CP, DFSOrderPattern, EntryCallback, IterationType, NodeCallback, NodePredicate, OptNode } from '../../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 import { Range } from '../../common';
 export declare class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
+    parent?: BSTNode<K, V>;
     /**
      * This TypeScript constructor function initializes an instance with a key and an optional value.
      * @param {K} key - The `key` parameter is typically used to uniquely identify an object or element
@@ -20,13 +21,12 @@ export declare class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
      * default to `undefined`.
      */
     constructor(key: K, value?: V);
-    parent?: BSTNode<K, V>;
-    _left?: OptNodeOrNull<BSTNode<K, V>>;
-    get left(): OptNodeOrNull<BSTNode<K, V>>;
-    set left(v: OptNodeOrNull<BSTNode<K, V>>);
-    _right?: OptNodeOrNull<BSTNode<K, V>>;
-    get right(): OptNodeOrNull<BSTNode<K, V>>;
-    set right(v: OptNodeOrNull<BSTNode<K, V>>);
+    _left?: BSTNode<K, V> | null | undefined;
+    get left(): BSTNode<K, V> | null | undefined;
+    set left(v: BSTNode<K, V> | null | undefined);
+    _right?: BSTNode<K, V> | null | undefined;
+    get right(): BSTNode<K, V> | null | undefined;
+    set right(v: BSTNode<K, V> | null | undefined);
 }
 /**
  * 1. Node Order: Each node's left child has a lesser value, and the right child has a greater value.
@@ -62,9 +62,9 @@ export declare class BSTNode<K = any, V = any> extends BinaryTreeNode<K, V> {
  * @example
  * // Find elements in a range
  *     const bst = new BST<number>([10, 5, 15, 3, 7, 12, 18]);
- *     console.log(bst.search(new Range(5, 10))); // [10, 5, 7]
- *     console.log(bst.rangeSearch([4, 12], node => node.key.toString())); // ['10', '12', '5', '7']
- *     console.log(bst.search(new Range(4, 12, true, false))); // [10, 5, 7]
+ *     console.log(bst.search(new Range(5, 10))); // [5, 7, 10]
+ *     console.log(bst.rangeSearch([4, 12], node => node.key.toString())); // ['5', '7', '10', '12']
+ *     console.log(bst.search(new Range(4, 12, true, false))); // [5, 7, 10]
  *     console.log(bst.rangeSearch([15, 20])); // [15, 18]
  *     console.log(bst.search(new Range(15, 20, false))); // [18]
  * @example
@@ -98,12 +98,12 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * This TypeScript constructor initializes a binary search tree with optional options and adds
      * elements if provided.
      * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter in the constructor is an
-     * iterable that can contain elements of type `BTNRep<K, V, BSTNode<K, V>>` or `R`. It is used to
+     * iterable that can contain elements of type `K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  ` or `R`. It is used to
      * initialize the binary search tree with keys, nodes, entries, or raw data.
      * @param [options] - The `options` parameter is an optional object that can contain the following
      * properties:
      */
-    constructor(keysNodesEntriesOrRaws?: Iterable<BTNRep<K, V, BSTNode<K, V>> | R>, options?: BSTOptions<K, V, R>);
+    constructor(keysNodesEntriesOrRaws?: Iterable<K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, options?: BSTOptions<K, V, R>);
     protected _root?: BSTNode<K, V>;
     get root(): OptNode<BSTNode<K, V>>;
     protected _isReverse: boolean;
@@ -141,7 +141,7 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      *
      * The function ensures the existence of a node in a data structure and returns it, or undefined if
      * it doesn't exist.
-     * @param {BTNRep<K, V, BSTNode<K, V>>} keyNodeOrEntry - The parameter
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  } keyNodeOrEntry - The parameter
      * `keyNodeOrEntry` can accept a value of type `R`, which represents the key, node,
      * entry, or raw element that needs to be ensured in the tree.
      * @param {IterationType} [iterationType=ITERATIVE] - The `iterationType` parameter is an optional
@@ -150,18 +150,18 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * @returns The method is returning either the node that was ensured or `undefined` if the node could
      * not be ensured.
      */
-    ensureNode(keyNodeOrEntry: BTNRep<K, V, BSTNode<K, V>>, iterationType?: IterationType): OptNode<BSTNode<K, V>>;
+    ensureNode(keyNodeOrEntry: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): OptNode<BSTNode<K, V>>;
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
      * The function checks if the input is an instance of the BSTNode class.
-     * @param {BTNRep<K, V, BSTNode<K, V>>} keyNodeOrEntry - The parameter
-     * `keyNodeOrEntry` can be of type `R` or `BTNRep<K, V, BSTNode<K, V>>`.
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  } keyNodeOrEntry - The parameter
+     * `keyNodeOrEntry` can be of type `R` or `K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  `.
      * @returns a boolean value indicating whether the input parameter `keyNodeOrEntry` is
      * an instance of the `BSTNode` class.
      */
-    isNode(keyNodeOrEntry: BTNRep<K, V, BSTNode<K, V>>): keyNodeOrEntry is BSTNode<K, V>;
+    isNode(keyNodeOrEntry: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is BSTNode<K, V>;
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -179,13 +179,13 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * Space Complexity: O(log n)
      *
      * The `add` function in TypeScript adds a new node to a binary search tree based on the key value.
-     * @param {BTNRep<K, V, BSTNode<K, V>>} keyNodeOrEntry - The parameter
-     * `keyNodeOrEntry` can accept a value of type `R` or `BTNRep<K, V, BSTNode<K, V>>`.
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  } keyNodeOrEntry - The parameter
+     * `keyNodeOrEntry` can accept a value of type `R` or `K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  `.
      * @param {V} [value] - The `value` parameter is an optional value that can be associated with the
      * key in the binary search tree. If provided, it will be stored in the node along with the key.
      * @returns a boolean value.
      */
-    add(keyNodeOrEntry: BTNRep<K, V, BSTNode<K, V>>, value?: V): boolean;
+    add(keyNodeOrEntry: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
      * Time Complexity: O(k log n)
      * Space Complexity: O(k + log n)
@@ -214,7 +214,7 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      *
      * The function `search` in TypeScript overrides the search behavior in a binary tree structure based
      * on specified criteria.
-     * @param {BTNRep<K, V, BSTNode<K, V>> | NodePredicate<BSTNode<K, V>>} keyNodeEntryOrPredicate - The
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined   | NodePredicate<BSTNode<K, V>>} keyNodeEntryOrPredicate - The
      * `keyNodeEntryOrPredicate` parameter in the `override search` method can accept one of the
      * following types:
      * @param [onlyOne=false] - The `onlyOne` parameter is a boolean flag that determines whether the
@@ -222,9 +222,9 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * search will return as soon as a matching node is found. If `onlyOne` is set to `false`, the
      * @param {C} callback - The `callback` parameter in the `override search` function is a function
      * that will be called on each node that matches the search criteria. It is of type `C`, which
-     * extends `NodeCallback<BSTNode<K, V>>`. The callback function should accept a node of type `BSTNode<K, V>` as its
+     * extends `NodeCallback<BSTNode<K, V> | null>`. The callback function should accept a node of type `BSTNode<K, V>` as its
      * argument and
-     * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter in the `override search`
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  } startNode - The `startNode` parameter in the `override search`
      * method represents the node from which the search operation will begin. It is the starting point
      * for searching within the tree data structure. The method ensures that the `startNode` is a valid
      * node before proceeding with the search operation. If the `
@@ -236,7 +236,7 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * structure based on the provided key, predicate, and other options. The search results are
      * collected in an array and returned as the output of the method.
      */
-    search<C extends NodeCallback<BSTNode<K, V>>>(keyNodeEntryOrPredicate: BTNRep<K, V, BSTNode<K, V>> | NodePredicate<BSTNode<K, V>> | Range<K>, onlyOne?: boolean, callback?: C, startNode?: BTNRep<K, V, BSTNode<K, V>>, iterationType?: IterationType): ReturnType<C>[];
+    search<C extends NodeCallback<BSTNode<K, V>>>(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>> | Range<K>, onlyOne?: boolean, callback?: C, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(k + log n)
@@ -246,9 +246,9 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * either a `Range` object or an array of two elements representing the range boundaries.
      * @param {C} callback - The `callback` parameter in the `rangeSearch` function is a callback
      * function that is used to process each node that is found within the specified range during the
-     * search operation. It is of type `NodeCallback<BSTNode<K, V>>`, where `BSTNode<K, V>` is the type of nodes in the
+     * search operation. It is of type `NodeCallback<BSTNode<K, V> | null>`, where `BSTNode<K, V>` is the type of nodes in the
      * data structure.
-     * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter in the `rangeSearch`
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  } startNode - The `startNode` parameter in the `rangeSearch`
      * function represents the node from which the search for nodes within the specified range will
      * begin. It is the starting point for the range search operation.
      * @param {IterationType} iterationType - The `iterationType` parameter in the `rangeSearch` function
@@ -258,14 +258,14 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * @returns The `rangeSearch` function is returning the result of calling the `search` method with
      * the specified parameters.
      */
-    rangeSearch<C extends NodeCallback<BSTNode<K, V>>>(range: Range<K> | [K, K], callback?: C, startNode?: BTNRep<K, V, BSTNode<K, V>>, iterationType?: IterationType): ReturnType<C>[];
+    rangeSearch<C extends NodeCallback<BSTNode<K, V>>>(range: Range<K> | [K, K], callback?: C, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
      *
      * This function retrieves a node based on a given keyNodeEntryOrPredicate within a binary search tree structure.
-     * @param {BTNRep<K, V, BSTNode<K, V>> | NodePredicate<BSTNode<K, V>>} keyNodeEntryOrPredicate - The `keyNodeEntryOrPredicate`
-     * parameter can be of type `BTNRep<K, V, BSTNode<K, V>>`, `R`, or `NodePredicate<BSTNode<K, V>>`.
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined   | NodePredicate<BSTNode<K, V>>} keyNodeEntryOrPredicate - The `keyNodeEntryOrPredicate`
+     * parameter can be of type `K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  `, `R`, or `NodePredicate<BSTNode<K, V>>`.
      * @param {BSTNOptKeyOrNode<K, BSTNode<K, V>>} startNode - The `startNode` parameter in the `getNode` method
      * is used to specify the starting point for searching nodes in the binary search tree. If no
      * specific starting point is provided, the default value is set to `this._root`, which is the root
@@ -279,28 +279,34 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * the specified root node (`startNode`) and using the specified iteration type. The method then
      * returns the first node found or `undefined` if no node is found.
      */
-    getNode(keyNodeEntryOrPredicate: BTNRep<K, V, BSTNode<K, V>> | NodePredicate<BSTNode<K, V>>, startNode?: BSTNOptKeyOrNode<K, BSTNode<K, V>>, iterationType?: IterationType): OptNode<BSTNode<K, V>>;
+    getNode(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>, startNode?: BSTNOptKeyOrNode<K, BSTNode<K, V>>, iterationType?: IterationType): OptNode<BSTNode<K, V>>;
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
      *
-     * The function overrides the depth-first search method and returns an array of the return types of
-     * the callback function.
+     * The function `dfs` in TypeScript overrides the base class method with default parameters and
+     * returns the result of the super class `dfs` method.
      * @param {C} callback - The `callback` parameter is a function that will be called for each node
-     * during the depth-first search traversal. It is an optional parameter and defaults to
-     * `this._DEFAULT_NODE_CALLBACK`. The type `C` represents the type of the callback function.
-     * @param {DFSOrderPattern} [pattern=IN] - The "pattern" parameter in the code snippet refers to the
-     * order in which the Depth-First Search (DFS) algorithm visits the nodes in a tree or graph. It can
-     * take one of the following values:
-     * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter is the starting
-     * point for the depth-first search traversal. It can be either a root node, a key-value pair, or a
-     * node entry. If not specified, the default value is the root of the tree.
-     * @param {IterationType} [iterationType=ITERATIVE] - The `iterationType` parameter specifies the
-     * type of iteration to be used during the Depth-First Search (DFS) traversal. It can have one of the
-     * following values:
-     * @returns The method is returning an array of the return type of the callback function.
+     * visited during the Depth-First Search traversal. It is a generic type `C` that extends the
+     * `NodeCallback` interface for `BSTNode<K, V>`. The default value for `callback` is `this._
+     * @param {DFSOrderPattern} [pattern=IN] - The `pattern` parameter in the `override dfs` method
+     * specifies the order in which the Depth-First Search (DFS) traversal should be performed on the
+     * Binary Search Tree (BST). The possible values for the `pattern` parameter are:
+     * @param {boolean} [onlyOne=false] - The `onlyOne` parameter in the `override dfs` method is a
+     * boolean flag that indicates whether you want to stop the depth-first search traversal after
+     * finding the first matching node or continue searching for all matching nodes. If `onlyOne` is set
+     * to `true`, the traversal will stop after finding
+     * @param {K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined} startNode -
+     * The `startNode` parameter in the `override dfs` method can be one of the following types:
+     * @param {IterationType} iterationType - The `iterationType` parameter in the `override dfs` method
+     * specifies the type of iteration to be performed during the Depth-First Search (DFS) traversal of a
+     * Binary Search Tree (BST). It is used to determine the order in which nodes are visited during the
+     * traversal. The possible values for `
+     * @returns The `override` function is returning the result of calling the `dfs` method from the
+     * superclass, with the provided arguments `callback`, `pattern`, `onlyOne`, `startNode`, and
+     * `iterationType`. The return type is an array of the return type of the callback function `C`.
      */
-    dfs<C extends NodeCallback<BSTNode<K, V>>>(callback?: C, pattern?: DFSOrderPattern, startNode?: BTNRep<K, V, BSTNode<K, V>>, iterationType?: IterationType): ReturnType<C>[];
+    dfs<C extends NodeCallback<BSTNode<K, V>>>(callback?: C, pattern?: DFSOrderPattern, onlyOne?: boolean, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -310,7 +316,7 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * @param {C} callback - The `callback` parameter is a function that will be called for each node
      * visited during the breadth-first search. It should take a single argument, which is the current
      * node being visited, and it can return a value of any type.
-     * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter is the starting
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  } startNode - The `startNode` parameter is the starting
      * point for the breadth-first search. It can be either a root node, a key-value pair, or an entry
      * object. If no value is provided, the default value is the root of the tree.
      * @param {IterationType} iterationType - The `iterationType` parameter is used to specify the type
@@ -318,7 +324,7 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * the following values:
      * @returns an array of the return type of the callback function.
      */
-    bfs<C extends NodeCallback<BSTNode<K, V>>>(callback?: C, startNode?: BTNRep<K, V, BSTNode<K, V>>, iterationType?: IterationType): ReturnType<C>[];
+    bfs<C extends NodeCallback<BSTNode<K, V>>>(callback?: C, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -326,9 +332,9 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * The function overrides the listLevels method from the superclass and returns an array of arrays
      * containing the results of the callback function applied to each level of the tree.
      * @param {C} callback - The `callback` parameter is a generic type `C` that extends
-     * `NodeCallback<BSTNode<K, V>>`. It represents a callback function that will be called for each node in the
+     * `NodeCallback<BSTNode<K, V> | null>`. It represents a callback function that will be called for each node in the
      * tree during the iteration process.
-     * @param {BTNRep<K, V, BSTNode<K, V>>} startNode - The `startNode` parameter is the starting
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  } startNode - The `startNode` parameter is the starting
      * point for listing the levels of the binary tree. It can be either a root node of the tree, a
      * key-value pair representing a node in the tree, or a key representing a node in the tree. If no
      * value is provided, the root of
@@ -337,7 +343,7 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * @returns The method is returning a two-dimensional array of the return type of the callback
      * function.
      */
-    listLevels<C extends NodeCallback<BSTNode<K, V>>>(callback?: C, startNode?: BTNRep<K, V, BSTNode<K, V>>, iterationType?: IterationType): ReturnType<C>[][];
+    listLevels<C extends NodeCallback<BSTNode<K, V>>>(callback?: C, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[][];
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -350,7 +356,7 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * @param {CP} lesserOrGreater - The `lesserOrGreater` parameter is used to determine whether to
      * traverse nodes that are lesser, greater, or both than the `targetNode`. It accepts the values -1,
      * 0, or 1, where:
-     * @param {BTNRep<K, V, BSTNode<K, V>>} targetNode - The `targetNode` parameter is the node in
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  } targetNode - The `targetNode` parameter is the node in
      * the binary tree that you want to start traversing from. It can be specified either by providing
      * the key of the node, the node itself, or an entry containing the key and value of the node. If no
      * `targetNode` is provided,
@@ -359,7 +365,7 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * @returns The function `lesserOrGreaterTraverse` returns an array of values of type
      * `ReturnType<C>`, which is the return type of the callback function passed as an argument.
      */
-    lesserOrGreaterTraverse<C extends NodeCallback<BSTNode<K, V>>>(callback?: C, lesserOrGreater?: CP, targetNode?: BTNRep<K, V, BSTNode<K, V>>, iterationType?: IterationType): ReturnType<C>[];
+    lesserOrGreaterTraverse<C extends NodeCallback<BSTNode<K, V>>>(callback?: C, lesserOrGreater?: CP, targetNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -420,14 +426,14 @@ export declare class BST<K = any, V = any, R = object, MK = any, MV = any, MR =
      * Space Complexity: O(1)
      *
      * The function overrides a method and converts a key, value pair or entry or raw element to a node.
-     * @param {BTNRep<K, V, BSTNode<K, V>>} keyNodeOrEntry - A variable that can be of
-     * type R or BTNRep<K, V, BSTNode<K, V>>. It represents either a key, a node, an entry, or a raw
+     * @param {K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  } keyNodeOrEntry - A variable that can be of
+     * type R or K |  BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined  . It represents either a key, a node, an entry, or a raw
      * element.
      * @param {V} [value] - The `value` parameter is an optional value of type `V`. It represents the
      * value associated with a key in a key-value pair.
      * @returns either a BSTNode<K, V> object or undefined.
      */
-    protected _keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry: BTNRep<K, V, BSTNode<K, V>>, value?: V): [OptNode<BSTNode<K, V>>, V | undefined];
+    protected _keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): [OptNode<BSTNode<K, V>>, V | undefined];
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)