added shuflr example

Author: BartMassey

README.md

@@ -31,3 +31,4 @@ in a controlled repository now.
 * `deref.rs`: deref trait example
 * `from.rs`: from / try_from trait example
 * `prog.rs`, `prog2.rs`: state machine examples using closures
+* `shuflr/`: iterator implementation example

shuflr/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "shuflr"
+version = "0.1.0"
+authors = ["Bart Massey <[email protected]>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+rand = "0.8.3"
+
+[lib]
+name = "shuflr"
+path = "shuflr.rs"

shuflr/shuflr.rs

@@ -0,0 +1,53 @@
+use rand::seq::SliceRandom;
+use rand::Rng;
+
+pub struct IterShuffled<'a, T> {
+    values: &'a [T],
+    indices: Vec<usize>,
+}
+
+impl<'a, T> IterShuffled<'a, T> {
+    pub fn new<R>(values: &'a [T], rng: &mut R) -> Self
+    where
+        R: Rng + ?Sized,
+    {
+        let nvalues = values.len();
+        let mut indices: Vec<usize> = (0..nvalues).collect();
+        indices.shuffle(rng);
+        IterShuffled { values, indices }
+    }
+}
+
+impl<'a, T> Iterator for IterShuffled<'a, T> {
+    type Item = &'a T;
+    fn next(&mut self) -> Option<Self::Item> {
+        self.indices.pop().map(|i| &self.values[i])
+    }
+}
+
+pub trait Shuffled<T> {
+    fn shuffled<R>(&self, rng: &mut R) -> IterShuffled<T>
+    where
+        R: Rng + ?Sized;
+}
+
+impl<T> Shuffled<T> for [T] {
+    fn shuffled<R>(&self, rng: &mut R) -> IterShuffled<T>
+    where
+        R: Rng + ?Sized,
+    {
+        IterShuffled::new(self, rng)
+    }
+}
+
+#[test]
+pub fn test_shuffled() {
+    let mut rng = rand::thread_rng();
+    let vals = &['a', 'b', 'c'];
+    let mut v = Vec::new();
+    for &c in vals.shuffled(&mut rng) {
+        v.push(c);
+    }
+    v.sort();
+    assert_eq!(&v, vals);
+}