Package ai.timefold.solver.core.impl.bavet.common.index

Interface UniqueRandomIterator<T>

Type Parameters:
T -
All Superinterfaces:
Iterator<T>
All Known Implementing Classes:
FilteredUniqueRandomIterator
@NullMarked public sealed interface UniqueRandomIterator<T> extends Iterator<T> permits FilteredUniqueRandomIterator<T> (not exhaustive)
Exists to support random unique selection. It accepts a list of unique items on input, and does not copy or modify it. Instead, it keeps metadata on which indexes of the list were removed already, never to return them again. Does not allow null values.

The iterator only behaves as unique if the client calls remove() after each next(). If the client only calls next(), it is possible to receive the same element again.

It is imperative for the overall fairness of the solver that the picking is random and fair, meaning each unpicked value has the same probability of being picked next.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    hasNext()
    Returns whether there are no more elements to pick from.
    T
    next()
    Picks a random element from the list which has not already been removed.
    static <T> Iterator<T>
    of(ElementAwareArrayList<T> list, Random random)
     
    void
    remove()
    Removes a random element in the underlying list which has not already been removed.

    Methods inherited from interface java.util.Iterator

    forEachRemaining

  • Method Details

    • of

      static <T> Iterator<T> of(ElementAwareArrayList<T> list, Random random)

    • hasNext

      boolean hasNext()
      Returns whether there are no more elements to pick from. In case of FilteredUniqueRandomIterator, this method may return false positives, as it cannot predict how many elements will be filtered out.
      Specified by:
      hasNext in interface Iterator<T>
      Returns:
      true if there are no more elements to pick from, false otherwise

    • next

      T next()
      Picks a random element from the list which has not already been removed. Once an element of the list is removed either via remove(), it will never be returned again by this method.
      Specified by:
      next in interface Iterator<T>
      Returns:
      a random element from the list which has not already been removed

    • remove

      void remove()
      Removes a random element in the underlying list which has not already been removed. Once this method returns, no subsequent next() will return this element ever again.
      Specified by:
      remove in interface Iterator<T>