allergies: add approaches (#1629)

Add approaches for the `allergies` exercise

Author: bobahop

exercises/practice/allergies/.approaches/config.json

@@ -0,0 +1,22 @@
+{
+  "introduction": {
+    "authors": ["bobahop"],
+    "contributors": []
+  },
+  "approaches": [
+    {
+      "uuid": "78997b92-fed7-484d-a6bf-aece9df9ab59",
+      "slug": "vec-on-new",
+      "title": "Create Vec on new",
+      "blurb": "Create and store Vec on new.",
+      "authors": ["bobahop"]
+    },
+    {
+      "uuid": "019c4a1a-e690-480c-96a2-e1221d48baff",
+      "slug": "vec-when-requested",
+      "title": "Create Vec when requested",
+      "blurb": "Store as u32 and create Vec when requested.",
+      "authors": ["bobahop"]
+    }
+  ]
+}

exercises/practice/allergies/.approaches/introduction.md

@@ -0,0 +1,135 @@
+# Introduction
+
+There is more than one way to solve Allergies.
+One approach can be to create a [`Vec`][vec] of `Allergen` values when the `Allergies` struct is created.
+Another approach can be to store the `Allergen` values as a [`u32`][u32] and only output a `Vec` of `Allergen` values when requested.
+
+## General guidance
+
+Something to keep in mind is to leverage [bitwise][bitwise] operations to implement the logic.
+
+
+## Approach: Create `Vec` on `new()`
+
+```rust
+pub struct Allergies {
+    allergens: Vec<Allergen>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Allergen {
+    Eggs = 1,
+    Peanuts = 2,
+    Shellfish = 4,
+    Strawberries = 8,
+    Tomatoes = 16,
+    Chocolate = 32,
+    Pollen = 64,
+    Cats = 128,
+}
+
+use self::Allergen::*;
+const ALLERGENS: [Allergen; 8] = [
+    Eggs,
+    Peanuts,
+    Shellfish,
+    Strawberries,
+    Tomatoes,
+    Chocolate,
+    Pollen,
+    Cats,
+];
+
+impl Allergies {
+    pub fn new(score: u32) -> Self {
+        Self {
+            allergens: Self::calculate_allergens(score),
+        }
+    }
+
+    pub fn is_allergic_to(&self, allergen: &Allergen) -> bool {
+        self.allergens.iter().any(|allergy| allergy == allergen)
+    }
+
+    pub fn allergies(&self) -> Vec<Allergen> {
+        self.allergens.clone()
+    }
+
+    fn calculate_allergens(score: u32) -> Vec<Allergen> {
+        let mut allergens = Vec::<Allergen>::new();
+
+        for flag in 0..=7 {
+            if score & 1 << flag != 0 {
+                allergens.push(ALLERGENS[flag as usize]);
+            }
+        }
+        allergens
+    }
+}
+```
+
+For more information, check the [create `Vec` on `new()` approach][approach-vec-on-new].
+
+## Approach: Create `Vec` when requested
+
+```rust
+#[derive(Debug, PartialEq, Copy, Clone)]
+pub enum Allergen {
+    Eggs = 1 << 0,
+    Peanuts = 1 << 1,
+    Shellfish = 1 << 2,
+    Strawberries = 1 << 3,
+    Tomatoes = 1 << 4,
+    Chocolate = 1 << 5,
+    Pollen = 1 << 6,
+    Cats = 1 << 7,
+}
+
+use self::Allergen::*;
+const ALLERGENS: [Allergen; 8] = [
+    Eggs,
+    Peanuts,
+    Shellfish,
+    Strawberries,
+    Tomatoes,
+    Chocolate,
+    Pollen,
+    Cats,
+];
+pub struct Allergies {
+    allergens: u32,
+}
+
+impl Allergies {
+    pub fn new(n: u32) -> Allergies {
+        Allergies { allergens: n }
+    }
+    
+    pub fn is_allergic_to(&self, allergen: &Allergen) -> bool {
+        self.allergens & *allergen as u32 != 0
+    }
+    
+    pub fn allergies(&self) -> Vec<Allergen> {
+        ALLERGENS
+            .iter()
+            .filter(|a| self.is_allergic_to(a))
+            .cloned()
+            .collect()
+    }
+}
+```
+
+For more information, check the [create `Vec` when requested approach][approach-vec-when-requested].
+
+## Which approach to use?
+
+Since benchmarking is currently outside the scope of this document, which to use is pretty much a matter of personal preference.
+To create the `Vec` on `new()` may be considered wasteful if the `allergies()` method is never called.
+On the other hand, if the `allergies()` method is called more than once on the same struct, then it may be considered wasteful
+to create the `Vec` multiple times.
+
+[vec]: https://doc.rust-lang.org/std/vec/struct.Vec.html
+[u32]: https://doc.rust-lang.org/std/primitive.u32.html
+[bitwise]: https://www.tutorialspoint.com/rust/rust_bitwise_operators.htm
+[approach-vec-on-new]: https://exercism.org/tracks/rust/exercises/allergies/approaches/vec-on-new
+[approach-vec-when-requested]: https://exercism.org/tracks/rust/exercises/allergies/approaches/vec-when-requested

exercises/practice/allergies/.approaches/vec-on-new/content.md

@@ -0,0 +1,104 @@
+# Create `Vec` on `new()`
+
+```rust
+pub struct Allergies {
+    allergens: Vec<Allergen>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Allergen {
+    Eggs = 1,
+    Peanuts = 2,
+    Shellfish = 4,
+    Strawberries = 8,
+    Tomatoes = 16,
+    Chocolate = 32,
+    Pollen = 64,
+    Cats = 128,
+}
+
+use self::Allergen::*;
+const ALLERGENS: [Allergen; 8] = [
+    Eggs,
+    Peanuts,
+    Shellfish,
+    Strawberries,
+    Tomatoes,
+    Chocolate,
+    Pollen,
+    Cats,
+];
+
+impl Allergies {
+    pub fn new(score: u32) -> Self {
+        Self {
+            allergens: Self::calculate_allergens(score),
+        }
+    }
+
+    pub fn is_allergic_to(&self, allergen: &Allergen) -> bool {
+        self.allergens.iter().any(|allergy| allergy == allergen)
+    }
+
+    pub fn allergies(&self) -> Vec<Allergen> {
+        self.allergens.clone()
+    }
+
+    fn calculate_allergens(score: u32) -> Vec<Allergen> {
+        let mut allergens = Vec::<Allergen>::new();
+
+        for flag in 0..=7 {
+            if score & 1 << flag != 0 {
+                allergens.push(ALLERGENS[flag as usize]);
+            }
+        }
+        allergens
+    }
+}
+```
+
+This approach starts by defining the `Allergies` struct with an `allergens` field of `Vec<Allergens>` type.
+
+Since the values of the `Allergen` enum are primitive numeric types, the [`Copy`][copy] trait is derived when defining the enum.
+[`Clone`][clone] is a supertrait of `Copy`, so everything which is `Copy` must also implement `Clone`, so `Clone` is derived as well.
+
+The `use self::Allergen::*;` line is so that the `Allergen` values can be referred to directly in the file,
+instead of needing to prefix every value with `Allergen`, e.g. 'Allergen::Eggs`.
+
+A fixed-size [array][array] is defined to hold the `Allergen` values in order, as enum values are not ordered to be acccessible by index.
+
+The `[Allergen; 8]` is used to give the type and length of the array.
+To be a [`const`][const], the size of the array must be known at compile time, so setting the type and length must be done explicitly,
+so the size in bytes of the fixed array can be deduced by the compiler from that and not by inspecting the element types and counting
+the elements itself.
+
+Next, the methods for the `Allergies` struct are implemented.
+
+The `new()` method uses the `calculate_allergens()` method to set the `allergens` field for a new `Allergies` struct.
+
+The `is_allergic_to()` method uses the [`any()`][any] method to see if the passed-in `Allergen` is contained in the `allergens`
+field, which is a `Vec` of `Allergen` values.
+
+The `allergies()` method uses the [`clone()`][clone-method] method to return a copy of the `allergens` `Vec`.
+Since the `Allergen` values derive from `Copy`, they are inexpensively copied.
+
+The `calculate_allergens()` method uses [`for` and `range`][for-and-range] to iterate through the indexes of the `ALLERGENS` array.
+The [bitwise AND operator][bitand] (`&`) is used to compare the score with `1` [shifted left][shl] (`<<`) for the value of the `flag`.
+
+So, if `flag` is `0`, then `1` is shifted left `0` places, and the score is compared with bitwise `1`, which is also decimal `1`.
+If the comparison is not `0`, then the score contains the `Allergen`, and the `ALLERGEN` at the index of the `flag` value (`Eggs`) is pushed
+to the output `Vec`.
+
+if `flag` is `7`, then `1` is shifted left `7` places, and the score is compared with bitwise `10000000`, which is decimal `128`.
+If the comparison is not `0`, then the score contains the `Allergen`, and the `ALLERGEN` at the index of the `flag` value (`Cats`) is pushed
+to the output `Vec`.
+
+[copy]: https://doc.rust-lang.org/std/marker/trait.Copy.html
+[clone]: https://doc.rust-lang.org/std/clone/trait.Clone.html
+[array]: https://doc.rust-lang.org/std/primitive.array.html
+[const]: https://doc.rust-lang.org/std/keyword.const.html
+[any]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.any
+[clone-method]: https://doc.rust-lang.org/std/clone/trait.Clone.html#tymethod.clone
+[for-and-range]: https://doc.rust-lang.org/rust-by-example/flow_control/for.html
+[bitand]: https://doc.rust-lang.org/std/ops/trait.BitAnd.html
+[shl]: https://doc.rust-lang.org/std/ops/trait.Shl.html

exercises/practice/allergies/.approaches/vec-on-new/snippet.txt

@@ -0,0 +1,8 @@
+fn calculate_allergens(score: u32) -> Vec<Allergen> {
+    let mut allergens = Vec::<Allergen>::new();
+    for flag in 0..=7 {
+        if score & 1 << flag != 0 {
+            allergens.push(ALLERGENS[flag as usize]);
+        }
+    }
+    allergens

exercises/practice/allergies/.approaches/vec-when-requested/content.md

@@ -0,0 +1,105 @@
+# Create `Vec` when requested
+
+```rust
+#[derive(Debug, PartialEq, Copy, Clone)]
+pub enum Allergen {
+    Eggs = 1 << 0,
+    Peanuts = 1 << 1,
+    Shellfish = 1 << 2,
+    Strawberries = 1 << 3,
+    Tomatoes = 1 << 4,
+    Chocolate = 1 << 5,
+    Pollen = 1 << 6,
+    Cats = 1 << 7,
+}
+
+use self::Allergen::*;
+const ALLERGENS: [Allergen; 8] = [
+    Eggs,
+    Peanuts,
+    Shellfish,
+    Strawberries,
+    Tomatoes,
+    Chocolate,
+    Pollen,
+    Cats,
+];
+pub struct Allergies {
+    allergens: u32,
+}
+
+impl Allergies {
+    pub fn new(n: u32) -> Allergies {
+        Allergies { allergens: n }
+    }
+    
+    pub fn is_allergic_to(&self, allergen: &Allergen) -> bool {
+        self.allergens & *allergen as u32 != 0
+    }
+    
+    pub fn allergies(&self) -> Vec<Allergen> {
+        ALLERGENS
+            .iter()
+            .filter(|a| self.is_allergic_to(a))
+            .cloned()
+            .collect()
+    }
+}
+```
+
+This approach starts by defining the `Allergen` enum.
+Since the values of the `Allergen` enum are primitive numeric types, the [`Copy`][copy] trait is derived when defining the enum.
+[`Clone`][clone] is a supertrait of `Copy`, so everything which is `Copy` must also implement `Clone`, so `Clone` is derived as well.
+
+The `use self::Allergen::*;` line is so that the `Allergen` values can be referred to directly in the file,
+instead of needing to prefix every value with `Allergen`, e.g. 'Allergen::Eggs`.
+
+A fixed-size [array][array] is defined to hold the `Allergen` values as a way to iterate the enum values without requiring an external crate.
+
+The `[Allergen; 8]` is used to give the type and length of the array.
+To be a [`const`][const], the size of the array must be known at compile time, so setting the type and length must be done explicitly,
+so the size in bytes of the fixed array can be deduced by the compiler from that and not by inspecting the element types and counting
+the elements itself.
+
+The `Allergies` struct is defined with its `allergens` field given the type of [`u32`][u32].
+
+Next, the methods for the `Allergies` struct are implemented.
+
+The `new()` method sets its `allergens` field to the `u232` value passed in.
+
+The `is_allergic_to()` method uses the [bitwise AND operator][bitand] (`&`) to compare the `Allergen` passed in with the `allergens` `u32` field.
+The dereferenced `Allergen` passed in is [cast][cast] to a `u32` for the purpose of comparison with the `allergens` `u32` value.
+The method returns if the comparison is not `0`. 
+If the comparison is not `0`, then the `allergens` field contains the value of the `Allergen`, and `true` is returned.
+
+For example, if the `allergens` field is decimal `3`, it is binary `11`.
+If the passed-in `Allergen` is `Peanuts`, which is the value `2` decimal, `10` binary, then `10` ANDed with `11` is `10`, not `0`,
+and so the method would return `true`.
+
+If the passed-in `Allergen` is `Shellfish`, which is the value `4` decimal, `100` binary, then `100` ANDed with `011` is `0`,
+and so the method would return `false`.
+
+The `allergies()` method iterates through the `ALLERGENS` array, passing each element of the array to the [`filter()`][filter] method.
+The [closure][closure] (also known as a lambda), returns the result of passing the `Allergen` to the `is_allergic_to()` method.
+The elements that survive the test of being present in the `allergens` field are passed to the [`cloned()`][cloned] method. which
+converts the iterator of references to `Allergen` values to an iterator of copies of the `Allergen` values.
+Since the `Allergen` values derive from `Copy`, they are inexpensively copied.
+The cloned elements are chained to the [`collect()`][collect] method, which uses [type inference][type-inference] to collect
+the elements into a `Vec<Allergen>` as defined in the method signature for the return value.
+
+[copy]: https://doc.rust-lang.org/std/marker/trait.Copy.html
+[clone]: https://doc.rust-lang.org/std/clone/trait.Clone.html
+[array]: https://doc.rust-lang.org/std/primitive.array.html
+[const]: https://doc.rust-lang.org/std/keyword.const.html
+[u32]: https://doc.rust-lang.org/std/primitive.u32.html
+[any]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.any
+[clone-method]: https://doc.rust-lang.org/std/clone/trait.Clone.html#tymethod.clone
+[for-and-range]: https://doc.rust-lang.org/rust-by-example/flow_control/for.html
+[bitand]: https://doc.rust-lang.org/std/ops/trait.BitAnd.html
+[shl]: https://doc.rust-lang.org/std/ops/trait.Shl.html
+[cast]: https://doc.rust-lang.org/1.8.0/book/casting-between-types.html
+[filter]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.filter
+[closure]: https://doc.rust-lang.org/rust-by-example/fn/closures.html
+[cloned]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.cloned
+[collect]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.collect
+[type-inference]: https://doc.rust-lang.org/rust-by-example/types/inference.html

exercises/practice/allergies/.approaches/vec-when-requested/snippet.txt

@@ -0,0 +1,7 @@
+pub fn allergies(&self) -> Vec<Allergen> {
+    ALLERGENS
+        .iter()
+        .filter(|a| self.is_allergic_to(a))
+        .cloned()
+        .collect()
+}