Added random shuffling of arrays and Lists (#305)

* Create Shuffler.java

* add Shuffler

* added shuffle methods

* update UML mermaid diagram

* update UML mermaid diagram

* fix UML diagram

* fix UML diagram

* Update CHANGELOG.md

* Bump org.cicirello.core to 2.7.0

* refactor

* Update Shuffler.java

* Update CHANGELOG.md

* refactor

* attempt to suppress PMD false positive

* Update Shuffler.java

* added missing override

* Update EnhancedStreamableGenerator.java

* added shuffling of Lists

* Update pom.xml

* update docs

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased] - 2024-05-10
+## [Unreleased] - 2024-05-14
 
 **BREAKING CHANGES: See Removed and Changed sections for details.**
 
@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   * Streams of random triples of distinct sorted integers (method sortedTriples)
   * Streams of random triples of distinct integers, separated by at most a specified window (method windowedTriples)
   * Streams of random triples of distinct sorted integers, separated by at most a specified window (method sortedWindowedTriples)
+* Shuffler class, and shuffle methods in EnhancedRandomGenerator class, for efficiently randomizing the ordering of elements in arrays and Lists.
 
 ### Changed
 * Refactored and optimized RandomIndexer.nextIntTriple methods.
@@ -46,7 +47,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Fixed potential finalizer vulnerability in class JacobiDiagonalization, identified by SpotBugs.
 
 ### Dependencies
-* Bump org.cicirello:core from 2.5.0 to 2.6.0.
+* Bump org.cicirello:core from 2.5.0 to 2.7.0.
 * Retired publishing of a `jar-with-dependencies` (BREAKING CHANGE only if you were using the `jar-with-dependencies`).
 
 ### CI/CD

README.md

@@ -56,6 +56,8 @@ Some of the randomization enhancements include:
 * Methods for generating random samples of k integers without replacement from a range of integers.
 * Methods to generate streams of numbers from distributions other than uniform, such as streams of random numbers 
   from binomial distributions, Cauchy distributions, exponential distributions, and Gaussian distributions.
+* Methods to generate streams of pairs of distinct integers, and streams of triples of distinct integers.
+* Methods for shuffling the elements of arrays and Lists.
 
 The ρμ library is a dependency of some of our other projects, 
 including [JavaPermutationTools](https://github.com/cicirello/JavaPermutationTools)
@@ -111,20 +113,23 @@ classDiagram
   class EnhancedRandomGenerator
   EnhancedRandomGenerator : -RandomGenerator generator
   RandomGenerator <|.. EnhancedRandomGenerator
+  class RandomVariates
+  class IndexPair
   class RandomSampler
-  RandomSampler <.. EnhancedRandomGenerator
   class RandomIndexer
+  class Shuffler
+  class IndexTriple
   RandomIndexer <.. EnhancedRandomGenerator
   RandomIndexer <.. RandomSampler
   RandomSampler <.. RandomIndexer
-  class RandomVariates
+  RandomSampler <.. EnhancedRandomGenerator
+  RandomIndexer <.. Shuffler
+  Shuffler <.. EnhancedRandomGenerator
   RandomVariates <.. EnhancedRandomGenerator
   RandomVariates <.. RandomSampler
-  class IndexPair
-  class IndexTriple
+  IndexPair <.. EnhancedRandomGenerator
   IndexPair <.. RandomIndexer
   IndexTriple <.. RandomIndexer
-  IndexPair <.. EnhancedRandomGenerator
   IndexTriple <.. EnhancedRandomGenerator
   class EnhancedStreamableGenerator
   EnhancedStreamableGenerator : -StreamableGenerator generator
@@ -176,7 +181,7 @@ and minimum supported Java version.
 
 | version | Java requirements |
 | --- | --- |
-| 2.w.x to 3.y.z | Java 17+ |
+| 2.w.x to 4.y.z | Java 17+ |
 | 1.x.y | Java 11+ |
 
 ## Versioning Scheme
@@ -249,7 +254,7 @@ the version number with the version that you want to use.
 <dependency>
   <groupId>org.cicirello</groupId>
   <artifactId>rho-mu</artifactId>
-  <version>3.0.0</version>
+  <version>4.0.0</version>
 </dependency>
 ```
 

pom.xml

@@ -6,7 +6,7 @@
 
 	<groupId>org.cicirello</groupId>
 	<artifactId>rho-mu</artifactId>
-	<version>3-SNAPSHOT</version>
+	<version>4-SNAPSHOT</version>
 	<packaging>jar</packaging>
 
 	<name>rho mu</name>
@@ -224,7 +224,7 @@
 		<dependency>
 			<groupId>org.cicirello</groupId>
 			<artifactId>core</artifactId>
-			<version>2.6.0</version>
+			<version>2.7.0</version>
 		</dependency>
 	</dependencies>
 

src/main/java/module-info.java

@@ -1,6 +1,6 @@
 /*
  * rho mu - A Java library of randomization enhancements and other math utilities.
- * Copyright 2017-2023 Vincent A. Cicirello
+ * Copyright 2017-2024 Vincent A. Cicirello
  *
  * This file is part of the rho mu library (https://rho-mu.cicirello.org/).
  *
@@ -26,7 +26,7 @@
  *
  * <h2>&rho;&mu; - A Java library of randomization enhancements and other math utilities.</h2>
  *
- * <p>Copyright &copy; 2017-2023 <a href="https://www.cicirello.org/" target=_top>Vincent A.
+ * <p>Copyright &copy; 2017-2024 <a href="https://www.cicirello.org/" target=_top>Vincent A.
  * Cicirello</a>.
  *
  * <p><a href="https://doi.org/10.21105/joss.04663"><img
@@ -107,6 +107,9 @@
  *   <li>Methods to generate streams of numbers from distributions other than uniform, such as
  *       streams of random numbers from binomial distributions, Cauchy distributions, exponential
  *       distributions, and Gaussian distributions.
+ *   <li>Methods to generate streams of pairs of distinct integers, and streams of triples of
+ *       distinct integers.
+ *   <li>Methods for shuffling the elements of arrays and Lists.
  * </ul>
  *
  * <p>The <a href="https://github.com/cicirello/rho-mu" target=_top>source code repository</a> is

src/main/java/org/cicirello/math/rand/EnhancedRandomGenerator.java

@@ -22,6 +22,7 @@
  */
 package org.cicirello.math.rand;
 
+import java.util.List;
 import java.util.SplittableRandom;
 import java.util.random.RandomGenerator;
 import java.util.stream.DoubleStream;
@@ -59,6 +60,7 @@
  *       distributions, and Gaussian distributions.
  *   <li>Methods to generate streams of pairs of distinct integers, and streams of triples of
  *       distinct integers.
+ *   <li>Methods for shuffling the elements of arrays and Lists.
  * </ul>
  *
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a
@@ -863,6 +865,223 @@ public final int[] sampleReservoir(int n, int k, int[] result) {
     return RandomSampler.sampleReservoir(n, k, result, generator);
   }
 
+  /**
+   * Randomizes the ordering of the elements of an array. All possible reorderings are equally
+   * likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   */
+  public final void shuffle(byte[] array) {
+    Shuffler.shuffle(array, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements within a portion of an array. All possible reorderings
+   * are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   * @param first the first element (inclusive) of the part of the array to shuffle
+   * @param last the last element (exclusive) of the part of the array to shuffle
+   * @throws ArrayIndexOutOfBoundsException if first is less than 0 or if last is greater than
+   *     array.length
+   */
+  public final void shuffle(byte[] array, int first, int last) {
+    Shuffler.shuffle(array, first, last, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements of an array. All possible reorderings are equally
+   * likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   */
+  public final void shuffle(char[] array) {
+    Shuffler.shuffle(array, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements within a portion of an array. All possible reorderings
+   * are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   * @param first the first element (inclusive) of the part of the array to shuffle
+   * @param last the last element (exclusive) of the part of the array to shuffle
+   * @throws ArrayIndexOutOfBoundsException if first is less than 0 or if last is greater than
+   *     array.length
+   */
+  public final void shuffle(char[] array, int first, int last) {
+    Shuffler.shuffle(array, first, last, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements of an array. All possible reorderings are equally
+   * likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   */
+  public final void shuffle(double[] array) {
+    Shuffler.shuffle(array, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements within a portion of an array. All possible reorderings
+   * are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   * @param first the first element (inclusive) of the part of the array to shuffle
+   * @param last the last element (exclusive) of the part of the array to shuffle
+   * @throws ArrayIndexOutOfBoundsException if first is less than 0 or if last is greater than
+   *     array.length
+   */
+  public final void shuffle(double[] array, int first, int last) {
+    Shuffler.shuffle(array, first, last, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements of an array. All possible reorderings are equally
+   * likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   */
+  public final void shuffle(float[] array) {
+    Shuffler.shuffle(array, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements within a portion of an array. All possible reorderings
+   * are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   * @param first the first element (inclusive) of the part of the array to shuffle
+   * @param last the last element (exclusive) of the part of the array to shuffle
+   * @throws ArrayIndexOutOfBoundsException if first is less than 0 or if last is greater than
+   *     array.length
+   */
+  public final void shuffle(float[] array, int first, int last) {
+    Shuffler.shuffle(array, first, last, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements of an array. All possible reorderings are equally
+   * likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   */
+  public final void shuffle(int[] array) {
+    Shuffler.shuffle(array, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements within a portion of an array. All possible reorderings
+   * are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   * @param first the first element (inclusive) of the part of the array to shuffle
+   * @param last the last element (exclusive) of the part of the array to shuffle
+   * @throws ArrayIndexOutOfBoundsException if first is less than 0 or if last is greater than
+   *     array.length
+   */
+  public final void shuffle(int[] array, int first, int last) {
+    Shuffler.shuffle(array, first, last, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements of an array. All possible reorderings are equally
+   * likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   */
+  public final void shuffle(long[] array) {
+    Shuffler.shuffle(array, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements within a portion of an array. All possible reorderings
+   * are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   * @param first the first element (inclusive) of the part of the array to shuffle
+   * @param last the last element (exclusive) of the part of the array to shuffle
+   * @throws ArrayIndexOutOfBoundsException if first is less than 0 or if last is greater than
+   *     array.length
+   */
+  public final void shuffle(long[] array, int first, int last) {
+    Shuffler.shuffle(array, first, last, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements of an array. All possible reorderings are equally
+   * likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   */
+  public final void shuffle(short[] array) {
+    Shuffler.shuffle(array, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements within a portion of an array. All possible reorderings
+   * are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   * @param first the first element (inclusive) of the part of the array to shuffle
+   * @param last the last element (exclusive) of the part of the array to shuffle
+   * @throws ArrayIndexOutOfBoundsException if first is less than 0 or if last is greater than
+   *     array.length
+   */
+  public final void shuffle(short[] array, int first, int last) {
+    Shuffler.shuffle(array, first, last, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements of an array. All possible reorderings are equally
+   * likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   * @param <T> type of array elements
+   */
+  public final <T> void shuffle(T[] array) {
+    Shuffler.shuffle(array, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements within a portion of an array. All possible reorderings
+   * are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * @param array the array to shuffle
+   * @param first the first element (inclusive) of the part of the array to shuffle
+   * @param last the last element (exclusive) of the part of the array to shuffle
+   * @param <T> type of array elements
+   * @throws ArrayIndexOutOfBoundsException if first is less than 0 or if last is greater than
+   *     array.length
+   */
+  public final <T> void shuffle(T[] array, int first, int last) {
+    Shuffler.shuffle(array, first, last, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements of a List. All possible reorderings are equally likely.
+   *
+   * @param list the List to shuffle
+   * @param <T> type of List elements
+   */
+  public final <T> void shuffle(List<T> list) {
+    Shuffler.shuffle(list, generator);
+  }
+
+  /**
+   * Randomizes the ordering of the elements of a portion of a List. All possible reorderings are
+   * equally likely.
+   *
+   * @param list the List to shuffle
+   * @param first the first element (inclusive) of the part of the List to shuffle
+   * @param last the last element (exclusive) of the part of the List to shuffle
+   * @param <T> type of List elements
+   */
+  public final <T> void shuffle(List<T> list, int first, int last) {
+    Shuffler.shuffle(list, first, last, generator);
+  }
+
   /**
    * Returns an effectively unlimited stream of pseudorandom pairs of int values, without
    * replacement, from the interval [0, n). Each pair is sorted such that i is the minimum and j is
@@ -1264,6 +1483,18 @@ public final IntStream ints(long streamSize) {
     return generator.ints(streamSize);
   }
 
+  /**
+   * Return true if the implementation of the RandomGenerator (algorithm) that is wrapped by this
+   * EnhancedRandomGenerator has been marked for deprecation.
+   *
+   * @return true if the implementation of the RandomGenerator (algorithm) that is wrapped by this
+   *     EnhancedRandomGenerator has been marked for deprecation
+   */
+  @Override
+  public final boolean isDeprecated() {
+    return generator.isDeprecated();
+  }
+
   /**
    * Returns an effectively unlimited stream of pseudorandom long values. <b>Delegates
    * implementation to the wrapped object.</b>

src/main/java/org/cicirello/math/rand/EnhancedStreamableGenerator.java

@@ -1,6 +1,6 @@
 /*
  * rho mu - A Java library of randomization enhancements and other math utilities.
- * Copyright (C) 2017-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ * Copyright (C) 2017-2024 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * This file is part of the rho mu library.
  *