Package org.apache.commons.collections4

# Class IteratorUtils

java.lang.Object
org.apache.commons.collections4.IteratorUtils

public class IteratorUtils extends Object
Provides static utility methods and decorators for `Iterator` instances. The implementations are provided in the iterators subpackage.

Since:
  2.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ResettableIterator`
  `EMPTY_ITERATOR`
  An iterator over no elements.
  `static final ResettableListIterator`
  `EMPTY_LIST_ITERATOR`
  A list iterator over no elements.
  `static final MapIterator`
  `EMPTY_MAP_ITERATOR`
  A map iterator over no elements.
  `static final OrderedIterator`
  `EMPTY_ORDERED_ITERATOR`
  An ordered iterator over no elements.
  `static final OrderedMapIterator`
  `EMPTY_ORDERED_MAP_ITERATOR`
  An ordered map iterator over no elements.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <E> ResettableIterator<E>`
  `arrayIterator(E... array)`
  Gets an iterator over an object array.
  `static <E> ResettableIterator<E>`
  `arrayIterator(E[] array, int start)`
  Gets an iterator over the end part of an object array.
  `static <E> ResettableIterator<E>`
  `arrayIterator(E[] array, int start, int end)`
  Gets an iterator over part of an object array.
  `static <E> ResettableIterator<E>`
  `arrayIterator(Object array)`
  Gets an iterator over an object or primitive array.
  `static <E> ResettableIterator<E>`
  `arrayIterator(Object array, int start)`
  Gets an iterator over the end part of an object or primitive array.
  `static <E> ResettableIterator<E>`
  `arrayIterator(Object array, int start, int end)`
  Gets an iterator over part of an object or primitive array.
  `static <E> ResettableListIterator<E>`
  `arrayListIterator(E... array)`
  Gets a list iterator over an object array.
  `static <E> ResettableListIterator<E>`
  `arrayListIterator(E[] array, int start)`
  Gets a list iterator over the end part of an object array.
  `static <E> ResettableListIterator<E>`
  `arrayListIterator(E[] array, int start, int end)`
  Gets a list iterator over part of an object array.
  `static <E> ResettableListIterator<E>`
  `arrayListIterator(Object array)`
  Gets a list iterator over an object or primitive array.
  `static <E> ResettableListIterator<E>`
  `arrayListIterator(Object array, int start)`
  Gets a list iterator over the end part of an object or primitive array.
  `static <E> ResettableListIterator<E>`
  `arrayListIterator(Object array, int start, int end)`
  Gets a list iterator over part of an object or primitive array.
  `static <E> Enumeration<E>`
  `asEnumeration(Iterator<? extends E> iterator)`
  Gets an enumeration that wraps an iterator.
  `static <E> Iterable<E>`
  `asIterable(Iterator<? extends E> iterator)`
  Gets an `Iterable` that wraps an iterator.
  `static <E> Iterator<E>`
  `asIterator(Enumeration<? extends E> enumeration)`
  Gets an iterator that provides an iterator view of the given enumeration.
  `static <E> Iterator<E>`
  `asIterator(Enumeration<? extends E> enumeration, Collection<? super E> removeCollection)`
  Gets an iterator that provides an iterator view of the given enumeration that will remove elements from the specified collection.
  `static <E> Iterable<E>`
  `asMultipleUseIterable(Iterator<? extends E> iterator)`
  Gets an iterable that wraps an iterator.
  `static <E> BoundedIterator<E>`
  `boundedIterator(Iterator<? extends E> iterator, long max)`
  Decorates the specified iterator to return at most the given number of elements.
  `static <E> BoundedIterator<E>`
  `boundedIterator(Iterator<? extends E> iterator, long offset, long max)`
  Decorates the specified iterator to return at most the given number of elements, skipping all elements until the iterator reaches the position at `offset`.
  `static <E> Iterator<E>`
  `chainedIterator(Collection<Iterator<? extends E>> iterators)`
  Gets an iterator that iterates through a collections of `Iterator`s one after another.
  `static <E> Iterator<E>`
  `chainedIterator(Iterator<? extends E>... iterators)`
  Gets an iterator that iterates through an array of `Iterator`s one after another.
  `static <E> Iterator<E>`
  `chainedIterator(Iterator<? extends E> iterator1, Iterator<? extends E> iterator2)`
  Gets an iterator that iterates through two `Iterator`s one after another.
  `static <E> Iterator<E>`
  `collatedIterator(Comparator<? super E> comparator, Collection<Iterator<? extends E>> iterators)`
  Gets an iterator that provides an ordered iteration over the elements contained in a collection of `Iterator`s.
  `static <E> Iterator<E>`
  `collatedIterator(Comparator<? super E> comparator, Iterator<? extends E>... iterators)`
  Gets an iterator that provides an ordered iteration over the elements contained in an array of `Iterator`s.
  `static <E> Iterator<E>`
  `collatedIterator(Comparator<? super E> comparator, Iterator<? extends E> iterator1, Iterator<? extends E> iterator2)`
  Gets an iterator that provides an ordered iteration over the elements contained in a collection of ordered `Iterator`s.
  `static <E> boolean`
  `contains(Iterator<E> iterator, Object object)`
  Checks if the object is contained in the given iterator.
  `static <E> ResettableIterator<E>`
  `emptyIterator()`
  Gets an empty iterator.
  `static <E> ResettableListIterator<E>`
  `emptyListIterator()`
  Gets an empty list iterator.
  `static <K, V> MapIterator<K,V>`
  `emptyMapIterator()`
  Gets an empty map iterator.
  `static <E> OrderedIterator<E>`
  `emptyOrderedIterator()`
  Gets an empty ordered iterator.
  `static <K, V> OrderedMapIterator<K,V>`
  `emptyOrderedMapIterator()`
  Gets an empty ordered map iterator.
  `static <E> Iterator<E>`
  `filteredIterator(Iterator<? extends E> iterator, Predicate<? super E> predicate)`
  Gets an iterator that filters another iterator.
  `static <E> ListIterator<E>`
  `filteredListIterator(ListIterator<? extends E> listIterator, Predicate<? super E> predicate)`
  Gets a list iterator that filters another list iterator.
  `static <E> E`
  `find(Iterator<E> iterator, Predicate<? super E> predicate)`
  Finds the first element in the given iterator which matches the given predicate.
  `static <E> E`
  `first(Iterator<E> iterator)`
  Shortcut for `get(iterator, 0)`.
  `static <E> void`
  `forEach(Iterator<E> iterator, Closure<? super E> closure)`
  Applies the closure to each element of the provided iterator.
  `static <E> E`
  `forEachButLast(Iterator<E> iterator, Closure<? super E> closure)`
  Executes the given closure on each but the last element in the iterator.
  `static <E> E`
  `get(Iterator<E> iterator, int index)`
  Returns the `index`-th value in `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.
  `static Iterator<?>`
  `getIterator(Object obj)`
  Gets a suitable Iterator for the given object.
  `static <E> int`
  `indexOf(Iterator<E> iterator, Predicate<? super E> predicate)`
  Returns the index of the first element in the specified iterator that matches the given predicate.
  `static boolean`
  `isEmpty(Iterator<?> iterator)`
  Checks if the given iterator is empty.
  `static <E> ResettableIterator<E>`
  `loopingIterator(Collection<? extends E> collection)`
  Gets an iterator that loops continuously over the supplied collection.
  `static <E> ResettableListIterator<E>`
  `loopingListIterator(List<E> list)`
  Gets an iterator that loops continuously over the supplied list.
  `static <E> boolean`
  `matchesAll(Iterator<E> iterator, Predicate<? super E> predicate)`
  Answers true if a predicate is true for every element of an iterator.
  `static <E> boolean`
  `matchesAny(Iterator<E> iterator, Predicate<? super E> predicate)`
  Answers true if a predicate is true for any element of the iterator.
  `static NodeListIterator`
  `nodeListIterator(Node node)`
  Gets an `Iterator` that wraps the specified node's childNodes.
  `static NodeListIterator`
  `nodeListIterator(NodeList nodeList)`
  Gets an `Iterator` that wraps the specified `NodeList`.
  `static <E> Iterator<E>`
  `objectGraphIterator(E root, Transformer<? super E,? extends E> transformer)`
  Gets an iterator that operates over an object graph.
  `static <E> Iterator<E>`
  `peekingIterator(Iterator<? extends E> iterator)`
  Gets an iterator that supports one-element lookahead.
  `static <E> Iterator<E>`
  `pushbackIterator(Iterator<? extends E> iterator)`
  Gets an iterator that supports pushback of elements.
  `static <E> ResettableIterator<E>`
  `singletonIterator(E object)`
  Gets a singleton iterator.
  `static <E> ListIterator<E>`
  `singletonListIterator(E object)`
  Gets a singleton list iterator.
  `static int`
  `size(Iterator<?> iterator)`
  Returns the number of elements contained in the given iterator.
  `static <E> SkippingIterator<E>`
  `skippingIterator(Iterator<E> iterator, long offset)`
  Decorates the specified iterator to skip the first N elements.
  `static Object[]`
  `toArray(Iterator<?> iterator)`
  Gets an array based on an iterator.
  `static <E> E[]`
  `toArray(Iterator<? extends E> iterator, Class<E> arrayClass)`
  Gets an array based on an iterator.
  `static <E> List<E>`
  `toList(Iterator<? extends E> iterator)`
  Gets a list based on an iterator.
  `static <E> List<E>`
  `toList(Iterator<? extends E> iterator, int estimatedSize)`
  Gets a list based on an iterator.
  `static <E> ListIterator<E>`
  `toListIterator(Iterator<? extends E> iterator)`
  Gets a list iterator based on a simple iterator.
  `static <E> String`
  `toString(Iterator<E> iterator)`
  Returns a string representation of the elements of the specified iterator.
  `static <E> String`
  `toString(Iterator<E> iterator, Transformer<? super E,String> transformer)`
  Returns a string representation of the elements of the specified iterator.
  `static <E> String`
  `toString(Iterator<E> iterator, Transformer<? super E,String> transformer, String delimiter, String prefix, String suffix)`
  Returns a string representation of the elements of the specified iterator.
  `static <I, O> Iterator<O>`
  `transformedIterator(Iterator<? extends I> iterator, Transformer<? super I,? extends O> transformer)`
  Gets an iterator that transforms the elements of another iterator.
  `static <E> Iterator<E>`
  `unmodifiableIterator(Iterator<E> iterator)`
  Gets an immutable version of an `Iterator`.
  `static <E> ListIterator<E>`
  `unmodifiableListIterator(ListIterator<E> listIterator)`
  Gets an immutable version of a `ListIterator`.
  `static <K, V> MapIterator<K,V>`
  `unmodifiableMapIterator(MapIterator<K,V> mapIterator)`
  Gets an immutable version of a `MapIterator`.
  `static <E> ZippingIterator<E>`
  `zippingIterator(Iterator<? extends E>... iterators)`
  Returns an iterator that interleaves elements from the decorated iterators.
  `static <E> ZippingIterator<E>`
  `zippingIterator(Iterator<? extends E> a, Iterator<? extends E> b)`
  Returns an iterator that interleaves elements from the decorated iterators.
  `static <E> ZippingIterator<E>`
  `zippingIterator(Iterator<? extends E> a, Iterator<? extends E> b, Iterator<? extends E> c)`
  Returns an iterator that interleaves elements from the decorated iterators.

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

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

- ## Field Details

  - ### EMPTY_ITERATOR

    public static final ResettableIterator EMPTY_ITERATOR
    An iterator over no elements.

  - ### EMPTY_LIST_ITERATOR

    public static final ResettableListIterator EMPTY_LIST_ITERATOR
    A list iterator over no elements.

  - ### EMPTY_ORDERED_ITERATOR

    public static final OrderedIterator EMPTY_ORDERED_ITERATOR
    An ordered iterator over no elements.

  - ### EMPTY_MAP_ITERATOR

    public static final MapIterator EMPTY_MAP_ITERATOR
    A map iterator over no elements.

  - ### EMPTY_ORDERED_MAP_ITERATOR

    public static final OrderedMapIterator EMPTY_ORDERED_MAP_ITERATOR
    An ordered map iterator over no elements.

- ## Method Details

  - ### arrayIterator

    public static <E> ResettableIterator<E> arrayIterator(E... array)
    Gets an iterator over an object array.
    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
    Returns:
      an iterator over the array
    Throws:
      `NullPointerException` - if array is null

  - ### arrayIterator

    public static <E> ResettableIterator<E> arrayIterator(E[] array, int start)
    Gets an iterator over the end part of an object array.
    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
      `start` - the index to start iterating at
    Returns:
      an iterator over part of the array
    Throws:
      `IndexOutOfBoundsException` - if start is less than zero or greater than the length of the array
      `NullPointerException` - if array is null

  - ### arrayIterator

    public static <E> ResettableIterator<E> arrayIterator(E[] array, int start, int end)
    Gets an iterator over part of an object array.
    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
      `start` - the index to start iterating at
      `end` - the index to finish iterating at
    Returns:
      an iterator over part of the array
    Throws:
      `IndexOutOfBoundsException` - if array bounds are invalid
      `IllegalArgumentException` - if end is before start
      `NullPointerException` - if array is null

  - ### arrayIterator

    public static <E> ResettableIterator<E> arrayIterator(Object array)
    Gets an iterator over an object or primitive array.

    This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.

    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
    Returns:
      an iterator over the array
    Throws:
      `IllegalArgumentException` - if the array is not an array
      `NullPointerException` - if array is null

  - ### arrayIterator

    public static <E> ResettableIterator<E> arrayIterator(Object array, int start)
    Gets an iterator over the end part of an object or primitive array.

    This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.

    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
      `start` - the index to start iterating at
    Returns:
      an iterator over part of the array
    Throws:
      `IllegalArgumentException` - if the array is not an array
      `IndexOutOfBoundsException` - if start is less than zero or greater than the length of the array
      `NullPointerException` - if array is null

  - ### arrayIterator

    public static <E> ResettableIterator<E> arrayIterator(Object array, int start, int end)
    Gets an iterator over part of an object or primitive array.

    This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.

    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
      `start` - the index to start iterating at
      `end` - the index to finish iterating at
    Returns:
      an iterator over part of the array
    Throws:
      `IllegalArgumentException` - if the array is not an array or end is before start
      `IndexOutOfBoundsException` - if array bounds are invalid
      `NullPointerException` - if array is null

  - ### arrayListIterator

    public static <E> ResettableListIterator<E> arrayListIterator(E... array)
    Gets a list iterator over an object array.
    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
    Returns:
      a list iterator over the array
    Throws:
      `NullPointerException` - if array is null

  - ### arrayListIterator

    public static <E> ResettableListIterator<E> arrayListIterator(E[] array, int start)
    Gets a list iterator over the end part of an object array.
    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
      `start` - the index to start iterating at
    Returns:
      a list iterator over part of the array
    Throws:
      `IndexOutOfBoundsException` - if start is less than zero
      `NullPointerException` - if array is null

  - ### arrayListIterator

    public static <E> ResettableListIterator<E> arrayListIterator(E[] array, int start, int end)
    Gets a list iterator over part of an object array.
    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
      `start` - the index to start iterating at
      `end` - the index to finish iterating at
    Returns:
      a list iterator over part of the array
    Throws:
      `IndexOutOfBoundsException` - if array bounds are invalid
      `IllegalArgumentException` - if end is before start
      `NullPointerException` - if array is null

  - ### arrayListIterator

    public static <E> ResettableListIterator<E> arrayListIterator(Object array)
    Gets a list iterator over an object or primitive array.

    This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.

    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
    Returns:
      a list iterator over the array
    Throws:
      `IllegalArgumentException` - if the array is not an array
      `NullPointerException` - if array is null

  - ### arrayListIterator

    public static <E> ResettableListIterator<E> arrayListIterator(Object array, int start)
    Gets a list iterator over the end part of an object or primitive array.

    This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.

    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
      `start` - the index to start iterating at
    Returns:
      a list iterator over part of the array
    Throws:
      `IllegalArgumentException` - if the array is not an array
      `IndexOutOfBoundsException` - if start is less than zero
      `NullPointerException` - if array is null

  - ### arrayListIterator

    public static <E> ResettableListIterator<E> arrayListIterator(Object array, int start, int end)
    Gets a list iterator over part of an object or primitive array.

    This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.

    Type Parameters:
      `E` - the element type
    Parameters:
      `array` - the array over which to iterate
      `start` - the index to start iterating at
      `end` - the index to finish iterating at
    Returns:
      a list iterator over part of the array
    Throws:
      `IllegalArgumentException` - if the array is not an array or end is before start
      `IndexOutOfBoundsException` - if array bounds are invalid
      `NullPointerException` - if array is null

  - ### asEnumeration

    public static <E> Enumeration<E> asEnumeration(Iterator<? extends E> iterator)
    Gets an enumeration that wraps an iterator.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to use, may not be null
    Returns:
      a new enumeration
    Throws:
      `NullPointerException` - if iterator is null

  - ### asIterable

    public static <E> Iterable<E> asIterable(Iterator<? extends E> iterator)
    Gets an `Iterable` that wraps an iterator. The returned `Iterable` can be used for a single iteration.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to use, may not be null
    Returns:
      a new, single use `Iterable`
    Throws:
      `NullPointerException` - if iterator is null

  - ### asIterator

    public static <E> Iterator<E> asIterator(Enumeration<? extends E> enumeration)
    Gets an iterator that provides an iterator view of the given enumeration.
    Type Parameters:
      `E` - the element type
    Parameters:
      `enumeration` - the enumeration to use, may not be null
    Returns:
      a new iterator
    Throws:
      `NullPointerException` - if enumeration is null

  - ### asIterator

    public static <E> Iterator<E> asIterator(Enumeration<? extends E> enumeration, Collection<? super E> removeCollection)
    Gets an iterator that provides an iterator view of the given enumeration that will remove elements from the specified collection.
    Type Parameters:
      `E` - the element type
    Parameters:
      `enumeration` - the enumeration to use, may not be null
      `removeCollection` - the collection to remove elements from, may not be null
    Returns:
      a new iterator
    Throws:
      `NullPointerException` - if enumeration or removeCollection is null

  - ### asMultipleUseIterable

    public static <E> Iterable<E> asMultipleUseIterable(Iterator<? extends E> iterator)
    Gets an iterable that wraps an iterator. The returned iterable can be used for multiple iterations.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to use, may not be null
    Returns:
      a new, multiple use iterable
    Throws:
      `NullPointerException` - if iterator is null

  - ### boundedIterator

    public static <E> BoundedIterator<E> boundedIterator(Iterator<? extends E> iterator, long max)
    Decorates the specified iterator to return at most the given number of elements.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to decorate
      `max` - the maximum number of elements returned by this iterator
    Returns:
      a new bounded iterator
    Throws:
      `NullPointerException` - if the iterator is null
      `IllegalArgumentException` - if max is negative
    Since:
      4.1

  - ### boundedIterator

    public static <E> BoundedIterator<E> boundedIterator(Iterator<? extends E> iterator, long offset, long max)
    Decorates the specified iterator to return at most the given number of elements, skipping all elements until the iterator reaches the position at `offset`.

    The iterator is immediately advanced until it reaches the position at `offset`, incurring O(n) time.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to decorate
      `offset` - the index of the first element of the decorated iterator to return
      `max` - the maximum number of elements returned by this iterator
    Returns:
      a new bounded iterator
    Throws:
      `NullPointerException` - if the iterator is null
      `IllegalArgumentException` - if either offset or max is negative
    Since:
      4.1

  - ### chainedIterator

    public static <E> Iterator<E> chainedIterator(Collection<Iterator<? extends E>> iterators)
    Gets an iterator that iterates through a collections of `Iterator`s one after another.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterators` - the iterators to use, not null or empty or contain nulls
    Returns:
      a combination iterator over the iterators
    Throws:
      `NullPointerException` - if iterators collection is null or contains a null
      `ClassCastException` - if the iterators collection contains the wrong object type

  - ### chainedIterator

    public static <E> Iterator<E> chainedIterator(Iterator<? extends E>... iterators)
    Gets an iterator that iterates through an array of `Iterator`s one after another.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterators` - the iterators to use, not null or empty or contain nulls
    Returns:
      a combination iterator over the iterators
    Throws:
      `NullPointerException` - if iterators array is null or contains a null

  - ### chainedIterator

    public static <E> Iterator<E> chainedIterator(Iterator<? extends E> iterator1, Iterator<? extends E> iterator2)
    Gets an iterator that iterates through two `Iterator`s one after another.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator1` - the first iterator to use, not null
      `iterator2` - the second iterator to use, not null
    Returns:
      a combination iterator over the iterators
    Throws:
      `NullPointerException` - if either iterator is null

  - ### collatedIterator

    public static <E> Iterator<E> collatedIterator(Comparator<? super E> comparator, Collection<Iterator<? extends E>> iterators)
    Gets an iterator that provides an ordered iteration over the elements contained in a collection of `Iterator`s.

    Given two ordered `Iterator`s `A` and `B`, the `Iterator.next()` method will return the lesser of `A.next()` and `B.next()` and so on.

    The comparator is optional. If null is specified then natural order is used.

    Type Parameters:
      `E` - the element type
    Parameters:
      `comparator` - the comparator to use, may be null for natural order
      `iterators` - the iterators to use, not null or empty or contain nulls
    Returns:
      a combination iterator over the iterators
    Throws:
      `NullPointerException` - if iterators collection is null or contains a null
      `ClassCastException` - if the iterators collection contains the wrong object type

  - ### collatedIterator

    public static <E> Iterator<E> collatedIterator(Comparator<? super E> comparator, Iterator<? extends E>... iterators)
    Gets an iterator that provides an ordered iteration over the elements contained in an array of `Iterator`s.

    Given two ordered `Iterator`s `A` and `B`, the `Iterator.next()` method will return the lesser of `A.next()` and `B.next()` and so on.

    The comparator is optional. If null is specified then natural order is used.

    Type Parameters:
      `E` - the element type
    Parameters:
      `comparator` - the comparator to use, may be null for natural order
      `iterators` - the iterators to use, not null or empty or contain nulls
    Returns:
      a combination iterator over the iterators
    Throws:
      `NullPointerException` - if iterators array is null or contains a null value

  - ### collatedIterator

    public static <E> Iterator<E> collatedIterator(Comparator<? super E> comparator, Iterator<? extends E> iterator1, Iterator<? extends E> iterator2)
    Gets an iterator that provides an ordered iteration over the elements contained in a collection of ordered `Iterator`s.

    Given two ordered `Iterator`s `A` and `B`, the `Iterator.next()` method will return the lesser of `A.next()` and `B.next()`.

    The comparator is optional. If null is specified then natural order is used.

    Type Parameters:
      `E` - the element type
    Parameters:
      `comparator` - the comparator to use, may be null for natural order
      `iterator1` - the first iterators to use, not null
      `iterator2` - the first iterators to use, not null
    Returns:
      a combination iterator over the iterators
    Throws:
      `NullPointerException` - if either iterator is null

  - ### contains

    public static <E> boolean contains(Iterator<E> iterator, Object object)
    Checks if the object is contained in the given iterator.

    A `null` or empty iterator returns false.

    Type Parameters:
      `E` - the type of object the `Iterator` contains
    Parameters:
      `iterator` - the iterator to check, may be null
      `object` - the object to check
    Returns:
      true if the object is contained in the iterator, false otherwise
    Since:
      4.1

  - ### emptyIterator

    public static <E> ResettableIterator<E> emptyIterator()
    Gets an empty iterator.

    This iterator is a valid iterator object that will iterate over nothing.

    Type Parameters:
      `E` - the element type
    Returns:
      an iterator over nothing

  - ### emptyListIterator

    public static <E> ResettableListIterator<E> emptyListIterator()
    Gets an empty list iterator.

    This iterator is a valid list iterator object that will iterate over nothing.

    Type Parameters:
      `E` - the element type
    Returns:
      a list iterator over nothing

  - ### emptyMapIterator

    public static <K, V> MapIterator<K,V> emptyMapIterator()
    Gets an empty map iterator.

    This iterator is a valid map iterator object that will iterate over nothing.

    Type Parameters:
      `K` - the key type
      `V` - the value type
    Returns:
      a map iterator over nothing

  - ### emptyOrderedIterator

    public static <E> OrderedIterator<E> emptyOrderedIterator()
    Gets an empty ordered iterator.

    This iterator is a valid iterator object that will iterate over nothing.

    Type Parameters:
      `E` - the element type
    Returns:
      an ordered iterator over nothing

  - ### emptyOrderedMapIterator

    public static <K, V> OrderedMapIterator<K,V> emptyOrderedMapIterator()
    Gets an empty ordered map iterator.

    This iterator is a valid map iterator object that will iterate over nothing.

    Type Parameters:
      `K` - the key type
      `V` - the value type
    Returns:
      a map iterator over nothing

  - ### filteredIterator

    public static <E> Iterator<E> filteredIterator(Iterator<? extends E> iterator, Predicate<? super E> predicate)
    Gets an iterator that filters another iterator.

    The returned iterator will only return objects that match the specified filtering predicate.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to use, not null
      `predicate` - the predicate to use as a filter, not null
    Returns:
      a new filtered iterator
    Throws:
      `NullPointerException` - if either parameter is null

  - ### filteredListIterator

    public static <E> ListIterator<E> filteredListIterator(ListIterator<? extends E> listIterator, Predicate<? super E> predicate)
    Gets a list iterator that filters another list iterator.

    The returned iterator will only return objects that match the specified filtering predicate.

    Type Parameters:
      `E` - the element type
    Parameters:
      `listIterator` - the list iterator to use, not null
      `predicate` - the predicate to use as a filter, not null
    Returns:
      a new filtered iterator
    Throws:
      `NullPointerException` - if either parameter is null

  - ### find

    public static <E> E find(Iterator<E> iterator, Predicate<? super E> predicate)
    Finds the first element in the given iterator which matches the given predicate.

    A `null` or empty iterator returns null.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to search, may be null
      `predicate` - the predicate to use, must not be null
    Returns:
      the first element of the iterator which matches the predicate or null if none could be found
    Throws:
      `NullPointerException` - if predicate is null
    Since:
      4.1

  - ### first

    public static <E> E first(Iterator<E> iterator)
    Shortcut for `get(iterator, 0)`.

    Returns the `first` value in `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.

    The Iterator is advanced to `0` (or to the end, if `0` exceeds the number of entries) as a side effect of this method.

    Type Parameters:
      `E` - the type of object in the `Iterator`
    Parameters:
      `iterator` - the iterator to get a value from
    Returns:
      the first object
    Throws:
      `IndexOutOfBoundsException` - if the request is invalid
    Since:
      4.2

  - ### forEach

    public static <E> void forEach(Iterator<E> iterator, Closure<? super E> closure)
    Applies the closure to each element of the provided iterator.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to use, may be null
      `closure` - the closure to apply to each element, may not be null
    Throws:
      `NullPointerException` - if closure is null
    Since:
      4.1

  - ### forEachButLast

    public static <E> E forEachButLast(Iterator<E> iterator, Closure<? super E> closure)
    Executes the given closure on each but the last element in the iterator.

    If the input iterator is null no change is made.

    Type Parameters:
      `E` - the type of object the `Iterator` contains
    Parameters:
      `iterator` - the iterator to get the input from, may be null
      `closure` - the closure to perform, may not be null
    Returns:
      the last element in the iterator, or null if iterator is null or empty
    Throws:
      `NullPointerException` - if closure is null
    Since:
      4.1

  - ### get

    public static <E> E get(Iterator<E> iterator, int index)
    Returns the `index`-th value in `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.

    The Iterator is advanced to `index` (or to the end, if `index` exceeds the number of entries) as a side effect of this method.

    Type Parameters:
      `E` - the type of object in the `Iterator`
    Parameters:
      `iterator` - the iterator to get a value from
      `index` - the index to get
    Returns:
      the object at the specified index
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid
    Since:
      4.1

  - ### getIterator

    public static Iterator<?> getIterator(Object obj)
    Gets a suitable Iterator for the given object.

    This method can handle objects as follows

    - null - empty iterator
    - Iterator - returned directly
    - Enumeration - wrapped
    - Collection - iterator from collection returned
    - Map - values iterator returned
    - Dictionary - values (elements) enumeration returned as iterator
    - array - iterator over array returned
    - object with iterator() public method accessed by reflection
    - object - singleton iterator
    - NodeList - iterator over the list
    - Node - iterator over the child nodes
    Parameters:
      `obj` - the object to convert to an iterator
    Returns:
      a suitable iterator, never null

  - ### indexOf

    public static <E> int indexOf(Iterator<E> iterator, Predicate<? super E> predicate)
    Returns the index of the first element in the specified iterator that matches the given predicate.

    A `null` or empty iterator returns -1.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to search, may be null
      `predicate` - the predicate to use, may not be null
    Returns:
      the index of the first element which matches the predicate or -1 if none matches
    Throws:
      `NullPointerException` - if predicate is null
    Since:
      4.1

  - ### isEmpty

    public static boolean isEmpty(Iterator<?> iterator)
    Checks if the given iterator is empty.

    A `null` or empty iterator returns true.

    Parameters:
      `iterator` - the `Iterator` to use, may be null
    Returns:
      true if the iterator is exhausted or null, false otherwise
    Since:
      4.1

  - ### loopingIterator

    public static <E> ResettableIterator<E> loopingIterator(Collection<? extends E> collection)
    Gets an iterator that loops continuously over the supplied collection.

    The iterator will only stop looping if the remove method is called enough times to empty the collection, or if the collection is empty to start with.

    Type Parameters:
      `E` - the element type
    Parameters:
      `collection` - the collection to iterate over, not null
    Returns:
      a new looping iterator
    Throws:
      `NullPointerException` - if the collection is null

  - ### loopingListIterator

    public static <E> ResettableListIterator<E> loopingListIterator(List<E> list)
    Gets an iterator that loops continuously over the supplied list.

    The iterator will only stop looping if the remove method is called enough times to empty the list, or if the list is empty to start with.

    Type Parameters:
      `E` - the element type
    Parameters:
      `list` - the list to iterate over, not null
    Returns:
      a new looping iterator
    Throws:
      `NullPointerException` - if the list is null
    Since:
      3.2

  - ### matchesAll

    public static <E> boolean matchesAll(Iterator<E> iterator, Predicate<? super E> predicate)
    Answers true if a predicate is true for every element of an iterator.

    A `null` or empty iterator returns true.

    Type Parameters:
      `E` - the type of object the `Iterator` contains
    Parameters:
      `iterator` - the `Iterator` to use, may be null
      `predicate` - the predicate to use, may not be null
    Returns:
      true if every element of the collection matches the predicate or if the collection is empty, false otherwise
    Throws:
      `NullPointerException` - if predicate is null
    Since:
      4.1

  - ### matchesAny

    public static <E> boolean matchesAny(Iterator<E> iterator, Predicate<? super E> predicate)
    Answers true if a predicate is true for any element of the iterator.

    A `null` or empty iterator returns false.

    Type Parameters:
      `E` - the type of object the `Iterator` contains
    Parameters:
      `iterator` - the `Iterator` to use, may be null
      `predicate` - the predicate to use, may not be null
    Returns:
      true if any element of the collection matches the predicate, false otherwise
    Throws:
      `NullPointerException` - if predicate is null
    Since:
      4.1

  - ### nodeListIterator

    public static NodeListIterator nodeListIterator(Node node)
    Gets an `Iterator` that wraps the specified node's childNodes. The returned `Iterator` can be used for a single iteration.

    Convenience method, allows easy iteration over NodeLists:

           Iterator<Node> iterator = IteratorUtils.nodeListIterator(node);
           for (Node childNode : IteratorUtils.asIterable(iterator)) {
             ...
           }

    Parameters:
      `node` - the node to use, may not be null
    Returns:
      a new, single use `Iterator`
    Throws:
      `NullPointerException` - if node is null
    Since:
      4.0

  - ### nodeListIterator

    public static NodeListIterator nodeListIterator(NodeList nodeList)
    Gets an `Iterator` that wraps the specified `NodeList`. The returned `Iterator` can be used for a single iteration.
    Parameters:
      `nodeList` - the node list to use, may not be null
    Returns:
      a new, single use `Iterator`
    Throws:
      `NullPointerException` - if nodeList is null
    Since:
      4.0

  - ### objectGraphIterator

    public static <E> Iterator<E> objectGraphIterator(E root, Transformer<? super E,? extends E> transformer)
    Gets an iterator that operates over an object graph.

    This iterator can extract multiple objects from a complex tree-like object graph. The iteration starts from a single root object. It uses a `Transformer` to extract the iterators and elements. Its main benefit is that no intermediate `List` is created.

    For example, consider an object graph:

                         |- Branch -- Leaf
                         |         \- Leaf
                 |- Tree |         /- Leaf
                 |       |- Branch -- Leaf
          Forest |                 \- Leaf
                 |       |- Branch -- Leaf
                 |       |         \- Leaf
                 |- Tree |         /- Leaf
                         |- Branch -- Leaf
                         |- Branch -- Leaf

    The following `Transformer`, used in this class, will extract all the Leaf objects without creating a combined intermediate list:

         public Object transform(Object input) {
           if (input instanceof Forest) {
             return ((Forest) input).treeIterator();
           }
           if (input instanceof Tree) {
             return ((Tree) input).branchIterator();
           }
           if (input instanceof Branch) {
             return ((Branch) input).leafIterator();
           }
           if (input instanceof Leaf) {
             return input;
           }
           throw new ClassCastException();
         }

    Internally, iteration starts from the root object. When next is called, the transformer is called to examine the object. The transformer will return either an iterator or an object. If the object is an Iterator, the next element from that iterator is obtained and the process repeats. If the element is an object it is returned.

    Under many circumstances, linking Iterators together in this manner is more efficient (and convenient) than using nested for loops to extract a list.

    Type Parameters:
      `E` - the element type
    Parameters:
      `root` - the root object to start iterating from, null results in an empty iterator
      `transformer` - the transformer to use, see above, null uses no effect transformer
    Returns:
      a new object graph iterator
    Since:
      3.1

  - ### peekingIterator

    public static <E> Iterator<E> peekingIterator(Iterator<? extends E> iterator)
    Gets an iterator that supports one-element lookahead.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to decorate, not null
    Returns:
      a peeking iterator
    Throws:
      `NullPointerException` - if the iterator is null
    Since:
      4.0

  - ### pushbackIterator

    public static <E> Iterator<E> pushbackIterator(Iterator<? extends E> iterator)
    Gets an iterator that supports pushback of elements.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to decorate, not null
    Returns:
      a pushback iterator
    Throws:
      `NullPointerException` - if the iterator is null
    Since:
      4.0

  - ### singletonIterator

    public static <E> ResettableIterator<E> singletonIterator(E object)
    Gets a singleton iterator.

    This iterator is a valid iterator object that will iterate over the specified object.

    Type Parameters:
      `E` - the element type
    Parameters:
      `object` - the single object over which to iterate
    Returns:
      a singleton iterator over the object

  - ### singletonListIterator

    public static <E> ListIterator<E> singletonListIterator(E object)
    Gets a singleton list iterator.

    This iterator is a valid list iterator object that will iterate over the specified object.

    Type Parameters:
      `E` - the element type
    Parameters:
      `object` - the single object over which to iterate
    Returns:
      a singleton list iterator over the object

  - ### size

    public static int size(Iterator<?> iterator)
    Returns the number of elements contained in the given iterator.

    A `null` or empty iterator returns `0`.

    Parameters:
      `iterator` - the iterator to check, may be null
    Returns:
      the number of elements contained in the iterator
    Since:
      4.1

  - ### skippingIterator

    public static <E> SkippingIterator<E> skippingIterator(Iterator<E> iterator, long offset)
    Decorates the specified iterator to skip the first N elements.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to decorate
      `offset` - the first number of elements to skip
    Returns:
      a new skipping iterator
    Throws:
      `NullPointerException` - if the iterator is null
      `IllegalArgumentException` - if offset is negative
    Since:
      4.1

  - ### toArray

    public static Object[] toArray(Iterator<?> iterator)
    Gets an array based on an iterator.

    As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, this is converted to an array.

    Parameters:
      `iterator` - the iterator to use, not null
    Returns:
      an array of the iterator contents
    Throws:
      `NullPointerException` - if iterator parameter is null

  - ### toArray

    public static <E> E[] toArray(Iterator<? extends E> iterator, Class<E> arrayClass)
    Gets an array based on an iterator.

    As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, this is converted to an array.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to use, not null
      `arrayClass` - the class of array to create
    Returns:
      an array of the iterator contents
    Throws:
      `NullPointerException` - if iterator parameter or arrayClass is null
      `ArrayStoreException` - if the arrayClass is invalid

  - ### toList

    public static <E> List<E> toList(Iterator<? extends E> iterator)
    Gets a list based on an iterator.

    As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, the list is returned.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to use, not null
    Returns:
      a list of the iterator contents
    Throws:
      `NullPointerException` - if iterator parameter is null

  - ### toList

    public static <E> List<E> toList(Iterator<? extends E> iterator, int estimatedSize)
    Gets a list based on an iterator.

    As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, the list is returned.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to use, not null
      `estimatedSize` - the initial size of the ArrayList
    Returns:
      a list of the iterator contents
    Throws:
      `NullPointerException` - if iterator parameter is null
      `IllegalArgumentException` - if the size is less than 1

  - ### toListIterator

    public static <E> ListIterator<E> toListIterator(Iterator<? extends E> iterator)
    Gets a list iterator based on a simple iterator.

    As the wrapped Iterator is traversed, a LinkedList of its values is cached, permitting all required operations of ListIterator.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to use, may not be null
    Returns:
      a new iterator
    Throws:
      `NullPointerException` - if iterator parameter is null

  - ### toString

    public static <E> String toString(Iterator<E> iterator)
    Returns a string representation of the elements of the specified iterator.

    The string representation consists of a list of the iterator's elements, enclosed in square brackets (`"[]"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Elements are converted to strings as by `String.valueOf(Object)`.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to convert to a string, may be null
    Returns:
      a string representation of `iterator`
    Since:
      4.1

  - ### toString

    public static <E> String toString(Iterator<E> iterator, Transformer<? super E,String> transformer)
    Returns a string representation of the elements of the specified iterator.

    The string representation consists of a list of the iterable's elements, enclosed in square brackets (`"[]"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Elements are converted to strings as by using the provided `transformer`.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to convert to a string, may be null
      `transformer` - the transformer used to get a string representation of an element
    Returns:
      a string representation of `iterator`
    Throws:
      `NullPointerException` - if `transformer` is null
    Since:
      4.1

  - ### toString

    public static <E> String toString(Iterator<E> iterator, Transformer<? super E,String> transformer, String delimiter, String prefix, String suffix)
    Returns a string representation of the elements of the specified iterator.

    The string representation consists of a list of the iterator's elements, enclosed by the provided `prefix` and `suffix`. Adjacent elements are separated by the provided `delimiter`. Elements are converted to strings as by using the provided `transformer`.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to convert to a string, may be null
      `transformer` - the transformer used to get a string representation of an element
      `delimiter` - the string to delimit elements
      `prefix` - the prefix, prepended to the string representation
      `suffix` - the suffix, appended to the string representation
    Returns:
      a string representation of `iterator`
    Throws:
      `NullPointerException` - if either transformer, delimiter, prefix or suffix is null
    Since:
      4.1

  - ### transformedIterator

    public static <I, O> Iterator<O> transformedIterator(Iterator<? extends I> iterator, Transformer<? super I,? extends O> transformer)
    Gets an iterator that transforms the elements of another iterator.

    The transformation occurs during the next() method and the underlying iterator is unaffected by the transformation.

    Type Parameters:
      `I` - the input type
      `O` - the output type
    Parameters:
      `iterator` - the iterator to use, not null
      `transformer` - the transform to use, not null
    Returns:
      a new transforming iterator
    Throws:
      `NullPointerException` - if either parameter is null

  - ### unmodifiableIterator

    public static <E> Iterator<E> unmodifiableIterator(Iterator<E> iterator)
    Gets an immutable version of an `Iterator`. The returned object will always throw an `UnsupportedOperationException` for the `Iterator.remove()` method.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - the iterator to make immutable
    Returns:
      an immutable version of the iterator

  - ### unmodifiableListIterator

    public static <E> ListIterator<E> unmodifiableListIterator(ListIterator<E> listIterator)
    Gets an immutable version of a `ListIterator`. The returned object will always throw an `UnsupportedOperationException` for the `Iterator.remove()`, `ListIterator.add(E)` and `ListIterator.set(E)` methods.
    Type Parameters:
      `E` - the element type
    Parameters:
      `listIterator` - the iterator to make immutable
    Returns:
      an immutable version of the iterator

  - ### unmodifiableMapIterator

    public static <K, V> MapIterator<K,V> unmodifiableMapIterator(MapIterator<K,V> mapIterator)
    Gets an immutable version of a `MapIterator`. The returned object will always throw an `UnsupportedOperationException` for the `Iterator.remove()`, `MapIterator.setValue(Object)` methods.
    Type Parameters:
      `K` - the key type
      `V` - the value type
    Parameters:
      `mapIterator` - the iterator to make immutable
    Returns:
      an immutable version of the iterator

  - ### zippingIterator

    public static <E> ZippingIterator<E> zippingIterator(Iterator<? extends E>... iterators)
    Returns an iterator that interleaves elements from the decorated iterators.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterators` - the array of iterators to interleave
    Returns:
      an iterator, interleaving the decorated iterators
    Throws:
      `NullPointerException` - if any iterator is null
    Since:
      4.1

  - ### zippingIterator

    public static <E> ZippingIterator<E> zippingIterator(Iterator<? extends E> a, Iterator<? extends E> b)
    Returns an iterator that interleaves elements from the decorated iterators.
    Type Parameters:
      `E` - the element type
    Parameters:
      `a` - the first iterator to interleave
      `b` - the second iterator to interleave
    Returns:
      an iterator, interleaving the decorated iterators
    Throws:
      `NullPointerException` - if any iterator is null
    Since:
      4.1

  - ### zippingIterator

    public static <E> ZippingIterator<E> zippingIterator(Iterator<? extends E> a, Iterator<? extends E> b, Iterator<? extends E> c)
    Returns an iterator that interleaves elements from the decorated iterators.
    Type Parameters:
      `E` - the element type
    Parameters:
      `a` - the first iterator to interleave
      `b` - the second iterator to interleave
      `c` - the third iterator to interleave
    Returns:
      an iterator, interleaving the decorated iterators
    Throws:
      `NullPointerException` - if any iterator is null
    Since:
      4.1