Add documentation for RandomLong & RandomDuration

manual/src/docs/asciidoc/chapters/03-random.adoc

@@ -3,41 +3,53 @@
 The Random module contains a collection of builders and utility functions to generate random data.
 
 
-== Random Integer
+== Random Integer/Long
 
-The link:{javadoc-url}/random/org/stubit/random/RandomInt.html[`RandomInt` class] allows to generate random Integer values within a defined min and max range (both inclusive).
+The link:{javadoc-url}/random/org/stubit/random/RandomInt.html[`RandomInt`] and link:{javadoc-url}/random/org/stubit/random/RandomInt.html[`RandomLong`] classes allow to generate random Integer/Long values within a defined min and max range (both inclusive).
 
-For simple integers there are several static methods available.
-More complex integers can be defined with a Builder class that's returned by the `andInt` method.
+For simple integers/longs there are several static methods available.
+More complex integers/long can be defined with Builder classes that's returned by the `anInt`/`aLong` methods.
 
-NOTE:: It is not possible to set max to Integer.MAX_VALUE.
-The maximum value is Integer.MAX_VALUE - 1.
-This is due to the fact that the SecureRandom.nextInt(int) method is exclusive of the upper bound.
+NOTE:: It is not possible to set max to `Integer.MAX_VALUE` or `Long.MAX_VALUE`.
+The maximum values are `Integer.MAX_VALUE - 1` and `Long.MAX_VALUE - 1`.
+This is due to the fact that the `SecureRandom.nextInt(int)` and `SecureRandom.nextLong(long)` methods are exclusive of the upper bound.
 
 
 === Between Min and Max
 
 [source,java,indent=0]
 ----
 include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=anIntBetween]
+
+include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=aLongBetween]
 ----
 
 
-=== Positive Integer
+=== Positive Integer/Long
 
 [source,java,indent=0]
 ----
 include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=aPositiveInt]
 ----
 
+[source,java,indent=0]
+----
+include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=aPositiveLong]
+----
+
 
-=== Negative Integer
+=== Negative Integer/Long
 
 [source,java,indent=0]
 ----
 include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=aNegativeInt]
 ----
 
+[source,java,indent=0]
+----
+include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=aNegativeLong]
+----
+
 
 === Builder
 
@@ -46,6 +58,11 @@ include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=aNegativeIn
 include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=anInt]
 ----
 
+[source,java,indent=0]
+----
+include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=aLong]
+----
+
 
 == Random Choice
 
@@ -128,3 +145,18 @@ include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=germanLicen
 ----
 include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=iranianLicensePlate]
 ----
+
+
+== Random Duration
+
+The link:{javadoc-url}/random/org/stubit/random/RandomDuration.html[`RandomDuration` class] allows to generate random Durations.
+
+[source,java,indent=0]
+----
+include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=aDurationBetween]
+----
+
+[source,java,indent=0]
+----
+include::../../../test/java/org/stubit/random/RandomDocTest.java[tag=aDuration]
+----

manual/src/test/java/org/stubit/random/RandomDocTest.java

@@ -5,17 +5,24 @@
 import static org.stubit.random.RandomChoice.aChoiceFromValuesOf;
 import static org.stubit.random.RandomChoice.any;
 import static org.stubit.random.RandomChoice.anyOf;
+import static org.stubit.random.RandomDuration.aDuration;
+import static org.stubit.random.RandomDuration.aDurationBetween;
 import static org.stubit.random.RandomInt.aNegativeInt;
 import static org.stubit.random.RandomInt.aPositiveInt;
 import static org.stubit.random.RandomInt.anInt;
 import static org.stubit.random.RandomInt.anIntBetween;
+import static org.stubit.random.RandomLong.aLong;
+import static org.stubit.random.RandomLong.aLongBetween;
+import static org.stubit.random.RandomLong.aNegativeLong;
+import static org.stubit.random.RandomLong.aPositiveLong;
 import static org.stubit.random.RandomString.aLetterFrom;
 import static org.stubit.random.RandomString.aStringStartingWith;
 import static org.stubit.random.RandomString.arabicDigits;
 import static org.stubit.random.RandomString.digitsFrom;
 import static org.stubit.random.RandomString.latinLetters;
 import static org.stubit.random.RandomString.lettersFrom;
 
+import java.time.Duration;
 import java.util.List;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
@@ -57,6 +64,41 @@ void randomIntBuilder_examples() {
     // end::anInt[]
   }
 
+  @Test
+  void randomLong_examples() {
+    // tag::aLongBetween[]
+    long someLongBetween42And4711 = aLongBetween(42, 4711);
+    assertThat(someLongBetween42And4711).isBetween(42L, 4711L);
+    // end::aLongBetween[]
+
+    // tag::aPositiveLong[]
+    long somePositiveLong = aPositiveLong();
+    assertThat(somePositiveLong).isPositive().isNotZero().isLessThan(Long.MAX_VALUE);
+    // end::aPositiveLong[]
+
+    // tag::aNegativeLong[]
+    long someNegativeLong = aNegativeLong();
+    assertThat(someNegativeLong).isNegative().isNotZero().isGreaterThanOrEqualTo(Long.MIN_VALUE);
+    // end::aNegativeLong[]
+  }
+
+  @Test
+  void randomLongBuilder_examples() {
+    // tag::aLong[]
+    long someLong = aLong().build();
+    assertThat(someLong).isBetween(Long.MIN_VALUE, Long.MAX_VALUE - 1);
+
+    long someLongBetween42And4711 = aLong().min(42L).max(4711L).build();
+    assertThat(someLongBetween42And4711).isBetween(42L, 4711L);
+
+    long someLongLessThan4711 = aLong().max(4711L).build();
+    assertThat(someLongLessThan4711).isLessThanOrEqualTo(4711L);
+
+    long someLongGreaterThanMinus10 = aLong().min(-42L).build();
+    assertThat(someLongGreaterThanMinus10).isGreaterThanOrEqualTo(-42L);
+    // end::aLong[]
+  }
+
   @Test
   void randomChoice_examples() {
     // tag::anyOf_ellipsis[]
@@ -162,4 +204,30 @@ void randomString_examples() {
     assertThat(iranianLicensePlate).matches("[۰-۹]{2}[\\u0600-\\u06FF][۰-۹]{3}");
     // end::iranianLicensePlate[]
   }
+
+  @Test
+  void randomDuration_examples() {
+    // tag::aDurationBetween[]
+    Duration someDuration = aDurationBetween(Duration.ZERO, Duration.ofDays(7));
+    assertThat(someDuration).isBetween(Duration.ZERO, Duration.ofDays(7));
+    // end::aDurationBetween[]
+  }
+
+  @Test
+  void randomDurationBuilder_examples() {
+    // tag::aDuration[]
+    Duration someDuration = aDuration().build();
+    assertThat(someDuration).isBetween(Duration.ZERO, Duration.ofSeconds(Long.MAX_VALUE - 1));
+
+    Duration someDurationBetween1And2Hours =
+        aDuration().min(Duration.ofHours(1)).max(Duration.ofHours(2)).build();
+    assertThat(someDurationBetween1And2Hours).isBetween(Duration.ofHours(1), Duration.ofHours(2));
+
+    Duration someDurationLessThan2Hours = aDuration().max(Duration.ofHours(2)).build();
+    assertThat(someDurationLessThan2Hours).isLessThanOrEqualTo(Duration.ofHours(2));
+
+    Duration someDurationGreaterThan1Hour = aDuration().min(Duration.ofHours(1)).build();
+    assertThat(someDurationGreaterThan1Hour).isGreaterThanOrEqualTo(Duration.ofHours(1));
+    // end::aDuration[]
+  }
 }