Merge branch 'main' into branch-binarySearchTree

Author: junnengsoo

build.gradle

@@ -1,21 +1,13 @@
-/*
- * This file was generated by the Gradle 'init' task.
- *
- * This is a general purpose Gradle build.
- * To learn more about Gradle by exploring our Samples at https://docs.gradle.org/8.3/samples
- */
 plugins {
     id 'java'
     id "com.adarshr.test-logger" version "3.2.0"
     id "checkstyle"
 }
 
-sourceSets {
-    main {
-        java {
-            srcDirs = ['src/main/java', 'scripts']
-        }
-    }
+sourceSets.main.java.srcDirs += ['scripts']
+
+checkstyle {
+    toolVersion = '10.2'
 }
 
 repositories {
@@ -32,9 +24,3 @@ java {
         languageVersion = JavaLanguageVersion.of(11)
     }
 }
-
-checkstyle {
-    def archive = configurations.checkstyle.resolve().find { it.name.startsWith("checkstyle") }
-    config = resources.text.fromArchiveEntry(archive, "google_checks.xml")
-}
-

config/checkstyle/checkstyle.xml

@@ -2,34 +2,8 @@
 
 /**
  * <p></p> Stable implementation of Counting Sort.
- *
- * <p></p> Brief Description: <br>
- * Counting sort is a non-comparison based sorting algorithm and isn't bounded by the O(nlogn) lower-bound
- * of most sorting algorithms. <br>
- * It first obtains the frequency map of all elements (ie counting the occurrence of every element), then
- * computes the prefix sum for the map. This prefix map tells us which position an element should be inserted. <br>
- * Ultimately, each group of elements will be placed together, and the groups in succession, in the sorted output.
- *
- * <p></p> Assumption for use: <br>
- * To perform counting sort, the elements must first have total ordering and their rank must be known.
- *
- * <p></p> Implementation Invariant: <br>
- * At the end of the ith iteration, the ith element from the back will be placed in its rightful position.
- *
- * <p></p>
- * COMMON MISCONCEPTION: Counting sort does not require total ordering of elements since it is non-comparison based.
- * This is incorrect. It requires total ordering of elements to determine their relative positions in the sorted output.
- * In fact, in conventional implementation, the total ordering property is reflected by virtue of the structure
- * of the frequency map.
- *
- * <p></p> Complexity Analysis: <br>
- * Time: O(k+n)=O(max(k,n)) where k is the value of the largest element and n is the number of elements. <br>
- * Space: O(k+n)=O(max(k,n)) <br>
- * Counting sort is most efficient if the range of input values do not exceed the number of input values. <br>
- * Counting sort is NOT AN IN-PLACE algorithm. For one, it requires additional space to store freq map. <br>
- *
- * <p></p> Note: Implementation deals with integers but the idea is the same and can be generalised to other objects,
- * as long as what was discussed above remains true.
+ * This non-comparison-based sorting algorithm is efficient for sorting integers with a small range.
+ * For detailed explanation and complexity analysis, see README.
  */
 public class CountingSort {
     /**
@@ -40,7 +14,7 @@ public class CountingSort {
     public static int[] sort(int[] arr) {
         int k = 0;
         int n = arr.length;
-        // Find the max. value in arr
+        // Find the max. value in arr. This tells us the size of the freq map array.
         for (int i = 0; i < n; i++) {
             k = Math.max(k, arr[i]);
         }
@@ -53,11 +27,11 @@ public static int[] sort(int[] arr) {
         for (int i = 1; i < k+1; i++) {
             freq[i] += freq[i-1];
         }
-        // Sort the array by placing in output array
+        // Sort the array by placing element in the output array
         int[] sorted = new int[n];
-        for (int i = arr.length-1; i >= 0; i--) { // Notice we start from the back to maintain stable property
+        for (int i = arr.length-1; i >= 0; i--) { // we start from the back to maintain stable property
             int num = arr[i];
-            sorted[freq[num]-1] = num;
+            sorted[freq[num]-1] = num; // freq[num]-1 because 0-indexed
             freq[num]--;
         }
         return sorted;

scripts/scripts.iml

@@ -1,21 +1,34 @@
 # Counting Sort
 
+## Background
 Counting sort is a non-comparison-based sorting algorithm and isn't bounded by the O(nlogn) lower-bound 
 of most sorting algorithms. <br>
-It first obtains the frequency map of all elements (ie counting the occurrence of every element), then
+It first obtains the frequency map of all elements (i.e. counting the occurrence of every element), then
 computes the prefix sum for the map. This prefix map tells us which position an element should be inserted.
-Ultimately, each group of elements will be placed together, and the groups in succession, in the sorted output.
+It is updated after each insertion to reflection the new position to insert the next time the same element is 
+encountered. <br>
+
+### Implementation Invariant
+At the end of the ith iteration, the ith element (of the original array) from the back will be placed in 
+its correct position.
+
+Note: An alternative implementation from the front is easily done with minor modification. 
+The catch is that this implementation is not stable.
+
+### Common Misconception
+_Counting sort does not require total ordering of elements since it is non-comparison based._
+
+This is incorrect. It requires total ordering of elements to determine their relative positions in the sorted output.
+In our implementation, the total ordering property is reflected by virtue of the structure of the frequency map.
 
 ## Complexity Analysis
-Time: O(k+n)=O(max(k,n)) where k is the value of the largest element and n is the number of elements. <br>
-Space: O(k+n)=O(max(k,n)) <br>
+**Time**: O(k+n)=O(max(k,n))  <br>
+**Space**: O(k+n)=O(max(k,n)) <br>
+where k is the value of the largest element and n is the number of elements.
+
 Counting sort is most efficient if the range of input values do not exceed the number of input values. <br>
 Counting sort is NOT AN IN-PLACE algorithm. For one, it requires additional space to store freq map. <br>
 
 ## Notes
-COMMON MISCONCEPTION: Counting sort does not require total ordering of elements since it is non-comparison based.
-This is incorrect. It requires total ordering of elements to determine their relative positions in the sorted output.
-In fact, in conventional implementation, the total ordering property is reflected by virtue of the structure
-of the frequency map.
-
-Supplementary: Here is a [video](https://www.youtube.com/watch?v=OKd534EWcdk) if you are still having troubles.
+1. Counting sort (stable version) is often used as a sub-routine for radix sort.
+2. Supplementary: Here is a [video](https://www.youtube.com/watch?v=OKd534EWcdk) if you are still having troubles.

src/main/java/algorithms/sorting/countingSort/CountingSort.java

@@ -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/countingSort/README.md

@@ -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/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/generalised/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
             }
         }
     }