(v2.4.0) Add shuffling of collections

README.md

@@ -130,6 +130,7 @@ import static io.qala.datagen.RandomShortApi.*;
 |`from("A", "B", "C", "D").sample()`                      | `sample("A", "B", "C")`                | `"C"`
 |`from("A", "B", "C", "D").sample(2)`                     | `sampleMultiple(2, "A", "B", "C")`     | `["B", "A"]`
 |`from("A", "B").sampleWithReplacement(3)`                |                                        | `["A", "A", "B"]`
+|`from("A", "B", "C").sampleWithReplacement(3)`           | shuffled("A", "B", "C")                | `["C", "A", "B"]`
 
 ## Java Date
 

datagen/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>qala-datagen-parent</artifactId>
         <groupId>io.qala.datagen</groupId>
-        <version>2.3.0</version>
+        <version>2.4.0</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

datagen/src/main/java/io/qala/datagen/RandomElements.java

@@ -1,9 +1,6 @@
 package io.qala.datagen;
 
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.List;
+import java.util.*;
 
 import static io.qala.datagen.RandomShortApi.integer;
 
@@ -90,6 +87,17 @@ public List<T> sampleWithReplacement(int nToReturn) {
         return result;
     }
 
+    /**
+     * Returns a collection with the elements passed in the constructor but with a random order.
+     *
+     * @return new List of the same size, but with elements in random order
+     */
+    public List<T> shuffled() {
+        List<T> result = new ArrayList<T>(this.elements);
+        Collections.shuffle(result);
+        return result;
+    }
+
     private int size() {
         return elements.size();
     }

datagen/src/main/java/io/qala/datagen/RandomShortApi.java

@@ -330,6 +330,24 @@ public static <T> List<T> sampleMultiple(int nToReturn, Collection<T> toSampleFr
     @SafeVarargs public static <T> List<T> sampleMultiple(int nToReturn, T... toSampleFrom) {
         return from(toSampleFrom).sample(nToReturn);
     }
+    /**
+     * Returns new collection with the same elements but in random order.
+     *
+     * @param toShuffle collection to shuffle
+     * @return new List of the same size, but with elements in random order
+     */
+    public static <T> List<T> shuffled(Collection<T> toShuffle) {
+        return from(toShuffle).shuffled();
+    }
+    /**
+     * Returns a List with the specified elements in random order.
+     *
+     * @param toShuffle elements to shuffle
+     * @return a List with the specified elements in random order
+     */
+    @SafeVarargs public static <T> List<T> shuffled(T... toShuffle) {
+        return from(toShuffle).shuffled();
+    }
 
     /**
      * Invokes one and only one of the specified functions. This is an API for Java8 Lambdas.

datagen/src/test/java/io/qala/datagen/RandomElementsTest.java

@@ -9,21 +9,20 @@
 
 import static io.qala.datagen.RandomElements.from;
 import static io.qala.datagen.RandomShortApi.*;
-import static io.qala.datagen.RandomValue.length;
-import static io.qala.datagen.RandomValue.upTo;
+import static io.qala.datagen.RandomValue.*;
 import static java.util.Collections.emptyList;
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.*;
 import static org.junit.jupiter.api.Assertions.*;
 
 @DisplayName("Random Elements")
-public class RandomElementsTest {
+class RandomElementsTest {
     @Test void canSampleTheOnlyElementOfList() {
         assertEquals("ABC", from("ABC").sample());
     }
 
     @Test void canSampleOneElementFromList() {
-        List<String> list = upTo(10).alphanumerics();
+        List<String> list = between(0, 10).alphanumerics();
         assertThat(list, hasItem(from(list).sample()));
         assertThat(list, hasItem(sample(list)));
     }
@@ -58,21 +57,48 @@ public class RandomElementsTest {
     @Test void throwsIfCollectionToSampleFromIsEmpty() {
         assertThrows(IllegalArgumentException.class, () -> from().sample(3));
         assertThrows(IllegalArgumentException.class, () -> sampleMultiple(0));
-        assertThrows(IllegalArgumentException.class, () -> sample());
+        assertThrows(IllegalArgumentException.class, RandomShortApi::sample);
     }
     @Test void canSampleMultipleElementsFromList() {
-        List<String> population = upTo(10).alphanumerics(5, 10);
+        List<String> population = between(0, 10).alphanumerics(5, 10);
         List<String> sample = from(population).sample(5);
 
         assertEquals(5, sample.size());
-        assertThat(population, hasItems(sample.toArray(new String[sample.size()])));
+        assertThat(population, hasItems(sample.toArray(new String[0])));
     }
     @Test void samplesDuplicateElements_ifSampleSizeLargerThanPopulation_andSamplingIsWithReplacement() {
-        List<String> population = upTo(10).alphanumerics(2);
+        System.out.println(from("A", "B", "C").shuffled());
+        List<String> population = between(0, 10).alphanumerics(2);
         List<String> sample = from(population).sampleWithReplacement(5);
 
         assertEquals(5, sample.size());
-        assertThat(population, hasItems(sample.toArray(new String[sample.size()])));
+        assertThat(population, hasItems(sample.toArray(new String[0])));
+    }
+    @Test void shuffledCollectionSharesAllElementsWithOriginalCollection() {
+        List<String> original = between(0, 10).alphanumerics(2);
+        List<String> shuffled = from(original).shuffled();
+
+        assertNotSame(original, shuffled);
+        assertEquals(original.size(), shuffled.size());
+        assertTrue(original.containsAll(shuffled));
+        assertTrue(shuffled.containsAll(original));
+    }
+    @Test void shuffledCollectionHasElementsInDifferentOrder_fromOriginalCollection() {
+        List<String> original = length(10).alphanumerics(200);
+        List<String> shuffled = shuffled(original);
+
+        assertNotEquals(original, shuffled);
+        assertTrue(original.containsAll(shuffled));
+        assertTrue(shuffled.containsAll(original));
+    }
+    @Test void shuffledCollectionHasElementsInDifferentOrder_fromOriginalArray() {
+        List<String> original = length(10).alphanumerics(200);
+        String[] originalArray = original.toArray(new String[]{});
+        List<String> shuffled = shuffled(originalArray);
+
+        assertNotEquals(original, shuffled);
+        assertTrue(original.containsAll(shuffled));
+        assertTrue(shuffled.containsAll(original));
     }
 
     @Test void nullOrObj_returnsNull_sometimes() {

examples/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>qala-datagen-parent</artifactId>
         <groupId>io.qala.datagen</groupId>
-        <version>2.3.0</version>
+        <version>2.4.0</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

java8types/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>qala-datagen-parent</artifactId>
         <groupId>io.qala.datagen</groupId>
-        <version>2.3.0</version>
+        <version>2.4.0</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

junit5/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <artifactId>qala-datagen-parent</artifactId>
         <groupId>io.qala.datagen</groupId>
-        <version>2.3.0</version>
+        <version>2.4.0</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 

pom.xml

@@ -7,7 +7,7 @@
     <groupId>io.qala.datagen</groupId>
     <artifactId>qala-datagen-parent</artifactId>
     <packaging>pom</packaging>
-    <version>2.3.0</version>
+    <version>2.4.0</version>
 
     <licenses>
         <license>