Sync docs with problem-specifications

exercises/practice/beer-song/.docs/instructions.md

@@ -305,17 +305,3 @@ Take it down and pass it around, no more bottles of beer on the wall.
 No more bottles of beer on the wall, no more bottles of beer.
 Go to the store and buy some more, 99 bottles of beer on the wall.
 ```
-
-## For bonus points
-
-Did you get the tests passing and the code clean? If you want to, these
-are some additional things you could try:
-
-* Remove as much duplication as you possibly can.
-* Optimize for readability, even if it means introducing duplication.
-* If you've removed all the duplication, do you have a lot of
-  conditionals? Try replacing the conditionals with polymorphism, if it
-  applies in this language. How readable is it?
-
-Then please share your thoughts in a comment on the submission. Did this
-experiment make the code better? Worse? Did you learn anything from it?

exercises/practice/binary-search-tree/.docs/instructions.md

@@ -2,29 +2,22 @@
 
 Insert and search for numbers in a binary tree.
 
-When we need to represent sorted data, an array does not make a good
-data structure.
-
-Say we have the array `[1, 3, 4, 5]`, and we add 2 to it so it becomes
-`[1, 3, 4, 5, 2]` now we must sort the entire array again! We can
-improve on this by realizing that we only need to make space for the new
-item `[1, nil, 3, 4, 5]`, and then adding the item in the space we
-added. But this still requires us to shift many elements down by one.
-
-Binary Search Trees, however, can operate on sorted data much more
-efficiently.
-
-A binary search tree consists of a series of connected nodes. Each node
-contains a piece of data (e.g. the number 3), a variable named `left`,
-and a variable named `right`. The `left` and `right` variables point at
-`nil`, or other nodes. Since these other nodes in turn have other nodes
-beneath them, we say that the left and right variables are pointing at
-subtrees. All data in the left subtree is less than or equal to the
-current node's data, and all data in the right subtree is greater than
-the current node's data.
-
-For example, if we had a node containing the data 4, and we added the
-data 2, our tree would look like this:
+When we need to represent sorted data, an array does not make a good data structure.
+
+Say we have the array `[1, 3, 4, 5]`, and we add 2 to it so it becomes `[1, 3, 4, 5, 2]`.
+Now we must sort the entire array again!
+We can improve on this by realizing that we only need to make space for the new item `[1, nil, 3, 4, 5]`, and then adding the item in the space we added.
+But this still requires us to shift many elements down by one.
+
+Binary Search Trees, however, can operate on sorted data much more efficiently.
+
+A binary search tree consists of a series of connected nodes.
+Each node contains a piece of data (e.g. the number 3), a variable named `left`, and a variable named `right`.
+The `left` and `right` variables point at `nil`, or other nodes.
+Since these other nodes in turn have other nodes beneath them, we say that the left and right variables are pointing at subtrees.
+All data in the left subtree is less than or equal to the current node's data, and all data in the right subtree is greater than the current node's data.
+
+For example, if we had a node containing the data 4, and we added the data 2, our tree would look like this:
 
       4
      /

exercises/practice/bowling/.docs/instructions.md

@@ -2,29 +2,24 @@
 
 Score a bowling game.
 
-Bowling is a game where players roll a heavy ball to knock down pins
-arranged in a triangle. Write code to keep track of the score
-of a game of bowling.
+Bowling is a game where players roll a heavy ball to knock down pins arranged in a triangle.
+Write code to keep track of the score of a game of bowling.
 
 ## Scoring Bowling
 
-The game consists of 10 frames. A frame is composed of one or two ball
-throws with 10 pins standing at frame initialization. There are three
-cases for the tabulation of a frame.
+The game consists of 10 frames.
+A frame is composed of one or two ball throws with 10 pins standing at frame initialization.
+There are three cases for the tabulation of a frame.
 
-* An open frame is where a score of less than 10 is recorded for the
-  frame. In this case the score for the frame is the number of pins
-  knocked down.
+- An open frame is where a score of less than 10 is recorded for the frame.
+  In this case the score for the frame is the number of pins knocked down.
 
-* A spare is where all ten pins are knocked down by the second
-  throw. The total value of a spare is 10 plus the number of pins
-  knocked down in their next throw.
+- A spare is where all ten pins are knocked down by the second throw.
+  The total value of a spare is 10 plus the number of pins knocked down in their next throw.
 
-* A strike is where all ten pins are knocked down by the first
-  throw. The total value of a strike is 10 plus the number of pins
-  knocked down in the next two throws. If a strike is immediately
-  followed by a second strike, then the value of the first strike
-  cannot be determined until the ball is thrown one more time.
+- A strike is where all ten pins are knocked down by the first throw.
+  The total value of a strike is 10 plus the number of pins knocked down in the next two throws.
+  If a strike is immediately followed by a second strike, then the value of the first strike cannot be determined until the ball is thrown one more time.
 
 Here is a three frame example:
 
@@ -40,22 +35,22 @@ Frame 3 is (9 + 0) = 9
 
 This means the current running total is 48.
 
-The tenth frame in the game is a special case. If someone throws a
-strike or a spare then they get a fill ball. Fill balls exist to
-calculate the total of the 10th frame. Scoring a strike or spare on
-the fill ball does not give the player more fill balls. The total
-value of the 10th frame is the total number of pins knocked down.
+The tenth frame in the game is a special case.
+If someone throws a spare or a strike then they get one or two fill balls respectively.
+Fill balls exist to calculate the total of the 10th frame.
+Scoring a strike or spare on the fill ball does not give the player more fill balls.
+The total value of the 10th frame is the total number of pins knocked down.
 
 For a tenth frame of X1/ (strike and a spare), the total value is 20.
 
 For a tenth frame of XXX (three strikes), the total value is 30.
 
 ## Requirements
 
-Write code to keep track of the score of a game of bowling. It should
-support two operations:
+Write code to keep track of the score of a game of bowling.
+It should support two operations:
 
-* `roll(pins : int)` is called each time the player rolls a ball.  The
-  argument is the number of pins knocked down.
-* `score() : int` is called only at the very end of the game.  It
-  returns the total score for that game.
+- `roll(pins : int)` is called each time the player rolls a ball.
+  The argument is the number of pins knocked down.
+- `score() : int` is called only at the very end of the game.
+  It returns the total score for that game.

exercises/practice/connect/.docs/instructions.md

@@ -2,19 +2,14 @@
 
 Compute the result for a game of Hex / Polygon.
 
-The abstract boardgame known as
-[Hex](https://en.wikipedia.org/wiki/Hex_%28board_game%29) / Polygon /
-CON-TAC-TIX is quite simple in rules, though complex in practice. Two players
-place stones on a parallelogram with hexagonal fields. The player to connect his/her
-stones to the opposite side first wins. The four sides of the parallelogram are
-divided between the two players (i.e. one player gets assigned a side and the
-side directly opposite it and the other player gets assigned the two other
-sides).
+The abstract boardgame known as [Hex][hex] / Polygon / CON-TAC-TIX is quite simple in rules, though complex in practice.
+Two players place stones on a parallelogram with hexagonal fields.
+The player to connect his/her stones to the opposite side first wins.
+The four sides of the parallelogram are divided between the two players (i.e. one player gets assigned a side and the side directly opposite it and the other player gets assigned the two other sides).
 
-Your goal is to build a program that given a simple representation of a board
-computes the winner (or lack thereof). Note that all games need not be "fair".
-(For example, players may have mismatched piece counts or the game's board might
-have a different width and height.)
+Your goal is to build a program that given a simple representation of a board computes the winner (or lack thereof).
+Note that all games need not be "fair".
+(For example, players may have mismatched piece counts or the game's board might have a different width and height.)
 
 The boards look like this:
 
@@ -26,6 +21,7 @@ The boards look like this:
     X O O O X
 ```
 
-"Player `O`" plays from top to bottom, "Player `X`" plays from left to right. In
-the above example `O` has made a connection from left to right but nobody has
-won since `O` didn't connect top and bottom.
+"Player `O`" plays from top to bottom, "Player `X`" plays from left to right.
+In the above example `O` has made a connection from left to right but nobody has won since `O` didn't connect top and bottom.
+
+[hex]: https://en.wikipedia.org/wiki/Hex_%28board_game%29

exercises/practice/grains/.docs/instructions.md

@@ -1,27 +1,15 @@
 # Instructions
 
-Calculate the number of grains of wheat on a chessboard given that the number
-on each square doubles.
+Calculate the number of grains of wheat on a chessboard given that the number on each square doubles.
 
-There once was a wise servant who saved the life of a prince. The king
-promised to pay whatever the servant could dream up. Knowing that the
-king loved chess, the servant told the king he would like to have grains
-of wheat. One grain on the first square of a chess board, with the number
-of grains doubling on each successive square.
+There once was a wise servant who saved the life of a prince.
+The king promised to pay whatever the servant could dream up.
+Knowing that the king loved chess, the servant told the king he would like to have grains of wheat.
+One grain on the first square of a chess board, with the number of grains doubling on each successive square.
 
 There are 64 squares on a chessboard (where square 1 has one grain, square 2 has two grains, and so on).
 
 Write code that shows:
+
 - how many grains were on a given square, and
 - the total number of grains on the chessboard
-
-## For bonus points
-
-Did you get the tests passing and the code clean? If you want to, these
-are some additional things you could try:
-
-- Optimize for speed.
-- Optimize for readability.
-
-Then please share your thoughts in a comment on the submission. Did this
-experiment make the code better? Worse? Did you learn anything from it?

exercises/practice/isbn-verifier/.docs/instructions.md

@@ -1,22 +1,26 @@
 # Instructions
 
-The [ISBN-10 verification process](https://en.wikipedia.org/wiki/International_Standard_Book_Number) is used to validate book identification
-numbers. These normally contain dashes and look like: `3-598-21508-8`
+The [ISBN-10 verification process][isbn-verification] is used to validate book identification numbers.
+These normally contain dashes and look like: `3-598-21508-8`
 
 ## ISBN
 
-The ISBN-10 format is 9 digits (0 to 9) plus one check character (either a digit or an X only). In the case the check character is an X, this represents the value '10'. These may be communicated with or without hyphens, and can be checked for their validity by the following formula:
+The ISBN-10 format is 9 digits (0 to 9) plus one check character (either a digit or an X only).
+In the case the check character is an X, this represents the value '10'.
+These may be communicated with or without hyphens, and can be checked for their validity by the following formula:
 
-```
-(x1 * 10 + x2 * 9 + x3 * 8 + x4 * 7 + x5 * 6 + x6 * 5 + x7 * 4 + x8 * 3 + x9 * 2 + x10 * 1) mod 11 == 0
+```text
+(d₁ * 10 + d₂ * 9 + d₃ * 8 + d₄ * 7 + d₅ * 6 + d₆ * 5 + d₇ * 4 + d₈ * 3 + d₉ * 2 + d₁₀ * 1) mod 11 == 0
 ```
 
 If the result is 0, then it is a valid ISBN-10, otherwise it is invalid.
 
 ## Example
 
-Let's take the ISBN-10 `3-598-21508-8`. We plug it in to the formula, and get:
-```
+Let's take the ISBN-10 `3-598-21508-8`.
+We plug it in to the formula, and get:
+
+```text
 (3 * 10 + 5 * 9 + 9 * 8 + 8 * 7 + 2 * 6 + 1 * 5 + 5 * 4 + 0 * 3 + 8 * 2 + 8 * 1) mod 11 == 0
 ```
 
@@ -29,14 +33,10 @@ Putting this into place requires some thinking about preprocessing/parsing of th
 
 The program should be able to verify ISBN-10 both with and without separating dashes.
 
-
 ## Caveats
 
 Converting from strings to numbers can be tricky in certain languages.
-Now, it's even trickier since the check digit of an ISBN-10 may be 'X' (representing '10'). For instance `3-598-21507-X` is a valid ISBN-10.
-
-## Bonus tasks
-
-* Generate a valid ISBN-13 from the input ISBN-10 (and maybe verify it again with a derived verifier).
+Now, it's even trickier since the check digit of an ISBN-10 may be 'X' (representing '10').
+For instance `3-598-21507-X` is a valid ISBN-10.
 
-* Generate valid ISBN, maybe even from a given starting ISBN.
+[isbn-verification]: https://en.wikipedia.org/wiki/International_Standard_Book_Number

exercises/practice/list-ops/.docs/instructions.md

@@ -2,19 +2,18 @@
 
 Implement basic list operations.
 
-In functional languages list operations like `length`, `map`, and
-`reduce` are very common. Implement a series of basic list operations,
-without using existing functions.
+In functional languages list operations like `length`, `map`, and `reduce` are very common.
+Implement a series of basic list operations, without using existing functions.
 
-The precise number and names of the operations to be implemented will be
-track dependent to avoid conflicts with existing names, but the general
-operations you will implement include:
+The precise number and names of the operations to be implemented will be track dependent to avoid conflicts with existing names, but the general operations you will implement include:
 
-* `append` (*given two lists, add all items in the second list to the end of the first list*);
-* `concatenate` (*given a series of lists, combine all items in all lists into one flattened list*);
-* `filter` (*given a predicate and a list, return the list of all items for which `predicate(item)` is True*);
-* `length` (*given a list, return the total number of items within it*);
-* `map` (*given a function and a list, return the list of the results of applying `function(item)` on all items*);
-* `foldl` (*given a function, a list, and initial accumulator, fold (reduce) each item into the accumulator from the left using `function(accumulator, item)`*);
-* `foldr` (*given a function, a list, and an initial accumulator, fold (reduce) each item into the accumulator from the right using `function(item, accumulator)`*);
-* `reverse` (*given a list, return a list with all the original items, but in reversed order*);
+- `append` (*given two lists, add all items in the second list to the end of the first list*);
+- `concatenate` (*given a series of lists, combine all items in all lists into one flattened list*);
+- `filter` (*given a predicate and a list, return the list of all items for which `predicate(item)` is True*);
+- `length` (*given a list, return the total number of items within it*);
+- `map` (*given a function and a list, return the list of the results of applying `function(item)` on all items*);
+- `foldl` (*given a function, a list, and initial accumulator, fold (reduce) each item into the accumulator from the left*);
+- `foldr` (*given a function, a list, and an initial accumulator, fold (reduce) each item into the accumulator from the right*);
+- `reverse` (*given a list, return a list with all the original items, but in reversed order*).
+
+Note, the ordering in which arguments are passed to the fold functions (`foldl`, `foldr`) is significant.

exercises/practice/matching-brackets/.docs/instructions.md

@@ -1,5 +1,4 @@
 # Instructions
 
-Given a string containing brackets `[]`, braces `{}`, parentheses `()`,
-or any combination thereof, verify that any and all pairs are matched
-and nested correctly.
+Given a string containing brackets `[]`, braces `{}`, parentheses `()`, or any combination thereof, verify that any and all pairs are matched and nested correctly.
+The string may also contain other characters, which for the purposes of this exercise should be ignored.

exercises/practice/meetup/.docs/instructions.md

@@ -1,27 +1,51 @@
 # Instructions
 
-Calculate the date of meetups.
+Recurring monthly meetups are generally scheduled on the given weekday of a given week each month.
+In this exercise you will be given the recurring schedule, along with a month and year, and then asked to find the exact date of the meetup.
 
-Typically meetups happen on the same day of the week.  In this exercise, you
-will take a description of a meetup date, and return the actual meetup date.
+For example a meetup might be scheduled on the _first Monday_ of every month.
+You might then be asked to find the date that this meetup will happen in January 2018.
+In other words, you need to determine the date of the first Monday of January 2018.
 
-Examples of general descriptions are:
+Similarly, you might be asked to find:
 
-- The first Monday of January 2017
-- The third Tuesday of January 2017
-- The wednesteenth of January 2017
-- The last Thursday of January 2017
+- the third Tuesday of August 2019 (August 20, 2019)
+- the teenth Wednesday of May 2020 (May 13, 2020)
+- the fourth Sunday of July 2021 (July 25, 2021)
+- the last Thursday of November 2022 (November 24, 2022)
 
-The descriptors you are expected to parse are:
-first, second, third, fourth, fifth, last, monteenth, tuesteenth, wednesteenth,
-thursteenth, friteenth, saturteenth, sunteenth
+The descriptors you are expected to process are: `first`, `second`, `third`, `fourth`, `last`, `teenth`.
 
-Note that "monteenth", "tuesteenth", etc are all made up words. There was a
-meetup whose members realized that there are exactly 7 numbered days in a month
-that end in '-teenth'. Therefore, one is guaranteed that each day of the week
-(Monday, Tuesday, ...) will have exactly one date that is named with '-teenth'
-in every month.
+Note that descriptor `teenth` is a made-up word.
 
-Given examples of a meetup dates, each containing a month, day, year, and
-descriptor calculate the date of the actual meetup.  For example, if given
-"The first Monday of January 2017", the correct meetup date is 2017/1/2.
+It refers to the seven numbers that end in '-teen' in English: 13, 14, 15, 16, 17, 18, and 19.
+But general descriptions of dates use ordinal numbers, e.g. the _first_ Monday, the _third_ Tuesday.
+
+For the numbers ending in '-teen', that becomes:
+
+- 13th (thirteenth)
+- 14th (fourteenth)
+- 15th (fifteenth)
+- 16th (sixteenth)
+- 17th (seventeenth)
+- 18th (eighteenth)
+- 19th (nineteenth)
+
+So there are seven numbers ending in '-teen'.
+And there are also seven weekdays (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday).
+Therefore, it is guaranteed that each day of the week (Monday, Tuesday, ...) will have exactly one numbered day ending with "teen" each month.
+
+If asked to find the teenth Saturday of August, 1953 (or, alternately the "Saturteenth" of August, 1953), we need to look at the calendar for August 1953:
+
+```plaintext
+    August 1953
+Su Mo Tu We Th Fr Sa
+                   1
+ 2  3  4  5  6  7  8
+ 9 10 11 12 13 14 15
+16 17 18 19 20 21 22
+23 24 25 26 27 28 29
+30 31
+```
+
+The Saturday that has a number ending in '-teen' is August 15, 1953.