Add tests and improve documentation on new sorting algorithms (#97)

This effectively standardizes the function arguments for all the new
sorting algorithms to be consistent with the other ones. Also fixes a few
bugs and performs some style improvements, such as moving documentation
of functions to after the function definition instead of before, and
adding documentation where it is missing.

Author: Tjstretchalot

pygorithm/sorting/brick_sort.py

@@ -1,17 +1,25 @@
-def brick_sort(arr, n): 
-    # Initially array is unsorted 
-    isSorted = 0
-    while isSorted == 0: 
-        isSorted = 1
-        temp = 0
-        for i in range(1, n-1, 2): 
-            if arr[i] > arr[i+1]: 
-                arr[i], arr[i+1] = arr[i+1], arr[i] 
-                isSorted = 0
-                  
-        for i in range(0, n-1, 2): 
-            if arr[i] > arr[i+1]: 
-                arr[i], arr[i+1] = arr[i+1], arr[i] 
-                isSorted = 0
-      
-    return
+def brick_sort(arr):
+    """Performs an odd-even in-place sort, which is a variation of a bubble
+    sort.
+
+    https://www.geeksforgeeks.org/odd-even-sort-brick-sort/
+
+    :param arr: the array of values to sort
+    :return: the sorted array
+    """
+    # Initially array is unsorted
+    is_sorted = False
+    while not is_sorted:
+        is_sorted = True
+
+        for i in range(1, len(arr) - 1, 2):
+            if arr[i] > arr[i + 1]:
+                arr[i], arr[i + 1] = arr[i + 1], arr[i]
+                is_sorted = False
+
+        for i in range(0, len(arr) - 1, 2):
+            if arr[i] > arr[i + 1]:
+                arr[i], arr[i + 1] = arr[i + 1], arr[i]
+                is_sorted = False
+
+    return arr

pygorithm/sorting/cocktail_sort.py

@@ -3,55 +3,58 @@
 last modified: 14-10-2019
 '''
 
-'''
 
-Cocktail Sort is a variation of Bubble sort. 
-The Bubble sort algorithm always traverses elements from left
-and moves the largest element to its correct position in first iteration 
-and second largest in second iteration and so on. 
-Cocktail Sort traverses through a given array in both directions alternatively.
+def cocktail_sort(arr):
+    '''
+    Cocktail Sort is a variation of Bubble sort.
+    The Bubble sort algorithm always traverses elements from left
+    and moves the largest element to its correct position in first iteration
+    and second largest in second iteration and so on.
+    Cocktail Sort traverses through a given array in both directions alternatively.
 
-'''
+    This is an in-place sort.
 
-def cocktail_sort(a): 
-    n = len(a) 
+    :param arr: the array to sort
+    :return: the sorted array, which is the same reference as arr
+    '''
     swapped = True
     start = 0
-    end = n-1
-    while swapped: 
-  
-        # reset the swapped flag on entering the loop, 
-        # because it might be true from a previous 
-        # iteration. 
+    end = len(arr) - 1
+    while swapped:
+        # reset the swapped flag on entering the loop,
+        # because it might be true from a previous
+        # iteration.
         swapped = False
-  
-        # loop from left to right same as the bubble 
-        # sort 
-        for i in range(start, end): 
-            if a[i] > a[i + 1]: 
-                a[i], a[i + 1] = a[i + 1], a[i] 
+
+        # loop from left to right same as the bubble
+        # sort
+        for i in range(start, end):
+            if arr[i] > arr[i + 1]:
+                arr[i], arr[i + 1] = arr[i + 1], arr[i]
                 swapped = True
-  
-        # if nothing moved, then array is sorted. 
-        if not swapped: 
+
+        # if nothing moved, then array is sorted.
+        if not swapped:
             break
-  
-        # otherwise, reset the swapped flag so that it 
-        # can be used in the next stage 
+
+        # otherwise, reset the swapped flag so that it
+        # can be used in the next stage
         swapped = False
-  
-        # move the end point back by one, because 
-        # item at the end is in its rightful spot 
+
+        # move the end point back by one, because
+        # item at the end is in its rightful spot
         end -= 1
-  
-        # from right to left, doing the same 
-        # comparison as in the previous stage 
-        for i in range(end-1, start-1, -1): 
-            if a[i] > a[i + 1]: 
-                a[i], a[i + 1] = a[i + 1], a[i] 
+
+        # from right to left, doing the same
+        # comparison as in the previous stage
+        for i in range(end - 1, start - 1, -1):
+            if arr[i] > arr[i + 1]:
+                arr[i], arr[i + 1] = arr[i + 1], arr[i]
                 swapped = True
-  
-        # increase the starting point, because 
-        # the last stage would have moved the next 
-        # smallest number to its rightful spot. 
+
+        # increase the starting point, because
+        # the last stage would have moved the next
+        # smallest number to its rightful spot.
         start = start + 1
+
+    return arr

pygorithm/sorting/gnome_sort.py

@@ -3,30 +3,34 @@
 last modified: 14-10-2019
 '''
 
-'''
 
-Gnome Sort also called Stupid sort is based on the concept of a Garden Gnome sorting his flower pots.
-A garden gnome sorts the flower pots by the following method-
 
-He looks at the flower pot next to him and the previous one; 
-if they are in the right order he steps one pot forward, otherwise he swaps them and steps one pot backwards.
-If there is no previous pot (he is at the starting of the pot line), he steps forwards; 
-if there is no pot next to him (he is at the end of the pot line), he is done.
 
-'''
 
+# A function to sort the given list using Gnome sort
+def gnome_sort(arr):
+    '''
+    Gnome Sort also called Stupid sort is based on the concept of a Garden Gnome sorting his flower pots.
+    A garden gnome sorts the flower pots by the following method-
 
+    He looks at the flower pot next to him and the previous one;
+    if they are in the right order he steps one pot forward, otherwise he swaps them and steps one pot backwards.
+    If there is no previous pot (he is at the starting of the pot line), he steps forwards;
+    if there is no pot next to him (he is at the end of the pot line), he is done.
 
-# A function to sort the given list using Gnome sort 
-def gnome_sort( arr, n): 
+    This is an in-place sort.
+
+    :param arr: the array of values to sort
+    :return: the sorted array, which is the same reference as arr
+    '''
     index = 0
-    while index < n: 
-        if index == 0: 
+    while index < len(arr):
+        if index == 0:
             index = index + 1
-        if arr[index] >= arr[index - 1]: 
+        elif arr[index] >= arr[index - 1]:
             index = index + 1
-        else: 
-            arr[index], arr[index-1] = arr[index-1], arr[index] 
+        else:
+            arr[index], arr[index - 1] = arr[index - 1], arr[index]
             index = index - 1
-  
+
     return arr

pygorithm/sorting/tim_sort.py

@@ -1,69 +1,108 @@
-from insertion_sort import sort
-# iterative Timsort function to sort the  
-# array[0...n-1] (similar to merge sort)  
-def tim_sort(arr, n):  
-   
-    # Sort individual subarrays of size RUN  
-    for i in range(0, n, RUN):  
-        sort(arr, i, min((i+31), (n-1)))  
-    
-    # start merging from size RUN (or 32). It will merge  
-    # to form size 64, then 128, 256 and so on ....  
-    size = RUN 
-    while size < n:  
-       
-        # pick starting point of left sub array. We  
-        # are going to merge arr[left..left+size-1]  
-        # and arr[left+size, left+2*size-1]  
-        # After every merge, we increase left by 2*size  
-        for left in range(0, n, 2*size):  
-           
-            # find ending point of left sub array  
-            # mid+1 is starting point of right sub array  
-            mid = left + size - 1 
-            right = min((left + 2*size - 1), (n-1))  
-    
-            # merge sub array arr[left.....mid] &  
-            # arr[mid+1....right]  
-            merge(arr, left, mid, right)  
-          
-        size = 2*size 
-
-def merge(arr, l, m, r): 
-   
-    # original array is broken in two parts  
-    # left and right array  
-    len1, len2 =  m - l + 1, r - m  
-    left, right = [], []  
-    for i in range(0, len1):  
-        left.append(arr[l + i])  
-    for i in range(0, len2):  
-        right.append(arr[m + 1 + i])  
-    
-    i, j, k = 0, 0, l 
-    # after comparing, we merge those two array  
-    # in larger sub array  
-    while i < len1 and j < len2:  
-       
-        if left[i] <= right[j]:  
-            arr[k] = left[i]  
-            i += 1 
-           
-        else: 
-            arr[k] = right[j]  
-            j += 1 
-           
-        k += 1
-       
-    # copy remaining elements of left, if any  
-    while i < len1:  
-       
-        arr[k] = left[i]  
-        k += 1 
-        i += 1
-    
-    # copy remaining element of right, if any  
-    while j < len2:  
-        arr[k] = right[j]  
-        k += 1
-        j += 1
+def inplace_insertion_sort(arr, start_ind, end_ind):
+    """
+    Performs an in-place insertion sort over a continuous slice of an
+    array. A natural way to avoid this would be to use numpy arrays,
+    where slicing does not copy.
+
+    This is in-place and has no result.
+
+    :param arr: the array to sort
+    :param start_ind: the index to begin sorting at
+    :param end_ind: the index to end sorting at. This index is excluded
+        from the sort (i.e., len(arr) is ok)
+    """
+    for i in range(start_ind + 1, end_ind):
+        current_number = arr[i]
+
+        for j in range(i - 1, start_ind - 1, -1):
+            if arr[j] > current_number:
+                arr[j], arr[j + 1] = arr[j + 1], arr[j]
+            else:
+                arr[j + 1] = current_number
+                break
+
+
+# iterative Timsort function to sort the
+# array[0...n-1] (similar to merge sort)
+def tim_sort(arr, run=32):
+    """
+    Tim sort algorithm. See https://en.wikipedia.org/wiki/Timsort.
+    This is performed in-place.
+
+    :param arr: list of values to sort
+    :param run: the largest array that is sorted with an insertion sort.
+    :return: the sorted array
+    """
+
+    # Sort individual subarrays of size run
+
+    for i in range(0, len(arr), run):
+        inplace_insertion_sort(arr, i, min(i + run, len(arr)))
+
+    # start merging from size RUN (or 32). It will merge
+    # to form size 64, then 128, 256 and so on ....
+    size = run
+    while size < len(arr):
+        # pick starting point of left sub array. We
+        # are going to merge arr[left..left+size-1]
+        # and arr[left+size, left+2*size-1]
+        # After every merge, we increase left by 2*size
+        for left in range(0, len(arr), 2 * size):
+            # find ending point of left sub array
+            # mid+1 is starting point of right sub array
+            mid = left + size
+            right = min(left + (2 * size), len(arr))
+
+            # merge sub array arr[left.....mid] &
+            # arr[mid+1....right]
+            merge(arr, left, mid, right)
+
+        size = 2 * size
+    return arr
+
+def merge(arr, left, mid, right):
+    """
+    Merge of two sections of array, both of which are individually
+    sorted. The result is that the entire chunk is sorted. Note that right
+    edges are exclusive (like slicing).
+
+    This modifies the passed array, but requires a complete copy of the array.
+
+    .. code:: python
+
+        merge([0, -1, 1, 3, 2, 4], 2, 4, 6) # [0, -1, 1, 2, 3, 4]
+
+    :param arr: the array which should have a portion sorted in-place
+    :param left: the left-most index which is included in the merge
+    :param mid: the first index that belongs to the second section
+    :param right: the right-edge in the merge, which is not included in the sort.
+    """
+    # original array is broken in two parts
+    # left and right array
+    left_arr = arr[left:mid]
+    right_arr = arr[mid:right]
+
+    left_pos = 0
+    right_pos = 0
+    arr_ind = left
+    # after comparing, we merge those two array
+    # in larger sub array
+    while left_pos < len(left_arr) and right_pos < len(right_arr):
+        if left_arr[left_pos] <= right_arr[right_pos]:
+            arr[arr_ind] = left_arr[left_pos]
+            left_pos += 1
+        else:
+            arr[arr_ind] = right_arr[right_pos]
+            right_pos += 1
+
+        arr_ind += 1
+
+    # copy remaining elements of left, if any
+    for i in range(left_pos, len(left_arr)):
+        arr[arr_ind] = left_arr[i]
+        arr_ind += 1
+
+    # copy remaining element of right, if any
+    for i in range(right_pos, len(right_arr)):
+        arr[arr_ind] = right_arr[i]
+        arr_ind += 1