Merge remote-tracking branch 'origin/fixing-JS-docs-for-Search-Folder' into fix-jsdocs

Author: mohmmadAyesh

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)

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) {

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) => {

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) {

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
  }

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)

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')

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

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)

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