This is an automated email from the ASF dual-hosted git repository.
aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-rng.git
The following commit(s) were added to refs/heads/master by this push:
new 9951b22e RNG-184: Change to return the input array to allow chaining
9951b22e is described below
commit 9951b22e5ca412c8388fcca3e78c08ecc06eae49
Author: aherbert <aherb...@apache.org>
AuthorDate: Fri Jul 21 09:54:36 2023 +0100
RNG-184: Change to return the input array to allow chaining
---
.../apache/commons/rng/sampling/ArraySampler.java | 72 ++++++++++++++++------
.../commons/rng/sampling/ArraySamplerTest.java | 54 ++++++++++++++++
2 files changed, 108 insertions(+), 18 deletions(-)
diff --git
a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/ArraySampler.java
b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/ArraySampler.java
index 8c739d57..e2772ce4 100644
---
a/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/ArraySampler.java
+++
b/commons-rng-sampling/src/main/java/org/apache/commons/rng/sampling/ArraySampler.java
@@ -36,11 +36,13 @@ public final class ArraySampler {
*
* @param rng Source of randomness.
* @param array Array whose entries will be shuffled (in-place).
+ * @return a reference to the given array
*/
- public static void shuffle(UniformRandomProvider rng, boolean[] array) {
+ public static boolean[] shuffle(UniformRandomProvider rng, boolean[]
array) {
for (int i = array.length; i > 1; i--) {
swap(array, i - 1, rng.nextInt(i));
}
+ return array;
}
/**
@@ -48,11 +50,13 @@ public final class ArraySampler {
*
* @param rng Source of randomness.
* @param array Array whose entries will be shuffled (in-place).
+ * @return a reference to the given array
*/
- public static void shuffle(UniformRandomProvider rng, byte[] array) {
+ public static byte[] shuffle(UniformRandomProvider rng, byte[] array) {
for (int i = array.length; i > 1; i--) {
swap(array, i - 1, rng.nextInt(i));
}
+ return array;
}
/**
@@ -60,11 +64,13 @@ public final class ArraySampler {
*
* @param rng Source of randomness.
* @param array Array whose entries will be shuffled (in-place).
+ * @return a reference to the given array
*/
- public static void shuffle(UniformRandomProvider rng, char[] array) {
+ public static char[] shuffle(UniformRandomProvider rng, char[] array) {
for (int i = array.length; i > 1; i--) {
swap(array, i - 1, rng.nextInt(i));
}
+ return array;
}
/**
@@ -72,11 +78,13 @@ public final class ArraySampler {
*
* @param rng Source of randomness.
* @param array Array whose entries will be shuffled (in-place).
+ * @return a reference to the given array
*/
- public static void shuffle(UniformRandomProvider rng, double[] array) {
+ public static double[] shuffle(UniformRandomProvider rng, double[] array) {
for (int i = array.length; i > 1; i--) {
swap(array, i - 1, rng.nextInt(i));
}
+ return array;
}
/**
@@ -84,11 +92,13 @@ public final class ArraySampler {
*
* @param rng Source of randomness.
* @param array Array whose entries will be shuffled (in-place).
+ * @return a reference to the given array
*/
- public static void shuffle(UniformRandomProvider rng, float[] array) {
+ public static float[] shuffle(UniformRandomProvider rng, float[] array) {
for (int i = array.length; i > 1; i--) {
swap(array, i - 1, rng.nextInt(i));
}
+ return array;
}
/**
@@ -96,11 +106,13 @@ public final class ArraySampler {
*
* @param rng Source of randomness.
* @param array Array whose entries will be shuffled (in-place).
+ * @return a reference to the given array
*/
- public static void shuffle(UniformRandomProvider rng, int[] array) {
+ public static int[] shuffle(UniformRandomProvider rng, int[] array) {
for (int i = array.length; i > 1; i--) {
swap(array, i - 1, rng.nextInt(i));
}
+ return array;
}
/**
@@ -108,11 +120,13 @@ public final class ArraySampler {
*
* @param rng Source of randomness.
* @param array Array whose entries will be shuffled (in-place).
+ * @return a reference to the given array
*/
- public static void shuffle(UniformRandomProvider rng, long[] array) {
+ public static long[] shuffle(UniformRandomProvider rng, long[] array) {
for (int i = array.length; i > 1; i--) {
swap(array, i - 1, rng.nextInt(i));
}
+ return array;
}
/**
@@ -120,11 +134,13 @@ public final class ArraySampler {
*
* @param rng Source of randomness.
* @param array Array whose entries will be shuffled (in-place).
+ * @return a reference to the given array
*/
- public static void shuffle(UniformRandomProvider rng, short[] array) {
+ public static short[] shuffle(UniformRandomProvider rng, short[] array) {
for (int i = array.length; i > 1; i--) {
swap(array, i - 1, rng.nextInt(i));
}
+ return array;
}
/**
@@ -133,11 +149,13 @@ public final class ArraySampler {
* @param <T> Type of the items.
* @param rng Source of randomness.
* @param array Array whose entries will be shuffled (in-place).
+ * @return a reference to the given array
*/
- public static <T> void shuffle(UniformRandomProvider rng, T[] array) {
+ public static <T> T[] shuffle(UniformRandomProvider rng, T[] array) {
for (int i = array.length; i > 1; i--) {
swap(array, i - 1, rng.nextInt(i));
}
+ return array;
}
/**
@@ -147,13 +165,15 @@ public final class ArraySampler {
* @param array Array whose entries will be shuffled (in-place).
* @param from Lower-bound (inclusive) of the sub-range.
* @param to Upper-bound (exclusive) of the sub-range.
+ * @return a reference to the given array
* @throws IndexOutOfBoundsException if the sub-range is out of bounds
*/
- public static void shuffle(UniformRandomProvider rng, boolean[] array, int
from, int to) {
+ public static boolean[] shuffle(UniformRandomProvider rng, boolean[]
array, int from, int to) {
final int length = to - checkFromToIndex(from, to, array.length);
for (int i = length; i > 1; i--) {
swap(array, from + i - 1, from + rng.nextInt(i));
}
+ return array;
}
/**
@@ -163,13 +183,15 @@ public final class ArraySampler {
* @param array Array whose entries will be shuffled (in-place).
* @param from Lower-bound (inclusive) of the sub-range.
* @param to Upper-bound (exclusive) of the sub-range.
+ * @return a reference to the given array
* @throws IndexOutOfBoundsException if the sub-range is out of bounds
*/
- public static void shuffle(UniformRandomProvider rng, byte[] array, int
from, int to) {
+ public static byte[] shuffle(UniformRandomProvider rng, byte[] array, int
from, int to) {
final int length = to - checkFromToIndex(from, to, array.length);
for (int i = length; i > 1; i--) {
swap(array, from + i - 1, from + rng.nextInt(i));
}
+ return array;
}
/**
@@ -179,13 +201,15 @@ public final class ArraySampler {
* @param array Array whose entries will be shuffled (in-place).
* @param from Lower-bound (inclusive) of the sub-range.
* @param to Upper-bound (exclusive) of the sub-range.
+ * @return a reference to the given array
* @throws IndexOutOfBoundsException if the sub-range is out of bounds
*/
- public static void shuffle(UniformRandomProvider rng, char[] array, int
from, int to) {
+ public static char[] shuffle(UniformRandomProvider rng, char[] array, int
from, int to) {
final int length = to - checkFromToIndex(from, to, array.length);
for (int i = length; i > 1; i--) {
swap(array, from + i - 1, from + rng.nextInt(i));
}
+ return array;
}
/**
@@ -195,13 +219,15 @@ public final class ArraySampler {
* @param array Array whose entries will be shuffled (in-place).
* @param from Lower-bound (inclusive) of the sub-range.
* @param to Upper-bound (exclusive) of the sub-range.
+ * @return a reference to the given array
* @throws IndexOutOfBoundsException if the sub-range is out of bounds
*/
- public static void shuffle(UniformRandomProvider rng, double[] array, int
from, int to) {
+ public static double[] shuffle(UniformRandomProvider rng, double[] array,
int from, int to) {
final int length = to - checkFromToIndex(from, to, array.length);
for (int i = length; i > 1; i--) {
swap(array, from + i - 1, from + rng.nextInt(i));
}
+ return array;
}
/**
@@ -211,13 +237,15 @@ public final class ArraySampler {
* @param array Array whose entries will be shuffled (in-place).
* @param from Lower-bound (inclusive) of the sub-range.
* @param to Upper-bound (exclusive) of the sub-range.
+ * @return a reference to the given array
* @throws IndexOutOfBoundsException if the sub-range is out of bounds
*/
- public static void shuffle(UniformRandomProvider rng, float[] array, int
from, int to) {
+ public static float[] shuffle(UniformRandomProvider rng, float[] array,
int from, int to) {
final int length = to - checkFromToIndex(from, to, array.length);
for (int i = length; i > 1; i--) {
swap(array, from + i - 1, from + rng.nextInt(i));
}
+ return array;
}
/**
@@ -227,13 +255,15 @@ public final class ArraySampler {
* @param array Array whose entries will be shuffled (in-place).
* @param from Lower-bound (inclusive) of the sub-range.
* @param to Upper-bound (exclusive) of the sub-range.
+ * @return a reference to the given array
* @throws IndexOutOfBoundsException if the sub-range is out of bounds
*/
- public static void shuffle(UniformRandomProvider rng, int[] array, int
from, int to) {
+ public static int[] shuffle(UniformRandomProvider rng, int[] array, int
from, int to) {
final int length = to - checkFromToIndex(from, to, array.length);
for (int i = length; i > 1; i--) {
swap(array, from + i - 1, from + rng.nextInt(i));
}
+ return array;
}
/**
@@ -243,13 +273,15 @@ public final class ArraySampler {
* @param array Array whose entries will be shuffled (in-place).
* @param from Lower-bound (inclusive) of the sub-range.
* @param to Upper-bound (exclusive) of the sub-range.
+ * @return a reference to the given array
* @throws IndexOutOfBoundsException if the sub-range is out of bounds
*/
- public static void shuffle(UniformRandomProvider rng, long[] array, int
from, int to) {
+ public static long[] shuffle(UniformRandomProvider rng, long[] array, int
from, int to) {
final int length = to - checkFromToIndex(from, to, array.length);
for (int i = length; i > 1; i--) {
swap(array, from + i - 1, from + rng.nextInt(i));
}
+ return array;
}
/**
@@ -259,13 +291,15 @@ public final class ArraySampler {
* @param array Array whose entries will be shuffled (in-place).
* @param from Lower-bound (inclusive) of the sub-range.
* @param to Upper-bound (exclusive) of the sub-range.
+ * @return a reference to the given array
* @throws IndexOutOfBoundsException if the sub-range is out of bounds
*/
- public static void shuffle(UniformRandomProvider rng, short[] array, int
from, int to) {
+ public static short[] shuffle(UniformRandomProvider rng, short[] array,
int from, int to) {
final int length = to - checkFromToIndex(from, to, array.length);
for (int i = length; i > 1; i--) {
swap(array, from + i - 1, from + rng.nextInt(i));
}
+ return array;
}
/**
@@ -276,13 +310,15 @@ public final class ArraySampler {
* @param array Array whose entries will be shuffled (in-place).
* @param from Lower-bound (inclusive) of the sub-range.
* @param to Upper-bound (exclusive) of the sub-range.
+ * @return a reference to the given array
* @throws IndexOutOfBoundsException if the sub-range is out of bounds
*/
- public static <T> void shuffle(UniformRandomProvider rng, T[] array, int
from, int to) {
+ public static <T> T[] shuffle(UniformRandomProvider rng, T[] array, int
from, int to) {
final int length = to - checkFromToIndex(from, to, array.length);
for (int i = length; i > 1; i--) {
swap(array, from + i - 1, from + rng.nextInt(i));
}
+ return array;
}
/**
diff --git
a/commons-rng-sampling/src/test/java/org/apache/commons/rng/sampling/ArraySamplerTest.java
b/commons-rng-sampling/src/test/java/org/apache/commons/rng/sampling/ArraySamplerTest.java
index 12c25c02..7229896d 100644
---
a/commons-rng-sampling/src/test/java/org/apache/commons/rng/sampling/ArraySamplerTest.java
+++
b/commons-rng-sampling/src/test/java/org/apache/commons/rng/sampling/ArraySamplerTest.java
@@ -100,6 +100,60 @@ class ArraySamplerTest {
Assertions.assertThrows(NullPointerException.class, () ->
ArraySampler.shuffle(rng, (Object[]) null, 0, 2));
}
+ @ParameterizedTest
+ @ValueSource(ints = {0, 1, 3})
+ void testReturnedReference(int length) {
+ final UniformRandomProvider rng = RandomAssert.seededRNG();
+ final boolean[] a = new boolean[length];
+ final byte[] b = new byte[length];
+ final char[] c = new char[length];
+ final double[] d = new double[length];
+ final float[] e = new float[length];
+ final int[] f = new int[length];
+ final long[] g = new long[length];
+ final short[] h = new short[length];
+ final Object[] i = new Object[length];
+ Assertions.assertSame(a, ArraySampler.shuffle(rng, a));
+ Assertions.assertSame(b, ArraySampler.shuffle(rng, b));
+ Assertions.assertSame(c, ArraySampler.shuffle(rng, c));
+ Assertions.assertSame(d, ArraySampler.shuffle(rng, d));
+ Assertions.assertSame(e, ArraySampler.shuffle(rng, e));
+ Assertions.assertSame(f, ArraySampler.shuffle(rng, f));
+ Assertions.assertSame(g, ArraySampler.shuffle(rng, g));
+ Assertions.assertSame(h, ArraySampler.shuffle(rng, h));
+ Assertions.assertSame(i, ArraySampler.shuffle(rng, i));
+ }
+
+ @ParameterizedTest
+ @CsvSource({
+ "0, 0, 0",
+ "0, 2, 2",
+ "0, 2, 4",
+ "1, 3, 4",
+ "2, 4, 4",
+ })
+ void testReturnedReferenceRange(int from, int to, int length) {
+ final UniformRandomProvider rng = RandomAssert.seededRNG();
+ final boolean[] a = new boolean[length];
+ final byte[] b = new byte[length];
+ final char[] c = new char[length];
+ final double[] d = new double[length];
+ final float[] e = new float[length];
+ final int[] f = new int[length];
+ final long[] g = new long[length];
+ final short[] h = new short[length];
+ final Object[] i = new Object[length];
+ Assertions.assertSame(a, ArraySampler.shuffle(rng, a, from, to));
+ Assertions.assertSame(b, ArraySampler.shuffle(rng, b, from, to));
+ Assertions.assertSame(c, ArraySampler.shuffle(rng, c, from, to));
+ Assertions.assertSame(d, ArraySampler.shuffle(rng, d, from, to));
+ Assertions.assertSame(e, ArraySampler.shuffle(rng, e, from, to));
+ Assertions.assertSame(f, ArraySampler.shuffle(rng, f, from, to));
+ Assertions.assertSame(g, ArraySampler.shuffle(rng, g, from, to));
+ Assertions.assertSame(h, ArraySampler.shuffle(rng, h, from, to));
+ Assertions.assertSame(i, ArraySampler.shuffle(rng, i, from, to));
+ }
+
// Shuffle tests for randomness performed on int[].
// All other implementations must match int[] shuffle.
