Add concept exercise: captains-log

Author: sanderploegsma

config.json

@@ -234,6 +234,19 @@
           "switch-statement",
           "constructors"
         ]
+      },
+      {
+        "slug": "captains-log",
+        "name": "Captain's Log",
+        "uuid": "1ade8233-7a73-4fd9-afe2-f80d7cca14ab",
+        "concepts": [
+          "randomness"
+        ],
+        "prerequisites": [
+          "arrays",
+          "numbers",
+          "strings"
+        ]
       }
     ],
     "practice": [

exercises/concept/captains-log/.docs/hints.md

@@ -0,0 +1,14 @@
+# Hints
+
+## 1. Generate a random planet
+
+- Java does not provide a function to choose an element from a collection at random.
+- Remember that you can retrieve an element from an array by its index, which is an integer.
+
+## 2. Generate a random starship registry number
+
+- The `java.util.Random` class provides a method to generate a random `int` between 0 and a given maximum.
+
+## 3. Generate a random stardate
+
+- The `java.util.Random` class method to generate a random `double` always returns a number between `0.0` and `1.0`.

exercises/concept/captains-log/.docs/instructions.md

@@ -0,0 +1,59 @@
+# Instructions
+
+Mary is a big fan of the TV series _Star Trek: The Next Generation_.
+She often plays pen-and-paper role playing games, where she and her friends pretend to be the crew of the _Starship Enterprise_.
+Mary's character is Captain Picard, which means she has to keep the captain's log.
+She loves the creative part of the game, but doesn't like to generate random data on the spot.
+
+Help Mary by creating random generators for data commonly appearing in the captain's log.
+
+~~~~exercism/note
+The starter implementation of this exercise takes a `java.util.Random` instance as constructor argument.
+This allows the exercise's tests to pass an instance with a predefined seed, which makes the test results predictable.
+
+Therefore, you are expected to use provided the `java.util.Random` instance in your implementation.
+~~~~
+
+## 1. Generate a random planet
+
+The _Starship Enterprise_ encounters many planets in its travels.
+Planets in the Star Trek universe are split into categories based on their properties.
+For example, Earth is a class `M` planet.
+All possible planetary classes are: `D`, `H`, `J`, `K`, `L`, `M`, `N`, `R`, `T`, and `Y`.
+
+Implement the `randomPlanetClass()` method.
+It should return one of the planetary classes at random.
+
+```java
+captainsLog.randomPlanetClass();
+// => "K"
+```
+
+## 2. Generate a random starship registry number
+
+Enterprise (registry number `NCC-1701`) is not the only starship flying around!
+When it rendezvous with another starship, Mary needs to log the registry number of that starship.
+
+Registry numbers start with the prefix "NCC-" and then use a number from `1000` to `9999` (inclusive).
+
+Implement the `randomShipRegistryNumber()` method that returns a random starship registry number.
+
+```java
+captainsLog.randomShipRegistryNumber();
+// => "NCC-1947"
+```
+
+## 3. Generate a random stardate
+
+What's the use of a log if it doesn't include dates?
+
+A stardate is a floating point number.
+The adventures of the _Starship Enterprise_ from the first season of _The Next Generation_ take place between the stardates `41000.0` and `42000.0`.
+The "4" stands for the 24th century, the "1" for the first season.
+
+Implement the `randomStardate()` method that returns a floating point number between `41000.0` (inclusive) and `42000.0` (exclusive).
+
+```java
+captainsLog.randomStardate();
+// => 41458.15721310934
+```

exercises/concept/captains-log/.docs/introduction.md

@@ -0,0 +1,59 @@
+# Introduction
+
+## Randomness
+
+An instance of the `java.util.Random` class can be used to generate random numbers in Java.
+
+### Random integers
+
+A random integer can be generated using the `nextInt()` method.
+This will generate a value in the range from `Integer.MIN_VALUE` to `Integer.MAX_VALUE`.
+
+```java
+Random random = new Random();
+
+random.nextInt();
+// => -1169335537
+```
+
+To limit the range of generated values, use `nextInt(int)`.
+This will generate a value in the range from `0` (inclusive) to the given upper bound (exclusive).
+
+For example, this will generate a random number from `0` through `9`.
+
+```java
+Random random = new Random();
+
+random.nextInt(10);
+// => 6
+```
+
+And this will generate a random number from `10` through `19`.
+
+```java
+Random random = new Random();
+
+10 + random.nextInt(10);
+// => 11
+```
+
+### Random doubles
+
+A random double can be generated using the `nextDouble()` method.
+This will generate a value in the range from `0.0` to `1.0`.
+
+```java
+Random random = new Random();
+
+random.nextDouble();
+// => 0.19250004204021398
+```
+
+And this will generate a random number from `100.0` to `200.0`.
+
+```java
+Random random = new Random();
+
+100.0 + 100.0 * random.nextDouble();
+// => 111.31849856260328
+```

exercises/concept/captains-log/.docs/introduction.md.tpl

@@ -0,0 +1,5 @@
+# Introduction
+
+## Randomness
+
+%{concept:randomness}

exercises/concept/captains-log/.meta/config.json

@@ -0,0 +1,23 @@
+{
+  "authors": [
+    "sanderploegsma"
+  ],
+  "files": {
+    "solution": [
+      "src/main/java/CaptainsLog.java"
+    ],
+    "test": [
+      "src/test/java/CaptainsLogTest.java"
+    ],
+    "exemplar": [
+      ".meta/src/reference/java/CaptainsLog.java"
+    ],
+    "invalidator": [
+      "build.gradle"
+    ]
+  },
+  "forked_from": [
+    "elixir/captains-log"
+  ],
+  "blurb": "Learn about randomness by helping Mary generate stardates and starship registry numbers for her Star Trek themed pen-and-paper role playing sessions."
+}

exercises/concept/captains-log/.meta/design.md

@@ -0,0 +1,21 @@
+# Design
+
+## Learning objectives
+
+- Know how to generate a random `Integer`.
+- Know how to generate a random `Double`.
+- Know how to select a random element from a collection.
+
+## Out of scope
+
+- `java.util.SecureRandom`.
+
+## Concepts
+
+- `randomness`
+
+## Prerequisites
+
+- `strings`: know how to use string formatting.
+- `numbers`: know how to apply basic mathematical operators.
+- `arrays`: know how to retrieve array elements by their index.

exercises/concept/captains-log/.meta/src/reference/java/CaptainsLog.java

@@ -0,0 +1,29 @@
+import java.util.Random;
+
+class CaptainsLog {
+
+    private static final char[] PLANET_CLASSES = new char[]{'D', 'H', 'J', 'K', 'L', 'M', 'N', 'R', 'T', 'Y'};
+
+    private final Random random;
+
+    CaptainsLog(Random random) {
+        this.random = random;
+    }
+
+    char randomPlanetClass() {
+        var index = random.nextInt(PLANET_CLASSES.length);
+        return PLANET_CLASSES[index];
+    }
+
+    String randomShipRegistryNumber() {
+        var start = 1000;
+        var end = 9999;
+        return String.format("NCC-%d", start + random.nextInt(end - start));
+    }
+
+    double randomStardate() {
+        var start = 41000.0;
+        var end = 42000.0;
+        return start + random.nextDouble() * (end - start);
+    }
+}

exercises/concept/captains-log/build.gradle

@@ -0,0 +1,23 @@
+plugins {
+  id "java"
+}
+
+repositories {
+  mavenCentral()
+}
+
+dependencies {
+  testImplementation platform("org.junit:junit-bom:5.10.0")
+  testImplementation "org.junit.jupiter:junit-jupiter"
+  testImplementation "org.assertj:assertj-core:3.15.0"
+}
+
+test {
+  useJUnitPlatform()
+
+  testLogging {
+    exceptionFormat = "full"
+    showStandardStreams = true
+    events = ["passed", "failed", "skipped"]
+  }
+}

exercises/concept/captains-log/src/main/java/CaptainsLog.java

@@ -0,0 +1,24 @@
+import java.util.Random;
+
+class CaptainsLog {
+
+    private static final char[] PLANET_CLASSES = new char[]{'D', 'H', 'J', 'K', 'L', 'M', 'N', 'R', 'T', 'Y'};
+
+    private Random random;
+
+    CaptainsLog(Random random) {
+        this.random = random;
+    }
+
+    char randomPlanetClass() {
+        throw new UnsupportedOperationException("Please implement the CaptainsLog.randomPlanetClass() method");
+    }
+
+    String randomShipRegistryNumber() {
+        throw new UnsupportedOperationException("Please implement the CaptainsLog.randomShipRegistryNumber() method");
+    }
+
+    double randomStardate() {
+        throw new UnsupportedOperationException("Please implement the CaptainsLog.randomStardate() method");
+    }
+}

exercises/concept/captains-log/src/test/java/CaptainsLogTest.java

@@ -0,0 +1,86 @@
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+
+import java.util.Random;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class CaptainsLogTest {
+
+    private Random random1;
+    private Random random2;
+    private Random random3;
+
+    @BeforeEach
+    public void setup() {
+        random1 = new Random(47);
+        random2 = new Random(474747);
+        random3 = new Random(474747474747L);
+    }
+
+    @Test
+    @Tag("task:1")
+    @DisplayName("Generating a random planet class")
+    public void testRandomPlanetClass() {
+        assertThat(new CaptainsLog(random1).randomPlanetClass()).isEqualTo('T');
+        assertThat(new CaptainsLog(random2).randomPlanetClass()).isEqualTo('K');
+        assertThat(new CaptainsLog(random3).randomPlanetClass()).isEqualTo('J');
+    }
+
+    @Test
+    @Tag("task:1")
+    @DisplayName("Generated planet classes are valid")
+    public void testRandomPlanetClassIsValid() {
+        var captainsLog = new CaptainsLog(new Random());
+
+        for (int i = 0; i < 100; i++) {
+            assertThat(captainsLog.randomPlanetClass())
+                    .isIn('D', 'H', 'J', 'K', 'L', 'M', 'N', 'R', 'T', 'Y');
+        }
+    }
+
+    @Test
+    @Tag("task:2")
+    @DisplayName("Generating a random ship registry number")
+    public void testRandomShipRegistryNumber() {
+        assertThat(new CaptainsLog(random1).randomShipRegistryNumber()).isEqualTo("NCC-8773");
+        assertThat(new CaptainsLog(random2).randomShipRegistryNumber()).isEqualTo("NCC-2473");
+        assertThat(new CaptainsLog(random3).randomShipRegistryNumber()).isEqualTo("NCC-9576");
+    }
+
+    @Test
+    @Tag("task:2")
+    @DisplayName("Generated ship registry numbers are valid")
+    public void testRandomShipRegistryNumberIsValid() {
+        var captainsLog = new CaptainsLog(new Random());
+
+        for (int i = 0; i < 100; i++) {
+            var shipRegistryNumber = captainsLog.randomShipRegistryNumber();
+            var number = Integer.parseInt(shipRegistryNumber.substring(4));
+
+            assertThat(number).isBetween(1000, 9999);
+        }
+    }
+
+    @Test
+    @Tag("task:3")
+    @DisplayName("Generating a random stardate")
+    public void testRandomStardate() {
+        assertThat(new CaptainsLog(random1).randomStardate()).isEqualTo(41727.115786073);
+        assertThat(new CaptainsLog(random2).randomStardate()).isEqualTo(41531.31240225019);
+        assertThat(new CaptainsLog(random3).randomStardate()).isEqualTo(41283.50713600276);
+    }
+
+    @Test
+    @Tag("task:3")
+    @DisplayName("Generated stardates are valid")
+    public void testRandomStardateIsValid() {
+        var captainsLog = new CaptainsLog(new Random());
+
+        for (int i = 0; i < 100; i++) {
+            assertThat(captainsLog.randomStardate()).isBetween(41000.0, 42000.0);
+        }
+    }
+}

exercises/settings.gradle

@@ -17,6 +17,7 @@ include 'concept:football-match-reports'
 include 'concept:wizards-and-warriors'
 include 'concept:calculator-conundrum'
 include 'concept:logs-logs-logs'
+include 'concept:captains-log'
 
 // practice exercises
 include 'practice:accumulate'