Merge remote-tracking branch 'origin/master'

goulag_sort/__init__.py

@@ -0,0 +1,2 @@
+from .goulagsort import send_to_goulag
+__all__ = ['send_to_goulag']

goulag_sort/goulagsort.py

@@ -0,0 +1,81 @@
+def send_to_goulag(input_list:list)-> list :
+    """Sorts a list of numbers using the unique "Goulag Sort" method.
+
+    This algorithm processes a list of numbers through a distinctive iterative and
+    recursive procedure, inspired by the "Stalin Sort" concept. Here's how it operates:
+
+    1.  **Iterative Filtering:** It iterates through the main list. If an element
+        is found to be greater than its subsequent element, the subsequent element
+        is moved to a temporary holding list (`temp`). The main list then continues
+        with the remaining elements.
+
+    2.  **Recursive Processing of Held Items:** If the `temp` list contains more than
+        one item, the `send_to_goulag` algorithm recursively processes `temp`. This
+        filtering and holding process continues until the sub-list contains a single
+        item or becomes empty.
+
+    3.  **Partial Re-insertion:** After the recursive calls (or if `temp` was empty/single-item),
+        the algorithm attempts to re-insert the elements from `temp` back into the main list.
+        This re-insertion is performed by finding a suitable position where the held item
+        is less than the current element in the main list, maintaining a partial order.
+
+    4.  **Final Appending:** Any remaining elements in `temp` that were not re-inserted
+        into the middle of the list are then appended to the end of the main list.
+
+    For a more detailed step-by-step explanation of the algorithm's flow, please refer to:
+    :ref:`goulag_sort_detailed_explanation`.
+
+    Args:
+        input_list (list): The list of numbers to be processed and sorted.
+                           This list will be modified **in-place**.
+
+    Returns:
+        list: The list after being processed by the Goulag Sort algorithm. The result
+              is an ordered list.
+
+    Examples:
+        >>> from goulag_sort import send_to_goulag
+        >>> my_list = [5, 2, 8, 1, 9, 4]
+        >>> send_to_goulag(my_list)
+        [1, 2, 4, 5, 8, 9]
+
+        >>> empty_list = []
+        >>> send_to_goulag(empty_list)
+        []
+    """
+
+
+    idx = 0
+    temp = []
+    while True:
+
+        if not input_list:
+            return []
+
+        while idx < len(input_list) - 1:
+            if input_list[idx] > input_list[idx + 1]:
+                temp.append(input_list[idx + 1])
+                # pop(idx+1) é uma operação O(N) no pior caso
+                input_list.pop(idx + 1)
+            else:
+                idx += 1
+
+        # Chamada recursiva (pode adicionar complexidade se for muito frequente)
+        if len(temp) > 1:
+            temp = send_to_goulag(temp)
+
+        idx = 0
+        # Loop para reinserir elementos de 'temp' na lista principal
+        while idx < len(input_list):
+            if temp and input_list[idx] > temp[0]:
+                # Inserção no meio da lista input_list[idx:idx] = temp é O(N) no pior caso
+                input_list[idx:idx] = temp
+                temp.clear()
+                break
+            idx += 1
+            if len(temp) == 0:
+                return input_list
+
+        if temp:
+            input_list.extend(temp)  # extend é O(k) onde k é o tamanho de temp
+            temp.clear()