Revamp cylic sort

Author: 4ndrelim

src/main/java/algorithms/sorting/cyclicSort/README.md

@@ -1,6 +1,27 @@
 # Cyclic Sort
-Cyclic sort is a comparison-based, in-place algorithm that performs sorting in O(n^2) time. 
-It is quite similar to selection sort, with both invariants ensuring that at the end of
-the ith iteration, the ith element is correctly positioned. But they differ slightly in how
-they ensure this invariant is maintained, allowing cyclic sort to have a time complexity of O(n) 
-for certain inputs (the relative ordering of the elements are already known).
+
+## Background
+Cyclic sort is a comparison-based, in-place algorithm that performs sorting (generally) in O(n^2) time. 
+Though under some conditions (discussed later), the best case could be done in O(n) time.
+
+### Implementation Invariant
+At the end of the ith iteration, the ith element 
+(of the original array, from either the back or front depending on implementation), is correctly positioned.
+
+### Comparison to Selection Sort
+Its invariant is quite similar as selection sort's. But they differ slightly in maintaining this invariant.
+The algorithm for cyclic sort does a bit more than selection sort's. 
+In the process of trying to find the correct element for the ith position, any element that was
+encountered will be correctly placed in their positions as well.
+
+This allows cyclic sort to have a time complexity of O(n) for certain inputs.
+(where the relative ordering of the elements is already known). This is discussed in the [**simple**](./simple) case.
+
+## Simple and Generalised Case
+We discuss more implementation-specific details and complexity analysis in the respective folders. In short,
+1. The [**simple**](./simple) case discusses the non-comparison based implementation of cyclic sort under 
+certain conditions. This allows the best case to be better than O(n^2).
+2. The [**generalised**](./generalised) case discusses cyclic sort for general inputs. This is comparison-based and is 
+usually implemented in O(n^2).
+
+

src/main/java/algorithms/sorting/cyclicSort/generalised/CyclicSort.java

@@ -1,95 +1,33 @@
 package algorithms.sorting.cyclicSort.generalised;
 /**
- * Implementation of cyclic sort in the generalised case where the input can contain any integer and even duplicates.
- * <p></p>
- *
- * Analysis: <br>
- *          Time:
- *              Best: O(n^2) even though no swaps, array still needs to be traversed in O(n) at each iteration <br>
- *              Worst: O(n^2) since we need O(n) time to find the correct position of an element at each iteration <br>
- *              Average: O(n^2)
- *          Space: O(1) auxiliary space, this is an in-place algorithm <p></p>
- *
- * Invariant: <br>
- *          At the end of the ith iteration, the ith element is correctly positioned
- *          (smallest or largest depending on implementation). <br>
- *
- *          This is exactly the same invariant as Selection sort. But the algorithm for cyclic sort actually does a bit
- *          more. In the process of trying to find the correct element for the ith position, whatever elements that were
- *          encountered will be correctly placed in their positions as well. Though, unlike the simple case where the
- *          ordering of the elements are known between one another, the time complexity here remains at O(n^2) because
- *          cyclic sort will still have to iterate over all the elements at each iteration to verify or find the correct
- *          position of the element. <p></p>
- *
- * Illustration: <br>
- *     Result:  6  10  6  5  7  4  2  1
- *       Read:  ^ 6 should be placed at index 4, so we do a swap,
- *     Result:  7  10  6  5  6  4  2  1
- *       Read:  ^ 7 should be placed at index 6, so we do a swap. Note that index 5 should be taken up by dup 6
- *     Result:  2  10  6  5  6  4  7  1
- *       Read:  ^ 2 should be placed at index 1, so swap.
- *     Result:  10  2  6  5  6  4  7  1
- *       Read:  ^ 10 is the largest, should be placed at last index, so swap.
- *     Result:   1  2  6  5  6  4  7  10
- *       Read:   ^ Correctly placed, so move on. Same for 2.
- *       Read:         ^ should be placed at index 4. But index 4 already has a 6. So place at index 5 and so on.
- *     Result:   1  2  4  5  6  6  7  10
- *       Read:            ^  ^  ^  ^  ^ Continue with O(n) verification of correct position at each iteration
- *
+ * Implementation of cyclic sort in the generalised case where the input can contain any integer and duplicates.
  */
 public class CyclicSort {
-    public static void cycleSort(int[] arr, int n) {
-        for (int currIdx = 0; currIdx < n - 1; currIdx++) {
+    public static void cyclicSort(int[] arr, int n) {
+        for (int currIdx = 0; currIdx < n-1; currIdx++) {
             int currElement = arr[currIdx];
-            int rightfulPos = currIdx;
-            for (int i = currIdx + 1; i < n; i++) { // O(n), find the rightful position of the curr element
-                if (arr[i] < currElement) {
-                    rightfulPos++;
-                }
-            }
-            if (rightfulPos == currIdx) { // verified currElement is already in its right position, go to next index
-                continue;
-            }
-
-            while (currElement == arr[rightfulPos]) { // when attempting to place currElement at rightful pos,
-                rightfulPos++; // found that currElement is a duplicate, so place duplicates at next immediate positions
-            }
-
-            int tmp = currElement; // swap, put item in its rightful position
-            arr[currIdx] = arr[rightfulPos];
-            arr[rightfulPos] = tmp;
-
-            /*
-            The currElement has now been placed at its right position, with the element previously at that position
-            at currIdx now. We shall continue this process until the element being swapped and placed at currIdx is the
-            correct one. In other words, the rightfulPos of the element to be considered is the same as currIdx.
-            Only then will we move on to the next index.
-             */
-            while (currIdx != rightfulPos) {
-                currElement = arr[currIdx];
-                rightfulPos = currIdx;
-                for (int i = currIdx + 1; i < n; i++) {
+            int rightfulPos;
+            do {
+                rightfulPos = currIdx; // initialization since elements before currIdx are correctly placed
+                for (int i = currIdx + 1; i < n; i++) { // O(n) find rightfulPos for the currElement
                     if (arr[i] < currElement) {
                         rightfulPos++;
                     }
                 }
-                if (currIdx == rightfulPos) {
-                    break;
-                }
-                while (currElement == arr[rightfulPos]) {
+                while (currElement == arr[rightfulPos]) { // duplicates found, so find next suitable position
                     rightfulPos++;
                 }
-                tmp = currElement;
+                int tmp = currElement; // swap, put item in its rightful position
                 arr[currIdx] = arr[rightfulPos];
                 arr[rightfulPos] = tmp;
-            }
+            } while (rightfulPos != currIdx);
         }
     }
 
     /*
     Overloaded helper method that calls internal implementation.
      */
     public static void sort(int[] arr) {
-        cycleSort(arr, arr.length);
+        cyclicSort(arr, arr.length);
     }
 }

src/main/java/algorithms/sorting/cyclicSort/generalised/README.md

@@ -0,0 +1,35 @@
+# Generalized Case
+
+## More Details
+Implementation of cyclic sort in the generalised case where the input can contain any integer and duplicates.
+
+This is a comparison-based algorithm. In short, for the element encountered at the ith position of the original array, 
+the algorithm does a O(n) traversal to search for its rightful position and does a swap. It repeats this until a swap 
+placing the correct element at the ith position, before moving onto the next (i+1)th.
+
+### Illustration
+Result:  6  10  6  5  7  4  2  1  <br> &nbsp;
+  Read:  ^ 6 should be placed at index 4, so we do a swap with 6 and 7,  <br><br>
+Result:  7  10  6  5  6  4  2  1  <br> &nbsp;
+  Read:  ^ 7 should be placed at index 6, so we do a swap. Note that index 5 should be taken up by dup 6 <br><br>
+Result:  2  10  6  5  6  4  7  1  <br> &nbsp;
+  Read:  ^ 2 should be placed at index 1, so swap. <br><br>
+Result:  10  2  6  5  6  4  7  1  <br> &nbsp;
+  Read:  ^ 10 is the largest, should be placed at last index, so swap. <br><br>
+Result:   1  2  6  5  6  4  7  10  <br> &nbsp;
+  Read:   ^ Correctly placed, so move on. Same for 2.  <br> &nbsp;
+  Read: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+                ^ 6 should be placed at index 4. But index 4 already has a 6. So place at index 5 and so on.  <br><br>
+Result:   1  2  4  5  6  6  7  10  <br> &nbsp;
+  Read: &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+                   ^  ^  ^  ^  ^ Continue with O(n) verification of correct position at each iteration
+
+
+## Complexity Analysis
+**Time**:
+- Best: O(n^2) even if the ith element is encountered in the ith position, a O(n) traversal validation check is needed
+- Worst: O(n^2) since we need O(n) time to find / validate the correct position of an element and 
+the total number of O(n) traversals is bounded by O(n).
+- Average: O(n^2), it's bounded by the above two
+
+**Space**: O(1) auxiliary space, this is an in-place algorithm

src/main/java/algorithms/sorting/cyclicSort/simple/CyclicSort.java

@@ -2,31 +2,7 @@
 
 /**
  * Implementation of cyclic sort in the simple case where the n elements of the given array are contiguous,
- * but not in sorted order. Below illustrates the idea using integers from 0 to n-1. <p></p>
- *
- * Analysis: <br>
- *          Time:
- *              Best: O(n) since the array has to be traversed <br>
- *              Worst: O(n) since each element is at most seen twice <br>
- *              Average: O(n), it's bounded by the above two <br>
- *          Space: O(1) auxiliary space, this is an in-place algorithm <p></p>
- *
- * Invariant: <br>
- *          At the end of the ith iteration, the ith element is correctly positioned
- *          (smallest or largest depending on implementation). <br>
- *
- *          This is exactly the same invariant as Selection sort. But the algorithm for cyclic sort actually does a bit
- *          more. In the process of trying to find the correct element for the ith position, whatever elements that were
- *          encountered will be correctly placed in their positions as well. This leads to the O(n) complexity as
- *          opposed to Selection sort's O(n^2). <p></p>
- *
- * NOTE: <br>
- *      In this implementation, the algorithm is not comparison-based! (unlike the general case) <br>
- *      It makes use of the known inherent ordering of the numbers. <br>
- *
- *      It may seem quite trivial to sort integers from 0 to n-1 when one could simply generate such a sequence. But
- *      this algorithm proves its use in cases where the integers to be sorted are keys to associated values and sorting
- *      to be done in O(1) auxiliary space.
+ * but not in sorted order. Below illustrates the idea using integers from 0 to n-1.
  */
  public class CyclicSort {
     /**
@@ -38,12 +14,12 @@ public static void sort(int[] arr) {
         while (curr < arr.length) { // iterate until the end of the array
             int ele = arr[curr]; // encounter an element that may not be in its correct position
             assert ele >= 0 && ele < arr.length : "Input array should only have integers from 0 to n-1 (inclusive)";
-            if (ele != curr) { // verified that it is indeed not the correct element to be placed at this curr position
+            if (ele != curr) { // verified that it is indeed not the correct element to be placed at curr position
                 int tmp = arr[ele]; // go to the correct position of ele
                 arr[ele] = ele; // do a swap
                 arr[curr] = tmp; // note that curr isn't incremented because we haven't yet placed the correct element
             } else {
-                curr += 1; // we found the correct element to be placed at pos curr, which in this example, is itself
+                curr += 1; // found the correct element to be placed at curr, which in this eg, is itself, so, increment
             }
         }
     }

src/main/java/algorithms/sorting/cyclicSort/simple/FindFirstMissingNonNegative.java

@@ -2,18 +2,7 @@
 
 /**
  * Cyclic sort algorithm can be easily modified to find first missing non-negative integer (i.e. starting from 0)
- * in O(n). <pr></pr>
- *
- * There are other ways of doing so, using a hash set for instance, but what makes cyclic sort stand out is that it is
- * able to do so in O(1) space. In other words, it is in-place and require no additional space. <pr></pr>
- *
- * The algorithm does a 2-pass iteration. In the 1st iteration, it places elements at its rightful position where
- * possible. And in the 2nd iteration, it will look for the first out of place element (element that is not supposed
- * to be in that position). The answer will be the index of that position. <br>
- * Note that the answer is necessarily between 0 and n (inclusive), where n is the length of the array,
- * otherwise there would be a contradiction. <br>
- * So, if a negative number or a number greater than n is encountered, simply ignore the number at the position and
- * move on first. It may be subject to swap later.
+ * in O(n).
  */
 public class FindFirstMissingNonNegative {
     public static int findMissing(int[] arr) {
@@ -25,11 +14,11 @@ public static int findMissing(int[] arr) {
                     curr += 1;
                     continue;
                 }
-                int tmp = arr[ele]; // do the swap and place ele at its right position
+                int tmp = arr[ele]; // do the swap and place ele at its right position first
                 arr[ele] = ele;
                 arr[curr] = tmp;
             } else {
-                curr += 1; // found curr and placed at position curr, move on.
+                curr += 1; // either found the correct element, or a number out of range to ignore first.
             }
         }
 

src/main/java/algorithms/sorting/cyclicSort/simple/README.md

@@ -0,0 +1,44 @@
+# Simple Case
+
+## More Details
+Cyclic Sort can achieve O(n) time complexity in cases where the elements of the collection have a known,
+continuous range, and there exists a direct, O(1) time-complexity mapping from each element to its respective index in
+the sorted order. 
+
+This is typically applicable when sorting a sequence of integers that are in a consecutive range
+or can be easily mapped to such a range. We illustrate the idea with n integers from 0 to n-1.
+
+In this implementation, the algorithm is **not comparison-based**! (unlike the general case). 
+It makes use of the known inherent ordering of the numbers, bypassing the nlogn lower bound for most sorting algorithms.
+
+## Complexity Analysis
+**Time**:
+- Best: O(n) since the array has to be traversed
+- Worst: O(n) since each element is at most seen twice
+- Average: O(n), it's bounded by the above two
+
+**Space**: O(1) auxiliary space, this is an in-place algorithm 
+
+## Case Study: Find First Missing Non-negative Integer
+Cyclic sort algorithm can be easily modified to find first missing non-negative integer (i.e. starting from 0) in O(n).
+ The invariant is the same, but for numbers that are out-of-range (negative or greater than n), 
+simply ignore the number at the position and
+move on first. It may be subject to swap later.
+
+There are other ways of doing so, using a hash set for instance, but what makes cyclic sort stand out is that it is
+able to do so in O(1) space. In other words, it is in-place and require no additional space.
+
+The algorithm does a 2-pass iteration. 
+1. In the 1st iteration, it places elements at its rightful position where possible. 
+2. In the 2nd iteration, it will look for the first out of place element (element that is not supposed
+to be in that position). The answer will be the index of that position.
+
+Note that the answer is necessarily between 0 and n (inclusive), where n is the length of the array,
+otherwise there would be a contradiction.
+
+## Misc
+1. It may seem quite trivial to sort integers from 0 to n-1 when one could simply generate such a sequence. 
+But this algorithm is useful in cases where the integers to be sorted are keys to associated values (or some mapping) 
+and sorting needs to be done in O(1) auxiliary space.
+2. The implementation here uses integers from 0 to n-1. This can be easily modified for n contiguous integers starting
+at some arbitrary number (simply offset by this start number).