Add Killer Sudoku Helper Exercise (#648)

Author: tomasnorre

config.json

@@ -1220,6 +1220,14 @@
         "prerequisites": [],
         "difficulty": 4
       },
+      {
+        "slug": "killer-sudoku-helper",
+        "name": "Killer Sudoku Helper",
+        "uuid": "1ccf740f-9c81-4742-8e00-1ecc5c52d7a3",
+        "practices": [],
+        "prerequisites": [],
+        "difficulty": 5
+      },
       {
         "slug": "circular-buffer",
         "name": "Circular Buffer",

exercises/practice/killer-sudoku-helper/.docs/instructions.md

@@ -0,0 +1,63 @@
+# Instructions
+
+A friend of yours is learning how to solve Killer Sudokus (rules below) but struggling to figure out which digits can go in a cage.
+They ask you to help them out by writing a small program that lists all valid combinations for a given cage, and any constraints that affect the cage.
+
+To make the output of your program easy to read, the combinations it returns must be sorted.
+
+## Killer Sudoku Rules
+
+- [Standard Sudoku rules][sudoku-rules] apply.
+- The digits in a cage, usually marked by a dotted line, add up to the small number given in the corner of the cage.
+- A digit may only occur once in a cage.
+
+For a more detailed explanation, check out [this guide][killer-guide].
+
+## Example 1: Cage with only 1 possible combination
+
+In a 3-digit cage with a sum of 7, there is only one valid combination: 124.
+
+- 1 + 2 + 4 = 7
+- Any other combination that adds up to 7, e.g. 232, would violate the rule of not repeating digits within a cage.
+
+![Sudoku grid, with three killer cages that are marked as grouped together. The first killer cage is in the 3×3 box in the top left corner of the grid. The middle column of that box forms the cage, with the followings cells from top to bottom: first cell contains a 1 and a pencil mark of 7, indicating a cage sum of 7, second cell contains a 2, third cell contains a 5. The numbers are highlighted in red to indicate a mistake. The second killer cage is in the central 3×3 box of the grid. The middle column of that box forms the cage, with the followings cells from top to bottom: first cell contains a 1 and a pencil mark of 7, indicating a cage sum of 7, second cell contains a 2, third cell contains a 4. None of the numbers in this cage are highlighted and therefore don't contain any mistakes. The third killer cage follows the outside corner of the central 3×3 box of the grid. It is made up of the following three cells: the top left cell of the cage contains a 2, highlighted in red, and a cage sum of 7. The top right cell of the cage contains a 3. The bottom right cell of the cage contains a 2, highlighted in red. All other cells are empty.][one-solution-img]
+
+## Example 2: Cage with several combinations
+
+In a 2-digit cage with a sum 10, there are 4 possible combinations:
+
+- 19
+- 28
+- 37
+- 46
+
+![Sudoku grid, all squares empty except for the middle column, column 5, which has 8 rows filled. Each continguous two rows form a killer cage and are marked as grouped together. From top to bottom: first group is a cell with value 1 and a pencil mark indicating a cage sum of 10, cell with value 9. Second group is a cell with value 2 and a pencil mark of 10, cell with value 8. Third group is a cell with value 3 and a pencil mark of 10, cell with value 7. Fourth group is a cell with value 4 and a pencil mark of 10, cell with value 6. The last cell in the column is empty.][four-solutions-img]
+
+## Example 3: Cage with several combinations that is restricted
+
+In a 2-digit cage with a sum 10, where the column already contains a 1 and a 4, there are 2 possible combinations:
+
+- 28
+- 37
+
+19 and 46 are not possible due to the 1 and 4 in the column according to standard Sudoku rules.
+
+![Sudoku grid, all squares empty except for the middle column, column 5, which has 8 rows filled. The first row contains a 4, the second is empty, and the third contains a 1. The 1 is highlighted in red to indicate a mistake. The last 6 rows in the column form killer cages of two cells each. From top to bottom: first group is a cell with value 2 and a pencil mark indicating a cage sum of 10, cell with value 8. Second group is a cell with value 3 and a pencil mark of 10, cell with value 7. Third group is a cell with value 1, highlighted in red, and a pencil mark of 10, cell with value 9.][not-possible-img]
+
+## Trying it yourself
+
+If you want to give an approachable Killer Sudoku a go, you can try out [this puzzle][clover-puzzle] by Clover, featured by [Mark Goodliffe on Cracking The Cryptic on the 21st of June 2021][goodliffe-video].
+
+You can also find Killer Sudokus in varying difficulty in numerous newspapers, as well as Sudoku apps, books and websites.
+
+## Credit
+
+The screenshots above have been generated using [F-Puzzles.com](https://www.f-puzzles.com/), a Puzzle Setting Tool by Eric Fox.
+
+[sudoku-rules]: https://masteringsudoku.com/sudoku-rules-beginners/
+[killer-guide]: https://masteringsudoku.com/killer-sudoku/
+[one-solution-img]: https://assets.exercism.org/images/exercises/killer-sudoku-helper/example1.png
+[four-solutions-img]: https://assets.exercism.org/images/exercises/killer-sudoku-helper/example2.png
+[not-possible-img]: https://assets.exercism.org/images/exercises/killer-sudoku-helper/example3.png
+[clover-puzzle]: https://app.crackingthecryptic.com/sudoku/HqTBn3Pr6R
+[goodliffe-video]: https://youtu.be/c_NjEbFEeW0?t=1180

exercises/practice/killer-sudoku-helper/.meta/config.json

@@ -0,0 +1,19 @@
+{
+  "authors": [
+    "tomasnorre"
+  ],
+  "files": {
+    "solution": [
+      "KillerSudokuHelper.php"
+    ],
+    "test": [
+      "KillerSudokuHelperTest.php"
+    ],
+    "example": [
+      ".meta/example.php"
+    ]
+  },
+  "blurb": "Write a tool that makes it easier to solve Killer Sudokus",
+  "source": "Created by Sascha Mann, Jeremy Walker, and BethanyG for the Julia track on Exercism.",
+  "source_url": "https://github.com/exercism/julia/pull/413"
+}

exercises/practice/killer-sudoku-helper/.meta/example.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+class KillerSudokuHelper
+{
+    public function combinations(int $sum, int $size, array $exclude): array
+    {
+        $candidates = array_filter(range(1, min($sum, 9)), static function ($i) use ($exclude) {
+            return !in_array($i, $exclude, true);
+        });
+
+        $result = [];
+        foreach ($this->combinationsHelper([], $candidates, $sum, $size) as $combo) {
+            $result[] = $combo;
+        }
+
+        return $result;
+    }
+
+    private function combinationsHelper(array $prefix, array $candidates, int $target, int $size): array
+    {
+        if ($size === 0) {
+            return $target === 0 ? [$prefix] : [];
+        }
+
+        $result = [];
+        foreach ($candidates as $index => $candidate) {
+            if ($candidate > $target) {
+                break;
+            }
+            $remaining = array_slice($candidates, $index + 1);
+            foreach ($this->combinationsHelper(array_merge($prefix, [$candidate]), $remaining, $target - $candidate, $size - 1) as $combo) {
+                $result[] = $combo;
+            }
+        }
+
+        return $result;
+    }
+}

exercises/practice/killer-sudoku-helper/.meta/tests.toml

@@ -0,0 +1,49 @@
+# This is an auto-generated file.
+#
+# Regenerating this file via `configlet sync` will:
+# - Recreate every `description` key/value pair
+# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
+# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
+# - Preserve any other key/value pair
+#
+# As user-added comments (using the # character) will be removed when this file
+# is regenerated, comments can be added via a `comment` key.
+
+[2aaa8f13-11b5-4054-b95c-a906e4d79fb6]
+description = "Trivial 1-digit cages -> 1"
+
+[4645da19-9fdd-4087-a910-a6ed66823563]
+description = "Trivial 1-digit cages -> 2"
+
+[07cfc704-f8aa-41b2-8f9a-cbefb674cb48]
+description = "Trivial 1-digit cages -> 3"
+
+[22b8b2ba-c4fd-40b3-b1bf-40aa5e7b5f24]
+description = "Trivial 1-digit cages -> 4"
+
+[b75d16e2-ff9b-464d-8578-71f73094cea7]
+description = "Trivial 1-digit cages -> 5"
+
+[bcbf5afc-4c89-4ff6-9357-07ab4d42788f]
+description = "Trivial 1-digit cages -> 6"
+
+[511b3bf8-186f-4e35-844f-c804d86f4a7a]
+description = "Trivial 1-digit cages -> 7"
+
+[bd09a60d-3aca-43bd-b6aa-6ccad01bedda]
+description = "Trivial 1-digit cages -> 8"
+
+[9b539f27-44ea-4ff8-bd3d-c7e136bee677]
+description = "Trivial 1-digit cages -> 9"
+
+[0a8b2078-b3a4-4dbd-be0d-b180f503d5c3]
+description = "Cage with sum 45 contains all digits 1:9"
+
+[2635d7c9-c716-4da1-84f1-c96e03900142]
+description = "Cage with only 1 possible combination"
+
+[a5bde743-e3a2-4a0c-8aac-e64fceea4228]
+description = "Cage with several combinations"
+
+[dfbf411c-737d-465a-a873-ca556360c274]
+description = "Cage with several combinations that is restricted"

exercises/practice/killer-sudoku-helper/KillerSudokuHelper.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * By adding type hints and enabling strict type checking, code can become
+ * easier to read, self-documenting and reduce the number of potential bugs.
+ * By default, type declarations are non-strict, which means they will attempt
+ * to change the original type to match the type specified by the
+ * type-declaration.
+ *
+ * In other words, if you pass a string to a function requiring a float,
+ * it will attempt to convert the string value to a float.
+ *
+ * To enable strict mode, a single declare directive must be placed at the top
+ * of the file.
+ * This means that the strictness of typing is configured on a per-file basis.
+ * This directive not only affects the type declarations of parameters, but also
+ * a function's return type.
+ *
+ * For more info review the Concept on strict type checking in the PHP track
+ * <link>.
+ *
+ * To disable strict typing, comment out the directive below.
+ */
+
+declare(strict_types=1);
+
+class KillerSudokuHelper
+{
+    public function combinations(int $sum, int $size, array $exclude): array
+    {
+        throw new \BadMethodCallException(sprintf('Implement the %s method', __FUNCTION__));
+    }
+}

exercises/practice/killer-sudoku-helper/KillerSudokuHelperTest.php

@@ -0,0 +1,161 @@
+<?php
+
+declare(strict_types=1);
+
+class KillerSudokuHelperTest extends PHPUnit\Framework\TestCase
+{
+    private KillerSudokuHelper $killerSudokuHelper;
+
+    public static function setUpBeforeClass(): void
+    {
+        require_once 'KillerSudokuHelper.php';
+    }
+
+    protected function setUp(): void
+    {
+        $this->killerSudokuHelper = new KillerSudokuHelper();
+    }
+
+    /**
+     * uuid: 2aaa8f13-11b5-4054-b95c-a906e4d79fb6
+     */
+    public function testTrivialOneDigitCages1(): void
+    {
+        $expected = [
+            [1]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(1, 1, []));
+    }
+
+    /**
+     * uuid: 4645da19-9fdd-4087-a910-a6ed66823563
+     */
+    public function testTrivialOneDigitCages2(): void
+    {
+        $expected = [
+            [2]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(2, 1, []));
+    }
+
+    /**
+     * uuid: 07cfc704-f8aa-41b2-8f9a-cbefb674cb48
+     */
+    public function testTrivialOneDigitCages3(): void
+    {
+        $expected = [
+            [3]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(3, 1, []));
+    }
+
+    /**
+     * uuid: 22b8b2ba-c4fd-40b3-b1bf-40aa5e7b5f24
+     */
+    public function testTrivialOneDigitCages4(): void
+    {
+        $expected = [
+            [4]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(4, 1, []));
+    }
+
+    /**
+     * uuid: b75d16e2-ff9b-464d-8578-71f73094cea7
+     */
+    public function testTrivialOneDigitCages5(): void
+    {
+        $expected = [
+            [5]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(5, 1, []));
+    }
+
+    /**
+     * uuid: bcbf5afc-4c89-4ff6-9357-07ab4d42788f
+     */
+    public function testTrivialOneDigitCages6(): void
+    {
+        $expected = [
+            [6]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(6, 1, []));
+    }
+
+    /**
+     * uuid: 511b3bf8-186f-4e35-844f-c804d86f4a7a
+     */
+    public function testTrivialOneDigitCages7(): void
+    {
+        $expected = [
+            [7]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(7, 1, []));
+    }
+
+    /**
+     * uuid: bd09a60d-3aca-43bd-b6aa-6ccad01bedda
+     */
+    public function testTrivialOneDigitCages8(): void
+    {
+        $expected = [
+            [8]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(8, 1, []));
+    }
+
+    /**
+     * uuid: 9b539f27-44ea-4ff8-bd3d-c7e136bee677
+     */
+    public function testTrivialOneDigitCages9(): void
+    {
+        $expected = [
+            [9]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(9, 1, []));
+    }
+
+    /**
+     * uuid: 0a8b2078-b3a4-4dbd-be0d-b180f503d5c3
+     */
+    public function testCageWithSum45ContainsAllDigits1To9(): void
+    {
+        $expected = [
+            [1, 2, 3, 4, 5, 6, 7, 8, 9]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(45, 9, []));
+    }
+
+    /**
+     * uuid: 2635d7c9-c716-4da1-84f1-c96e03900142
+     */
+    public function testCageWithOnlyOnePossibleCombination(): void
+    {
+        $expected = [
+            [1, 2, 4]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(7, 3, []));
+    }
+
+    /**
+     * uuid: a5bde743-e3a2-4a0c-8aac-e64fceea4228
+     */
+    public function testCageWithSeveralCombinations(): void
+    {
+        $expected = [
+            [1, 9], [2, 8], [3, 7], [4, 6]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(10, 2, []));
+    }
+
+    /**
+     * uuid: dfbf411c-737d-465a-a873-ca556360c274
+     */
+    public function testCageWithSeveralCombinationsThatIsRestricted(): void
+    {
+        $expected = [
+            [2, 8], [3, 7]
+        ];
+        $this->assertEquals($expected, $this->killerSudokuHelper->combinations(10, 2, [1, 4]));
+    }
+}