Package org.apache.commons.collections4.iterators

Class CollatingIterator<E>

java.lang.Object
org.apache.commons.collections4.iterators.CollatingIterator<E>
All Implemented Interfaces:
Iterator<E>
public class CollatingIterator<E> extends Object implements Iterator<E>
Provides an ordered iteration over the elements contained in a collection of ordered Iterators.

Given two ordered Iterator instances A and B, the next() method on this iterator will return the lesser of A.next() and B.next().

Since:
2.1

  • Field Details

    • comparator

      private Comparator<? super E> comparator
      The Comparator used to evaluate order.

    • iterators

      private List<Iterator<? extends E>> iterators
      The list of Iterators to evaluate.

    • values

      private List<E> values
      Next objects peeked from each iterator.

    • valueSet

      private BitSet valueSet
      Whether or not each values element has been set.

    • lastReturned

      private int lastReturned
      Index of the iterator from whom the last returned value was obtained.

  • Constructor Details

    • CollatingIterator

      public CollatingIterator()
      Constructs a new CollatingIterator. A comparator must be set by calling setComparator(Comparator) before invoking hasNext(), or next() for the first time. Child iterators will have to be manually added using the addIterator(Iterator) method.

    • CollatingIterator

      public CollatingIterator(Comparator<? super E> comp)
      Constructs a new CollatingIterator that will used the specified comparator for ordering. Child iterators will have to be manually added using the addIterator(Iterator) method.
      Parameters:
      comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.

    • CollatingIterator

      public CollatingIterator(Comparator<? super E> comp, int initIterCapacity)
      Constructs a new CollatingIterator that will used the specified comparator for ordering and have the specified initial capacity. Child iterators will have to be manually added using the addIterator(Iterator) method.
      Parameters:
      comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
      initIterCapacity - the initial capacity for the internal list of child iterators

    • CollatingIterator

      public CollatingIterator(Comparator<? super E> comp, Iterator<? extends E> a, Iterator<? extends E> b)
      Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the two given iterators.
      Parameters:
      comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
      a - the first child ordered iterator
      b - the second child ordered iterator
      Throws:
      NullPointerException - if either iterator is null

    • CollatingIterator

      public CollatingIterator(Comparator<? super E> comp, Iterator<? extends E>[] iterators)
      Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the array of iterators.
      Parameters:
      comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
      iterators - the array of iterators
      Throws:
      NullPointerException - if iterators array is or contains null

    • CollatingIterator

      public CollatingIterator(Comparator<? super E> comp, Collection<Iterator<? extends E>> iterators)
      Constructs a new CollatingIterator that will use the specified comparator to provide ordered iteration over the collection of iterators.
      Parameters:
      comp - the comparator to use to sort; must not be null, unless you'll be invoking setComparator(Comparator) later on.
      iterators - the collection of iterators
      Throws:
      NullPointerException - if the iterators collection is or contains null
      ClassCastException - if the iterators collection contains an element that's not an Iterator

  • Method Details

    • addIterator

      public void addIterator(Iterator<? extends E> iterator)
      Adds the given Iterator to the iterators being collated.
      Parameters:
      iterator - the iterator to add to the collation, must not be null
      Throws:
      IllegalStateException - if iteration has started
      NullPointerException - if the iterator is null

    • setIterator

      public void setIterator(int index, Iterator<? extends E> iterator)
      Sets the iterator at the given index.
      Parameters:
      index - index of the Iterator to replace
      iterator - Iterator to place at the given index
      Throws:
      IndexOutOfBoundsException - if index < 0 or index > size()
      IllegalStateException - if iteration has started
      NullPointerException - if the iterator is null

    • getIterators

      public List<Iterator<? extends E>> getIterators()
      Gets the list of Iterators (unmodifiable).
      Returns:
      the unmodifiable list of iterators added

    • getComparator

      public Comparator<? super E> getComparator()
      Gets the Comparator by which collatation occurs.
      Returns:
      the Comparator

    • setComparator

      public void setComparator(Comparator<? super E> comp)
      Sets the Comparator by which collation occurs. If you would like to use the natural sort order (or, in other words, if the elements in the iterators are implementing the Comparable interface), then use the ComparableComparator.
      Parameters:
      comp - the Comparator to set
      Throws:
      IllegalStateException - if iteration has started

    • hasNext

      public boolean hasNext()
      Returns true if any child iterator has remaining elements.
      Specified by:
      hasNext in interface Iterator<E>
      Returns:
      true if this iterator has remaining elements

    • next

      public E next() throws NoSuchElementException
      Returns the next ordered element from a child iterator.
      Specified by:
      next in interface Iterator<E>
      Returns:
      the next ordered element
      Throws:
      NoSuchElementException - if no child iterator has any more elements

    • remove

      public void remove()
      Removes the last returned element from the child iterator that produced it.
      Specified by:
      remove in interface Iterator<E>
      Throws:
      IllegalStateException - if there is no last returned element, or if the last returned element has already been removed

    • getIteratorIndex

      public int getIteratorIndex()
      Returns the index of the iterator that returned the last element.
      Returns:
      the index of the iterator that returned the last element
      Throws:
      IllegalStateException - if there is no last returned element

    • start

      private void start()
      Initializes the collating state if it hasn't been already.

    • set

      private boolean set(int i)
      Sets the values and valueSet attributes at position i to the next value of the iterator at position i, or clear them if the ith iterator has no next value.
      Returns:
      false iff there was no value to set

    • clear

      private void clear(int i)
      Clears the values and valueSet attributes at position i.

    • checkNotStarted

      private void checkNotStarted() throws IllegalStateException
      Throws IllegalStateException if iteration has started via start().
      Throws:
      IllegalStateException - if iteration started

    • least

      private int least()
      Returns the index of the least element in values, setting any uninitialized values.
      Throws:
      NullPointerException - if no comparator is set

    • anyValueSet

      private boolean anyValueSet(BitSet set)
      Returns true iff any bit in the given set is true.

    • anyHasNext

      private boolean anyHasNext(List<Iterator<? extends E>> iters)
      Returns true iff any Iterator in the given list has a next value.