Add rail-fence-cipher exercise (#665)

* Add rail-fence-cipher exercise

We already have a fair number of ciphering exercises, but a few
more never hurt.

In particular, this one is interesting because it's all about text
permutation, and it's not a block cipher: you can't generate any
subset of the message without processing the entire thing at once.

This means that it's unsuitable for standard text stream traits
such as io::Read and io::Write, but by the same token, it means we
can design a very simple API for the student to implement.

This PR includes one test not present in the canonical data. The
intent of this test is to ensure that students are handling individual
characters, not just bytes. While the general policy for exercism
is to avoid unicode unless it adds something to the exercise, I believe
that in this case it adds something to the exercise: as a text permutation
exercise, it makes sense to ensure that wide characters are handled properly.

One potential extension not included in this exercise would be to add
a case oriented around grapheme clusters. As grapheme clustering is
fairly complicated and best accomplished through the use of external
crates, such a thing would best be hidden behind a feature gate.

* implement suggested changes

Author: coriolinus

config.json

@@ -464,6 +464,18 @@
         "str_vs_string"
       ]
     },
+    {
+      "slug": "rail-fence-cipher",
+      "uuid": "9a8bae4f-2c0b-4e9e-aab2-b92f82dd3b87",
+      "core": false,
+      "unlocked_by": "atbash-cipher",
+      "difficulty": 4,
+      "topics": [
+        "chars",
+        "cipher",
+        "string_permutation"
+      ]
+    },
     {
       "slug": "etl",
       "uuid": "0c8eeef7-4bab-4cf9-9047-c208b5618312",

exercises/rail-fence-cipher/.gitignore

@@ -0,0 +1,8 @@
+# Generated by Cargo
+# will have compiled files and executables
+/target/
+**/*.rs.bk
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here http://doc.crates.io/guide.html#cargotoml-vs-cargolock
+Cargo.lock

exercises/rail-fence-cipher/Cargo.toml

@@ -0,0 +1,3 @@
+[package]
+name = "rail_fence_cipher"
+version = "1.1.0"

exercises/rail-fence-cipher/README.md

@@ -0,0 +1,119 @@
+# Rail Fence Cipher
+
+Implement encoding and decoding for the rail fence cipher.
+
+The Rail Fence cipher is a form of transposition cipher that gets its name from
+the way in which it's encoded. It was already used by the ancient Greeks.
+
+In the Rail Fence cipher, the message is written downwards on successive "rails"
+of an imaginary fence, then moving up when we get to the bottom (like a zig-zag).
+Finally the message is then read off in rows.
+
+For example, using three "rails" and the message "WE ARE DISCOVERED FLEE AT ONCE",
+the cipherer writes out:
+
+```text
+W . . . E . . . C . . . R . . . L . . . T . . . E
+. E . R . D . S . O . E . E . F . E . A . O . C .
+. . A . . . I . . . V . . . D . . . E . . . N . .
+```
+
+Then reads off:
+
+```text
+WECRLTEERDSOEEFEAOCAIVDEN
+```
+
+To decrypt a message you take the zig-zag shape and fill the ciphertext along the rows.
+
+```text
+? . . . ? . . . ? . . . ? . . . ? . . . ? . . . ?
+. ? . ? . ? . ? . ? . ? . ? . ? . ? . ? . ? . ? .
+. . ? . . . ? . . . ? . . . ? . . . ? . . . ? . .
+```
+
+The first row has seven spots that can be filled with "WECRLTE".
+
+```text
+W . . . E . . . C . . . R . . . L . . . T . . . E
+. ? . ? . ? . ? . ? . ? . ? . ? . ? . ? . ? . ? .
+. . ? . . . ? . . . ? . . . ? . . . ? . . . ? . .
+```
+
+Now the 2nd row takes "ERDSOEEFEAOC".
+
+```text
+W . . . E . . . C . . . R . . . L . . . T . . . E
+. E . R . D . S . O . E . E . F . E . A . O . C .
+. . ? . . . ? . . . ? . . . ? . . . ? . . . ? . .
+```
+
+Leaving "AIVDEN" for the last row.
+
+```text
+W . . . E . . . C . . . R . . . L . . . T . . . E
+. E . R . D . S . O . E . E . F . E . A . O . C .
+. . A . . . I . . . V . . . D . . . E . . . N . .
+```
+
+If you now read along the zig-zag shape you can read the original message.
+
+## 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, open the tests source file which is located in the `tests` directory
+and remove the `#[ignore]` flag from the next test and get the tests to pass
+again. Each separate test is a function with `#[test]` flag above it.
+Continue, until you pass every test.
+
+If you wish to run all tests without editing the tests source file, use:
+
+```bash
+$ cargo test -- --ignored
+```
+
+To run a specific test, for example `some_test`, you can use:
+
+```bash
+$ cargo test some_test
+```
+
+If the specific test is ignored use:
+
+```bash
+$ cargo test some_test -- --ignored
+```
+
+To learn more about Rust tests refer to the [online test documentation][rust-tests]
+
+Make sure to read the [Modules](https://doc.rust-lang.org/book/2018-edition/ch07-00-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 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]: https://exercism.io/tracks/rust/learning
+[modules]: https://doc.rust-lang.org/book/2018-edition/ch07-00-modules.html
+[cargo]: https://doc.rust-lang.org/book/2018-edition/ch14-00-more-about-cargo.html
+[rust-tests]: https://doc.rust-lang.org/book/2018-edition/ch11-02-running-tests.html
+
+## Source
+
+Wikipedia [https://en.wikipedia.org/wiki/Transposition_cipher#Rail_Fence_cipher](https://en.wikipedia.org/wiki/Transposition_cipher#Rail_Fence_cipher)
+
+## Submitting Incomplete Solutions
+It's possible to submit an incomplete solution so you can see how others have completed the exercise.

exercises/rail-fence-cipher/example.rs

@@ -0,0 +1,87 @@
+pub struct RailFence(u32);
+
+fn uncons(s: &str) -> (&str, &str) {
+    s.split_at(s.chars().next().map_or(0, |c| c.len_utf8()))
+}
+
+impl RailFence {
+    pub fn new(rails: u32) -> RailFence {
+        RailFence(rails)
+    }
+
+    fn next(&self, down: &mut bool, rail: &mut usize) {
+        if *down {
+            if *rail + 1 < self.0 as usize {
+                *rail += 1;
+            } else {
+                *down = false;
+                *rail -= 1;
+            }
+        } else {
+            if *rail > 0 {
+                *rail -= 1;
+            } else {
+                *down = true;
+                *rail += 1;
+            }
+        }
+    }
+
+    pub fn encode(&self, text: &str) -> String {
+        let mut rails =
+            vec![String::with_capacity(1 + (text.len() / self.0 as usize)); self.0 as usize];
+        let mut down = true;
+        let mut rail = 0;
+
+        for ch in text.chars() {
+            rails[rail].push(ch);
+            self.next(&mut down, &mut rail);
+        }
+
+        rails.join("")
+    }
+
+    pub fn decode(&self, cipher: &str) -> String {
+        let mut rail_caps = vec![0; self.0 as usize];
+        let mut down = true;
+        let mut rail = 0;
+
+        for _ in cipher.chars() {
+            rail_caps[rail] += 1;
+            self.next(&mut down, &mut rail);
+        }
+
+        // this vector owns the text of each rail
+        let mut rails_own = Vec::with_capacity(self.0 as usize);
+        let mut skip = 0;
+
+        for &cap in rail_caps.iter() {
+            rails_own.push(
+                cipher
+                    .chars()
+                    .skip(skip)
+                    .enumerate()
+                    .take_while(|&(i, _)| i < cap)
+                    .map(|(_, c)| c)
+                    .collect::<String>(),
+            );
+            skip += cap;
+        }
+
+        // this vector holds string slices viewing into rails_own
+        let mut rails: Vec<&str> = rails_own.iter().map(|r| r.as_ref()).collect();
+
+        let mut out = String::with_capacity(cipher.len());
+        down = true;
+        rail = 0;
+
+        while rails.iter().any(|r: &&str| r.len() > 0) {
+            let (head, t_rail) = uncons(rails[rail]);
+            rails[rail] = t_rail;
+            self.next(&mut down, &mut rail);
+            out.push_str(head);
+        }
+
+        out
+    }
+}

exercises/rail-fence-cipher/src/lib.rs

@@ -0,0 +1,15 @@
+pub struct RailFence;
+
+impl RailFence {
+    pub fn new(rails: u32) -> RailFence {
+        unimplemented!("Construct a new fence with {} rails", rails)
+    }
+
+    pub fn encode(&self, text: &str) -> String {
+        unimplemented!("Encode this text: {}", text)
+    }
+
+    pub fn decode(&self, cipher: &str) -> String {
+        unimplemented!("Decode this ciphertext: {}", cipher)
+    }
+}

exercises/rail-fence-cipher/tests/rail-fence-cipher.rs

@@ -0,0 +1,97 @@
+//! Tests for rail-fence-cipher
+//!
+//! Generated by [script][script] using [canonical data][canonical-data]
+//!
+//! [script]: https://github.com/exercism/rust/blob/master/bin/init_exercise.py
+//! [canonical-data]: https://raw.githubusercontent.com/exercism/problem-specifications/master/exercises/rail-fence-cipher/canonical_data.json
+//!
+//! The tests do not expect any normalization or cleaning.
+//! That trade is tested in enough other exercises.
+
+extern crate rail_fence_cipher;
+use rail_fence_cipher::*;
+
+/// Process a single test case for the property `encode`
+///
+/// All cases for the `encode` property are implemented
+/// in terms of this function.
+fn process_encode_case(input: &str, rails: u32, expected: &str) {
+    let rail_fence = RailFence::new(rails);
+    assert_eq!(rail_fence.encode(input), expected);
+}
+
+/// Process a single test case for the property `decode`
+///
+/// All cases for the `decode` property are implemented
+/// in terms of this function.
+fn process_decode_case(input: &str, rails: u32, expected: &str) {
+    let rail_fence = RailFence::new(rails);
+    assert_eq!(rail_fence.decode(input), expected);
+}
+
+// encode
+
+#[test]
+/// encode with two rails
+fn test_encode_with_two_rails() {
+    process_encode_case("XOXOXOXOXOXOXOXOXO", 2, "XXXXXXXXXOOOOOOOOO");
+}
+
+#[test]
+#[ignore]
+/// encode with three rails
+fn test_encode_with_three_rails() {
+    process_encode_case("WEAREDISCOVEREDFLEEATONCE", 3, "WECRLTEERDSOEEFEAOCAIVDEN");
+}
+
+#[test]
+#[ignore]
+/// encode with ending in the middle
+fn test_encode_with_ending_in_the_middle() {
+    process_encode_case("EXERCISES", 4, "ESXIEECSR");
+}
+
+// decode
+
+#[test]
+#[ignore]
+/// decode with three rails
+fn test_decode_with_three_rails() {
+    process_decode_case("TEITELHDVLSNHDTISEIIEA", 3, "THEDEVILISINTHEDETAILS");
+}
+
+#[test]
+#[ignore]
+/// decode with five rails
+fn test_decode_with_five_rails() {
+    process_decode_case("EIEXMSMESAORIWSCE", 5, "EXERCISMISAWESOME");
+}
+
+#[test]
+#[ignore]
+/// decode with six rails
+fn test_decode_with_six_rails() {
+    process_decode_case(
+        "133714114238148966225439541018335470986172518171757571896261",
+        6,
+        "112358132134558914423337761098715972584418167651094617711286",
+    );
+}
+
+#[test]
+#[ignore]
+/// encode wide characters
+///
+/// normally unicode is not part of exercism exercises, but in an exercise
+/// specifically oriented around shuffling characters, it seems worth ensuring
+/// that wide characters are handled properly
+///
+/// this text is possibly one of the most famous haiku of all time, by
+/// Matsuo Bashō (松尾芭蕉)
+fn test_encode_wide_characters() {
+    process_encode_case(
+        "古池 蛙飛び込む 水の音",
+        3,
+        "古飛 池蛙びむ水音 込の",
+    );
+}