Package org.apache.commons.collections4.iterators

# Class ExtendedIterator<T>

java.lang.Object
org.apache.commons.collections4.iterators.ExtendedIterator<T>

Type Parameters:
  `T` - The type of object returned from the iterator.

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

public final class ExtendedIterator<T> extends Object implements IteratorOperations<T>
Extends Iterator functionality to include operations commonly found on streams (e.g. filtering, concatenating, mapping). It also provides convenience methods for common operations.

Since:
  4.5.0-M3

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<X extends T>
  ExtendedIterator<T>`
  `andThen(Iterator<X> other)`
  Chains the `other` iterator to the end of this one.
  `static <T> ExtendedIterator<T>`
  `create(Iterator<T> it)`
  Create an ExtendedIterator returning the elements of `it`.
  `static <T> ExtendedIterator<T>`
  `create(Stream<T> stream)`
  Creates an ExtendedIterator wrapped round a `Stream`.
  `static <T> ExtendedIterator<T>`
  `createNoRemove(Iterator<T> it)`
  Creates an ExtendedIterator wrapped round `it`, which does not permit `.remove()` even if `it` does.
  `static ExtendedIterator<?>`
  `emptyIterator()`
  Creates an empty Extended iterator.
  `ExtendedIterator<T>`
  `filter(Predicate<T> predicate)`
  Filter this iterator using a predicate.
  `static <T> ExtendedIterator<T>`
  `flatten(Iterator<Iterator<T>> iterators)`
  Flattens an iterator of iterators into an Iterator over the next level values.
  `void`
  `forEachRemaining(Consumer<? super T> action)`
  `boolean`
  `hasNext()`
  `<U> ExtendedIterator<U>`
  `map(Function<T,U> function)`
  Map the elements of the iterator to a now type.
  `T`
  `next()`
  `void`
  `remove()`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

  `addTo, removeNext, toCollection, toList, toSet`

- ## Method Details

  - ### create

    public static <T> ExtendedIterator<T> create(Iterator<T> it)
    Create an ExtendedIterator returning the elements of `it`. If `it` is itself an ExtendedIterator, return that; otherwise wrap `it`.
    Type Parameters:
      `T` - The type of object returned from the iterator.
    Parameters:
      `it` - The iterator to wrap.
    Returns:
      An Extended iterator wrapping `it`

  - ### create

    public static <T> ExtendedIterator<T> create(Stream<T> stream)
    Creates an ExtendedIterator wrapped round a `Stream`. The extended iterator does not permit `.remove()`.

    The stream should not be used directly. The effect of doing so is undefined.

    Type Parameters:
      `T` - The type of object returned from the iterator.
    Parameters:
      `stream` - the Stream to create an iterator from.
    Returns:
      an Extended iterator on the `stream` iterator.

  - ### createNoRemove

    public static <T> ExtendedIterator<T> createNoRemove(Iterator<T> it)
    Creates an ExtendedIterator wrapped round `it`, which does not permit `.remove()` even if `it` does.
    Type Parameters:
      `T` - The type of object returned from the iterator.
    Parameters:
      `it` - The Iterator to wrap.
    Returns:
      an Extended iterator on `it`
    Throws:
      `UnsupportedOperationException` - if remove() is called on the resulting iterator.

  - ### emptyIterator

    public static ExtendedIterator<?> emptyIterator()
    Creates an empty Extended iterator.
    Returns:
      An empty Extended iterator.

  - ### flatten

    public static <T> ExtendedIterator<T> flatten(Iterator<Iterator<T>> iterators)
    Flattens an iterator of iterators into an Iterator over the next level values. Similar to list splicing in lisp.
    Type Parameters:
      `T` - The type of object returned from the iterator.
    Parameters:
      `iterators` - An iterator of iterators.
    Returns:
      An iterator over the logical concatenation of the inner iterators.

  - ### andThen

    public <X extends T> ExtendedIterator<T> andThen(Iterator<X> other)
    Chains the `other` iterator to the end of this one.
    Type Parameters:
      `X` - The type of object returned from the other iterator.
    Parameters:
      `other` - the other iterator to extend this iterator with.
    Returns:
      A new iterator returning the contents of `this` iterator followed by the contents of `other` iterator.

  - ### filter

    public ExtendedIterator<T> filter(Predicate<T> predicate)
    Filter this iterator using a predicate. Only items for which the predicate returns `true` will be included in the result.
    Parameters:
      `predicate` - The predicate to filter the items with.
    Returns:
      An iterator filtered by the predicate.

  - ### forEachRemaining

    public void forEachRemaining(Consumer<? super T> action)
    Specified by:
      `forEachRemaining` in interface `Iterator<T>`

  - ### hasNext

    public boolean hasNext()
    Specified by:
      `hasNext` in interface `Iterator<T>`

  - ### map

    public <U> ExtendedIterator<U> map(Function<T,U> function)
    Map the elements of the iterator to a now type.
    Type Parameters:
      `U` - The object type to return.
    Parameters:
      `function` - The function to map elements of `<T>` to type `<U>`.
    Returns:
      An Extended iterator that returns a `<U>` for very `<T>` in the original iterator.

  - ### next

    public T next()
    Specified by:
      `next` in interface `Iterator<T>`

  - ### remove

    public void remove()
    Specified by:
      `remove` in interface `Iterator<T>`