Merge branch 'exercism:main' into main

dem4ron · web-flow · commit abb08c457476 · 2023-03-09T23:55:49.000+01:00
diff --git a/exercises/practice/binary-search/.docs/instructions.md b/exercises/practice/binary-search/.docs/instructions.md
@@ -1,35 +1,28 @@
 # Instructions
 
-Implement a binary search algorithm.
+Your task is to implement a binary search algorithm.
 
-Searching a sorted collection is a common task. A dictionary is a sorted
-list of word definitions. Given a word, one can find its definition. A
-telephone book is a sorted list of people's names, addresses, and
-telephone numbers. Knowing someone's name allows one to quickly find
-their telephone number and address.
+A binary search algorithm finds an item in a list by repeatedly splitting it in half, only keeping the half which contains the item we're looking for.
+It allows us to quickly narrow down the possible locations of our item until we find it, or until we've eliminated all possible locations.
 
-If the list to be searched contains more than a few items (a dozen, say)
-a binary search will require far fewer comparisons than a linear search,
-but it imposes the requirement that the list be sorted.
+```exercism/caution
+Binary search only works when a list has been sorted.
+```
 
-In computer science, a binary search or half-interval search algorithm
-finds the position of a specified input value (the search "key") within
-an array sorted by key value.
+The algorithm looks like this:
 
-In each step, the algorithm compares the search key value with the key
-value of the middle element of the array.
+- Divide the sorted list in half and compare the middle element with the item we're looking for.
+- If the middle element is our item, then we're done.
+- If the middle element is greater than our item, we can eliminate that number and all the numbers **after** it.
+- If the middle element is less than our item, we can eliminate that number and all the numbers **before** it.
+- Repeat the process on the part of the list that we kept.
 
-If the keys match, then a matching element has been found and its index,
-or position, is returned.
+Here's an example:
 
-Otherwise, if the search key is less than the middle element's key, then
-the algorithm repeats its action on the sub-array to the left of the
-middle element or, if the search key is greater, on the sub-array to the
-right.
+Let's say we're looking for the number 23 in the following sorted list: `[4, 8, 12, 16, 23, 28, 32]`.
 
-If the remaining array to be searched is empty, then the key cannot be
-found in the array and a special "not found" indication is returned.
-
-A binary search halves the number of items to check with each iteration,
-so locating an item (or determining its absence) takes logarithmic time.
-A binary search is a dichotomic divide and conquer search algorithm.
+- We start by comparing 23 with the middle element, 16.
+- Since 23 is greater than 16, we can eliminate the left half of the list, leaving us with `[23, 28, 32]`.
+- We then compare 23 with the new middle element, 28.
+- Since 23 is less than 28, we can eliminate the right half of the list: `[23]`.
+- We've found our item.
diff --git a/exercises/practice/binary-search/.docs/introduction.md b/exercises/practice/binary-search/.docs/introduction.md
@@ -0,0 +1,9 @@
+# Introduction
+
+You have stumbled upon a group of mathematicians who are also singer-songwriters.
+They have written a song for each of their favorite numbers, and, as you can imagine, they have a lot of favorite numbers.
+
+You are curious to hear the song for your favorite number, but with so many songs to wade through, finding the right song could take a while.
+Fortunately, they have organized their songs in a playlist sorted by the title — which is simply the number that the song is about.
+
+You realize that you can use a binary search algorithm to quickly find a song given the title.
diff --git a/exercises/practice/bob/.docs/instructions.md b/exercises/practice/bob/.docs/instructions.md
@@ -1,16 +1,19 @@
 # Instructions
 
-Bob is a lackadaisical teenager. In conversation, his responses are very limited.
+Your task is to determine what Bob will reply to someone when they say something to him or ask him a question.
 
-Bob answers 'Sure.' if you ask him a question, such as "How are you?".
+Bob only ever answers one of five things:
 
-He answers 'Whoa, chill out!' if you YELL AT HIM (in all capitals).
-
-He answers 'Calm down, I know what I'm doing!' if you yell a question at him.
-
-He says 'Fine. Be that way!' if you address him without actually saying
-anything.
-
-He answers 'Whatever.' to anything else.
-
-Bob's conversational partner is a purist when it comes to written communication and always follows normal rules regarding sentence punctuation in English.
+- **"Sure."**
+  This is his response if you ask him a question, such as "How are you?"
+  The convention used for questions is that it ends with a question mark.
+- **"Whoa, chill out!"**
+  This is his answer if you YELL AT HIM.
+  The convention used for yelling is ALL CAPITAL LETTERS.
+- **"Calm down, I know what I'm doing!"**
+  This is what he says if you yell a question at him.
+- **"Fine. Be that way!"**
+  This is how he responds to silence.
+  The convention used for silence is nothing, or various combinations of whitespace characters.
+- **"Whatever."**
+  This is what he answers to anything else.
diff --git a/exercises/practice/bob/.docs/introduction.md b/exercises/practice/bob/.docs/introduction.md
@@ -0,0 +1,10 @@
+# Introduction
+
+Bob is a [lackadaisical][] teenager.
+He likes to think that he's very cool.
+And he definitely doesn't get excited about things.
+That wouldn't be cool.
+
+When people talk to him, his responses are pretty limited.
+
+[lackadaisical]: https://www.collinsdictionary.com/dictionary/english/lackadaisical
diff --git a/exercises/practice/gigasecond/.docs/instructions.md b/exercises/practice/gigasecond/.docs/instructions.md
@@ -1,6 +1,8 @@
 # Instructions
 
-Given a moment, determine the moment that would be after a gigasecond
-has passed.
+Your task is to determine the date and time one gigasecond after a certain date.
 
-A gigasecond is 10^9 (1,000,000,000) seconds.
+A gigasecond is one thousand million seconds.
+That is a one with nine zeros after it.
+
+If you were born on _January 24th, 2015 at 22:00 (10:00:00pm)_, then you would be a gigasecond old on _October 2nd, 2046 at 23:46:40 (11:46:40pm)_.
diff --git a/exercises/practice/gigasecond/.docs/introduction.md b/exercises/practice/gigasecond/.docs/introduction.md
@@ -0,0 +1,24 @@
+# Introduction
+
+The way we measure time is kind of messy.
+We have 60 seconds in a minute, and 60 minutes in an hour.
+This comes from ancient Babylon, where they used 60 as the basis for their number system.
+We have 24 hours in a day, 7 days in a week, and how many days in a month?
+Well, for days in a month it depends not only on which month it is, but also on what type of calendar is used in the country you live in.
+
+What if, instead, we only use seconds to express time intervals?
+Then we can use metric system prefixes for writing large numbers of seconds in more easily comprehensible quantities.
+
+- A food recipe might explain that you need to let the brownies cook in the oven for two kiloseconds (that's two thousand seconds).
+- Perhaps you and your family would travel to somewhere exotic for two megaseconds (that's two million seconds).
+- And if you and your spouse were married for _a thousand million_ seconds, you would celebrate your one gigasecond anniversary.
+
+```exercism/note
+If we ever colonize Mars or some other planet, measuring time is going to get even messier.
+If someone says "year" do they mean a year on Earth or a year on Mars?
+
+The idea for this exercise came from the science fiction novel ["A Deepness in the Sky"][vinge-novel] by author Vernor Vinge.
+In it the author uses the metric system as the basis for time measurements.
+
+[vinge-novel]: https://www.tor.com/2017/08/03/science-fiction-with-something-for-everyone-a-deepness-in-the-sky-by-vernor-vinge/
+```
diff --git a/exercises/practice/paasio/src/lib.rs b/exercises/practice/paasio/src/lib.rs
@@ -1,5 +1,8 @@
 use std::io::{Read, Result, Write};
 
+// the PhantomData instances in this file are just to stop compiler complaints
+// about missing generics; feel free to remove them
+
 pub struct ReadStats<R>(::std::marker::PhantomData<R>);
 
 impl<R: Read> ReadStats<R> {
diff --git a/exercises/practice/pangram/.docs/instructions.md b/exercises/practice/pangram/.docs/instructions.md
@@ -1,9 +1,8 @@
 # Instructions
 
-Determine if a sentence is a pangram. A pangram (Greek: παν γράμμα, pan gramma,
-"every letter") is a sentence using every letter of the alphabet at least once.
-The best known English pangram is:
-> The quick brown fox jumps over the lazy dog.
+Your task is to figure out if a sentence is a pangram.
 
-The alphabet used consists of ASCII letters `a` to `z`, inclusive, and is case
-insensitive. Any characters which are not an ASCII letter should be ignored.
+A pangram is a sentence using every letter of the alphabet at least once.
+It is case insensitive, so it doesn't matter if a letter is lower-case (e.g. `k`) or upper-case (e.g. `K`).
+
+For this exercise we only use the basic letters used in the English alphabet: `a` to `z`.
diff --git a/exercises/practice/pangram/.docs/introduction.md b/exercises/practice/pangram/.docs/introduction.md
@@ -0,0 +1,16 @@
+# Introduction
+
+You work for a company that sells fonts through their website.
+They'd like to show a different sentence each time someone views a font on their website.
+To give a comprehensive sense of the font, the random sentences should use **all** the letters in the English alphabet.
+
+They're running a competition to get suggestions for sentences that they can use.
+You're in charge of checking the submissions to see if they are valid.
+
+```exercism/note
+Pangram comes from Greek, παν γράμμα, pan gramma, which means "every letter".
+
+The best known English pangram is:
+
+> The quick brown fox jumps over the lazy dog.
+```
diff --git a/exercises/practice/secret-handshake/.approaches/config.json b/exercises/practice/secret-handshake/.approaches/config.json
@@ -0,0 +1,15 @@
+{
+  "introduction": {
+    "authors": ["bobahop"],
+    "contributors": []
+  },
+  "approaches": [
+    {
+      "uuid": "cd0c0a31-0905-47f0-815c-02597a7cdf40",
+      "slug": "iterate-once",
+      "title": "Iterate once",
+      "blurb": "Iterate once even when reversed.",
+      "authors": ["bobahop"]
+    }
+  ]
+}
diff --git a/exercises/practice/secret-handshake/.approaches/introduction.md b/exercises/practice/secret-handshake/.approaches/introduction.md
@@ -0,0 +1,39 @@
+# Introduction
+
+There are many ways to solve Secret Handshake.
+One approach is to iterate only once, even when the signs are to be reversed.
+
+## General guidance
+
+Something to consider is to keep the number of iterations at a minimum to get the best performance.
+However, if that is felt to adversely impact readability, then to use a series of `if` statements and then reverse is also valid.
+
+## Approach: Iterate once
+
+```rust
+const SIGNS: [&'static str; 4] = ["wink", "double blink", "close your eyes", "jump"];
+const REVERSE_SIGNS: u8 = 16;
+
+pub fn actions(n: u8) -> Vec<&'static str> {
+    let (mut action, action_incr, end) = match n & REVERSE_SIGNS {
+        0 => (0, 1, 4),
+        _ => (3, -1, -1),
+    };
+    let mut output: Vec<&'static str> = Vec::new();
+    
+    loop {
+        if action == end {
+            break;
+        }
+        if (n & (1 << action)) != 0 {
+            output.push(SIGNS[action as usize])
+        }
+        action += action_incr
+    }
+    output
+}
+```
+
+For more information, check the [Iterate once approach][approach-iterate-once].
+
+[approach-iterate-once]: https://exercism.org/tracks/rust/exercises/secret-handshake/approaches/iterate-once
diff --git a/exercises/practice/secret-handshake/.approaches/iterate-once/content.md b/exercises/practice/secret-handshake/.approaches/iterate-once/content.md
@@ -0,0 +1,97 @@
+# Iterate once
+
+```rust
+const SIGNS: [&'static str; 4] = ["wink", "double blink", "close your eyes", "jump"];
+const REVERSE_SIGNS: u8 = 16;
+
+pub fn actions(n: u8) -> Vec<&'static str> {
+    let (mut action, action_incr, end) = match n & REVERSE_SIGNS {
+        0 => (0, 1, 4),
+        _ => (3, -1, -1),
+    };
+    let mut output: Vec<&'static str> = Vec::new();
+    
+    loop {
+        if action == end {
+            break;
+        }
+        if (n & (1 << action)) != 0 {
+            output.push(SIGNS[action as usize])
+        }
+        action += action_incr
+    }
+    output
+}
+```
+
+This approach starts by defining a fixed-size [array][array] to hold the signal values in normal order.
+
+The `[&'static str; 4]` 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 value of `16` is defined as a `const` with a meaningful name so it won't be used as a [magic number][magic-number].
+
+The `actions` function uses multiple assignment with a `match` expression to define the variables that control iterating through the signals array,
+setting their values to iterate in either the normal or reverse order.
+
+The [bitwise AND operator][bitand] is used to check if the input number contains the signal for reversing the order of the other signals.
+
+For example, if the number passed in is `19`, which is `10011` in binary, then it is ANDed with `16`, which is `10000` in binary.
+The `1` in `10000` is also at the same position in `10011`, so the two values ANDed will not be `0`.
+- `10011` AND
+- `10000` =
+- `10000`
+
+If the number passed in is `3`, which is `00011` in binary, then it is ANDed with `16`, which is `10000` in binary.
+The `1` in `10000` is not at the same position in `00011`, so the two values ANDed will be `0`.
+- `00011` AND
+- `10000` =
+- `00000`
+
+If the number passed in does not contain the signal for reverse, then the iteration variables are set to iterate through the array of signals
+in their normal order, otherwise they are set to iterate through the arrray backwards..
+
+The output `vector` is defined, and then the [`loop`][loop] begins.
+
+Normal iteration will start at index `0`.
+Reverse iteration will start at index `3`.
+
+Normal iteration will terminate when the index equals `4`.
+Reverse iteration will terminate when the index equals `-1`.
+
+Normal iteration will increase the index by `1` for each iteration.
+Reverse iteration will decrease the index by `1` for each iteration.
+
+For each iteration of the `loop`, the AND operator is used to check if the number passed in contains `1` [shifted left][shl] (`<<`) for the number of positions
+as the value being iterated.
+
+```rust
+if (n & (1 << action)) != 0 {
+    output.push(SIGNS[action as usize])
+}
+```
+
+For example, if the number being iterated is `0`, then `1` is shifted left `0` times (so not shifted at all), and the number passed in is ANDed with `00001`.
+If the number passed in is `3`, which is `00011` in binary, then it is ANDed with `00001`.
+`00011` ANDed with `00001` is not equal to `0`, so the signal at the index of the array of signals is added to the output `vector`.
+The index used is the number being iterated, which is `0`, so the element at index `0` (`"wink"`) would be added to the output `vector`
+using the [push][push] function.
+
+If the number being iterated is `1`, then `1` is shifted left `1` time, and the number passed in is ANDed with `00010`.
+If the number passed in is `3`, which is `00011` in binary, then it is ANDed with `00010`.
+`00011` ANDed with `00010` is not equal to `0`, so the signal at the index of the array of signals is added to the output `vector`.
+The index used is the number being iterated, which is `1`, so the element at index `1` (`"double blink"`) would be added to the output `vector`.
+
+If the number passed in ANDed with the number being iterated is equal to `0`, then the signal in the array for that index is not added to the output `vector`.
+
+After iterating through the array of signals is done, the output `vector` is returned from the function.
+
+[array]: https://doc.rust-lang.org/std/primitive.array.html
+[const]: https://doc.rust-lang.org/std/keyword.const.html
+[magic-number]: https://en.wikipedia.org/wiki/Magic_number_(programming)
+[bitand]: https://doc.rust-lang.org/std/ops/trait.BitAnd.html
+[shl]: https://doc.rust-lang.org/std/ops/trait.Shl.html
+[loop]: https://doc.rust-lang.org/rust-by-example/flow_control/loop.html
+[push]: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.push
diff --git a/exercises/practice/secret-handshake/.approaches/iterate-once/snippet.txt b/exercises/practice/secret-handshake/.approaches/iterate-once/snippet.txt
@@ -0,0 +1,4 @@
+let (mut action, action_incr, end) = match n & REVERSE_SIGNS {
+    0 => (0, 1, 4),
+    _ => (3, -1, -1),
+};
diff --git a/exercises/practice/secret-handshake/.docs/instructions.md b/exercises/practice/secret-handshake/.docs/instructions.md
diff --git a/exercises/practice/secret-handshake/.docs/introduction.md b/exercises/practice/secret-handshake/.docs/introduction.md
diff --git a/exercises/practice/sieve/.docs/instructions.md b/exercises/practice/sieve/.docs/instructions.md
diff --git a/exercises/practice/sieve/.docs/introduction.md b/exercises/practice/sieve/.docs/introduction.md
