Package com.globalmentor.collections.iterators

Class ListRandomIterator<E>

  • All Implemented Interfaces:
    java.util.Iterator<E>
    public class ListRandomIterator<E>
extends java.lang.Object
implements java.util.Iterator<E>
    An iterator that randomly iterates a list.

    A subset of the list can optionally be returned.

    By default the iterator returns a random selection in random order. To iterate a random subset in non-random list order, call setRandomOrder with false.

    This iterator allows filtering of the returned objects.

    Author:
    Garret Wilson

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected class  ListRandomIterator.IndexFilter
      A class that filters random integers based upon whether the object at the given index in our list passes the criteria of our local filter.

    • Constructor Summary

      Constructors 
      Constructor Description
      ListRandomIterator​(java.util.List<E> list)
      Constructs an iterator that returns all of the elements of the list.
      ListRandomIterator​(java.util.List<E> list, int maxCount)
      Constructs an iterator that returns at most maxCount elements of the list.
      ListRandomIterator​(java.util.List<E> list, java.util.Random random)
      Constructs an iterator that returns all of the elements of the list.
      ListRandomIterator​(java.util.List<E> list, java.util.Random random, int maxCount)
      Constructs an iterator that returns at most maxCount elements of the list.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Filter<E> getFilter()  
      boolean hasNext()  
      E next()  
      void remove()
      This implementation does not support element removal, and always throws an exception.
      void setExcluded​(int index, boolean exclude)
      Determines whether the given index should be excluded from the iteration.
      void setExcluded​(E object, boolean exclude)
      Determines whether the given element should be excluded from the iteration.
      void setFilter​(Filter<E> 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 Detail

      • indexIterator

        protected final RandomIntegerIterator indexIterator
        The iterator that determines the next index of the list to return.

    • Constructor Detail

      • ListRandomIterator

        public ListRandomIterator​(java.util.List<E> list)
        Constructs an iterator that returns all of the elements of the list.

        A default random number generator is used.

        Parameters:
        list - The list to randomly iterate.

      • ListRandomIterator

        public ListRandomIterator​(java.util.List<E> list,
                          java.util.Random random)
        Constructs an iterator that returns all of the elements of the list.
        Parameters:
        list - The list to randomly iterate.
        random - The random number generator.

      • ListRandomIterator

        public ListRandomIterator​(java.util.List<E> list,
                          int maxCount)
        Constructs an iterator that returns at most maxCount elements of the list.

        A default random number generator is used.

        Parameters:
        list - The list to randomly iterate.
        maxCount - The number of elements to return.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range or less than zero.

      • ListRandomIterator

        public ListRandomIterator​(java.util.List<E> list,
                          java.util.Random random,
                          int maxCount)
        Constructs an iterator that returns at most maxCount elements of the list.
        Parameters:
        list - The list to randomly iterate.
        random - The random number generator.
        maxCount - The number of elements to return.
        Throws:
        java.lang.IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range or less than zero.

    • Method Detail

      • getFilter

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

      • setFilter

        public void setFilter​(Filter<E> filter)
        Sets the filter used to exclude items from the iterator.
        Parameters:
        filter - The new filter to use.

      • setExcluded

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

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

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

      • setExcluded

        public void setExcluded​(E object,
                        boolean exclude)
        Determines whether the given element should be excluded from the iteration. If the given element is not in the list, no action occurs.

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

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

      • hasNext

        public boolean hasNext()
        Specified by:
        hasNext in interface java.util.Iterator<E>
        Returns:
        true if there are more elements left to retrieve.

      • next

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