8294693: Add Collections.shuffle overload that accepts RandomGenerator interface

Reviewed-by: smarks, darcy
This commit is contained in:
Tagir F. Valeev 2023-01-21 18:36:31 +00:00
parent c8dd7583a9
commit 67b1c890b3
2 changed files with 105 additions and 6 deletions
src/java.base/share/classes/java/util
test/jdk/java/util/Collections

@ -1,5 +1,5 @@
/*
* Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -37,6 +37,7 @@ import java.util.function.Function;
import java.util.function.IntFunction;
import java.util.function.Predicate;
import java.util.function.UnaryOperator;
import java.util.random.RandomGenerator;
import java.util.stream.IntStream;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;
@ -411,8 +412,8 @@ public class Collections {
* portion of the list that runs from the first element to the current
* position, inclusive.
*
* <p>This method runs in linear time. If the specified list does not
* implement the {@link RandomAccess} interface and is large, this
* @implSpec This method runs in linear time. If the specified list does
* not implement the {@link RandomAccess} interface and is large, this
* implementation dumps the specified list into an array before shuffling
* it, and dumps the shuffled array back into the list. This avoids the
* quadratic behavior that would result from shuffling a "sequential
@ -431,6 +432,24 @@ public class Collections {
private static Random r;
/**
* Randomly permute the specified list using the specified source of
* randomness.<p>
*
* This method is equivalent to {@link #shuffle(List, RandomGenerator)}
* and exists for backward compatibility. The {@link #shuffle(List, RandomGenerator)}
* method is preferred, as it is not limited to random generators
* that extend the {@link Random} class.
*
* @param list the list to be shuffled.
* @param rnd the source of randomness to use to shuffle the list.
* @throws UnsupportedOperationException if the specified list or its
* list-iterator does not support the {@code set} operation.
*/
public static void shuffle(List<?> list, Random rnd) {
shuffle(list, (RandomGenerator) rnd);
}
/**
* Randomly permute the specified list using the specified source of
* randomness. All permutations occur with equal likelihood
@ -442,8 +461,8 @@ public class Collections {
* portion of the list that runs from the first element to the current
* position, inclusive.<p>
*
* This method runs in linear time. If the specified list does not
* implement the {@link RandomAccess} interface and is large, this
* @implSpec This method runs in linear time. If the specified list does
* not implement the {@link RandomAccess} interface and is large, this
* implementation dumps the specified list into an array before shuffling
* it, and dumps the shuffled array back into the list. This avoids the
* quadratic behavior that would result from shuffling a "sequential
@ -453,9 +472,10 @@ public class Collections {
* @param rnd the source of randomness to use to shuffle the list.
* @throws UnsupportedOperationException if the specified list or its
* list-iterator does not support the {@code set} operation.
* @since 21
*/
@SuppressWarnings({"rawtypes", "unchecked"})
public static void shuffle(List<?> list, Random rnd) {
public static void shuffle(List<?> list, RandomGenerator rnd) {
int size = list.size();
if (size < SHUFFLE_THRESHOLD || list instanceof RandomAccess) {
for (int i=size; i>1; i--)

@ -0,0 +1,79 @@
/*
* Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
* @test
* @bug 8294693
* @summary Basic test for Collections.shuffle
* @key randomness
*/
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedList;
import java.util.List;
import java.util.Random;
import java.util.function.Consumer;
import java.util.random.RandomGenerator;
public class Shuffle {
static final int N = 100;
public static void main(String[] args) {
test(new ArrayList<>());
test(new LinkedList<>());
}
static void test(List<Integer> list) {
for (int i = 0; i < N; i++) {
list.add(i);
}
Collections.shuffle(list);
if (list.size() != N) {
throw new RuntimeException(list.getClass() + ": size " + list.size() + " != " + N);
}
for (int i = 0; i < N; i++) {
if (!list.contains(i)) {
throw new RuntimeException(list.getClass() + ": does not contain " + i);
}
}
checkRandom(list, l -> Collections.shuffle(l, new Random(1)));
RandomGenerator.JumpableGenerator generator = RandomGenerator.JumpableGenerator.of("Xoshiro256PlusPlus");
checkRandom(list, l -> Collections.shuffle(l, generator.copy()));
}
private static void checkRandom(List<Integer> list, Consumer<List<?>> randomizer) {
list.sort(null);
randomizer.accept(list);
ArrayList<Integer> copy = new ArrayList<>(list);
list.sort(null);
if (list.equals(copy)) {
// Assume that at least one pair of elements must be reordered during shuffle
throw new RuntimeException(list.getClass() + ": list is not shuffled");
}
randomizer.accept(list);
if (!list.equals(copy)) {
throw new RuntimeException(list.getClass() + ": " + list + " != " + copy);
}
}
}