Add doctests to interpolation_search.py

Author: Ihor-Pryyma

searches/interpolation_search.py

@@ -3,13 +3,34 @@
 """
 
 
-def interpolation_search(sorted_collection, item):
-    """Pure implementation of interpolation search algorithm in Python
-    Be careful collection must be ascending sorted, otherwise result will be
-    unpredictable
-    :param sorted_collection: some ascending sorted collection with comparable items
-    :param item: item value to search
-    :return: index of found item or None if item is not found
+def interpolation_search(sorted_collection: list[int], item: int) -> int | None:
+    """
+    Searches for an item in a sorted collection by interpolation search algorithm.
+
+    Args:
+        sorted_collection: An ascending sorted collection of comparable items.
+        item : The item value to search for.
+
+    Returns:
+        int: The index of the found item, or None if the item is not found.
+    Examples:
+    >>> interpolation_search([1, 2, 3, 4, 5], 2)
+    1
+    >>> interpolation_search([1, 2, 3, 4, 5], 4)
+    3
+    >>> interpolation_search([1, 2, 3, 4, 5], 6)
+    >>> interpolation_search([], 1)
+    >>> interpolation_search([100], 100)
+    0
+    >>> interpolation_search([1, 2, 3, 4, 5], 0)
+    >>> interpolation_search([1, 2, 3, 4, 5], 7)
+    >>> interpolation_search([1, 2, 3, 4, 5], 2)
+    1
+    >>> interpolation_search([1, 2, 3, 4, 5], 0)
+    >>> interpolation_search([1, 2, 3, 4, 5], 7)
+    >>> interpolation_search([1, 2, 3, 4, 5], 2)
+    1
+    >>> interpolation_search([5, 5, 5, 5, 5], 3)
     """
     left = 0
     right = len(sorted_collection) - 1
@@ -46,16 +67,35 @@ def interpolation_search(sorted_collection, item):
     return None
 
 
-def interpolation_search_by_recursion(sorted_collection, item, left, right):
+def interpolation_search_by_recursion(
+    sorted_collection: list[int], item: int, left: int = 0, right: int | None = None
+) -> int | None:
     """Pure implementation of interpolation search algorithm in Python by recursion
     Be careful collection must be ascending sorted, otherwise result will be
     unpredictable
     First recursion should be started with left=0 and right=(len(sorted_collection)-1)
-    :param sorted_collection: some ascending sorted collection with comparable items
-    :param item: item value to search
-    :return: index of found item or None if item is not found
-    """
 
+    Args:
+        sorted_collection: some sorted collection with comparable items
+        item: item value to search
+        left: left index in collection
+        right: right index in collection
+
+    Returns:
+        index of item in collection or None if item is not present
+
+    Examples:
+    >>> interpolation_search_by_recursion([0, 5, 7, 10, 15], 0)
+    0
+    >>> interpolation_search_by_recursion([0, 5, 7, 10, 15], 15)
+    4
+    >>> interpolation_search_by_recursion([0, 5, 7, 10, 15], 5)
+    1
+    >>> interpolation_search_by_recursion([0, 5, 7, 10, 15], 100)
+    >>> interpolation_search_by_recursion([5, 5, 5, 5, 5], 3)
+    """
+    if right is None:
+        right = len(sorted_collection) - 1
     # avoid divided by 0 during interpolation
     if sorted_collection[left] == sorted_collection[right]:
         if sorted_collection[left] == item:
@@ -87,50 +127,7 @@ def interpolation_search_by_recursion(sorted_collection, item, left, right):
         )
 
 
-def __assert_sorted(collection):
-    """Check if collection is ascending sorted, if not - raises :py:class:`ValueError`
-    :param collection: collection
-    :return: True if collection is ascending sorted
-    :raise: :py:class:`ValueError` if collection is not ascending sorted
-    Examples:
-    >>> __assert_sorted([0, 1, 2, 4])
-    True
-    >>> __assert_sorted([10, -1, 5])
-    Traceback (most recent call last):
-        ...
-    ValueError: Collection must be ascending sorted
-    """
-    if collection != sorted(collection):
-        raise ValueError("Collection must be ascending sorted")
-    return True
-
-
 if __name__ == "__main__":
-    import sys
+    import doctest
 
-    """
-        user_input = input('Enter numbers separated by comma:\n').strip()
-    collection = [int(item) for item in user_input.split(',')]
-    try:
-        __assert_sorted(collection)
-    except ValueError:
-        sys.exit('Sequence must be ascending sorted to apply interpolation search')
-
-    target_input = input('Enter a single number to be found in the list:\n')
-    target = int(target_input)
-        """
-
-    debug = 0
-    if debug == 1:
-        collection = [10, 30, 40, 45, 50, 66, 77, 93]
-        try:
-            __assert_sorted(collection)
-        except ValueError:
-            sys.exit("Sequence must be ascending sorted to apply interpolation search")
-        target = 67
-
-    result = interpolation_search(collection, target)
-    if result is not None:
-        print(f"{target} found at positions: {result}")
-    else:
-        print("Not found")
+    doctest.testmod()