Package org.apache.commons.collections4.iterators

# Class FilterIterator<E>

java.lang.Object
org.apache.commons.collections4.iterators.FilterIterator<E>

Type Parameters:
  `E` - the type of elements returned by this iterator.

All Implemented Interfaces:
  `Iterator<E>`, `IteratorOperations<E>`

Direct Known Subclasses:
  `UniqueFilterIterator`

public class FilterIterator<E> extends Object implements IteratorOperations<E>
Decorates an `Iterator` using an optional predicate to filter elements.

This iterator decorates the underlying iterator, only allowing through those elements that match the specified `Predicate`.

Since:
  1.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FilterIterator()`
  Constructs a new `FilterIterator` that will not function until `setIterator` is invoked.
  `FilterIterator(Iterator<? extends E> iterator)`
  Constructs a new `FilterIterator` that will not function until `setPredicate` is invoked.
  `FilterIterator(Iterator<? extends E> iterator, Predicate<? super E> predicate)`
  Constructs a new `FilterIterator` that will use the given iterator and predicate.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Iterator<? extends E>`
  `getIterator()`
  Gets the iterator this iterator is using.
  `Predicate<? super E>`
  `getPredicate()`
  Gets the predicate this iterator is using.
  `boolean`
  `hasNext()`
  Returns true if the underlying iterator contains an object that matches the predicate.
  `E`
  `next()`
  Returns the next object that matches the predicate.
  `void`
  `remove()`
  Removes from the underlying collection of the base iterator the last element returned by this iterator.
  `void`
  `setIterator(Iterator<? extends E> iterator)`
  Sets the iterator for this iterator to use.
  `void`
  `setPredicate(Predicate<? super E> predicate)`
  Sets the predicate this the iterator to use where null accepts all values.

  ### 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`

  ### Methods inherited from interface org.apache.commons.collections4.iterators.IteratorOperations

  `addTo, removeNext, toCollection, toList, toSet`

- ## Constructor Details

  - ### FilterIterator

    public FilterIterator()
    Constructs a new `FilterIterator` that will not function until `setIterator` is invoked.

  - ### FilterIterator

    public FilterIterator(Iterator<? extends E> iterator)
    Constructs a new `FilterIterator` that will not function until `setPredicate` is invoked.
    Parameters:
      `iterator` - the iterator to use

  - ### FilterIterator

    public FilterIterator(Iterator<? extends E> iterator, Predicate<? super E> predicate)
    Constructs a new `FilterIterator` that will use the given iterator and predicate.
    Parameters:
      `iterator` - the iterator to use
      `predicate` - the predicate to use, null accepts all values.

- ## Method Details

  - ### getIterator

    public Iterator<? extends E> getIterator()
    Gets the iterator this iterator is using.
    Returns:
      the underlying iterator.

  - ### getPredicate

    public Predicate<? super E> getPredicate()
    Gets the predicate this iterator is using.
    Returns:
      the filtering predicate.

  - ### hasNext

    public boolean hasNext()
    Returns true if the underlying iterator contains an object that matches the predicate.
    Specified by:
      `hasNext` in interface `Iterator<E>`
    Returns:
      true if there is another object that matches the predicate
    Throws:
      `NullPointerException` - if either the iterator or predicate are null

  - ### next

    public E next()
    Returns the next object that matches the predicate.
    Specified by:
      `next` in interface `Iterator<E>`
    Returns:
      the next object which matches the given predicate
    Throws:
      `NullPointerException` - if either the iterator or predicate are null
      `NoSuchElementException` - if there are no more elements that match the predicate

  - ### remove

    public void remove()
    Removes from the underlying collection of the base iterator the last element returned by this iterator. This method can only be called if `next()` was called, but not after `hasNext()`, because the `hasNext()` call changes the base iterator.
    Specified by:
      `remove` in interface `Iterator<E>`
    Throws:
      `IllegalStateException` - if `hasNext()` has already been called.

  - ### setIterator

    public void setIterator(Iterator<? extends E> iterator)
    Sets the iterator for this iterator to use. If iteration has started, this effectively resets the iterator.
    Parameters:
      `iterator` - the iterator to use

  - ### setPredicate

    public void setPredicate(Predicate<? super E> predicate)
    Sets the predicate this the iterator to use where null accepts all values.
    Parameters:
      `predicate` - the predicate to use, null accepts all values.