diff --git a/Search/BinarySearch.js b/Search/BinarySearch.js index c5477cb7b9..0ff6130022 100644 --- a/Search/BinarySearch.js +++ b/Search/BinarySearch.js @@ -6,7 +6,14 @@ * to the lower half. Otherwise narrow it to the upper half. Repeatedly check until the * value is found or the interval is empty. */ - +/** + * Binary Search (Recursive) + * @param {number[]} arr - The sorted array to search within. + * @param {number} x - The value to search for in the array. + * @param {number} low - The lower bound index of the search interval (default is 0). + * @param {number} high - The upper bound index of the search interval (default is arr.length - 1). + * @returns {number} - The index of the found element if present, otherwise -1. + */ function binarySearchRecursive(arr, x, low = 0, high = arr.length - 1) { const mid = Math.floor(low + (high - low) / 2) @@ -28,6 +35,13 @@ function binarySearchRecursive(arr, x, low = 0, high = arr.length - 1) { return -1 } } +/** + * @param {number[]} arr - The sorted array to search within. + * @param {number} x - The value to search for in the array. + * @param {number} low - The lower bound index of the search interval (default is 0). + * @param {number} high - The upper bound index of the search interval (default is arr.length - 1). + * @returns {number} - The index of the found element if present, otherwise -1. + */ function binarySearchIterative(arr, x, low = 0, high = arr.length - 1) { while (high >= low) { const mid = Math.floor(low + (high - low) / 2) diff --git a/Search/ExponentialSearch.js b/Search/ExponentialSearch.js index d00a981645..0e06f6a8d5 100644 --- a/Search/ExponentialSearch.js +++ b/Search/ExponentialSearch.js @@ -8,7 +8,15 @@ * * */ - +/** + * Binary Search + * + * @param {number[]} arr - The array to search within. + * @param {number} value - The value to search for in the array. + * @param {number} floor - The lower bound index of the search range. + * @param {number} ceiling - The upper bound index of the search range. + * @returns {number} - The index of the found element if present, otherwise -1. + */ function binarySearch(arr, value, floor, ceiling) { // Middle index const mid = Math.floor((floor + ceiling) / 2) @@ -30,7 +38,13 @@ function binarySearch(arr, value, floor, ceiling) { return binarySearch(arr, value, mid + 1, ceiling) } } - +/** + * Exponential Search + * @param {number[]} arr - The array to search within. + * @param {number} length - The length of the array. + * @param {number} value - The value to search for in the array. + * @returns {number} - The index of the found element if present, otherwise -1. + */ function exponentialSearch(arr, length, value) { // If value is the first element of the array return this position if (arr[0] === value) { diff --git a/Search/FibonacciSearch.js b/Search/FibonacciSearch.js index 36459ec8de..8810862009 100644 --- a/Search/FibonacciSearch.js +++ b/Search/FibonacciSearch.js @@ -17,6 +17,11 @@ * * We define a function fibonacciSearch() that takes an array of numbers, * the item (number) to be searched for and the length of the items in the array + * @function fibonacciSearch + * @param {number[]} arr - The array of numbers to search within. + * @param {number} x - The number to search for in the array. + * @param {number} n - The length of the array. + * @returns {number} - The index of the found element if present, otherwise -1. ****************************************************************************/ export const fibonacciSearch = (arr, x, n) => { diff --git a/Search/InterpolationSearch.js b/Search/InterpolationSearch.js index 93f3b78b0e..7499155a4c 100644 --- a/Search/InterpolationSearch.js +++ b/Search/InterpolationSearch.js @@ -6,7 +6,9 @@ * -Worst case: O(n) * -O((log(log(n))) If the data are uniformly distributed * - * + * @param {number[]} arr - The sorted array to search in. + * @param {number} key - The value to search for in the array. + * @returns {number} - The index of the value in the array if found, otherwise -1 */ export function interpolationSearch(arr, key) { diff --git a/Search/JumpSearch.js b/Search/JumpSearch.js index a7b7b443e7..ce12bf2d0e 100644 --- a/Search/JumpSearch.js +++ b/Search/JumpSearch.js @@ -1,14 +1,23 @@ -/* The Jump Search algorithm allows to combine a linear search with a speed optimization. - * This means that instead of going 1 by 1, we will increase the step of √n and increase that - * step of √n which make the step getting bigger and bigger. - * The asymptotic analysis of Jump Search is o(√n). Like the binary search, it needs to be sorted. - * The advantage against binary search is that Jump Search traversed back only once. +/** + * The Jump Search algorithm allows combining a linear search with a speed optimization. + * Instead of searching one element at a time, it increases the step size by √n each time, + * making the step size progressively larger. The asymptotic analysis of Jump Search is O(√n). + * Similar to binary search, the array needs to be sorted for Jump Search to work correctly. + * The advantage of Jump Search over binary search is that it traverses back only once. + * + * @param {number[]} arr - The sorted array to search in. + * @param {number} value - The value to search for in the array. + * @returns {number} - The index of the value in the array if found, otherwise -1. + * + * @example + * const arr = [1, 3, 5, 7, 9, 11, 13, 15] + * const index = jumpSearch(arr, 7) // index will be 3 */ - const jumpSearch = (arr, value) => { const length = arr.length let step = Math.floor(Math.sqrt(length)) let lowerBound = 0 + while (arr[Math.min(step, length) - 1] < value) { lowerBound = step step += step @@ -24,6 +33,7 @@ const jumpSearch = (arr, value) => { return -1 } } + if (arr[lowerBound] === value) { return lowerBound } diff --git a/Search/LinearSearch.js b/Search/LinearSearch.js index 637ebc1589..ca722737d0 100644 --- a/Search/LinearSearch.js +++ b/Search/LinearSearch.js @@ -1,8 +1,19 @@ -/* - * Linear search or sequential search is a method for finding a target - * value within a list. It sequentially checks each element of the list - * for the target value until a match is found or until all the elements - * have been searched. +/** + * Linear search or sequential search is a method for finding a target value within a list. + * It sequentially checks each element of the list for the target value until a match is found + * or until all the elements have been searched. + * @function SearchArray + * @param {number} searchNum - The number to search for in the array. + * @param {number[]} ar - The array in which to search for the number. + * @param {(output: string) => void} [output=(v) => console.log(v)] - Optional callback function to handle output messages. + * @returns {void} + * + * @example + * // Example usage: + * const ar = [1, 2, 3, 4, 5, 6, 7, 8, 9] + * SearchArray(3, ar) // Output: The element was found at 3 + * SearchArray(4, ar) // Output: The element was found at 4 + * SearchArray(11, ar) // Output: The element not found */ function SearchArray(searchNum, ar, output = (v) => console.log(v)) { const position = Search(ar, searchNum) @@ -13,7 +24,18 @@ function SearchArray(searchNum, ar, output = (v) => console.log(v)) { } } -// Search “theArray” for the specified “key” value +/** + * Search for a key in an array using linear search. + * @function Search + * @param {number[]} theArray - The array to search. + * @param {number} key - The key to search for in the array. + * @returns {number} - The index of the key in the array if found, otherwise -1. + * + * @example + * const ar = [1, 2, 3, 4, 5, 6, 7, 8, 9] + * const index1 = Search(ar, 3) // index1 will be 2 + * const index2 = Search(ar, 10) // index2 will be -1 + */ function Search(theArray, key) { for (let n = 0; n < theArray.length; n++) { if (theArray[n] === key) { @@ -24,8 +46,3 @@ function Search(theArray, key) { } export { SearchArray, Search } - -// const ar = [1, 2, 3, 4, 5, 6, 7, 8, 9] -// SearchArray(3, ar) -// SearchArray(4, ar) -// SearchArray(11, ar) diff --git a/Search/QuickSelectSearch.js b/Search/QuickSelectSearch.js index c332af6721..a5274c4826 100644 --- a/Search/QuickSelectSearch.js +++ b/Search/QuickSelectSearch.js @@ -11,6 +11,20 @@ * * [Reference](http://en.wikipedia.org/wiki/Quickselect) */ +/** + * @function quickSelectSearch + * @param {number[]} array - The array of numbers to select the `k` smallest elements from. + * @param {number} k - The number of smallest elements to select. + * @returns {number[]} - A slice of the `k` smallest elements from the array. + * @throws {Error} - Throws an error if the array is empty or if `k` is greater than or equal to the array length. + * @example + * const arr = [1121111, 21, 333, 41, 5, 66, 7777, 28, 19, 11110] + * const result1 = quickSelectSearch(arr, 5) // [19, 21, 28, 41, 5] + * const result2 = quickSelectSearch(arr, 2) // [19, 5] + * const result3 = quickSelectSearch(arr, 7) // [19, 5, 21, 41, 28, 66, 333] + * + * @see {@link http://en.wikipedia.org/wiki/Quickselect} + */ export function quickSelectSearch(array, k) { if (!array || array.length <= k) { throw new Error('Invalid arguments') diff --git a/Search/RabinKarp.js b/Search/RabinKarp.js index e6d6394ede..05991858e8 100644 --- a/Search/RabinKarp.js +++ b/Search/RabinKarp.js @@ -12,6 +12,20 @@ * * [Reference](https://en.wikipedia.org/wiki/Rabin%E2%80%93Karp_algorithm) */ +/** + * @param {string} text - The text string in which to search for the pattern. + * @param {string} pattern - The pattern string to search for in the text. + * @returns {number[]} - An array of indices where the pattern is found in the text. Returns an empty array if the pattern is not found. + * + * @example + * // Example usage: + * const text = 'abracadabra' + * const pattern = 'cad' + * const indices = rabinKarpSearch(text, pattern) + * console.log(indices) // Output: [3] + * + * @see {@link https://en.wikipedia.org/wiki/Rabin%E2%80%93Karp_algorithm} + */ const BASE = 256 // The number of characters in the alphabet const MOD = 997 // A prime number used for the hash function diff --git a/Search/StringSearch.js b/Search/StringSearch.js index cc3ad737a7..2e78662757 100644 --- a/Search/StringSearch.js +++ b/Search/StringSearch.js @@ -1,7 +1,12 @@ /* * String Search */ - +/** + * Builds a prefix table for String where table[i] store prefix of lengest prefix of + * substring str[0..i] + * @param {string} str - The word to build the prefix table for. + * @returns {number[]} - The prefix table for the word. + */ function makeTable(str) { // create a table of size equal to the length of `str` // table[i] will store the prefix of the longest prefix of the substring str[0..i] @@ -35,6 +40,11 @@ function makeTable(str) { } // Find all the words that matches in a given string `str` +/** + * @param {string} str - The main text string to search within. + * @param {string} word - The word to search for within the text. + * @returns {number[]} - An array of indices where the word matches occur in the text. + */ export function stringSearch(str, word) { // find the prefix table in O(n) const prefixes = makeTable(word) diff --git a/Search/TernarySearch.js b/Search/TernarySearch.js index ea0d049341..c9e6209841 100644 --- a/Search/TernarySearch.js +++ b/Search/TernarySearch.js @@ -10,6 +10,14 @@ * * Reference: https://www.geeksforgeeks.org/ternary-search/ */ +/** + * + * @param {number[]} arr - The sorted array to search in. + * @param {number} key - The key to search for. + * @param {number} [low=0] - The lowest index of the search range. + * @param {number} [high=arr.length - 1] - The highest index of the search range. + * @returns {number} - The index of the key if found, otherwise -1. + */ function ternarySearchRecursive(arr, key, low = 0, high = arr.length - 1) { if (high >= low) { @@ -46,7 +54,13 @@ function ternarySearchRecursive(arr, key, low = 0, high = arr.length - 1) { return -1 } } - +/** + * @param {number[]} arr - The sorted array to search in. + * @param {number} key - The key to search for. + * @param {number} [low=0] - The lowest index of the search range. + * @param {number} [high=arr.length - 1] - The highest index of the search range. + * @returns {number} - The index of the key if found, otherwise -1. + */ function ternarySearchIterative(arr, key, low = 0, high = arr.length - 1) { while (high >= low) { // find the mid1 and mid2 diff --git a/Search/UnionFind.js b/Search/UnionFind.js index 5b234da9a1..0b956ec8fb 100644 --- a/Search/UnionFind.js +++ b/Search/UnionFind.js @@ -13,6 +13,8 @@ * especially for register allocation problems. * * you can learn more on disjoint-set / union–find data structure at https://en.wikipedia.org/wiki/Disjoint-set_data_structure + * @param {number} n The number of distinct groups to initialize the Union Find data structure. + * @param {function(number): number} [key] Optional key function that maps indices of groups. Default is the identity function. */ function UnionFind(n, key) { if (!(this instanceof UnionFind)) return new UnionFind(n)