Merge ready, with README and comments

Author: johannes67890

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "rust-analyzer.linkedProjects": [
+        ".\\Cargo.toml"
+    ]
+}

README.md

@@ -1,23 +1,99 @@
 # Sorting-algorithm
 
-Sorting algorithms in Rust.
+Tested and Benchmarked Sorting algorithms in Rust.
 
 ## Table of Contents
 
 - [Install](#install)
 - [Usage](#usage)
 - [Showcase](#showcase)
+- [Supported Algoritms](#supported-algoritms)
 - [Benchmarks](#benchmarks)
-- [Instructions](#instructions)
-- [Supported Curves](#supported-curves)
-- [3rd party libraries used](#supported-curves)
 
 ## Install
-
+Clone and install this Github repository
+```git 
+git clone https://github.com/johannes67890/Sorting-algorithm.git
+```
+```
+cargo install
+```
 ## Usage
+```js
+// Run tests on functions
+> npm test
 
-## Benchmarks
+// Run benchmarks on functions
+> npm bench
+```
 
 ## Showcase
+```rust
+/// Imported algorithm modules (See `Supported Algoritms`)
+mod bubble_sort;
+mod quick_sort;
+
+fn main(){
+    let mut arr = [6, 2, 4, 1, 9, -2, 5]; // array to sort
 
+    // Bubble sort
+    bubble_sort::bubblesort(&mut arr); // sort the array
+    println!("Bubble sort: {:?}", arr); // print the sorted array
+
+    // Quick sort
+    quick_sort::quicksort(&mut arr); // sort the array
+    println!("Quick sort: {:?}", arr); // print the sorted array
+}
+```
 ## Supported Algoritms
+- Bubble Sort 
+- Insertion Sort
+- Merge Sort
+- Quick Sort
+- Shell Sort
+## Benchmarks
+Line Chart of all supported algoritms from size 1 to 1000 element arrays
+![Benchmark Image](./assets/1to1000SizeBench.PNG)
+## Individual Benchmarks (Size 100)
+Benchmarks of all sorting algorithms with size of array of 100 elements. 
+#### Bubble Sort
+```
+Sorting Algorithms/Bubble Sort/100
+    time:   [8.1996 µs 8.2539 µs 8.3318 µs]
+Found 10 outliers among 100 measurements (10.00%)
+  1 (1.00%) high mild
+  9 (9.00%) high severe
+```
+### Merge Sort
+```
+Sorting Algorithms/Merge Sort/100
+    time:   [12.033 µs 12.143 µs 12.277 µs]
+Found 17 outliers among 100 measurements (17.00%)
+  4 (4.00%) high mild
+  13 (13.00%) high severe
+```
+### Insertion Sort
+```
+Sorting Algorithms/Insertion Sort/100
+    time:   [3.0122 µs 3.0183 µs 3.0256 µs]
+Found 7 outliers among 100 measurements (7.00%)
+  3 (3.00%) high mild
+  4 (4.00%) high severe
+```
+### Quick Sort
+```
+Sorting Algorithms/Quick Sort/100
+    time:   [2.2028 µs 2.2116 µs 2.2222 µs]
+Found 10 outliers among 100 measurements (10.00%)
+  5 (5.00%) high mild
+  5 (5.00%) high severe
+```
+### Shell Sort
+```
+Sorting Algorithms/Shell Sort/100
+    time:   [2.6537 µs 2.6644 µs 2.6769 µs]
+Found 10 outliers among 100 measurements (10.00%)
+  6 (6.00%) high mild
+  4 (4.00%) high severe
+```
+# [Back to the top](#sorting-algorithm)

assets/1to1000SizeBench.PNG

@@ -5,16 +5,16 @@ use sorting_algorithm::{bubblesort, insertionsort, mergesort, quicksort, shellso
 fn sorting_benchmarks(c: &mut Criterion) {
     let mut group = c.benchmark_group("Sorting Algorithms");
 
-    for i in [1,5,10, 25,50,75, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000] { // size of array
+    for i in [1,5,10, 25,50,75, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000] { // size of array  
         let mut rng = rand::thread_rng();
         let range = Uniform::new(0, 100); // range of random numbers
 
         // Bubble sort benchmark (Time complexity: O(n^2))
         group.bench_function(BenchmarkId::new("Bubble Sort", i), |b| {
             b.iter_batched_ref(
-                || -> Vec<usize> { (0..i).map(|_| rng.sample(&range)).collect() },
-                |v| bubblesort( v),
-                BatchSize::SmallInput,
+                || -> Vec<usize> { (0..i).map(|_| rng.sample(&range)).collect() }, // creates a vector of random numbers
+                |v| bubblesort( v), // v is the vector/array to be sorted
+                BatchSize::SmallInput, // BatchSize::SmallInput is the number of times the function is run
             )
         });
         // Merge sort benchmark (Time complexity: O(nlogn))

benches/sort_benchmark.rs

@@ -1,12 +1,28 @@
+ /// Bubble sort
+ /// 
+ /// Bubble sort swaps each pair of adjacent items if they are in the wrong order.
+ /// repeat until no swaps are needed.
+ /// 
+ /// # Time complexity
+ /// * Best case: O(n)
+ /// * Average case: O(n^2)
+ /// * Worst case: O(n^2)
+ /// 
+ /// # Ilustration
+ /// ```` ignore
+ /// arr = [ 8, 5, 9, 2, 7 ]
+ /// 
+ /// [ 8, 5, 9, 2, 7 ] -> [ 5, 8, 9, 2, 7 ] -> [ 5, 8, 9, 2, 7 ] -> [ 2, 5, 8, 9, 7 ] -> [ 2, 5, 7, 8, 9 ]
+ /// ````
  pub fn bubblesort<T: Ord>(arr: &mut [T]) {
-        let len = arr.len();
-        for i in 0..len {
-            for j in 0..len - i - 1 {
-                if arr[j] > arr[j + 1] {
-                    arr.swap(j, j + 1);
-                }
+    let len = arr.len();
+    for i in 0..len {
+        for j in 0..len - i - 1 {
+            if arr[j] > arr[j + 1] { // swap if the current value is greater than the next value
+                arr.swap(j, j + 1);
             }
         }
     }
+}
 
 

src/bubble_sort.rs

@@ -2,11 +2,17 @@
 /// 
 /// The Insertion sort algorithm is a simple sorting algorithm that builds the final sorted array (or list) one item at a time.
 /// 
+/// # Time complexity
+/// * Best case: O(n)
+/// * Average case: O(n^2)
+/// * Worst case: O(n^2)
+/// 
 /// # Ilustration
-/// `arr = [ 8, 5, 9, 2, 7 ]`
+/// ```` ignore
+/// arr = [ 8, 5, 9, 2, 7 ]
 /// 
 /// [ 8, 5, 9, 2, 7 ] -> [ 5, 8, 9, 2, 7 ] -> [ 5, 8, 9, 2, 7 ] -> [ 2, 5, 8, 9, 7 ] -> [ 2, 5, 7, 8, 9 ]
-/// 
+/// ````
 pub fn insertionsort<T: Ord>(array: &mut [T]) {
     let mut n = array.len();
     for i in 1..n {

src/insertion_sort.rs

@@ -9,14 +9,12 @@ pub use quick_sort::quicksort;
 pub use insertion_sort::insertionsort;
 pub use merge_sort::mergesort;
 pub use shell_sort::shellsort;
-
+///
+/// Test sorting algorithms
+///
 #[cfg(test)]
 mod tests {
     use super::*;
-    ///
-    /// Test sorting algorithms
-    /// 
-
     #[test]
     fn test_bubble_sort() {
         let mut arr = [6, 2, 4, 1, 9, -2, 5];

src/lib.rs

@@ -1,3 +1,45 @@
+/// Merge Sort
+/// 
+/// Merge sort is a divide and conquer algorithm.
+/// 
+/// The pivot point is the middle index of array. It is calculated by `(left index + right index) / 2`.
+/// The array is divided into two subarrays, left and right.
+/// The left subarray is sorted by recursively calling the merge sort function.
+/// The right subarray is sorted by recursively calling the merge sort function, after the left subarray is sorted.
+/// At the end, the two subarrays are merged into one sorted array.
+/// 
+/// # Time complexity
+/// * Best case: O(n log n)
+/// * Average case: O(n log n)
+/// * Worst case: O(n log n)
+/// 
+/// # Ilustration 
+/// ``` ignore
+/// arr = [ 8, 5, 9, 2, 7 ]`
+///       if left index < right index -> pivot point = (left index + right index) / 2
+///                 
+///                   <-- Left Index          Right Index -->
+/// 
+///                              [ 8, 5, 9, 2, 7 ]        --> pivot point = 2
+///                                      |                                
+///                       / -------------------------------\ 
+///                  [ 8, 5, 9 ]                         [ 2, 7 ]
+///                      |                                  |
+///           [ 8, 5 ] ------ [9]                     [2] ----- [7]   
+///                      |                                  |      
+///          [ 8 ] -- [ 5 ] -- [  ]                         |            -> sort and merge the two subarrays into one sorted array
+///                     |                                   |
+///          [ 5 ] -- [ 8 ] -- [ 9 ]                 [ 2 ] -- [ 7 ]
+///                     |                                   |
+///            [ 5, 8 ] -- [ 9 ]                         [ 2, 7 ]
+///                     |                                   |
+///                [ 5, 8, 9 ]                              |
+///                     |                                   |
+///                      \-----    [ 2, 5, 7, 8, 9 ]   ---- /
+///                                 
+/// ```
+/// [See detailed illustration of Merge sort in action](https://media.geeksforgeeks.org/wp-content/uploads/20220722205737/MergeSortTutorial.png)
+/// 
 pub fn mergesort<T: Ord + Clone>(arr: &mut [T]) {
     sort(arr, 0, arr.len() - 1);
 }

src/merge_sort.rs

@@ -4,6 +4,11 @@
 /// The Quicksort algoritm is a Divide and Conquer algorithm. 
 /// Quicksort selects a `pivot` element, and takes the other elements smaller or equal on one side and bigger on the other side.
 /// 
+/// # Time complexity
+/// * Best case: O(n log(n))
+/// * Average case: O(n log(n))
+/// * Worst case: O(n^2)
+/// 
 /// # Ilustration 
 /// ``` ignore
 /// arr = [ 8, 5, 9, 2, 7 ]` (pivot is the last element, in this case 7).

src/quick_sort.rs

@@ -1,5 +1,16 @@
 /// Shell sort
 /// 
+/// # Algorithm
+/// Shell sort is a variation of insertion sort.
+/// Shell sort uses a gap value to create sublists.
+/// The gap value starts with a larger value and gets smaller each time through the loop until it becomes 1.
+/// Once the gap is 1, the list is then sorted using insertion sort.
+/// 
+/// # Time complexity
+/// * Best case: O(n)
+/// * Average case: O(n^2)
+/// * Worst case: O(n^2)
+/// 
 /// # Ilustration
 /// ``` ignore
 /// arr = [ 8, 5, 9, 2, 7 ]
@@ -12,13 +23,7 @@
 /// 
 /// [ 5, 8, 2, 7, 9 ] -> [ 2, 5, 7, 8, 9 ]
 /// ```
-/// 
-/// # Complexity
-/// 
-/// | Best | Average | Worst |
-/// |------|---------|-------|
-/// | O(n) | O(n^2)  | O(n^2)|
-/// 
+
 pub fn shellsort<T: Ord + Copy>(arr: &mut [T]) {
     let len = arr.len();
     let mut gap = len / 2;