T
- the type of items to iterate over; ideally, the items are uniquepublic class GapShuffler<T>
extends java.lang.Object
implements java.util.Iterator<T>, java.lang.Iterable<T>, java.io.Serializable
Constructor and Description |
---|
GapShuffler(java.util.Collection<T> elements)
Constructor that takes any Collection of T, shuffles it with an unseeded RNG, and can then iterate infinitely
through mostly-random shuffles of the given collection.
|
GapShuffler(java.util.Collection<T> items,
IRNG rng,
boolean shareRNG)
Constructor that takes any Collection of T, shuffles it with the given RNG, and can then iterate infinitely
through mostly-random shuffles of the given collection.
|
GapShuffler(java.util.Collection<T> items,
RandomnessSource rng)
Constructor that takes any Collection of T, shuffles it with the given RNG, and can then iterate infinitely
through mostly-random shuffles of the given collection.
|
GapShuffler(java.util.Collection<T> elements,
java.lang.String seed)
Constructor that takes any Collection of T, shuffles it with an unseeded RNG, and can then iterate infinitely
through mostly-random shuffles of the given collection.
|
GapShuffler(T single) |
GapShuffler(T[] elements)
Constructor that takes any Collection of T, shuffles it with an unseeded RNG, and can then iterate infinitely
through mostly-random shuffles of the given collection.
|
GapShuffler(T[] elements,
java.lang.CharSequence seed)
Constructor that takes any Collection of T, shuffles it with an unseeded RNG, and can then iterate infinitely
through mostly-random shuffles of the given collection.
|
GapShuffler(T[] items,
IRNG rng,
boolean shareRNG)
Constructor that takes any Collection of T, shuffles it with the given RNG, and can then iterate infinitely
through mostly-random shuffles of the given collection.
|
GapShuffler(T[] items,
RandomnessSource rng)
Constructor that takes any Collection of T, shuffles it with the given RNG, and can then iterate infinitely
through mostly-random shuffles of the given collection.
|
Modifier and Type | Method and Description |
---|---|
void |
fillInto(java.util.Collection<T> coll)
The internal items used here are private, but you can still use this method to put a shallow copy of them into
some other Collection.
|
IRNG |
getRNG() |
boolean |
hasNext()
Returns
true if the iteration has more elements. |
java.util.Iterator<T> |
iterator()
Returns an infinite iterator over elements of type
T ; the returned iterator is this object. |
T |
next()
Gets the next element of the infinite sequence of T this shuffles through.
|
void |
remove()
Not supported.
|
void |
setRNG(IRNG rng)
Sets the IRNG this uses to shuffle the order of elements, always copying the given IRNG before using it.
|
void |
setRNG(IRNG rng,
boolean shareRNG)
Sets the IRNG this uses to shuffle the order of elements, optionally sharing a reference between outside code and
the internal rng (when
shareRNG is true). |
public IRNG rng
public GapShuffler(T single)
public GapShuffler(java.util.Collection<T> elements)
elements
- a Collection of T that will not be modifiedpublic GapShuffler(java.util.Collection<T> elements, java.lang.String seed)
elements
- a Collection of T that will not be modifiedpublic GapShuffler(java.util.Collection<T> items, RandomnessSource rng)
LongPeriodRNG
as its RandomnessSource, since it is in general a good choice for shuffling, or
XoshiroStarPhi32RNG
for GWT or other 32-bit platforms, but the choice is unlikely to matter in practice.items
- a Collection of T that will not be modifiedrng
- an IRNG that can be pre-seeded; will be copied and not used directlypublic GapShuffler(java.util.Collection<T> items, IRNG rng, boolean shareRNG)
shareRNG
is true, otherwise the reference will be shared (which could
make the results of this GapShuffler depend on outside code, though it will always maintain a gap between
identical elements if the elements are unique). I suggest that the IRNG should use LongPeriodRNG
as its
RandomnessSource, since it is in general a good choice for shuffling, or XoshiroStarPhi32RNG
for GWT or
other 32-bit platforms, but the choice is unlikely to matter in practice. Any IStatefulRNG
should work in
most cases, like GWTRNG
, StatefulRNG
, or SilkRNG
. If you encounter unusually-low-quality
shuffles, try a different starting seed, and if that doesn't work, try SilkRNG (it has a different internal
structure than the other types; it could yield better results at the very start).items
- a Collection of T that will not be modifiedrng
- an IRNG that can be pre-seeded; will be copied and not used directlyshareRNG
- if false, rng
will be copied and no reference will be kept; if true, rng
will be shared with the outside codepublic GapShuffler(T[] elements)
elements
- a Collection of T that will not be modifiedpublic GapShuffler(T[] elements, java.lang.CharSequence seed)
elements
- a Collection of T that will not be modifiedpublic GapShuffler(T[] items, RandomnessSource rng)
LongPeriodRNG
as its RandomnessSource, since it is in general a good choice for shuffling, or
XoshiroStarPhi32RNG
for GWT or other 32-bit platforms, but the choice is unlikely to matter in practice.items
- a Collection of T that will not be modifiedrng
- an IRNG that can be pre-seeded; will be copied and not used directlypublic GapShuffler(T[] items, IRNG rng, boolean shareRNG)
shareRNG
is false, otherwise the reference will be shared (which could
make the results of this GapShuffler depend on outside code, though it will always maintain a gap between
identical elements if the elements are unique). I suggest that the IRNG should use LongPeriodRNG
as its
RandomnessSource, since it is in general a good choice for shuffling, or XoshiroStarPhi32RNG
for GWT or
other 32-bit platforms, but the choice is unlikely to matter in practice. Any IStatefulRNG
should work in
most cases, like GWTRNG
, StatefulRNG
, or SilkRNG
. If you encounter unusually-low-quality
shuffles, try a different starting seed, and if that doesn't work, try SilkRNG (it has a different internal
structure than the other types; it could yield better results at the very start).items
- a Collection of T that will not be modifiedrng
- an IRNG that can be pre-seeded; will be copied and not used directlyshareRNG
- if false, rng
will be copied and no reference will be kept; if true, rng
will be shared with the outside codepublic T next()
next
in interface java.util.Iterator<T>
public boolean hasNext()
true
if the iteration has more elements.
This is always the case for GapShuffler.hasNext
in interface java.util.Iterator<T>
true
alwayspublic void remove()
remove
in interface java.util.Iterator<T>
java.lang.UnsupportedOperationException
- always throws this exceptionpublic java.util.Iterator<T> iterator()
T
; the returned iterator is this object.
You should be prepared to break out of any for loops that use this once you've gotten enough elements!
The remove() method is not supported by this iterator and hasNext() will always return true.iterator
in interface java.lang.Iterable<T>
public IRNG getRNG()
public void setRNG(IRNG rng)
rng
- an IRNG, such as RNG
, GWTRNG
, StatefulRNG
, and so on; always copiedpublic void setRNG(IRNG rng, boolean shareRNG)
shareRNG
is true). Always reshuffles the order, which may eliminate a gap that
should have been present, so treat the sequence before and after like separate GapShuffler objects.rng
- an IRNG, such as RNG
, GWTRNG
, StatefulRNG
, and so onshareRNG
- if false, rng
will be copied and no reference will be kept; if true, rng
will be shared with the outside codepublic void fillInto(java.util.Collection<T> coll)
T
is mutable, changes to individual items will be reflected in this
GapShuffler, so be careful in that case (if T is immutable, like if it is String, then there's nothing to need to
be careful about). This copies each item in the GapShuffler's sequence once, in no particular order, but it may
give a prediction of what items this will return in the future (or has already returned).coll
- a Collection that will have each of the possible items this can produce added into it, in no particular orderCopyright © Eben Howard 2012–2022. All rights reserved.