Recipe Series: Sort Vector #437

* Add simple sorting vector of integers
* Add sorting of vector of floats
* Add sorting of vector of structs

Author: Januson

src/SUMMARY.md

@@ -4,6 +4,7 @@
 [About](about.md)
 - [Algorithms](algorithms.md)
   - [Generate Random Values](algorithms/randomness.md)
+  - [Sort a Vector](algorithms/sorting.md)
 - [Command Line](cli.md)
   - [Argument Parsing](cli/arguments.md)
 - [Compression](compression.md)

src/algorithms.md

@@ -8,12 +8,18 @@
 | [Generate random values of a custom type][ex-rand-custom] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
 | [Create random passwords from a set of alphanumeric characters][ex-rand-passwd] | [![rand-badge]][rand] | [![cat-os-badge]][cat-os] |
 | [Create random passwords from a set of user-defined characters][ex-rand-choose] | [![rand-badge]][rand] | [![cat-os-badge]][cat-os] |
+| [Sort a Vector of Integers][ex-sort-integers] | [![std-badge]][std] | [![cat-science-badge]][cat-science] |
+| [Sort a Vector of Floats][ex-sort-floats] | [![std-badge]][std] | [![cat-science-badge]][cat-science] |
+| [Sort a Vector of Structs][ex-sort-structs] | [![std-badge]][std] | [![cat-science-badge]][cat-science] |
 
 [ex-rand]: algorithms/randomness.html#generate-random-numbers
 [ex-rand-range]: algorithms/randomness.html#generate-random-numbers-within-a-range
 [ex-rand-dist]: algorithms/randomness.html#generate-random-numbers-with-given-distribution
 [ex-rand-custom]: algorithms/randomness.html#generate-random-values-of-a-custom-type
 [ex-rand-passwd]: algorithms/randomness.html#create-random-passwords-from-a-set-of-alphanumeric-characters
 [ex-rand-choose]:   algorithms/randomness.html#create-random-passwords-from-a-set-of-user-defined-characters
+[ex-sort-integers]:   algorithms/sorting.html#sort-a-vector-of-integers
+[ex-sort-floats]:   algorithms/sorting.html#sort-a-vector-of-floats
+[ex-sort-structs]:   algorithms/sorting.html#sort-a-vector-of-structs
 
 {{#include links.md}}

src/algorithms/sorting.md

@@ -0,0 +1,7 @@
+# Sorting Vectors
+
+{{#include sorting/sort.md}}
+{{#include sorting/sort_float.md}}
+{{#include sorting/sort_struct.md}}
+
+{{#include ../links.md}}

src/algorithms/sorting/sort.md

@@ -0,0 +1,20 @@
+## Sort a Vector of Integers
+
+[![std-badge]][std] [![cat-science-badge]][cat-science]
+
+This example sorts a Vector of integers via [`vec::sort`]. Alternative would
+be to use [`vec::sort_unstable`] which can be faster, but does not preserve
+the order of equal elements.
+
+```rust
+fn main() {
+    let mut vec = vec![1, 5, 10, 2, 15];
+    
+    vec.sort();
+
+    assert_eq!(vec, vec![1, 2, 5, 10, 15]);
+}
+```
+
+[`vec::sort`]: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.sort
+[`vec::sort_unstable`]: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.sort_unstable

src/algorithms/sorting/sort_float.md

@@ -0,0 +1,18 @@
+## Sort a Vector of Floats 
+
+[![std-badge]][std] [![cat-science-badge]][cat-science]
+
+A Vector of f32 or f64 can be sorted with [`vec::sort_by`] and [`PartialOrd::partial_cmp`].
+
+```rust
+fn main() {
+    let mut vec = vec![1.1, 1.15, 5.5, 1.123, 2.0];
+
+    vec.sort_by(|a, b| a.partial_cmp(b).unwrap());
+
+    assert_eq!(vec, vec![1.1, 1.123, 1.15, 2.0, 5.5]);
+}
+```
+
+[`vec::sort_by`]: https://doc.rust-lang.org/std/primitive.slice.html#method.sort_by
+[`PartialOrd::partial_cmp`]: https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#tymethod.partial_cmp

src/algorithms/sorting/sort_struct.md

@@ -0,0 +1,63 @@
+## Sort a Vector of Structs
+
+[![std-badge]][std] [![cat-science-badge]][cat-science]
+
+Sorts a Vector of Person structs with properties `name` and `age` by its natural
+order (By name and age). In order to make Person sortable you need four traits [`Eq`],
+[`PartialEq`], [`Ord`] and [`PartialOrd`]. These traits can be siply derived.
+You can also provide a custom comparator function using a [`vec:sort_by`] method and sort only by age.
+
+```rust
+#[derive(Debug, Eq, Ord, PartialEq, PartialOrd)]
+struct Person {
+    name: String,
+    age: u32
+}
+
+impl Person {
+    pub fn new(name: String, age: u32) -> Self {
+        Person {
+            name,
+            age
+        }
+    }
+}
+
+fn main() {
+    let mut people = vec![
+        Person::new("Zoe".to_string(), 25),
+        Person::new("Al".to_string(), 60),
+        Person::new("John".to_string(), 1),
+    ];
+
+    // Sort people by derived natural order (Name and age)
+    people.sort();
+
+    assert_eq!(
+        people,
+        vec![
+            Person::new("Al".to_string(), 60),
+            Person::new("John".to_string(), 1),
+            Person::new("Zoe".to_string(), 25),
+        ]);
+
+    // Sort people by age
+    people.sort_by(|a, b| b.age.cmp(&a.age));
+
+    assert_eq!(
+        people,
+        vec![
+            Person::new("Al".to_string(), 60),
+            Person::new("Zoe".to_string(), 25),
+            Person::new("John".to_string(), 1),
+        ]);
+
+}
+
+```
+
+[`Eq`]: https://doc.rust-lang.org/std/cmp/trait.Eq.html 
+[`PartialEq`]: https://doc.rust-lang.org/std/cmp/trait.PartialEq.html
+[`Ord`]: https://doc.rust-lang.org/std/cmp/trait.Ord.html
+[`PartialOrd`]: https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html
+[`vec:sort_by`]: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.sort_by