Add detailed docstring with examples to binary_search

Author: jd878

searches/binary_search.py

@@ -178,43 +178,36 @@ def insort_right(
     sorted_collection.insert(bisect_right(sorted_collection, item, lo, hi), item)
 
 
-def binary_search(sorted_collection: list[int], item: int) -> int:
-    """Pure implementation of a binary search algorithm in Python
+def binary_search(arr: list[int], target: int) -> int:
+    """
+    Perform binary search on a sorted list to find the index of a target value.
 
-    Be careful collection must be ascending sorted otherwise, the result will be
-    unpredictable
+    Args:
+        arr (list[int]): A sorted list of integers.
+        target (int): The value to search for in the list.
 
-    :param sorted_collection: some ascending sorted collection with comparable items
-    :param item: item value to search
-    :return: index of the found item or -1 if the item is not found
+    Returns:
+        int: The index of target in arr if found, otherwise -1.
 
-    Examples:
-    >>> binary_search([0, 5, 7, 10, 15], 0)
-    0
-    >>> binary_search([0, 5, 7, 10, 15], 15)
-    4
-    >>> binary_search([0, 5, 7, 10, 15], 5)
-    1
-    >>> binary_search([0, 5, 7, 10, 15], 6)
-    -1
+    Example:
+        >>> binary_search([1, 2, 3, 4, 5], 3)
+        2
+        >>> binary_search([1, 2, 3], 7)
+        -1
     """
-    if list(sorted_collection) != sorted(sorted_collection):
-        raise ValueError("sorted_collection must be sorted in ascending order")
-    left = 0
-    right = len(sorted_collection) - 1
-
-    while left <= right:
-        midpoint = left + (right - left) // 2
-        current_item = sorted_collection[midpoint]
-        if current_item == item:
-            return midpoint
-        elif item < current_item:
-            right = midpoint - 1
+    low, high = 0, len(arr) - 1
+    while low <= high:
+        mid = (low + high) // 2
+        if arr[mid] == target:
+            return mid
+        elif arr[mid] < target:
+            low = mid + 1
         else:
-            left = midpoint + 1
+            high = mid - 1
     return -1
 
 
+
 def binary_search_std_lib(sorted_collection: list[int], item: int) -> int:
     """Pure implementation of a binary search algorithm in Python using stdlib