Class GapShuffler<T>

java.lang.Object
com.github.yellowstonegames.core.GapShuffler<T>
Type Parameters:
T - the type of items to iterate over; ideally, the items are unique
All Implemented Interfaces:
ISerializersNeeded, Iterable<T>, Iterator<T>
public class GapShuffler<T> extends Object implements Iterator<T>, Iterable<T>, ISerializersNeeded
Meant to take a fixed-size set of items and produce a shuffled stream of them such that an element is never chosen in quick succession; that is, there should always be a gap between the same item's occurrences. This is an Iterable of T, not a Collection, because it can iterate without stopping, infinitely, unless you break out of a foreach loop that iterates through one of these, or call the iterator's next() method only a limited number of times. Collections have a size that can be checked, but Iterables can be infinite (and in this case, this one is).
You can serialize this with Fory without needing a serializer, as long as you have the classes in getSerializersNeeded() registered. You probably need to register the concrete subclass of EnhancedRandom you use here; the default subclass of EnhancedRandom used here is AceRandom, unless you have provided your own with a different type. If you use JSON, a serializer is available in squidstore.grid, and if you use Kryo, one is available in squidfreeze.grid .

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected com.github.tommyettinger.ds.ObjectList<T>
    elements
     
    protected int
    index
     
    com.github.tommyettinger.random.EnhancedRandom
    random
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    GapShuffler()
     
    GapShuffler(GapShuffler<T> other)
    Copy constructor; duplicates other, you know the deal.
    GapShuffler(Collection<T> elements)
    Constructor that takes any Collection of T, shuffles it with an unseeded AceRandom, and can then iterate infinitely through mostly-random shuffles of the given collection.
    GapShuffler(Collection<T> items, com.github.tommyettinger.random.EnhancedRandom random)
    Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom, WhiskerRandom or, if you need compatibility with SquidLib 3.0.0, a SilkRNG from squidold), and can then iterate infinitely through mostly-random shuffles of the given collection.
    GapShuffler(Collection<T> items, com.github.tommyettinger.random.EnhancedRandom random, boolean shareRNG)
    Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom, WhiskerRandom or, if you need compatibility with SquidLib 3.0.0, a SilkRNG from squidold), and can then iterate infinitely through mostly-random shuffles of the given collection.
    GapShuffler(Collection<T> items, com.github.tommyettinger.random.EnhancedRandom random, int index, boolean shareRNG)
    Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom, WhiskerRandom or, if you need compatibility with SquidLib 3.0.0, a SilkRNG from squidold), and can then iterate infinitely through mostly-random shuffles of the given collection.
    GapShuffler(Collection<T> items, com.github.tommyettinger.random.EnhancedRandom random, int index, boolean shareRNG, boolean initialShuffle)
    Constructor that takes any Collection of T, optionally shuffles it with the given EnhancedRandom (only if initialShuffle is true), and can then iterate infinitely through mostly-random shuffles of the given collection.
    GapShuffler(Collection<T> elements, String seed)
    Constructor that takes any Collection of T, shuffles it with an AceRandom seeded by seed, 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 AceRandom, and can then iterate infinitely through mostly-random shuffles of the given collection.
    GapShuffler(T[] items, com.github.tommyettinger.random.EnhancedRandom random)
    Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom or WhiskerRandom), and can then iterate infinitely through mostly-random shuffles of the given collection.
    GapShuffler(T[] items, com.github.tommyettinger.random.EnhancedRandom random, boolean shareRNG)
    Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom, WhiskerRandom or, if you need compatibility with SquidLib 3.0.0, a SilkRNG from squidold), and can then iterate infinitely through mostly-random shuffles of the given collection.
    GapShuffler(T[] elements, CharSequence seed)
    Constructor that takes any Collection of T, shuffles it with an AceRandom seeded with the given CharSequence (hashed 3 different ways by Hasher), and can then iterate infinitely through mostly-random shuffles of the given collection.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object o)
     
    void
    fillInto(Collection<T> coll)
    The internal items used here are protected, but you can still use this method to put a shallow copy of them into some other Collection.
    int
    getIndex()
    Allows getting (but not setting) the internal index this uses as it iterates through shuffled versions of the same collection indefinitely.
    com.github.tommyettinger.random.EnhancedRandom
    getRNG()
     
    List<Class<?>>
    getSerializersNeeded()
    Gets a List of Class instances that must each be registered with a serialization library before this object can be successfully serialized or deserialized.
    boolean
    hasNext()
    Returns true if the iteration has more elements.
    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(com.github.tommyettinger.random.EnhancedRandom random)
    Sets the EnhancedRandom this uses to shuffle the order of elements, always copying the given EnhancedRandom before using it.
    void
    setRNG(com.github.tommyettinger.random.EnhancedRandom random, boolean shareRNG)
    Sets the EnhancedRandom this uses to shuffle the order of elements, optionally sharing a reference between outside code and the internal EnhancedRandom (when shareRNG is true).
    String
    toString()
     

    Methods inherited from class Object

    clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface Iterable

    forEach, spliterator

    Methods inherited from interface Iterator

    forEachRemaining

  • Field Details

    • random

      public com.github.tommyettinger.random.EnhancedRandom random

    • elements

      protected com.github.tommyettinger.ds.ObjectList<T> elements

    • index

      protected int index

  • Constructor Details

    • GapShuffler

      public GapShuffler()

    • GapShuffler

      public GapShuffler(T single)

    • GapShuffler

      public GapShuffler(Collection<T> elements)
      Constructor that takes any Collection of T, shuffles it with an unseeded AceRandom, and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have a large amount of "gap" in order between one appearance and the next. It helps to keep the appearance of a gap if every item in elements is unique, but that is not necessary and does not affect how this works.
      Parameters:
      elements - a Collection of T that will not be modified

    • GapShuffler

      public GapShuffler(Collection<T> elements, String seed)
      Constructor that takes any Collection of T, shuffles it with an AceRandom seeded by seed, and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have a large amount of "gap" in order between one appearance and the next. It helps to keep the appearance of a gap if every item in elements is unique, but that is not necessary and does not affect how this works.
      Parameters:
      elements - a Collection of T that will not be modified

    • GapShuffler

      public GapShuffler(Collection<T> items, com.github.tommyettinger.random.EnhancedRandom random)
      Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom, WhiskerRandom or, if you need compatibility with SquidLib 3.0.0, a SilkRNG from squidold), and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have a large amount of "gap" in order between one appearance and the next. It helps to keep the appearance of a gap if every item in items is unique, but that is not necessary and does not affect how this works. The random parameter is copied so externally using it won't change the order this produces its values; the random field is used whenever the iterator needs to re-shuffle the internal ordering of items.
      Parameters:
      items - a Collection of T that will not be modified
      random - an EnhancedRandom, such as a WhiskerRandom or AceRandom; will be copied and not used directly

    • GapShuffler

      public GapShuffler(Collection<T> items, com.github.tommyettinger.random.EnhancedRandom random, boolean shareRNG)
      Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom, WhiskerRandom or, if you need compatibility with SquidLib 3.0.0, a SilkRNG from squidold), and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have a large amount of "gap" in order between one appearance and the next. It helps to keep the appearance of a gap if every item in items is unique, but that is not necessary and does not affect how this works. The random parameter will be copied if 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).
      Parameters:
      items - a Collection of T that will not be modified
      random - an EnhancedRandom, such as a WhiskerRandom; will be copied and not used directly
      shareRNG - if false, random will be copied and no reference will be kept; if true, random will be shared with the outside code

    • GapShuffler

      public GapShuffler(Collection<T> items, com.github.tommyettinger.random.EnhancedRandom random, int index, boolean shareRNG)
      Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom, WhiskerRandom or, if you need compatibility with SquidLib 3.0.0, a SilkRNG from squidold), and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have a large amount of "gap" in order between one appearance and the next. It helps to keep the appearance of a gap if every item in items is unique, but that is not necessary and does not affect how this works. The random parameter will be copied if 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). This constructor takes an index to allow duplicating an existing GapShuffler given the parts that are externally available (using random, fillInto(Collection), and getIndex()). To actually complete a (shallow) copy, shareRNG must be false; to do a deep copy, you need to deep-copy items.
      Parameters:
      items - a Collection of T that will not be modified
      random - an EnhancedRandom, such as a WhiskerRandom; will be copied and not used directly
      index - an index in the iteration, as obtained by getIndex()
      shareRNG - if false, random will be copied and no reference will be kept; if true, random will be shared with the outside code

    • GapShuffler

      public GapShuffler(Collection<T> items, com.github.tommyettinger.random.EnhancedRandom random, int index, boolean shareRNG, boolean initialShuffle)
      Constructor that takes any Collection of T, optionally shuffles it with the given EnhancedRandom (only if initialShuffle is true), and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have a large amount of "gap" in order between one appearance and the next. It helps to keep the appearance of a gap if every item in items is unique, but that is not necessary and does not affect how this works. The random parameter will be copied if 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). This constructor takes an index to allow duplicating an existing GapShuffler given the parts that are externally available (using random, fillInto(Collection), and getIndex()). To actually complete a (shallow) copy, shareRNG must be false; to do a deep copy, you need to deep-copy items. You can use initialShuffle to copy items from another GapShuffler; most of the constructors here act like this does when initialShuffle is true, but the copy constructor GapShuffler(GapShuffler) does not (it uses this method).
      Parameters:
      items - a Collection of T that will not be modified
      random - an EnhancedRandom, such as a WhiskerRandom; will be copied and not used directly
      index - an index in the iteration, as obtained by getIndex()
      shareRNG - if false, random will be copied and no reference will be kept; if true, random will be shared with the outside code
      initialShuffle - if true, this will shuffle its copy of items; if false, then items will be kept in the same order

    • GapShuffler

      public GapShuffler(GapShuffler<T> other)
      Copy constructor; duplicates other, you know the deal. This does not share its random field with other.
      Parameters:
      other - another GapShuffler; its item type will also be used here

    • GapShuffler

      public GapShuffler(T[] elements)
      Constructor that takes any Collection of T, shuffles it with an unseeded AceRandom, and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have a large amount of "gap" in order between one appearance and the next. It helps to keep the appearance of a gap if every item in elements is unique, but that is not necessary and does not affect how this works.
      Parameters:
      elements - an array of T that will not be modified

    • GapShuffler

      public GapShuffler(T[] elements, CharSequence seed)
      Constructor that takes any Collection of T, shuffles it with an AceRandom seeded with the given CharSequence (hashed 3 different ways by Hasher), and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have a large amount of "gap" in order between one appearance and the next. It helps to keep the appearance of a gap if every item in elements is unique, but that is not necessary and does not affect how this works.
      Parameters:
      elements - an array of T that will not be modified

    • GapShuffler

      public GapShuffler(T[] items, com.github.tommyettinger.random.EnhancedRandom random)
      Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom or WhiskerRandom), and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have a large amount of "gap" in order between one appearance and the next. It helps to keep the appearance of a gap if every item in items is unique, but that is not necessary and does not affect how this works. The random parameter is copied so externally using it won't change the order this produces its values; the random field is used whenever the iterator needs to re-shuffle the internal ordering of items.
      Parameters:
      items - an array of T that will not be modified
      random - an EnhancedRandom, such as an AceRandom or WhiskerRandom; will be copied and not used directly

    • GapShuffler

      public GapShuffler(T[] items, com.github.tommyettinger.random.EnhancedRandom random, boolean shareRNG)
      Constructor that takes any Collection of T, shuffles it with the given EnhancedRandom (such as an AceRandom, WhiskerRandom or, if you need compatibility with SquidLib 3.0.0, a SilkRNG from squidold), and can then iterate infinitely through mostly-random shuffles of the given collection. These shuffles are spaced so that a single element should always have at least one "gap" element between one appearance and the next. It helps to keep the appearance of a gap if every item in items is unique, but that is not necessary and does not affect how this works. The random parameter will be copied if 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).
      Parameters:
      items - an array of T that will not be modified
      random - an EnhancedRandom, such as a WhiskerRandom; will be copied and not used directly
      shareRNG - if false, random will be copied and no reference will be kept; if true, random will be shared with the outside code

  • Method Details

    • next

      public T next()
      Gets the next element of the infinite sequence of T this shuffles through. This class can be used as an Iterator or Iterable of type T.
      Specified by:
      next in interface Iterator<T>
      Returns:
      the next element in the infinite sequence

    • hasNext

      public boolean hasNext()
      Returns true if the iteration has more elements. This is always the case for GapShuffler.
      Specified by:
      hasNext in interface Iterator<T>
      Returns:
      true always

    • remove

      public void remove()
      Not supported.
      Specified by:
      remove in interface Iterator<T>
      Throws:
      UnsupportedOperationException - always throws this exception

    • iterator

      public Iterator<T> iterator()
      Returns an infinite iterator over elements of type T; the returned iterator is this object. You should be prepared to break out of any 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.
      Specified by:
      iterator in interface Iterable<T>
      Returns:
      an infinite Iterator over elements of type T.

    • getRNG

      public com.github.tommyettinger.random.EnhancedRandom getRNG()

    • setRNG

      public void setRNG(com.github.tommyettinger.random.EnhancedRandom random)
      Sets the EnhancedRandom this uses to shuffle the order of elements, always copying the given EnhancedRandom before using it. 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.
      Parameters:
      random - an EnhancedRandom, such as a WhiskerRandom; always copied

    • setRNG

      public void setRNG(com.github.tommyettinger.random.EnhancedRandom random, boolean shareRNG)
      Sets the EnhancedRandom this uses to shuffle the order of elements, optionally sharing a reference between outside code and the internal EnhancedRandom (when 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.
      Parameters:
      random - an EnhancedRandom, such as a WhiskerRandom; optionally copied
      shareRNG - if false, random will be copied and no reference will be kept; if true, random will be shared with the outside code

    • fillInto

      public void fillInto(Collection<T> coll)
      The internal items used here are protected, but you can still use this method to put a shallow copy of them into some other Collection. If the type 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).
      Parameters:
      coll - a Collection that will have each of the possible items this can produce added into it, in no particular order

    • getIndex

      public int getIndex()
      Allows getting (but not setting) the internal index this uses as it iterates through shuffled versions of the same collection indefinitely. This is mostly meant for serialization code to be able to replicate the state of this GapShuffler. This is mostly useful with fillInto(Collection) and some kind of insertion-ordered Collection (like ObjectList, which lets the index match an item in that Collection.
      Returns:
      an index used internally to determine how far through a particular shuffle the iteration has gotten

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • getSerializersNeeded

      public List<Class<?>> getSerializersNeeded()
      Description copied from interface: ISerializersNeeded
      Gets a List of Class instances that must each be registered with a serialization library before this object can be successfully serialized or deserialized. This is GwtIncompatible; none of the serialization libraries this is meant for have any support for GWT.
      Specified by:
      getSerializersNeeded in interface ISerializersNeeded
      Returns:
      a List of Class instances that must each be registered with a serialization library