Package com.globalmentor.collections.iterators

Class ListRandomIterator<E>

java.lang.Object
com.globalmentor.collections.iterators.ListRandomIterator<E>
All Implemented Interfaces:
Iterator<E>
public class ListRandomIterator<E> extends Object implements 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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final RandomIntegerIterator
    indexIterator
    The iterator that determines the next index of the list to return.

  • Constructor Summary

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

  • Method Summary

    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 Details

    • indexIterator

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

  • Constructor Details

    • ListRandomIterator

      public ListRandomIterator(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(List<E> list, 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(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:
      IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range or less than zero.

    • ListRandomIterator

      public ListRandomIterator(List<E> list, 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:
      IllegalArgumentException - Thrown if the given maximum count is greater than the allowed range or less than zero.

  • Method Details

    • 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 Iterator<E>
      Returns:
      true if there are more elements left to retrieve.

    • next

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