Package com.globalmentor.collections.iterators

Class RandomIntegerIterator

  • All Implemented Interfaces:
    java.util.Iterator<java.lang.Integer>
    public class RandomIntegerIterator
extends java.lang.Object
implements java.util.Iterator<java.lang.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:
    Integer

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected int count
      The total number of integers returned.
      protected java.util.SortedSet<java.lang.Integer> excludedIntegerSortedSet
      Create a new set to hold the integers excluded from the iterator.
      protected int maxCount
      The number of integers to return, or -1 if an unlimited number of integers should be returned.
      protected java.lang.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 java.util.Random random
      The random number generator.
      protected int range
      The absolute positive length of the range of possible values.
      protected int rangeMax
      The upper bound, inclusive, of the range to include.
      protected int rangeMin
      The lower bound, inclusive, of the range to include.
      protected 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​(java.util.Random random, int maxValue)
      Shuffle constructor with random number generator.
      RandomIntegerIterator​(java.util.Random random, int maxValue, int maxCount)
      Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive).
      RandomIntegerIterator​(java.util.Random random, int maxValue, int maxCount, boolean repeat)
      Constructs an iterator that returns numbers between zero (inclusive) and the given maximum value (exclusive).
      RandomIntegerIterator​(java.util.Random random, int rangeMin, int rangeMax, int maxCount, boolean repeat)
      Full constructor with random number generator.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Filter<java.lang.Integer> getFilter()  
      protected java.lang.Integer getNext()  
      boolean hasNext()  
      java.lang.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​(java.lang.Integer integer, boolean exclude)
      Determines whether the given integer value should be excluded from the iteration.
      void setFilter​(Filter<java.lang.Integer> filter)  

      • 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 Detail

      • random

        protected final java.util.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 java.util.SortedSet<java.lang.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 java.lang.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 Detail

      • 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​(java.util.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:
        java.lang.IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

      • RandomIntegerIterator

        public RandomIntegerIterator​(java.util.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:
        java.lang.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:
        java.lang.IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

      • RandomIntegerIterator

        public RandomIntegerIterator​(java.util.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:
        java.lang.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:
        java.lang.IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

      • RandomIntegerIterator

        public RandomIntegerIterator​(java.util.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:
        java.lang.IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range.

    • Method Detail

      • getFilter

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

      • setFilter

        public void setFilter​(Filter<java.lang.Integer> filter)

      • 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​(java.lang.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 java.util.Iterator<java.lang.Integer>
        Returns:
        true if there are more integers left to retrieve.

      • next

        public java.lang.Integer next()
        Specified by:
        next in interface java.util.Iterator<java.lang.Integer>
        Returns:
        The next random integer in the iteration.
        Throws:
        java.util.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 java.lang.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 java.util.Iterator<java.lang.Integer>
        Throws:
        java.lang.UnsupportedOperationException - Thrown because the remove operation is not supported by this iterator.