data-structure-typed 0.9.16 → 1.12.10

package/dist/data-structures/priority-queue/priority-queue.js

@@ -38,6 +38,11 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PriorityQueue = void 0;
 var PriorityQueue = /** @class */ (function () {
+    /**
+     * The constructor initializes a priority queue with the given options, including an array of nodes and a comparator
+     * function.
+     * @param options - The `options` parameter is an object that contains the following properties:
+     */
     function PriorityQueue(options) {
         this.nodes = [];
         this._comparator = function (a, b) {
@@ -59,21 +64,49 @@ var PriorityQueue = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    /**
+     * The `heapify` function creates a new PriorityQueue instance and fixes the heap property.
+     * @param options - The "options" parameter is an object that contains the configuration options for the PriorityQueue.
+     * It can include properties such as "comparator" which specifies the comparison function used to order the elements in
+     * the priority queue, and "initialValues" which is an array of initial values to be added to the priority
+     * @returns a new instance of the PriorityQueue class after performing the heapify operation on it.
+     */
     PriorityQueue.heapify = function (options) {
         var heap = new PriorityQueue(options);
         heap._fix();
         return heap;
     };
+    /**
+     * The function checks if a priority queue is valid by creating a new priority queue with a fix option and then calling
+     * the isValid method.
+     * @param options - An object containing options for creating a priority queue. The options object should have the
+     * following properties:
+     * @returns the result of calling the `isValid()` method on a new instance of the `PriorityQueue` class.
+     */
     PriorityQueue.isPriorityQueueified = function (options) {
         return new PriorityQueue(__assign(__assign({}, options), { isFix: true })).isValid();
     };
+    /**
+     * The "offer" function adds a node to the heap and ensures that the heap property is maintained.
+     * @param {T} node - The parameter "node" is of type T, which means it can be any data type. It represents the node
+     * that needs to be added to the heap.
+     */
     PriorityQueue.prototype.offer = function (node) {
         this.nodes.push(node);
         this._heapifyUp(this.size - 1);
     };
+    /**
+     * The `peek` function returns the first element of the `nodes` array if it exists, otherwise it returns `null`.
+     * @returns The `peek()` function is returning the first element (`T`) of the `nodes` array if the `size` is not zero.
+     * Otherwise, it returns `null`.
+     */
     PriorityQueue.prototype.peek = function () {
         return this.size ? this.nodes[0] : null;
     };
+    /**
+     * The `poll` function removes and returns the top element from a heap data structure.
+     * @returns The `poll()` method returns a value of type `T` or `null`.
+     */
     PriorityQueue.prototype.poll = function () {
         var _a, _b;
         var res = null;
@@ -87,23 +120,51 @@ var PriorityQueue = /** @class */ (function () {
         }
         return res;
     };
+    /**
+     * The `leaf` function returns the last element in the `nodes` array or `null` if the array is empty.
+     * @returns The method `leaf()` is returning the last element (`T`) in the `nodes` array if it exists. If the array is
+     * empty or the last element is `null`, then it returns `null`.
+     */
     PriorityQueue.prototype.leaf = function () {
         var _a;
         return (_a = this.nodes[this.size - 1]) !== null && _a !== void 0 ? _a : null;
     };
+    /**
+     * The function checks if the size of an object is equal to zero and returns a boolean value indicating whether the
+     * object is empty or not.
+     * @returns The method `isEmpty()` is returning a boolean value indicating whether the size of the object is equal to
+     * 0.
+     */
     PriorityQueue.prototype.isEmpty = function () {
         return this.size === 0;
     };
+    /**
+     * The clear function clears the nodes array.
+     */
     PriorityQueue.prototype.clear = function () {
         this.nodes = [];
     };
+    /**
+     * The toArray function returns an array containing all the elements in the nodes property.
+     * @returns An array of type T, which is the elements of the nodes property.
+     */
     PriorityQueue.prototype.toArray = function () {
         return __spreadArray([], __read(this.nodes), false);
     };
+    /**
+     * The `clone` function returns a new instance of the `PriorityQueue` class with the same nodes and comparator as the
+     * original instance.
+     * @returns The `clone()` method is returning a new instance of the `PriorityQueue` class with the same `nodes` and
+     * `comparator` properties as the original instance.
+     */
     PriorityQueue.prototype.clone = function () {
         return new PriorityQueue({ nodes: this.nodes, comparator: this._comparator });
     };
     // --- start additional methods ---
+    /**
+     * The `isValid` function recursively checks if a binary tree satisfies a certain condition.
+     * @returns The function `isValid()` returns a boolean value.
+     */
     PriorityQueue.prototype.isValid = function () {
         var _this = this;
         var isValidRecursive = function (parentIndex) {
@@ -125,6 +186,10 @@ var PriorityQueue = /** @class */ (function () {
         };
         return isValidRecursive(0);
     };
+    /**
+     * The function sorts the elements in a data structure and returns them in ascending order.
+     * @returns The `sort()` function is returning an array of type `T[]`.
+     */
     PriorityQueue.prototype.sort = function () {
         var visitedNode = [];
         while (this.size !== 0) {
@@ -134,6 +199,13 @@ var PriorityQueue = /** @class */ (function () {
         }
         return visitedNode;
     };
+    /**
+     * The DFS function performs a depth-first search traversal on a binary tree and returns an array of visited nodes
+     * based on the specified traversal order.
+     * @param {PriorityQueueDFSOrderPattern} dfsMode - The dfsMode parameter is a string that specifies the order in which
+     * the nodes should be visited during the Depth-First Search (DFS) traversal. It can have one of the following values:
+     * @returns an array of type `(T | null)[]`.
+     */
     PriorityQueue.prototype.DFS = function (dfsMode) {
         var _this = this;
         var visitedNode = [];
@@ -162,26 +234,66 @@ var PriorityQueue = /** @class */ (function () {
         this._isValidIndex(0) && traverse(0);
         return visitedNode;
     };
+    /**
+     * The function compares two numbers using a custom comparator function.
+     * @param {number} a - The parameter "a" is a number that represents the index of a node in an array.
+     * @param {number} b - The parameter "b" is a number.
+     * @returns the result of the comparison between the elements at indices `a` and `b` in the `nodes` array. The
+     * comparison is done using the `_comparator` function, and if the result is greater than 0, `true` is returned,
+     * indicating that the element at index `a` is greater than the element at index `b`.
+     */
     PriorityQueue.prototype._compare = function (a, b) {
         return this._comparator(this.nodes[a], this.nodes[b]) > 0;
     };
+    /**
+     * The function swaps two elements in an array.
+     * @param {number} a - The parameter "a" is a number that represents the index of an element in an array.
+     * @param {number} b - The parameter "b" is a number.
+     */
     PriorityQueue.prototype._swap = function (a, b) {
         var temp = this.nodes[a];
         this.nodes[a] = this.nodes[b];
         this.nodes[b] = temp;
     };
+    /**
+     * The function checks if a given index is valid within an array.
+     * @param {number} index - The parameter "index" is of type number and represents the index value that needs to be
+     * checked for validity.
+     * @returns A boolean value indicating whether the given index is valid or not.
+     */
     PriorityQueue.prototype._isValidIndex = function (index) {
         return index > -1 && index < this.nodes.length;
     };
+    /**
+     * The function returns the index of the parent node given the index of a child node in a binary tree.
+     * @param {number} child - The "child" parameter is a number representing the index of a child node in a binary tree.
+     * @returns the parent of the given child node.
+     */
     PriorityQueue.prototype._getParent = function (child) {
         return Math.floor((child - 1) / 2);
     };
+    /**
+     * The function returns the index of the left child node in a binary tree given the index of its parent node.
+     * @param {number} parent - The parameter "parent" is a number that represents the index of a node in a binary tree.
+     * @returns the left child of a given parent node in a binary tree.
+     */
     PriorityQueue.prototype._getLeft = function (parent) {
         return (2 * parent) + 1;
     };
+    /**
+     * The function returns the index of the right child node in a binary tree given the index of its parent node.
+     * @param {number} parent - The parameter "parent" is a number that represents the index of a node in a binary tree.
+     * @returns the right child of a given parent node in a binary tree.
+     */
     PriorityQueue.prototype._getRight = function (parent) {
         return (2 * parent) + 2;
     };
+    /**
+     * The function returns the index of the smallest child node of a given parent node.
+     * @param {number} parent - The parent parameter is a number that represents the index of the parent node in a binary
+     * tree.
+     * @returns the minimum value between the parent node and its left and right child nodes.
+     */
     PriorityQueue.prototype._getComparedChild = function (parent) {
         var min = parent;
         var left = this._getLeft(parent), right = this._getRight(parent);
@@ -193,6 +305,11 @@ var PriorityQueue = /** @class */ (function () {
         }
         return min;
     };
+    /**
+     * The function `_heapifyUp` is used to maintain the heap property by moving an element up the heap until it is in the
+     * correct position.
+     * @param {number} start - The start parameter is the index of the element that needs to be moved up in the heap.
+     */
     PriorityQueue.prototype._heapifyUp = function (start) {
         while (start > 0 && this._compare(this._getParent(start), start)) {
             var parent = this._getParent(start);
@@ -200,6 +317,11 @@ var PriorityQueue = /** @class */ (function () {
             start = parent;
         }
     };
+    /**
+     * The function performs a heapify operation by comparing and swapping elements in a binary heap.
+     * @param {number} start - The start parameter is the index of the element in the heap from where the heapifyDown
+     * operation should start.
+     */
     PriorityQueue.prototype._heapifyDown = function (start) {
         var min = this._getComparedChild(start);
         while (this._compare(start, min)) {
@@ -208,6 +330,10 @@ var PriorityQueue = /** @class */ (function () {
             min = this._getComparedChild(start);
         }
     };
+    /**
+     * The _fix function performs a heapify operation on the elements of the heap starting from the middle and moving
+     * towards the root.
+     */
     PriorityQueue.prototype._fix = function () {
         for (var i = Math.floor(this.size / 2); i > -1; i--)
             this._heapifyDown(i);

package/dist/data-structures/queue/deque.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @copyright 2030 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT
+ */
 import { DoublyLinkedList } from '../linked-list';
 export declare class Deque<T> extends DoublyLinkedList<T> {
 }
@@ -23,15 +27,80 @@ export declare class ObjectDeque<T> {
 export declare class ArrayDeque<T> {
     protected _nodes: T[];
     get size(): number;
+    /**
+     * The function "offerLast" adds a value to the end of an array.
+     * @param {T} value - The value parameter represents the value that you want to add to the end of the array.
+     * @returns The return value is the new length of the array after the value has been added.
+     */
     offerLast(value: T): number;
+    /**
+     * The function "pollLast" returns and removes the last element from an array, or returns null if the array is empty.
+     * @returns The method `pollLast()` returns the last element of the `_nodes` array, or `null` if the array is empty.
+     */
     pollLast(): T | null;
+    /**
+     * The `pollFirst` function removes and returns the first element from an array, or returns null if the array is empty.
+     * @returns The `pollFirst()` function returns the first element of the `_nodes` array, or `null` if the array is
+     * empty.
+     */
     pollFirst(): T | null;
+    /**
+     * The function "offerFirst" adds a value to the beginning of an array.
+     * @param {T} value - The value parameter represents the value that you want to add to the beginning of the array.
+     * @returns The return value of the `offerFirst` function is the new length of the array `_nodes` after adding the
+     * `value` at the beginning.
+     */
     offerFirst(value: T): number;
+    /**
+     * The `peekFirst` function returns the first element of an array or null if the array is empty.
+     * @returns The function `peekFirst()` is returning the first element (`T`) of the `_nodes` array. If the array is
+     * empty, it will return `null`.
+     */
     peekFirst(): T | null;
+    /**
+     * The `peekLast` function returns the last element of an array or null if the array is empty.
+     * @returns The method `peekLast()` returns the last element of the `_nodes` array, or `null` if the array is empty.
+     */
     peekLast(): T | null;
+    /**
+     * The get function returns the element at the specified index in an array, or null if the index is out of bounds.
+     * @param {number} index - The index parameter is a number that represents the position of the element you want to
+     * retrieve from the array.
+     * @returns The method is returning the element at the specified index in the `_nodes` array. If the element exists, it
+     * will be returned. If the element does not exist (i.e., the index is out of bounds), `null` will be returned.
+     */
     get(index: number): T | null;
+    /**
+     * The set function assigns a value to a specific index in an array.
+     * @param {number} index - The index parameter is a number that represents the position of the element in the array
+     * that you want to set a new value for.
+     * @param {T} value - The value parameter represents the new value that you want to set at the specified index in the
+     * _nodes array.
+     * @returns The value that is being set at the specified index in the `_nodes` array.
+     */
     set(index: number, value: T): T;
+    /**
+     * The insert function adds a value at a specified index in an array.
+     * @param {number} index - The index parameter specifies the position at which the value should be inserted in the
+     * array. It is a number that represents the index of the array where the value should be inserted. The index starts
+     * from 0, so the first element of the array has an index of 0, the second element has
+     * @param {T} value - The value parameter represents the value that you want to insert into the array at the specified
+     * index.
+     * @returns The splice method returns an array containing the removed elements, if any. In this case, since no elements
+     * are being removed, an empty array will be returned.
+     */
     insert(index: number, value: T): T[];
+    /**
+     * The remove function removes an element from an array at a specified index.
+     * @param {number} index - The index parameter specifies the position of the element to be removed from the array. It
+     * is a number that represents the index of the element to be removed.
+     * @returns The method is returning an array containing the removed element.
+     */
     remove(index: number): T[];
+    /**
+     * The function checks if an array called "_nodes" is empty.
+     * @returns The method `isEmpty()` is returning a boolean value. It returns `true` if the length of the `_nodes` array
+     * is 0, indicating that the array is empty. Otherwise, it returns `false`.
+     */
     isEmpty(): boolean;
 }

package/dist/data-structures/queue/deque.js

@@ -16,6 +16,10 @@ var __extends = (this && this.__extends) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArrayDeque = exports.ObjectDeque = exports.Deque = void 0;
+/**
+ * @copyright 2030 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT
+ */
 var linked_list_1 = require("../linked-list");
 // O(n) time complexity of obtaining the value
 // O(1) time complexity of adding at the beginning and the end
@@ -115,41 +119,106 @@ var ArrayDeque = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    /**
+     * The function "offerLast" adds a value to the end of an array.
+     * @param {T} value - The value parameter represents the value that you want to add to the end of the array.
+     * @returns The return value is the new length of the array after the value has been added.
+     */
     ArrayDeque.prototype.offerLast = function (value) {
         return this._nodes.push(value);
     };
+    /**
+     * The function "pollLast" returns and removes the last element from an array, or returns null if the array is empty.
+     * @returns The method `pollLast()` returns the last element of the `_nodes` array, or `null` if the array is empty.
+     */
     ArrayDeque.prototype.pollLast = function () {
         var _a;
         return (_a = this._nodes.pop()) !== null && _a !== void 0 ? _a : null;
     };
+    /**
+     * The `pollFirst` function removes and returns the first element from an array, or returns null if the array is empty.
+     * @returns The `pollFirst()` function returns the first element of the `_nodes` array, or `null` if the array is
+     * empty.
+     */
     ArrayDeque.prototype.pollFirst = function () {
         var _a;
         return (_a = this._nodes.shift()) !== null && _a !== void 0 ? _a : null;
     };
+    /**
+     * The function "offerFirst" adds a value to the beginning of an array.
+     * @param {T} value - The value parameter represents the value that you want to add to the beginning of the array.
+     * @returns The return value of the `offerFirst` function is the new length of the array `_nodes` after adding the
+     * `value` at the beginning.
+     */
     ArrayDeque.prototype.offerFirst = function (value) {
         return this._nodes.unshift(value);
     };
+    /**
+     * The `peekFirst` function returns the first element of an array or null if the array is empty.
+     * @returns The function `peekFirst()` is returning the first element (`T`) of the `_nodes` array. If the array is
+     * empty, it will return `null`.
+     */
     ArrayDeque.prototype.peekFirst = function () {
         var _a;
         return (_a = this._nodes[0]) !== null && _a !== void 0 ? _a : null;
     };
+    /**
+     * The `peekLast` function returns the last element of an array or null if the array is empty.
+     * @returns The method `peekLast()` returns the last element of the `_nodes` array, or `null` if the array is empty.
+     */
     ArrayDeque.prototype.peekLast = function () {
         var _a;
         return (_a = this._nodes[this._nodes.length - 1]) !== null && _a !== void 0 ? _a : null;
     };
+    /**
+     * The get function returns the element at the specified index in an array, or null if the index is out of bounds.
+     * @param {number} index - The index parameter is a number that represents the position of the element you want to
+     * retrieve from the array.
+     * @returns The method is returning the element at the specified index in the `_nodes` array. If the element exists, it
+     * will be returned. If the element does not exist (i.e., the index is out of bounds), `null` will be returned.
+     */
     ArrayDeque.prototype.get = function (index) {
         var _a;
         return (_a = this._nodes[index]) !== null && _a !== void 0 ? _a : null;
     };
+    /**
+     * The set function assigns a value to a specific index in an array.
+     * @param {number} index - The index parameter is a number that represents the position of the element in the array
+     * that you want to set a new value for.
+     * @param {T} value - The value parameter represents the new value that you want to set at the specified index in the
+     * _nodes array.
+     * @returns The value that is being set at the specified index in the `_nodes` array.
+     */
     ArrayDeque.prototype.set = function (index, value) {
         return this._nodes[index] = value;
     };
+    /**
+     * The insert function adds a value at a specified index in an array.
+     * @param {number} index - The index parameter specifies the position at which the value should be inserted in the
+     * array. It is a number that represents the index of the array where the value should be inserted. The index starts
+     * from 0, so the first element of the array has an index of 0, the second element has
+     * @param {T} value - The value parameter represents the value that you want to insert into the array at the specified
+     * index.
+     * @returns The splice method returns an array containing the removed elements, if any. In this case, since no elements
+     * are being removed, an empty array will be returned.
+     */
     ArrayDeque.prototype.insert = function (index, value) {
         return this._nodes.splice(index, 0, value);
     };
+    /**
+     * The remove function removes an element from an array at a specified index.
+     * @param {number} index - The index parameter specifies the position of the element to be removed from the array. It
+     * is a number that represents the index of the element to be removed.
+     * @returns The method is returning an array containing the removed element.
+     */
     ArrayDeque.prototype.remove = function (index) {
         return this._nodes.splice(index, 1);
     };
+    /**
+     * The function checks if an array called "_nodes" is empty.
+     * @returns The method `isEmpty()` is returning a boolean value. It returns `true` if the length of the `_nodes` array
+     * is 0, indicating that the array is empty. Otherwise, it returns `false`.
+     */
     ArrayDeque.prototype.isEmpty = function () {
         return this._nodes.length === 0;
     };

package/dist/data-structures/queue/queue.d.ts

@@ -1,75 +1,73 @@
 /**
  * @license MIT
- * @copyright 2020 Tyler Zeng <zrwusa@gmail.com>
+ * @copyright 2030 Tyler Zeng <zrwusa@gmail.com>
  * @class
  */
 export declare class Queue<T> {
     protected _nodes: T[];
     protected _offset: number;
     /**
-     * Creates a queue.
-     * @param {array} [elements]
+     * The constructor initializes an instance of a class with an optional array of elements and sets the offset to 0.
+     * @param {T[]} [elements] - The `elements` parameter is an optional array of elements of type `T`. If provided, it
+     * will be used to initialize the `_nodes` property of the class. If not provided, the `_nodes` property will be
+     * initialized as an empty array.
      */
     constructor(elements?: T[]);
     /**
-     * Creates a queue from an existing array.
+     * The function "fromArray" creates a new Queue object from an array of elements.Creates a queue from an existing array.
      * @public
      * @static
-     * @param {array} elements
-     * @return {Queue}
+     * @param {T[]} elements - The "elements" parameter is an array of elements of type T.
+     * @returns The method is returning a new instance of the Queue class, initialized with the elements from the input
+     * array.
      */
     static fromArray<T>(elements: T[]): Queue<T>;
     /**
-     * Adds an element at the back of the queue.
-     * @public
-     * @param {any} element
+     * The offer function adds an element to the end of the queue and returns the updated queue.Adds an element at the back of the queue.
+     * @param {T} element - The `element` parameter represents the element that you want to add to the queue.
+     * @returns The `offer` method is returning a `Queue<T>` object.
      */
     offer(element: T): Queue<T>;
     /**
-     * Dequeues the front element in the queue.
-     * @public
-     * @returns {any}
+     * The `poll` function removes and returns the first element in the queue, and adjusts the internal data structure if
+     * necessary to optimize performance.
+     * @returns The function `poll()` returns either the first element in the queue or `null` if the queue is empty.
      */
     poll(): T | null;
     /**
-     * Returns the front element of the queue.
-     * @public
-     * @returns {any}
+     * The `peek` function returns the first element of the array `_nodes` if it exists, otherwise it returns `null`.
+     * @returns The `peek()` method returns the first element of the data structure, represented by the `_nodes` array at
+     * the `_offset` index. If the data structure is empty (size is 0), it returns `null`.
      */
     peek(): T | null;
     /**
-     * Returns the back element of the queue.
-     * @public
-     * @returns {any}
+     * The `peekLast` function returns the last element in an array-like data structure, or null if the structure is empty.
+     * @returns The method `peekLast()` returns the last element of the `_nodes` array if the array is not empty. If the
+     * array is empty, it returns `null`.
      */
     peekLast(): T | null;
     /**
-     * Returns the number of elements in the queue.
-     * @public
-     * @returns {number}
+     * The size function returns the number of elements in an array.
+     * @returns {number} The size of the array, which is the difference between the length of the array and the offset.
      */
     size(): number;
     /**
-     * Checks if the queue is empty.
-     * @public
-     * @returns {boolean}
+     * The function checks if a data structure is empty by comparing its size to zero.
+     * @returns {boolean} A boolean value indicating whether the size of the object is 0 or not.
      */
     isEmpty(): boolean;
     /**
-     * Returns the remaining elements in the queue as an array.
-     * @public
-     * @returns {array}
+     * The toArray() function returns an array of elements from the current offset to the end of the _nodes array.
+     * @returns An array of type T is being returned.
      */
     toArray(): T[];
     /**
-     * Clears the queue.
-     * @public
+     * The clear function resets the nodes array and offset to their initial values.
      */
     clear(): void;
     /**
-     * Creates a shallow copy of the queue.
-     * @public
-     * @return {Queue}
+     * The `clone()` function returns a new Queue object with the same elements as the original Queue.
+     * @returns The `clone()` method is returning a new instance of the `Queue` class.
      */
     clone(): Queue<T>;
 }