Added search algorithms for OneDimensionalArray (#454)

* Added helping note in README.md

Co-authored-by: Gagandeep Singh <gdp.1807@gmail.com>

Author: r-avenous

README.md

@@ -25,6 +25,9 @@ For development purposes, you can use the option `e` as shown below,
 python -m pip install -e .
 ```
 
+In the above commands, `.` in the end means the current directory. So, make sure you change your working directory
+to `pydatastructs` before executing any of the above commands.
+
 Make sure that your python version is above `3.5`.
 
 Testing

docs/source/pydatastructs/linear_data_structures/algorithms.rst

@@ -33,4 +33,10 @@ Algorithms
 
 .. autofunction:: pydatastructs.next_permutation
 
-.. autofunction:: pydatastructs.prev_permutation
+.. autofunction:: pydatastructs.prev_permutation
+
+.. autofunction:: pydatastructs.linear_search
+
+.. autofunction:: pydatastructs.binary_search
+
+.. autofunction:: pydatastructs.jump_search

pydatastructs/linear_data_structures/__init__.py

@@ -39,6 +39,9 @@
     longest_increasing_subsequence,
     next_permutation,
     prev_permutation,
-    bubble_sort
+    bubble_sort,
+    linear_search,
+    binary_search,
+    jump_search
 )
 __all__.extend(algorithms.__all__)

pydatastructs/linear_data_structures/algorithms.py

@@ -4,7 +4,7 @@
     _check_type, _comp, Backend,
     raise_if_backend_is_not_python)
 from concurrent.futures import ThreadPoolExecutor
-from math import log, floor
+from math import log, floor, sqrt
 
 __all__ = [
     'merge_sort_parallel',
@@ -23,7 +23,10 @@
     'longest_increasing_subsequence',
     'next_permutation',
     'prev_permutation',
-    'bubble_sort'
+    'bubble_sort',
+    'linear_search',
+    'binary_search',
+    'jump_search'
 ]
 
 def _merge(array, sl, el, sr, er, end, comp):
@@ -1369,3 +1372,216 @@ def bubble_sort(array, **kwargs):
         array._modify(force=True)
 
     return array
+
+def linear_search(array, value, **kwargs):
+    """
+    Implements linear search algorithm.
+
+    Parameters
+    ==========
+
+    array: OneDimensionalArray
+        The array which is to be searched.
+    value:
+        The value which is to be searched
+        inside the array.
+    start: int
+        The starting index of the portion
+        which is to be searched.
+        Optional, by default 0
+    end: int
+        The ending index of the portion which
+        is to be searched.
+        Optional, by default the index
+        of the last position filled.
+    backend: pydatastructs.Backend
+        The backend to be used.
+        Optional, by default, the best available
+        backend is used.
+
+    Returns
+    =======
+
+    output: int
+        The index of value if found.
+        If not found, returns None.
+
+    Examples
+    ========
+
+    >>> from pydatastructs import OneDimensionalArray, linear_search
+    >>> arr = OneDimensionalArray(int,[3, 2, 1])
+    >>> linear_search(arr, 2)
+    1
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Linear_search
+    """
+    raise_if_backend_is_not_python(
+            linear_search, kwargs.get('backend', Backend.PYTHON))
+    start = kwargs.get('start', 0)
+    end = kwargs.get('end', len(array) - 1)
+
+    for i in range(start, end + 1):
+        if array[i] == value:
+            return i
+
+    return None
+
+def binary_search(array, value, **kwargs):
+    """
+    Implements binary search algorithm.
+
+    Parameters
+    ==========
+
+    array: OneDimensionalArray
+        The array which is to be searched.
+    value:
+        The value which is to be searched
+        inside the array.
+    start: int
+        The starting index of the portion
+        which is to be searched.
+        Optional, by default 0
+    end: int
+        The ending index of the portion which
+        is to be searched.
+        Optional, by default the index
+        of the last position filled.
+    comp: lambda/function
+        The comparator which is to be used
+        for performing comparisons.
+        Optional, by default, less than or
+        equal to is used for comparing two
+        values.
+    backend: pydatastructs.Backend
+        The backend to be used.
+        Optional, by default, the best available
+        backend is used.
+
+    Returns
+    =======
+
+    output: int
+        The index of elem if found.
+        If not found, returns None.
+
+    Examples
+    ========
+
+    >>> from pydatastructs import OneDimensionalArray, binary_search
+    >>> arr = OneDimensionalArray(int,[1, 2, 3, 5, 10, 12])
+    >>> binary_search(arr, 5)
+    3
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Binary_search_algorithm
+
+    Note
+    ====
+
+    This algorithm assumes that the portion of the array
+    to be searched is already sorted.
+    """
+    raise_if_backend_is_not_python(
+            binary_search, kwargs.get('backend', Backend.PYTHON))
+    start = kwargs.get('start', 0)
+    end = kwargs.get('end', len(array) - 1)
+    comp = kwargs.get("comp", lambda u, v: u <= v)
+
+    left = start
+    right = end
+    while left <= right:
+        middle = left//2 + right//2 + left % 2 * right % 2
+        if array[middle] == value:
+                return middle
+        if comp(array[middle], value):
+            left = middle + 1
+        else:
+            right = middle - 1
+
+    return None
+
+def jump_search(array, value, **kwargs):
+    """
+    Implements jump search algorithm.
+
+    Parameters
+    ==========
+
+    array: OneDimensionalArray
+        The array which is to be searched.
+    value:
+        The value which is to be searched
+        inside the array.
+    start: int
+        The starting index of the portion
+        which is to be searched.
+        Optional, by default 0
+    end: int
+        The ending index of the portion which
+        is to be searched.
+        Optional, by default the index
+        of the last position filled.
+    comp: lambda/function
+        The comparator which is to be used
+        for performing comparisons.
+        Optional, by default, less than or
+        equal to is used for comparing two
+        values.
+    backend: pydatastructs.Backend
+        The backend to be used.
+        Optional, by default, the best available
+        backend is used.
+
+    Returns
+    =======
+
+    output: int
+        The index of elem if found.
+        If not found, returns None.
+
+    Examples
+    ========
+
+    >>> from pydatastructs import OneDimensionalArray, jump_search
+    >>> arr = OneDimensionalArray(int,[1, 2, 3, 5, 10, 12])
+    >>> linear_search(arr, 5)
+    3
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Jump_search
+
+    Note
+    ====
+
+    This algorithm assumes that the portion of the array
+    to be searched is already sorted.
+    """
+    raise_if_backend_is_not_python(
+            jump_search, kwargs.get('backend', Backend.PYTHON))
+    start = kwargs.get('start', 0)
+    end = kwargs.get('end', len(array) - 1)
+    comp = kwargs.get("comp", lambda u, v: u < v)
+
+    step = int(sqrt(end - start + 1))
+    current_position = step
+    prev = start
+    while comp(array[min(current_position, end)], value):
+        prev = current_position
+        current_position += step
+        if prev > end:
+            return None
+    while prev <= min(current_position, end):
+        if array[prev] == value:
+            return prev
+        prev += 1
+
+    return None

pydatastructs/linear_data_structures/tests/test_algorithms.py

@@ -4,7 +4,7 @@
     heapsort, matrix_multiply_parallel, counting_sort, bucket_sort,
     cocktail_shaker_sort, quick_sort, longest_common_subsequence, is_ordered,
     upper_bound, lower_bound, longest_increasing_subsequence, next_permutation,
-    prev_permutation, bubble_sort)
+    prev_permutation, bubble_sort, linear_search, binary_search, jump_search)
 
 from pydatastructs.utils.raises_util import raises
 import random
@@ -322,3 +322,39 @@ def test_next_prev_permutation():
         _, prev_array = prev_permutation(array)
         _, orig_array = next_permutation(prev_array)
         assert str(orig_array) == str(array)
+
+def _test_common_search(search_func, sort_array=True):
+    ODA = OneDimensionalArray
+
+    array = ODA(int, [1, 2, 5, 7, 10, 29, 40])
+    for i in range(len(array)):
+        assert i == search_func(array, array[i])
+
+    checker_array = [None, None, 2, 3, 4, 5, None]
+    for i in range(len(array)):
+        assert checker_array[i] == search_func(array, array[i], start=2, end=5)
+
+    random.seed(1000)
+
+    for i in range(25):
+        data = list(set(random.sample(range(1, 10000), 100)))
+
+        if sort_array:
+            data.sort()
+
+        array = ODA(int, list(data))
+
+        for i in range(len(array)):
+            assert search_func(array, array[i]) == i
+
+        for _ in range(50):
+            assert search_func(array, random.randint(10001, 50000)) is None
+
+def test_linear_search():
+    _test_common_search(linear_search, sort_array=False)
+
+def test_binary_search():
+    _test_common_search(binary_search)
+
+def test_jump_search():
+    _test_common_search(jump_search)

pydatastructs/utils/tests/test_code_quality.py

@@ -103,7 +103,7 @@ def _apis():
     pyds.AdjacencyMatrixGraphNode, pyds.GraphEdge, pyds.Set, pyds.BinaryIndexedTree,
     pyds.CartesianTree, pyds.CartesianTreeNode, pyds.Treap, pyds.RedBlackTreeNode, pyds.RedBlackTree,
     pyds.Trie, pyds.TrieNode, pyds.SkipList, pyds.RangeQueryStatic, pyds.SparseTable,
-    pyds.bubble_sort]
+    pyds.bubble_sort, pyds.linear_search, pyds.binary_search, pyds.jump_search]
 
 def test_public_api():
     pyds = pydatastructs