Merge pull request #60 from 4ndrelim/branch-UpdateDocs

docs: Standardise READMEs and improve clarity

Author: junnengsoo

src/main/java/algorithms/sorting/bubbleSort/BubbleSort.java

@@ -2,20 +2,16 @@
 
 /**
  * Here, we are implementing BubbleSort where we sort the array in increasing (or more precisely, non-decreasing)
- * order.
- * <p>
- * Brief Description and Implementation Invariant:
- * BubbleSort relies on the outer loop variant that after the kth iteration, the biggest k items are correctly sorted
- * at the final k positions of the array. The job of the kth iteration of the outer loop is to bubble the kth
- * largest element to the kth position of the array from the right (i.e. its correct position). This is done through
- * repeatedly comparing adjacent elements and swapping them if they are in the wrong order.
+ * order. Below are some details specific to this implementation.
  * <p>
+ * Early Termination:
  * At the end of the (n-1)th iteration of the outer loop, where n is the length of the array, the largest (n-1)
  * elements are correctly sorted at the final (n-1) positions of the array, leaving the last 1 element placed correctly
  * in the first position of the array. Therefore, (n-1) iterations of the outer loop is sufficient.
  * <p>
- * At the kth iteration of the outer loop, we only require (n-k) adjacent comparisons to get the kth largest
- * element to its correct position.
+ * Slight optimisation:
+ * At the kth iteration of the outer loop, we only require (n-k) adjacent comparisons to get the kth-largest element
+ * to its correct position.
  */
 public class BubbleSort {
     /**
@@ -28,10 +24,10 @@ public static int[] sort(int[] arr) {
         int n = arr.length;
         boolean swapped; // tracks of the presence of swaps within one iteration of the outer loop to
         // facilitate early termination
-        for (int i = 0; i < n - 1; i++) { //outer loop which supports the invariant
+        for (int i = 0; i < n - 1; i++) { // outer loop which supports the invariant; n-1 suffice
             swapped = false;
-            for (int j = 0; j < n - 1 - i; j++) { //inner loop that does the adjacent comparisons
-                if (arr[j] > arr[j + 1]) { //if we changed this to <, we will sort the array in non-increasing order
+            for (int j = 0; j < n - 1 - i; j++) { // inner loop that does the adjacent comparisons
+                if (arr[j] > arr[j + 1]) { // if we changed this to <, we will sort the array in non-increasing order
                     int temp = arr[j];
                     arr[j] = arr[j + 1];
                     arr[j + 1] = temp;

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

@@ -1,11 +1,20 @@
 # Bubble Sort
 
+## Background
+
 Bubble sort is one of the more intuitive comparison-based sorting algorithms.
 It makes repeated comparisons between neighbouring elements, 'bubbling' (side-by-side swaps)
 largest (or smallest) element in the unsorted region to the sorted region (often the front or the back).
 
 ![bubble sort img](../../../../../../docs/assets/images/BubbleSort.jpeg)
 
+### Implementation Invariant
+After the kth iteration, the biggest k items are correctly sorted at the final k positions of the array. 
+
+The job of the kth iteration of the outer loop is to bubble the kth-largest element to the kth position of the array 
+from the right (i.e. its correct position). 
+This is done through repeatedly comparing adjacent elements and swapping them if they are in the wrong order.
+
 ## Complexity Analysis
 
 **Time**:
@@ -22,3 +31,5 @@ This implementation of BubbleSort terminates the outer loop once there are no sw
 outer loop. This improves the best case time complexity to O(n) for an already sorted array.
 
 **Space**: O(1) since sorting is done in-place
+
+## Notes

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

@@ -15,7 +15,7 @@ At the end of the ith iteration, the ith element (of the original array) from th
 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.
+The catch is that this implementation would not be stable.
 
 ### Common Misconception
 

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

@@ -1,6 +1,6 @@
 # Generalized Case
 
-## More Details
+## Background
 
 Implementation of cyclic sort in the generalised case where the input can contain any integer and duplicates.
 
@@ -36,3 +36,5 @@ Read:         
 - Average: O(n^2), it's bounded by the above two
 
 **Space**: O(1) auxiliary space, this is an in-place algorithm
+
+## Notes

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

@@ -1,6 +1,6 @@
 # Simple Case
 
-## More Details
+## Background
 
 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
@@ -41,7 +41,7 @@ The algorithm does a 2-pass iteration.
 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
+## Notes
 
 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)

src/main/java/algorithms/sorting/insertionSort/InsertionSort.java

@@ -4,10 +4,6 @@
  * Here, we are implementing InsertionSort where we sort the array in increasing (or more precisely, non-decreasing)
  * order.
  * <p>
- * Implementation Invariant:
- * The loop invariant is: at the end of kth iteration, the first (k+1) items in the array are in sorted order.
- * At the end of the (n-1)th iteration, all n items in the array will be in sorted order.
- * <p>
  * Note:
  * 1. the loop invariant here slightly differs from the lecture slides as we are using 0-based indexing
  * 2. Insertion into the sorted portion is done byb 'bubbling' elements as in bubble sort

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

@@ -1,15 +1,23 @@
 # Insertion Sort
 
+## Background
+
 Insertion sort is a comparison-based sorting algorithm that builds the final sorted array one element at a
 time. It works by repeatedly taking an element from the unsorted portion of the array and
 inserting it correctly (portion remains sorted) into the sorted portion. Note that the position is not final
 since subsequent elements from unsorted portion may displace previously inserted elements. What's important is
-the sorted region remains sorted. More succinctly: <br>
-At the kth iteration, we take the element arr[k] and insert
+the sorted region remains sorted. 
+
+More succinctly, at the kth iteration, we take the element arr[k] and insert
 it into arr[0, k-1] following sorted order, returning us arr[0, k] in sorted order.
 
 ![InsertionSort](../../../../../../docs/assets/images/InsertionSort.png)
 
+### Implementation Invariant
+The loop invariant: At the end of kth iteration, the first (k+1) items in the array are in sorted order.
+
+At the end of the (n-1)th iteration, all n items in the array will be in sorted order.
+
 ## Complexity Analysis
 
 **Time**:

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

@@ -20,3 +20,9 @@ pivot check.
 So, we introduced 3-way partitioning to handle duplicates by partitioning the array into three sections: elements less
 than the pivot, elements equal to the pivot, and elements greater than the pivot. Now the good pivot check ignores the
 size of the segment that comprises elements = to pivot.
+
+## Recommended Order of Reading
+1. [Hoares](./hoares)
+2. [Lomuto](./lomuto)
+3. [Paranoid](./paranoid)
+4. [3-way partitioning](./threeWayPartitioning)

src/main/java/algorithms/sorting/quickSort/lomuto/README.md

@@ -1,4 +1,4 @@
-This is how QuickSort works if we always pick the first element as the pivot.
+This is how QuickSort works if we always pick the first element as the pivot with Lomuto's partitioning.
 
 ![QuickSort with first element as pivot](../../../../../../../docs/assets/images/QuickSortFirstPivot.png)
 

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

@@ -2,25 +2,24 @@
 
 ## Background
 
-Radix Sort is a non-comparison based, stable sorting algorithm with a counting sort subroutine.
+Radix Sort is a non-comparison based, stable sorting algorithm that conventionally uses counting sort as a subroutine.
 
-Radix Sort continuously sorts based on the least-significant segment of a element
-to the most-significant value of a element.
+Radix Sort performs counting sort several times on the numbers. It sorts starting with the least-significant segment 
+to the most-significant segment.
 
+### Segments
 The definition of a 'segment' is user defined and defers from implementation to implementation.
-Within our implementation, we define each segment as a bit chunk.
+It is most commonly defined as a bit chunk.
 
 For example, if we aim to sort integers, we can sort each element
 from the least to most significant digit, with the digits being our 'segments'.
 
 Within our implementation, we take the binary representation of the elements and
-partition it into 8-bit segments, a integer is represented in 32 bits,
+partition it into 8-bit segments. An integer is represented in 32 bits,
 this gives us 4 total segments to sort through.
 
-Note that the binary representation is weighted positional,
-where each bit's value is dependent on its overall position
-within the representation (the n-th bit from the right represents *2^n*),
-hence we can actually increase / decrease the number segments we wish to conduct a split from.
+Note that the number of segments is flexible and can range up to the number of digits in the binary representation.
+(In this case, sub-routine sort is done on every digit from right to left)
 
 ![Radix Sort](https://miro.medium.com/v2/resize:fit:661/1*xFnpQ4UNK0TvyxiL8r1svg.png)
 
@@ -46,22 +45,23 @@ Hence, a stable sort is required to maintain the order as
 the sorting is done with respect to each of the segments.
 
 ## Complexity Analysis
+Let b-bit words be broken into r-bit pieces. Let n be the number of elements to sort.
 
-**Time**:
-Let *b* be the length of a single element we are sorting and *r* is the amount of bit-string
-we plan to break each element into.
-(Essentially, *b/r* represents the number of segments we
-sort on and hence the number of passes we do during our sort).
+*b/r* represents the number of segments and hence the number of counting sort passes. Note that each pass
+of counting sort takes *(2^r + n)* (O(k+n) where k is the range which is 2^r here).
 
-Note that we derive *(2^r + n)* from the counting sort subroutine,
-since we have *2^r* represents the range since we have *r* bits.
-
-We get a general time complexity of *O((b/r) * (2^r + n))*
+**Time**: *O((b/r) * (2^r + n))*
 
 **Space**: *O(n + 2^r)*
 
-## Notes
+### Choosing r
+Previously we said the number of segments is flexible. Indeed, it is but for more optimised performance, r needs to be
+carefully chosen. The optimal choice of r is slightly smaller than logn which can be justified with differentiation.
 
+Briefly, r=lgn --> Time complexity can be simplified to (b/lgn)(2n). <br>
+For numbers in the range of 0 - n^m, b = mlgn and so the expression can be further simplified to *O(mn)*.
+
+## Notes
 - Radix sort's time complexity is dependent on the maximum number of digits in each element,
   hence it is ideal to use it on integers with a large range and with little digits.
 - This could mean that Radix Sort might end up performing worst on small sets of data