Package com.globalmentor.collections.iterators

Class RandomIntegerIterator

java.lang.Object
com.globalmentor.collections.iterators.RandomIntegerIterator
All Implemented Interfaces:
Iterator<Integer>
public class RandomIntegerIterator extends Object implements Iterator<Integer>
An iterator that iterates a sequence of random iterators. The iterator has the ability to restrict its output to a particular range. A subset of the range can optionally be returned. This iterator can keep track of the numbers used and only return unused integers.
Author:
Garret Wilson
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected int
    count
    The total number of integers returned.
    protected final SortedSet<Integer>
    excludedIntegerSortedSet
    Create a new set to hold the integers excluded from the iterator.
    protected final int
    maxCount
    The number of integers to return, or -1 if an unlimited number of integers should be returned.
    protected Integer
    primedNext
    The value that has been retrieved and has passed the filter and is waiting to be returned, or null if there is no primed next object.
    protected final Random
    random
    The random number generator.
    protected final int
    range
    The absolute positive length of the range of possible values.
    protected final int
    rangeMax
    The upper bound, inclusive, of the range to include.
    protected final int
    rangeMin
    The lower bound, inclusive, of the range to include.
    protected final boolean
    repeat
    true if values should be repeated, else false.

  • Constructor Summary

    Constructors
    Constructor
    Description
    RandomIntegerIterator(int maxValue)
    Shuffle constructor.
    RandomIntegerIterator(int maxValue, int maxCount)
    Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive).
    RandomIntegerIterator(int maxValue, int maxCount, boolean repeat)
    Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive).
    RandomIntegerIterator(int rangeMin, int rangeMax, int maxCount, boolean repeat)
    Full constructor with default random number generator.
    RandomIntegerIterator(Random random, int maxValue)
    Shuffle constructor with random number generator.
    RandomIntegerIterator(Random random, int maxValue, int maxCount)
    Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive).
    RandomIntegerIterator(Random random, int maxValue, int maxCount, boolean repeat)
    Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive).
    RandomIntegerIterator(Random random, int rangeMin, int rangeMax, int maxCount, boolean repeat)
    Full constructor with random number generator.

  • Method Summary

    Modifier and Type
    Method
    Description
    Filter<Integer>
    getFilter()
     
    protected Integer
    getNext()
     
    boolean
    hasNext()
     
    Integer
    next()
     
    protected boolean
    primeNext()
    Retrieves the next object and stores it locally to return from the next call to next().
    void
    remove()
    This implementation does not support element removal, and always throws an exception.
    void
    setExcluded(int integer, boolean exclude)
    Determines whether the given integer value should be excluded from the iteration.
    void
    setExcluded(Integer integer, boolean exclude)
    Determines whether the given integer value should be excluded from the iteration.
    void
    setFilter(Filter<Integer> filter)
    Sets the filter used to exclude items from the iterator.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.Iterator

    forEachRemaining

  • Field Details

    • random

      protected final Random random
      The random number generator.

    • rangeMin

      protected final int rangeMin
      The lower bound, inclusive, of the range to include.

    • rangeMax

      protected final int rangeMax
      The upper bound, inclusive, of the range to include.

    • range

      protected final int range
      The absolute positive length of the range of possible values.

    • maxCount

      protected final int maxCount
      The number of integers to return, or -1 if an unlimited number of integers should be returned.

    • repeat

      protected final boolean repeat
      true if values should be repeated, else false.

    • excludedIntegerSortedSet

      protected final SortedSet<Integer> excludedIntegerSortedSet
      Create a new set to hold the integers excluded from the iterator.

    • count

      protected int count
      The total number of integers returned.

    • primedNext

      protected Integer primedNext
      The value that has been retrieved and has passed the filter and is waiting to be returned, or null if there is no primed next object.

  • Constructor Details

    • RandomIntegerIterator

      public RandomIntegerIterator(int maxValue)
      Shuffle constructor. Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive). Values returned will be 0≤value<maxValue, and will not be repeated. All numbers will be returned.
      Parameters:
      maxValue - The upper bound, exclusive, of the values to return.

    • RandomIntegerIterator

      public RandomIntegerIterator(Random random, int maxValue)
      Shuffle constructor with random number generator. Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive). Values returned will be 0≤value<maxValue, and will not be repeated. All numbers will be returned.
      Parameters:
      random - The random number generator.
      maxValue - The upper bound, exclusive, of the values to return.

    • RandomIntegerIterator

      public RandomIntegerIterator(int maxValue, int maxCount)
      Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive). Values returned will be 0≤value<maxValue, and will not be repeated.
      Parameters:
      maxValue - The upper bound, exclusive, of the values to return.
      maxCount - The number of integers to return, or -1 if an unlimited number of integers should be returned.
      Throws:
      IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

    • RandomIntegerIterator

      public RandomIntegerIterator(Random random, int maxValue, int maxCount)
      Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive). Values returned will be 0≤value<maxValue, and will not be repeated.
      Parameters:
      random - The random number generator.
      maxValue - The upper bound, exclusive, of the values to return.
      maxCount - The number of integers to return, or -1 if an unlimited number of integers should be returned.
      Throws:
      IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

    • RandomIntegerIterator

      public RandomIntegerIterator(int maxValue, int maxCount, boolean repeat)
      Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive). Values returned will be 0≤value<maxValue.
      Parameters:
      maxValue - The upper bound, exclusive, of the values to return.
      maxCount - The number of integers to return, or -1 if an unlimited number of integers should be returned.
      repeat - true if values should be repeated, else false.
      Throws:
      IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

    • RandomIntegerIterator

      public RandomIntegerIterator(Random random, int maxValue, int maxCount, boolean repeat)
      Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive). Values returned will be 0≤value<maxValue.
      Parameters:
      random - The random number generator.
      maxValue - The upper bound, exclusive, of the values to return.
      maxCount - The number of integers to return, or -1 if an unlimited number of integers should be returned.
      repeat - true if values should be repeated, else false.
      Throws:
      IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

    • RandomIntegerIterator

      public RandomIntegerIterator(int rangeMin, int rangeMax, int maxCount, boolean repeat)
      Full constructor with default random number generator.
      Parameters:
      rangeMin - The lower bound, inclusive, of the range to include.
      rangeMax - The upper bound, inclusive, of the range to include.
      maxCount - The number of integers to return, or -1 if an unlimited number of integers should be returned.
      repeat - true if values should be repeated, else false.
      Throws:
      IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

    • RandomIntegerIterator

      public RandomIntegerIterator(Random random, int rangeMin, int rangeMax, int maxCount, boolean repeat)
      Full constructor with random number generator.
      Parameters:
      random - The random number generator.
      rangeMin - The lower bound, inclusive, of the range to include.
      rangeMax - The upper bound, inclusive, of the range to include.
      maxCount - The number of integers to return, or -1 if an unlimited number of integers should be returned.
      repeat - true if values should be repeated, else false.
      Throws:
      IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

  • Method Details

    • getFilter

      public Filter<Integer> getFilter()
      Returns:
      The filter used to exclude items from the iterator.

    • setFilter

      public void setFilter(Filter<Integer> filter)
      Sets the filter used to exclude items from the iterator.
      Parameters:
      filter - The new filter to use, or null if there should be no filtering.

    • setExcluded

      public void setExcluded(int integer, boolean exclude)
      Determines whether the given integer value should be excluded from the iteration.

      This method may safely be called in between calls to next().

      Parameters:
      integer - The integer to exclude or not.
      exclude - true if the value should be excluded from future calls to next(), else false if it should be possible (but not guaranteed) that the value will be returned from future calls to next().

    • setExcluded

      public void setExcluded(Integer integer, boolean exclude)
      Determines whether the given integer value should be excluded from the iteration.

      This method may safely be called in between calls to next().

      Parameters:
      integer - The integer to exclude or not.
      exclude - true if the value should be excluded from future calls to next(), else false if it should be possible (but not guaranteed) that the value will be returned from future calls to next().

    • hasNext

      public boolean hasNext()
      Specified by:
      hasNext in interface Iterator<Integer>
      Returns:
      true if there are more integers left to retrieve.

    • next

      public Integer next()
      Specified by:
      next in interface Iterator<Integer>
      Returns:
      The next random integer in the iteration.
      Throws:
      NoSuchElementException - Thrown if the iteration has no more elements.

    • primeNext

      protected boolean primeNext()
      Retrieves the next object and stores it locally to return from the next call to next(). If an object is already primed, no action occurs.
      Returns:
      true if there is another integer left to retrieve.

    • getNext

      protected Integer getNext()
      Returns:
      The next random integer in the iteration, or null if the iteration has no more elements.

    • remove

      public void remove()
      This implementation does not support element removal, and always throws an exception.
      Specified by:
      remove in interface Iterator<Integer>
      Throws:
      UnsupportedOperationException - Thrown because the remove operation is not supported by this iterator.