feat: Reworked binary_search.cpp (#1854)

* feat: Reworked binary_search.cpp

* clang-format and clang-tidy fixes for 137be8ab

* Update search/binary_search.cpp

Co-authored-by: David Leal <halfpacho@gmail.com>

Co-authored-by: github-actions <${GITHUB_ACTOR}@users.noreply.github.com>
Co-authored-by: David Leal <halfpacho@gmail.com>

search/binary_search.cpp

@@ -1,56 +1,148 @@
-/**
+/******************************************************************************
  * @file
  * @brief [Binary search
  * algorithm](https://en.wikipedia.org/wiki/Binary_search_algorithm)
- */
-#include <iostream>
+ * @details
+ * Binary search is a search algorithm that finds the position of a target value
+ * within a sorted array. Binary search compares the target value to the middle
+ * element of the array. If they are not equal, the half in which the target
+ * cannot lie is eliminated and the search continues on the remaining half,
+ * again taking the middle element to compare to the target value, and repeating
+ * this until the target value is found. If the search ends with the remaining
+ * half being empty, the target is not in the array.
+ *
+ * ### Implementation
+ *
+ * Binary search works on sorted arrays. Binary search begins by comparing an
+ * element in the middle of the array with the target value. If the target value
+ * matches the element, its position in the array is returned. If the target
+ * value is less than the element, the search continues in the lower half of
+ * the array. If the target value is greater than the element, the search
+ * continues in the upper half of the array. By doing this, the algorithm
+ * eliminates the half in which the target value cannot lie in each iteration.
+ *
+ * ### Complexities
+ *
+ * //n is the number of element in the array.
+ *
+ * Worst-case time complexity	O(log n)
+ * Best-case time complexity	O(1)
+ * Average time complexity	    O(log n)
+ * Worst-case space complexity  0(1)
+ *
+ * @author [Lajat Manekar](https://github.com/Lazeeez)
+ * @author Unknown author
+ *******************************************************************************/
 
-/** binary_search function
- * \param [in] a array to sort
- * \param [in] r right hand limit = \f$n-1\f$
- * \param [in] key value to find
- * \returns index if T is found
- * \return -1 if T is not found
- */
-int binary_search(int a[], int r, int key) {
-    int l = 0;
+#include <algorithm>  /// for std::sort function
+#include <cassert>    /// for std::assert
+#include <iostream>   /// for IO operations
+#include <vector>     /// for std::vector
+/******************************************************************************
+ * @namespace search
+ * @brief Searching algorithms
+ *******************************************************************************/
+namespace search {
 
-    while (l <= r) {
-        int m = l + (r - l) / 2;
-        if (key == a[m])
+/******************************************************************************
+ * @namespace binary_search
+ * @brief Binary search searching algorihm
+ *******************************************************************************/
+namespace binary_search {
+
+/******************************************************************************
+ * @brief The main function which implements binary search
+ * @param arr vector to be searched in
+ * @param val value to be searched
+ * @returns @param int index of val in vector arr
+ *******************************************************************************/
+uint64_t binarySearch(std::vector<uint64_t> arr, uint64_t val) {
+    uint64_t low = 0;                // set the lowest point of the vector.
+    uint64_t high = arr.size() - 1;  // set the highest point of the vector.
+
+    while (low <= high) {
+        uint64_t m = low + (high - low) / 2;  // set the pivot point
+
+        if (val == arr[m]) {
             return m;
-        else if (key < a[m])
-            r = m - 1;
-        else
-            l = m + 1;
+        } /****************************************************
+           * if pivot point is the val, return it,
+           * else check if val is greater or smaller than pivot value
+           * and set the next pivot point accordingly.
+           ****************************************************/
+        else if (val < arr[m]) {
+            high = m - 1;
+        } else {
+            low = m + 1;
+        }
     }
-    return -1;
+    return -1;  // if val is not in the array, return -1.
 }
 
-/** main function */
-int main(int argc, char const* argv[]) {
-    int n, key;
-    std::cout << "Enter size of array: ";
-    std::cin >> n;
-    std::cout << "Enter array elements: ";
+}  // namespace binary_search
 
-    int* a = new int[n];
+}  // namespace search
 
-    // this loop use for store value in Array
-    for (int i = 0; i < n; i++) {
-        std::cin >> a[i];
-    }
+/*******************************************************************************
+ * @brief Self-test implementation #1
+ * @returns void
+ *******************************************************************************/
+static void test1() {
+    // testcase #1
+    // array = [1,3,5,7,9,8,6,4,2] , Value = 4
+    // should return 3
 
-    std::cout << "Enter search key: ";
-    std::cin >> key;
+    std::vector<uint64_t> arr = {{1, 3, 5, 7, 9, 8, 6, 4, 2}};
+    std::sort(arr.begin(), arr.end());
+    uint64_t expected_ans = 3;
+    uint64_t derived_ans = search::binary_search::binarySearch(arr, 4);
+    std::cout << "Test #1: ";
+    assert(derived_ans == expected_ans);
+    std::cout << "Passed!" << std::endl;
+}
 
-    // this is use for find value in given array
-    int res = binary_search(a, n - 1, key);
-    if (res != -1)
-        std::cout << key << " found at index " << res << std::endl;
-    else
-        std::cout << key << " not found" << std::endl;
+/*******************************************************************************
+ * @brief Self-test implementation #2
+ * @returns void
+ *******************************************************************************/
+void test2() {
+    // testcase #2
+    // array = [1,23,25,4,2] , Value = 25
+    // should return 4
+    std::vector<uint64_t> arr = {{1, 23, 25, 4, 2}};
+    std::sort(arr.begin(), arr.end());
+    uint64_t expected_ans = 4;
+    uint64_t derived_ans = search::binary_search::binarySearch(arr, 25);
+    std::cout << "Test #2: ";
+    assert(derived_ans == expected_ans);
+    std::cout << "Passed!" << std::endl;
+}
+
+/*******************************************************************************
+ * @brief Self-test implementation #3
+ * @returns void
+ *******************************************************************************/
+void test3() {
+    // testcase #3
+    // array = [1,31,231,12,12,2,5,51,21,23,12,3] , Value = 5
+    // should return 8
+    std::vector<uint64_t> arr = {{1, 31, 231, 12, 2, 5, 51, 21, 23, 12, 3}};
+    std::sort(arr.begin(), arr.end());
+    uint64_t expected_ans = 8;
+    uint64_t derived_ans = search::binary_search::binarySearch(arr, 31);
+    std::cout << "Test #3: ";
+    assert(derived_ans == expected_ans);
+    std::cout << "Passed!" << std::endl;
+}
+
+/*******************************************************************************
+ * @brief Main function
+ * @returns 0 on exit
+ *******************************************************************************/
+int main() {
+    test1();  // run self-test implementation #1
+    test2();  // run self-test implementation #2
+    test3();  // run self-test implementation #3
 
-    delete[] a;
     return 0;
 }