adding js docs to files that missing it in search folder like binarySearch,ExponentialSearch,FibonacciSearch,InterpolationSearch,JumpSearch,LinearSearch,QuickSelectSearch,RabinKarp,StringSearch,TernarySearch

Author: mohmmadAyesh

Diff for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: Search/RabinKarp.js

@@ -12,7 +12,21 @@
  *
  * [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 for: 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 for: Search/TernarySearch.js

@@ -10,7 +10,15 @@
  *
  * 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) {
     // find the mid1 and mid2
@@ -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 for: 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)