Recipe Series: Sort Vector #437

* Add simple sorting vector of integers
* Add sorting of vector of floats
* Add sorting of vector of structs by custom natural order
* Add sorting of vector of structs by custom comparator

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,20 @@
 | [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 by natural ordering][ex-sort-structs-natural] | [![std-badge]][std] | [![cat-science-badge]][cat-science] |
+| [Sort a Vector of Structs by custom criteria][ex-sort-structs-custom] | [![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-natural]:   algorithms/sorting.html#sort-a-vector-of-structs-by-natural-ordering
+[ex-sort-structs-custom]:   algorithms/sorting.html#sort-a-vector-of-structs-by-custom-criteria
 
 {{#include links.md}}

src/algorithms/sorting.md

@@ -0,0 +1,8 @@
+# Sorting Vectors
+
+{{#include sorting/sort.md}}
+{{#include sorting/sort_float.md}}
+{{#include sorting/sort_struct_natural.md}}
+{{#include sorting/sort_struct_custom.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_custom.md

@@ -0,0 +1,55 @@
+## Sort a Vector of Structs by custom criteria
+
+[![std-badge]][std] [![cat-science-badge]][cat-science]
+
+This example sorts a Vector of Person structs by age. This is achieved
+with [`vec:sort_by`] and providing it with custom comparator function.
+
+```rust
+use std::fmt;
+
+struct Person {
+	name: String,
+	age: u32
+}
+
+impl Person {
+    pub fn new(name: String, age: u32) -> Self {
+        Person {
+            name,
+            age
+        }
+    }
+}
+
+impl PartialEq for Person {
+    fn eq(&self, other: &Person) -> bool {
+        self.name == other.name
+    }
+}
+
+impl fmt::Debug for Person {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}", self.name)
+    }
+}
+
+fn main() {
+    let expected = vec![
+        Person::new("Al".to_string(), 60),
+        Person::new("Zoe".to_string(), 25),
+        Person::new("John".to_string(), 1),
+        ];
+
+    let mut people = vec![
+    	Person::new("Zoe".to_string(), 25),
+    	Person::new("Al".to_string(), 60),
+    	Person::new("John".to_string(), 1)];
+
+    people.sort_by(|a, b| b.age.cmp(&a.age));
+
+    assert_eq!(people, expected);
+}
+```
+
+[`vec:sort_by`]: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.sort_by

src/algorithms/sorting/sort_struct_natural.md

@@ -0,0 +1,70 @@
+## Sort a Vector of Structs by natural ordering
+
+[![std-badge]][std] [![cat-science-badge]][cat-science]
+
+Sorts a Vector of Person structs with a single property `name` by its natural
+order (By name). In order to make Person sortable you need four traits [`Eq`],
+[`PartialEq`], [`Ord`] and [`PartialOrd`]. Eq can be simply derived.
+
+```rust
+use std::{cmp, fmt};
+
+#[derive(Eq)]
+struct Person {
+	name: String
+}
+
+impl Person {
+    pub fn new(name: String) -> Self {
+        Person {
+            name,
+        }
+    }
+}
+
+impl PartialOrd for Person {
+    fn partial_cmp(&self, other: &Person) -> Option<cmp::Ordering> {
+        Some(other.cmp(self))
+    }
+}
+
+impl Ord for Person {
+    fn cmp(&self, other: &Person) -> cmp::Ordering {
+        self.name.cmp(&other.name)
+    }
+}
+
+impl PartialEq for Person {
+    fn eq(&self, other: &Person) -> bool {
+        self.name == other.name
+    }
+}
+
+impl fmt::Debug for Person {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "{}", self.name)
+    }
+}
+
+fn main() {
+    let expected = vec![
+        Person::new("Zoe".to_string()),
+        Person::new("John".to_string()),
+        Person::new("Al".to_string())
+        ];
+
+    let mut people = vec![
+    	Person::new("Zoe".to_string()),
+    	Person::new("Al".to_string()),
+    	Person::new("John".to_string())];
+
+    people.sort();
+
+    assert_eq!(people, expected);
+}
+```
+
+[`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