Sync Grains (#930)

[no important files changed]

Author: A-O-Emmanuel

bin/auto-sync.txt

@@ -29,6 +29,7 @@ flower-field
 food-chain
 gigasecond
 grade-school
+grains
 hamming
 hello-world
 high-scores

config.json

@@ -919,7 +919,7 @@
         "uuid": "3b001897-4052-4dab-84fd-b971a9946e0a",
         "practices": [],
         "prerequisites": [],
-        "difficulty": 3,
+        "difficulty": 4,
         "topics": [
           "algorithms",
           "floating_point_numbers"

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

@@ -0,0 +1,29 @@
+# Instructions append
+
+## Maximum integer value
+
+According to [the PHP docs][php-int] there is a maximum integer value:
+
+> The size of an `int` is platform-dependent, although a maximum value of about two billion is the usual value (that's 32 bits signed).
+> 64-bit platforms usually have a maximum value of about 9E18.
+> PHP does not support unsigned `int`s.
+
+In other words, PHP cannot express any number `2^63` or greater as an integer.
+Some of the tests for this exercise require 64 bit integers (`2^64`) which is beyond the integer size limitation of PHP.
+
+[PHP automatically converts][php-int-to-float] `int`s to `float`s, when the numbers get too big:
+
+> If PHP encounters a number beyond the bounds of the `int` type, it will be interpreted as a `float` instead.
+> Also, an operation which results in a number beyond the bounds of the `int` type will return a `float` instead.
+
+But the `float` type [has limited precision][php-float-precision].
+And King hates unprecision.
+So King decided to expect the results of the calculations as a string which expresses the integer value, rather than expressing the answer as `int` or `float`.
+And he wants integer calculations, not just a lazy conversion at the end.
+
+Can you solve this by avoiding numbers that are larger than the language will allow directly?
+And please don't use other PHP libraries like `gmp` or `bc`, too.
+
+[php-int]: https://www.php.net/manual/en/language.types.integer.php
+[php-int-to-float]: https://www.php.net/manual/en/language.types.integer.php
+[php-float-precision]: https://php.net/manual/en/language.types.float.php

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

@@ -1,27 +1,11 @@
 # 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.
 
-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.
+A chessboard has 64 squares.
+Square 1 has one grain, square 2 has two grains, square 3 has four grains, and so on, doubling each time.
 
-There are 64 squares on a chessboard (where square 1 has one grain, square 2 has two grains, and so on).
+Write code that calculates:
 
-Write code that shows:
-- how many grains were on a given square, and
+- the number of grains on a given square
 - 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/grains/.docs/introduction.md

@@ -0,0 +1,6 @@
+# Introduction
+
+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 chessboard, with the number of grains doubling on each successive square.

exercises/practice/grains/.meta/config.json

@@ -6,7 +6,8 @@
     "arueckauer",
     "G-Rath",
     "kytrinyx",
-    "petemcfarlane"
+    "petemcfarlane",
+    "A-O-Emmanuel"
   ],
   "files": {
     "solution": [
@@ -20,6 +21,6 @@
     ]
   },
   "blurb": "Calculate the number of grains of wheat on a chessboard given that the number on each square doubles.",
-  "source": "JavaRanch Cattle Drive, exercise 6",
-  "source_url": "https://www.javaranch.com/grains.jsp"
+  "source": "The CodeRanch Cattle Drive, Assignment 6",
+  "source_url": "https://web.archive.org/web/20240908084142/https://coderanch.com/wiki/718824/Grains"
 }

exercises/practice/grains/.meta/example.php

@@ -1,27 +1,5 @@
 <?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);
 
 /**

exercises/practice/grains/.meta/tests.toml

@@ -3,34 +3,34 @@
 # so comments can be added in a "comment" key.
 
 [9fbde8de-36b2-49de-baf2-cd42d6f28405]
-description = "1"
+description = "grains on square 1"
 
 [ee1f30c2-01d8-4298-b25d-c677331b5e6d]
-description = "2"
+description = "grains on square 2"
 
 [10f45584-2fc3-4875-8ec6-666065d1163b]
-description = "3"
+description = "grains on square 3"
 
 [a7cbe01b-36f4-4601-b053-c5f6ae055170]
-description = "4"
+description = "grains on square 4"
 
 [c50acc89-8535-44e4-918f-b848ad2817d4]
-description = "16"
+description = "grains on square 16"
 
 [acd81b46-c2ad-4951-b848-80d15ed5a04f]
-description = "32"
+description = "grains on square 32"
 
 [c73b470a-5efb-4d53-9ac6-c5f6487f227b]
-description = "64"
+description = "grains on square 64"
 
 [1d47d832-3e85-4974-9466-5bd35af484e3]
-description = "square 0 raises an exception"
+description = "square 0 is invalid"
 
 [61974483-eeb2-465e-be54-ca5dde366453]
-description = "negative square raises an exception"
+description = "negative square is invalid"
 
 [a95e4374-f32c-45a7-a10d-ffec475c012f]
-description = "square greater than 64 raises an exception"
+description = "square greater than 64 is invalid"
 
 [6eb07385-3659-4b45-a6be-9dc474222750]
 description = "returns the total number of grains on the board"

exercises/practice/grains/GrainsTest.php

@@ -1,29 +1,8 @@
 <?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);
 
+use PHPUnit\Framework\Attributes\TestDox;
 use PHPUnit\Framework\TestCase;
 
 class GrainsTest extends TestCase
@@ -34,73 +13,105 @@ public static function setUpBeforeClass(): void
     }
 
     /**
-     * PHP integers greater than 2^31 (32-bit systems)
-     * or 2^63 (64-bit) are casted to floats.
-     * In some cases it may lead to problems
-     * https://php.net/manual/ru/language.types.float.php#warn.float-precision
-     *
-     * Consider King hates floats and demands solution with
-     * precise integer-only calculations. Don't involve any floats.
-     * Don't use gmp or any other similar libraries.
-     * Try to make the solution for virtually any board size.
+     * uuid: 9fbde8de-36b2-49de-baf2-cd42d6f28405
      */
-
-    public function testInput1(): void
+    #[TestDox('grains on square 1')]
+    public function testGrainsOnSquare1(): void
     {
         $this->assertSame('1', square(1));
     }
 
-    public function testInput2(): void
+    /**
+     * uuid: ee1f30c2-01d8-4298-b25d-c677331b5e6d
+     */
+    #[TestDox('grains on square 2')]
+    public function testGrainsOnSquare2(): void
     {
         $this->assertSame('2', square(2));
     }
 
-    public function testInput3(): void
+     /**
+     * uuid: 10f45584-2fc3-4875-8ec6-666065d1163b
+     */
+    #[TestDox('grains on square 3')]
+    public function testGrainsOnSquare3(): void
     {
         $this->assertSame('4', square(3));
     }
 
-    public function testInput4(): void
+    /**
+     * uuid: a7cbe01b-36f4-4601-b053-c5f6ae055170
+     */
+    #[TestDox('grains on square 4')]
+    public function testGrainsOnSquare4(): void
     {
         $this->assertSame('8', square(4));
     }
 
-    public function testInput16(): void
+    /**
+     * uuid: c50acc89-8535-44e4-918f-b848ad2817d4
+     */
+    #[TestDox('grains on square 16')]
+    public function testGrainsOnSquare16(): void
     {
         $this->assertSame('32768', square(16));
     }
 
-    public function testInput32(): void
+    /**
+     * uuid: acd81b46-c2ad-4951-b848-80d15ed5a04f
+     */
+    #[TestDox('grains on square 32')]
+    public function testGrainsOnSquare32(): void
     {
         $this->assertSame('2147483648', square(32));
     }
 
-    public function testInput64(): void
+    /**
+     * uuid: c73b470a-5efb-4d53-9ac6-c5f6487f227b
+     */
+    #[TestDox('grains on square 64')]
+    public function testGrainsOnSquare64(): void
     {
         $this->assertSame('9223372036854775808', square(64));
     }
 
-    public function testRejectsZero(): void
+    /**
+     * uuid: 1d47d832-3e85-4974-9466-5bd35af484e3
+     */
+    #[TestDox('square 0 is invalid')]
+    public function testSquare0IsInvalid(): void
     {
         $this->expectException(InvalidArgumentException::class);
 
         square(0);
     }
 
+     /**
+     * uuid: 61974483-eeb2-465e-be54-ca5dde366453
+     */
+    #[TestDox('negative square is invalid')]
     public function testRejectsNegative(): void
     {
         $this->expectException(InvalidArgumentException::class);
 
         square(-1);
     }
 
+     /**
+     * uuid: a95e4374-f32c-45a7-a10d-ffec475c012f
+     */
+    #[TestDox('square greater than 64 is invalid')]
     public function testRejectsGreaterThan64(): void
     {
         $this->expectException(InvalidArgumentException::class);
 
         square(65);
     }
 
+    /**
+     * uuid: 6eb07385-3659-4b45-a6be-9dc474222750
+     */
+    #[TestDox('returns the total number of grains on the board')]
     public function testTotal(): void
     {
         $this->assertSame('18446744073709551615', total());