[Searches] Fix Binary Search bug with duplicate elements (#13946)

* Fix binary search with duplicates issue #13886 * Add docstrings to binary search functions Added docstrings for lower_bound and upper_bound functions. * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update searches/binary_search.py Co-authored-by: Copilot <[email protected]> * Refactor docstrings for lower_bound and upper_bound Updated docstring parameter and return type annotations for lower_bound and upper_bound functions. * Update searches/binary_search.py Co-authored-by: Copilot <[email protected]> --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Copilot <[email protected]> Co-authored-by: John Law <[email protected]>

Author: 4 people

searches/binary_search.py

@@ -243,6 +243,81 @@ def binary_search_std_lib(sorted_collection: list[int], item: int) -> int:
 return-1
 
 
+defbinary_search_with_duplicates(sorted_collection: list[int], item: int) ->list[int]:
+"""Pure implementation of a binary search algorithm in Python that supports
+ duplicates.
+
+ Resources used:
+ https://stackoverflow.com/questions/13197552/using-binary-search-with-sorted-array-with-duplicates
+
+ The collection must be sorted in ascending order; otherwise the result will be
+ unpredictable. If the target appears multiple times, this function returns a
+ list of all indexes where the target occurs. If the target is not found,
+ this function returns an empty list.
+
+ :param sorted_collection: some ascending sorted collection with comparable items
+ :param item: item value to search for
+ :return: a list of indexes where the item is found (empty list if not found)
+
+ Examples:
+ >>> binary_search_with_duplicates([0, 5, 7, 10, 15], 0)
+ [0]
+ >>> binary_search_with_duplicates([0, 5, 7, 10, 15], 15)
+ [4]
+ >>> binary_search_with_duplicates([1, 2, 2, 2, 3], 2)
+ [1, 2, 3]
+ >>> binary_search_with_duplicates([1, 2, 2, 2, 3], 4)
+ []
+ """
+iflist(sorted_collection) !=sorted(sorted_collection):
+raiseValueError("sorted_collection must be sorted in ascending order")
+
+deflower_bound(sorted_collection: list[int], item: int) ->int:
+"""
+ Returns the index of the first element greater than or equal to the item.
+
+ :param sorted_collection: The sorted list to search.
+ :param item: The item to find the lower bound for.
+ :return: The index where the item can be inserted while maintaining order.
+ """
+left=0
+right=len(sorted_collection)
+whileleft<right:
+midpoint=left+ (right-left) //2
+current_item=sorted_collection[midpoint]
+ifcurrent_item<item:
+left=midpoint+1
+else:
+right=midpoint
+returnleft
+
+defupper_bound(sorted_collection: list[int], item: int) ->int:
+"""
+ Returns the index of the first element strictly greater than the item.
+
+ :param sorted_collection: The sorted list to search.
+ :param item: The item to find the upper bound for.
+ :return: The index where the item can be inserted after all existing instances.
+ """
+left=0
+right=len(sorted_collection)
+whileleft<right:
+midpoint=left+ (right-left) //2
+current_item=sorted_collection[midpoint]
+ifcurrent_item<=item:
+left=midpoint+1
+else:
+right=midpoint
+returnleft
+
+left=lower_bound(sorted_collection, item)
+right=upper_bound(sorted_collection, item)
+
+ifleft==len(sorted_collection) orsorted_collection[left] !=item:
+return []
+returnlist(range(left, right))
+
+
 defbinary_search_by_recursion(
 sorted_collection: list[int], item: int, left: int=0, right: int=-1
 ) ->int: