Add two-bucket test

This test is listed in the problem-specifications repo ([1]), but hadn't been
added to the rust track yet. This commit adds the description, test
cases, and a sample solution based on breadth-first search.

[1] https://github.com/exercism/problem-specifications/blob/master/exercises/two-bucket

exercises/two-bucket/Cargo.toml

@@ -0,0 +1,3 @@
+[package]
+name = "two-bucket"
+version = "1.0.0"

exercises/two-bucket/README.md

@@ -0,0 +1,65 @@
+# Two Buckets
+
+Given two buckets of different size, demonstrate how to measure an exact number of liters by strategically transferring liters of fluid between the buckets.
+
+Since this mathematical problem is fairly subject to interpretation / individual approach, the tests have been written specifically to expect one overarching solution.
+
+To help, the tests provide you with which bucket to fill first. That means, when starting with the larger bucket full, you are NOT allowed at any point to have the smaller bucket full and the larger bucket empty (aka, the opposite starting point); that would defeat the purpose of comparing both approaches!
+
+Your program will take as input:
+- the size of bucket one, passed as a numeric value
+- the size of bucket two, passed as a numeric value
+- the desired number of liters to reach, passed as a numeric value
+- which bucket to fill first, passed as a String (either 'one' or 'two')
+
+Your program should determine:
+- the total number of "moves" it should take to reach the desired number of liters, including the first fill - expects a numeric value
+- which bucket should end up with the desired number of liters (let's say this is bucket A) - expects a String (either 'one' or 'two')
+- how many liters are left in the other bucket (bucket B) - expects a numeric value
+
+Note: any time a change is made to either or both buckets counts as one (1) move.
+
+Example:
+Bucket one can hold up to 7 liters, and bucket two can hold up to 11 liters. Let's say bucket one, at a given step, is holding 7 liters, and bucket two is holding 8 liters (7,8). If you empty bucket one and make no change to bucket two, leaving you with 0 liters and 8 liters respectively (0,8), that counts as one "move". Instead, if you had poured from bucket one into bucket two until bucket two was full, leaving you with 4 liters in bucket one and 11 liters in bucket two (4,11), that would count as only one "move" as well.
+
+To conclude, the only valid moves are:
+- pouring from one bucket to another
+- emptying one bucket and doing nothing to the other
+- filling one bucket and doing nothing to the other
+
+Written with <3 at [Fullstack Academy](http://www.fullstackacademy.com/) by [Lindsay](http://lindsaylevine.com).
+
+## Rust Installation
+
+Refer to the [exercism help page][help-page] for Rust installation and learning
+resources.
+
+## Writing the Code
+
+Execute the tests with:
+
+```bash
+$ cargo test
+```
+
+All but the first test have been ignored.  After you get the first test to
+pass, remove the ignore flag (`#[ignore]`) from the next test and get the tests
+to pass again.  The test file is located in the `tests` directory.   You can
+also remove the ignore flag from all the tests to get them to run all at once
+if you wish.
+
+Make sure to read the [Crates and Modules](https://doc.rust-lang.org/stable/book/crates-and-modules.html) chapter if you
+haven't already, it will help you with organizing your files.
+
+## Feedback, Issues, Pull Requests
+
+The [exercism/rust](https://github.com/exercism/rust) repository on GitHub is the home for all of the Rust exercises. If you have feedback about an exercise, or want to help implement new exercises, head over there and create an issue. Members of the [rust track team](https://github.com/orgs/exercism/teams/rust) are happy to help!
+
+If you want to know more about Exercism, take a look at the [contribution guide](https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/README.md).
+
+[help-page]: http://exercism.io/languages/rust
+[crates-and-modules]: http://doc.rust-lang.org/stable/book/crates-and-modules.html
+
+
+## Submitting Incomplete Solutions
+It's possible to submit an incomplete solution so you can see how others have completed the exercise.

exercises/two-bucket/example.rs

@@ -0,0 +1,126 @@
+use std::collections::{HashSet, VecDeque};
+
+// We can turn this problem into a simple graph searching problem. Each move represents an
+// edge in our graph; the buckets' fill states form the graph's vertices. For example, say bucket
+// one holds up to 7 liters, and bucket two holds up to 11 liters, and at the current step, bucket
+// one has 7 liters and bucket two has 8 liters: (7, 8). By emptying the first bucket, we form an
+// edge (7, 8) -> (0, 8). Similarly, by pouring the first bucket into the second, we form an edge
+// (7, 8) -> (4, 11).
+//
+// Since we want to minimize the number of moves, we search the graph breadth-first, starting with
+// the configuration provided as the problem input. Note that, to avoid cheating, we mark both
+// possible starting configurations as visited; otherwise, our search might just empty the initial
+// bucket and fill the other one.
+
+/// A struct to hold your results in.
+#[derive(PartialEq, Eq, Debug)]
+pub struct BucketStats<'a> {
+    /// The total number of "moves" it should take to reach the desired number of liters, including
+    /// the first fill.
+    pub moves: u8,
+    /// Which bucket should end up with the desired number of liters? (Either "one" or "two")
+    pub goal_bucket: &'a str,
+    /// How many liters are left in the other bucket?
+    pub other_bucket: u8,
+}
+
+
+/// Solve the bucket problem
+pub fn solve(capacity_1: u8,
+             capacity_2: u8,
+             goal: u8,
+             start_bucket: &str) -> BucketStats
+{
+    let state = match start_bucket {
+        "one" => (capacity_1, 0),
+        "two" => (0, capacity_2),
+        _ => panic!("Invalid start bucket"),
+    };
+
+    let mut next_search = VecDeque::new();
+    let mut visited = HashSet::new();
+    let mut moves = 1;
+
+    next_search.push_front(state);
+
+    // "Visit" both starting states. This will ensure that we don't cheat, i.e.
+    // empty our starting bucket completely and fill the other bucket.
+    visited.insert((capacity_1, 0));
+    visited.insert((0, capacity_2));
+
+    loop {
+        let mut current_search = next_search;
+        next_search = VecDeque::new();
+
+        for state in current_search.drain(0..) {
+            let (bucket_1, bucket_2) = state;
+
+            if bucket_1 == goal {
+                return BucketStats {
+                    moves: moves,
+                    goal_bucket: "one",
+                    other_bucket: bucket_2,
+                };
+            } else if bucket_2 == goal {
+                return BucketStats {
+                    moves: moves,
+                    goal_bucket: "two",
+                    other_bucket: bucket_1,
+                };
+            }
+
+            // Empty the first bucket
+            let empty_1 = (0, bucket_2);
+            if !visited.contains(&empty_1) {
+                next_search.push_front(empty_1);
+                visited.insert(empty_1);
+            }
+
+            // Empty the second bucket
+            let empty_2 = (bucket_1, 0);
+            if !visited.contains(&empty_2) {
+                next_search.push_front(empty_2);
+                visited.insert(empty_2);
+            }
+
+            // Fill the first bucket
+            let fill_1 = (capacity_1, bucket_2);
+            if !visited.contains(&fill_1) {
+                next_search.push_front(fill_1);
+                visited.insert(fill_1);
+            }
+
+            // Fill the second bucket
+            let fill_2 = (bucket_1, capacity_2);
+            if !visited.contains(&fill_2) {
+                next_search.push_front(fill_2);
+                visited.insert(fill_2);
+            }
+
+            // Pour the first bucket into the second bucket
+            let pour_1_into_2 = if bucket_1 + bucket_2 <= capacity_1 {
+                (bucket_1 + bucket_2, 0)
+            } else {
+                (capacity_1, bucket_1 + bucket_2 - capacity_1)
+            };
+            if !visited.contains(&pour_1_into_2) {
+                next_search.push_front(pour_1_into_2);
+                visited.insert(pour_1_into_2);
+            }
+
+            // Pour the second bucket into the first bucket
+            let pour_2_into_1 = if bucket_1 + bucket_2 <= capacity_2 {
+                (0, bucket_1 + bucket_2)
+            } else {
+                (bucket_1 + bucket_2 - capacity_2, capacity_2)
+            };
+            if !visited.contains(&pour_2_into_1) {
+                next_search.push_front(pour_2_into_1);
+                visited.insert(pour_2_into_1);
+            }
+        }
+
+        moves += 1;
+    }
+}
+

exercises/two-bucket/src/lib.rs

@@ -0,0 +1,24 @@
+/// A struct to hold your results in.
+#[derive(PartialEq, Eq, Debug)]
+pub struct BucketStats<'a> {
+    /// The total number of "moves" it should take to reach the desired number of liters, including
+    /// the first fill.
+    pub moves: u8,
+    /// Which bucket should end up with the desired number of liters? (Either "one" or "two")
+    pub goal_bucket: &'a str,
+    /// How many liters are left in the other bucket?
+    pub other_bucket: u8,
+}
+
+/// Solve the bucket problem
+pub fn solve(_capacity_1: u8,
+             _capacity_2: u8,
+             _goal: u8,
+             _start_bucket: &str) -> BucketStats
+{
+    return BucketStats {
+        moves: 0,
+        goal_bucket: "one",
+        other_bucket: 0,
+    };
+}

exercises/two-bucket/tests/two-bucket.rs

@@ -0,0 +1,68 @@
+extern crate two_bucket;
+
+use two_bucket::{solve, BucketStats};
+
+#[test]
+fn test_case_1() {
+    assert_eq!(solve(3, 5, 1, "one"),
+               BucketStats {
+                   moves: 4,
+                   goal_bucket: "one",
+                   other_bucket: 5,
+               });
+}
+
+#[test]
+#[ignore]
+fn test_case_2() {
+    assert_eq!(solve(3, 5, 1, "two"),
+               BucketStats {
+                   moves: 8,
+                   goal_bucket: "two",
+                   other_bucket: 3,
+               });
+}
+
+#[test]
+#[ignore]
+fn test_case_3() {
+    assert_eq!(solve(7, 11, 2, "one"),
+               BucketStats {
+                   moves: 14,
+                   goal_bucket: "one",
+                   other_bucket: 11,
+               });
+}
+
+#[test]
+#[ignore]
+fn test_case_4() {
+    assert_eq!(solve(7, 11, 2, "two"),
+               BucketStats {
+                   moves: 18,
+                   goal_bucket: "two",
+                   other_bucket: 7,
+               });
+}
+
+#[test]
+#[ignore]
+fn test_case_5() {
+    assert_eq!(solve(1, 3, 3, "two"),
+               BucketStats {
+                   moves: 1,
+                   goal_bucket: "two",
+                   other_bucket: 0,
+               });
+}
+
+#[test]
+#[ignore]
+fn test_case_6() {
+    assert_eq!(solve(2, 3, 3, "one"),
+               BucketStats {
+                   moves: 2,
+                   goal_bucket: "two",
+                   other_bucket: 2,
+               });
+}