grains: add approaches (#1579)

grains: add approaches

Author: bobahop

exercises/practice/grains/.approaches/bit-shifting/content.md

@@ -0,0 +1,60 @@
+# Bit-shifting
+
+```rust
+pub fn square(s: u32) -> u64 {
+    if (s < 1) | (s > 64) {
+        panic!("Square must be between 1 and 64");
+    }
+    1 << (s - 1)
+}
+
+pub fn total() -> u64 {
+    ((1_u128 << 64) - 1) as u64
+}
+```
+
+Instead of using math to calculate the number of grains on a square, you can simply set a bit in the correct position of a [`u64`][u64] or [`u128`][u128] value.
+
+To understand how this works, consider just two squares that are represented in binary bits as `00`.
+
+You use the [left-shift operator][left-shift-operator] to set `1` at the position needed to make the correct decimal value.
+- To set the one grain on Square One you shift `1` for `0` positions to the left.
+So, if `n` is `1` for square One, you subtract `n` by `1` to get `0`, which will not move it any positions to the left.
+The result is binary `01`, which is decimal `1`.
+- To set the two grains on Square Two you shift `1` for `1` position to the left.
+So, if `n` is `2` for square Two, you subtract `n` by `1` to get `1`, which will move it `1` position to the left.
+The result is binary `10`, which is decimal `2`.
+
+| Square  | Shift Left By | Binary Value | Decimal Value |
+| ------- | ------------- | ------------ | ------------- |
+|       1 |             0 |         0001 |             1 |
+|       2 |             1 |         0010 |             2 |
+|       3 |             2 |         0100 |             4 |
+|       4 |             3 |         1000 |             8 |
+
+For `total` we want all of the 64 bits set to `1` to get the sum of grains on all sixty-four squares.
+The easy way to do this is to set the 65th bit to `1` and then subtract `1`.
+However, we can't do this with a `u64` which has only `64` bits, so we need to use a `u128`.
+To go back to our two-square example, if we can grow to three squares, then we can shift `1_u128` two positions to the left for binary `100`,
+which is decimal `4`.
+
+```exercism/note
+Note that the type of a binding can be defined by appending it to the binding name.
+It can optionally be appended using one or more `_` separators between the value and the type.
+More info can be found in the [Literals](https://doc.rust-lang.org/rust-by-example/types/literals.html) section of
+[Rust by Example](https://doc.rust-lang.org/rust-by-example/index.html)
+```
+By subtracting `1` we get `3`, which is the total amount of grains on the two squares.
+
+| Square  | Binary Value | Decimal Value |
+| ------- | ------------ | ------------- |
+|       3 |         0100 |             4 |
+
+| Square  | Sum Binary Value | Sum Decimal Value |
+| ------- | ---------------- | ----------------- |
+|       1 |             0001 |                 1 |
+|       2 |             0011 |                 3 |
+
+[u64]: https://doc.rust-lang.org/std/primitive.u64.html
+[u128]: https://doc.rust-lang.org/std/primitive.u128.html
+[left-shift-operator]: https://doc.rust-lang.org/std/ops/trait.Shl.html

exercises/practice/grains/.approaches/bit-shifting/snippet.txt

@@ -0,0 +1,8 @@
+pub fn square(s: u32) -> u64 {
+    // code snipped
+    1 << (s - 1)
+}
+
+pub fn total() -> u64 {
+    ((1_u128 << 64) - 1) as u64
+}

exercises/practice/grains/.approaches/config.json

@@ -0,0 +1,28 @@
+{
+  "introduction": {
+    "authors": ["bobahop"]
+  },
+  "approaches": [
+    {
+      "uuid": "319aa2eb-512d-4133-b3da-7df83e48c87f",
+      "slug": "pow",
+      "title": "pow",
+      "blurb": "Use pow to raise 2 by a specified power.",
+      "authors": ["bobahop"]
+    },
+    {
+      "uuid": "84e5365f-3928-46b4-9750-49575dc924ae",
+      "slug": "bit-shifting",
+      "title": "Bit-shifting",
+      "blurb": "Use bit-shifting to raise 2 by a specified power.",
+      "authors": ["bobahop"]
+    },
+    {
+      "uuid": "c245c1f7-7d8c-4a73-81c4-d91ff50a5986",
+      "slug": "max-value",
+      "title": "Max value",
+      "blurb": "Use u64::MAX for total.",
+      "authors": ["bobahop"]
+    }
+  ]
+}

exercises/practice/grains/.approaches/introduction.md

@@ -0,0 +1,77 @@
+# Introduction
+
+There are various idiomatic approaches to solve Grains.
+You can use `pow` to calculate the number on grains on a square.
+Or you can use bit-shifting.
+
+## General guidance
+
+The key to solving Grains is to focus on each square having double the amount of grains as the square before it.
+This means that the amount of grains grows exponentially.
+The first square has one grain, which is `2` to the power of `0`.
+The second square has two grains, which is `2` to the power of `1`.
+The third square has four grains, which is `2` to the power of `2`.
+You can see that the exponent, or power, that `2` is raised by is always one less than the square number.
+
+| Square  | Power      | Value                   |
+| ------- | ---------- | ----------------------- |
+|       1 |          0 | 2 to the power of 0 = 1 |
+|       2 |          1 | 2 to the power of 1 = 2 |
+|       3 |          2 | 2 to the power of 2 = 4 |
+|       4 |          3 | 2 to the power of 4 = 8 |
+
+## Approach: `pow`
+
+```rust
+pub fn square(s: u32) -> u64 {
+    if (s < 1) | (s > 64) {
+        panic!("Square must be between 1 and 64");
+    }
+    2u64.pow(s - 1)
+}
+
+pub fn total() -> u64 {
+    (2_u128.pow(64) - 1) as u64
+}
+```
+
+For more information, check the [`pow` approach][approach-pow].
+
+## Approach: Bit-shifting
+
+```rust
+pub fn square(s: u32) -> u64 {
+    if (s < 1) | (s > 64) {
+        panic!("Square must be between 1 and 64");
+    }
+    1 << (s - 1)
+}
+
+pub fn total() -> u64 {
+    ((1_u128 << 64) - 1) as u64
+}
+```
+
+For more information, check the [Bit-shifting approach][approach-bit-shifting].
+
+## Other approaches
+
+Besides the aforementioned, idiomatic approaches, you could also approach the exercise as follows:
+
+### Other approach: Max value
+
+The maximum value for an unsigned integer gives the total number of grains on all sixty-four squares.
+For more information, check the [`u64::MAX` for Total Approach][approach-max-value].
+
+## Which approach to use?
+
+`pow` may be considered the most readable solution.
+
+Bit-shifting is the same measurable performance as `pow`, but may be considered less readable.
+
+For more information, check the [Performance article][article-performance].
+
+[approach-pow]: https://exercism.org/tracks/rust/exercises/grains/approaches/pow
+[approach-bit-shifting]: https://exercism.org/tracks/rust/exercises/grains/approaches/bit-shifting
+[approach-max-value]: https://exercism.org/tracks/rust/exercises/grains/approaches/max-value
+[article-performance]: https://exercism.org/tracks/rust/exercises/grains/articles/performance

exercises/practice/grains/.approaches/max-value/content.md

@@ -0,0 +1,23 @@
+# `u64::MAX` for total
+
+```rust
+pub fn total() -> u64 {
+    u64::MAX
+}
+```
+
+The maximum value for an unsigned integer gives the total number of grains on all sixty-four squares.
+It is essentially getting all of the bits of a 64-bit number set to `1`.
+
+This might seem like a "cheat".
+To understand how it works, consider just two squares that are represented in bits as `00`.
+
+- If there is a grain on square One, then the first bit (on the right) is set to binary `01`, which is the decimal value of `1`.
+- If there are two grains on square Two, then the second bit (from the right) is set to binary `10`, which is the decimal value of `2`.
+- If there are is one grain on Square One and two grains on square Two, then both bits are set to binary `11`, which is the decimal value of `3`.
+- So, with all of the two bits set you get `3`, which is the number of all grains on both squares.
+
+Getting the value of [`u64::MAX`][u64-max] is getting 64 bits set to `1`, which is just what we need to get the total number of grains on
+sixty-four squares, given that the grains double on each square, starting with one grain on the first square.
+
+[u64-max]: https://doc.rust-lang.org/std/u64/constant.MAX.html

exercises/practice/grains/.approaches/max-value/snippet.txt

@@ -0,0 +1,3 @@
+pub fn total() -> u64 {
+    u64::MAX
+}

exercises/practice/grains/.approaches/pow/content.md

@@ -0,0 +1,43 @@
+## `pow`
+
+```rust
+pub fn square(s: u32) -> u64 {
+    if (s < 1) | (s > 64) {
+        panic!("Square must be between 1 and 64");
+    }
+    2u64.pow(s - 1)
+}
+
+pub fn total() -> u64 {
+    (2_u128.pow(64) - 1) as u64
+}
+```
+
+Other languages may have an exponential operator such as `**` or `^` to raise a number by a specified power.
+Rust does not have an exponential operator, but uses the [`pow`][pow-u64] method.
+
+`pow` is nicely suited to the problem, since we start with one grain and keep doubling the number of grains on each successive square.
+`1` grain is `2u64.pow(0)`, `2` grains is `2u64.pow(1)`, `4` is `2u64.pow(2)`, and so on.
+
+```exercism/note
+Note that the type of a binding can be defined by appending it to the binding name.
+It can optionally be appended using one or more `_` separators between the value and the type.
+More info can be found in the [Literals](https://doc.rust-lang.org/rust-by-example/types/literals.html) section of
+[Rust by Example](https://doc.rust-lang.org/rust-by-example/index.html)
+```
+
+So, to get the right exponent, we subtract `1` from the square number `s`.
+
+The easiest way to get `total` is to use [`u128::pow`][pow-u128] to get the value for an imaginary 65th square,
+and then subtract `1` from it.
+To understand how that works, consider a board that has only two squares.
+If we could grow the board to three squares, then we could get the number of grains on the imaginary third square,
+which would be `4.`
+You could then subtract `4` by `1` to get `3`, which is the number of grains on the first square (`1`) and the second square (`2`).
+Remembering that the exponent must be one less than the square you want,
+you might like to call `2u64.pow(64)` to get the number of grains on the imaginary 65th square.
+However, that won't work, because the resulting number is too large for a `u64`.
+So, you can use `2u128.pow(64)`, and when it is subtracted by `1` it will then fit in the `u64` value which is returned.
+
+[pow-u64]: https://doc.rust-lang.org/std/primitive.u64.html#method.pow
+[pow-u128]: https://doc.rust-lang.org/std/primitive.u128.html#method.pow

exercises/practice/grains/.approaches/pow/snippet.txt

@@ -0,0 +1,8 @@
+pub fn square(s: u32) -> u64 {
+    // code snipped
+    2u64.pow(s - 1)
+}
+
+pub fn total() -> u64 {
+    (2_u128.pow(64) - 1) as u64
+}

exercises/practice/grains/.articles/config.json

@@ -0,0 +1,11 @@
+{
+  "articles": [
+    {
+      "uuid": "6f224b6e-6cbf-4ff6-9618-4423435084aa",
+      "slug": "performance",
+      "title": "Performance deep dive",
+      "blurb": "Deep dive to find out the most performant approach to calculating Grains.",
+      "authors": ["bobahop"]
+    }
+  ]
+}

exercises/practice/grains/.articles/performance/code/main.rs

@@ -0,0 +1,71 @@
+#![feature(test)]
+extern crate test;
+use test::Bencher;
+
+fn main() {
+    println!("Hello, world!");
+}
+
+pub fn square_bit(s: u32) -> u64 {
+    if (s < 1) | (s > 64) {
+        panic!("Square must be between 1 and 64");
+    }
+    1 << (s - 1)
+}
+
+pub fn total_bit() -> u64 {
+    ((1_u128 << 64) - 1) as u64
+}
+
+pub fn square_pow(s: u32) -> u64 {
+    if (s < 1) | (s > 64) {
+        panic!("Square must be between 1 and 64");
+    }
+    2u64.pow(s - 1)
+}
+
+pub fn total_pow_u128() -> u64 {
+    (2_u128.pow(64) - 1) as u64
+}
+
+pub fn total_pow_fold() -> u64 {
+    (1_u32..=64_u32).fold(0u64, |total, num| total + square_pow(num))
+}
+
+pub fn total_pow_for() -> u64 {
+    let mut accum = 0;
+    for i in 1..=64 {
+        accum += square_pow(i)
+    }
+    accum
+}
+
+#[bench]
+fn test_square_bit(b: &mut Bencher) {
+    b.iter(|| square_bit(64));
+}
+
+#[bench]
+fn test_total_bit(b: &mut Bencher) {
+    b.iter(|| total_bit());
+}
+
+#[bench]
+fn test_square_pow(b: &mut Bencher) {
+    b.iter(|| square_pow(64));
+}
+
+#[bench]
+fn test_total_pow_u128(b: &mut Bencher) {
+    b.iter(|| total_pow_u128());
+}
+
+#[bench]
+fn test_total_pow_fold(b: &mut Bencher) {
+    b.iter(|| total_pow_fold());
+}
+
+#[bench]
+fn test_total_pow_for(b: &mut Bencher) {
+    b.iter(|| total_pow_for());
+}