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.

  WARNING: Due to human error certain binary incompatibilities were introduced between Commons Collections 2.1 and 3.0. The class remained source and test compatible, so if you can recompile all your classes and dependencies everything is OK. Those methods which are binary incompatible are marked as such, together with alternate solutions that are binary compatible against versions 2.1.1 and 3.1.

  Since:
    2.1
  Version:
    $Id: IteratorUtils.java 1543964 2013-11-20 21:53:39Z tn $

- - ### Field Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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> 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> 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 Iterator<?>` | `getIterator(Object obj)` Gets a suitable Iterator for the given object.
    `static <E> ResettableIterator<E>` | `loopingIterator(Collection<? extends E> coll)` 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 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 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 <I,O> Iterator<O>` | `transformedIterator(Iterator<? extends I> iterator, Transformer<? super I,? extends O> transform)` 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`.

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

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

- - ### Field Detail

    - #### EMPTY_ITERATOR

          public static final ResettableIterator EMPTY_ITERATOR

      An iterator over no elements.

      WARNING: This constant is binary incompatible with Commons Collections 2.1 and 2.1.1. Use `EmptyIterator.INSTANCE` for compatibility with Commons Collections 2.1.1.

    - #### EMPTY_LIST_ITERATOR

          public static final ResettableListIterator EMPTY_LIST_ITERATOR

      A list iterator over no elements.

      WARNING: This constant is binary incompatible with Commons Collections 2.1 and 2.1.1. Use `EmptyListIterator.INSTANCE` for compatibility with Commons Collections 2.1.1.

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

    - #### emptyIterator

          public static <E> ResettableIterator<E> emptyIterator()

      Gets an empty iterator.

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

      WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use `EmptyIterator.INSTANCE` for compatibility with Commons Collections 2.1.1.

      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.

      WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use `EmptyListIterator.INSTANCE` for compatibility with Commons Collections 2.1.1.

      Type Parameters:
        `E` - the element type
      Returns:
        a list 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

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

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

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

      WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use `new SingletonIterator(object)` for compatibility.

      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

    - #### arrayIterator

          public static <E> ResettableIterator<E> arrayIterator(E... array)

      Gets an iterator over an object array.

      WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use `new ArrayIterator(array)` for compatibility.

      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(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(E[] array,
                                                int start)

      Gets an iterator over the end part of an object array.

      WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use `new ArrayIterator(array,start)` for compatibility.

      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(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(E[] array,
                                                int start,
                                                int end)

      Gets an iterator over part of an object array.

      WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1. Use `new ArrayIterator(array,start,end)` for compatibility.

      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,
                                                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(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(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(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(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,
                                                        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

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

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

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

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

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

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

    - #### transformedIterator

          public static <I,O> Iterator<O> transformedIterator(Iterator<? extends I> iterator,
                                              Transformer<? super I,? extends O> transform)

      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
        `transform` - the transform to use, not null
      Returns:
        a new transforming iterator
      Throws:
        `NullPointerException` - if either parameter is null

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

    - #### loopingIterator

          public static <E> ResettableIterator<E> loopingIterator(Collection<? extends E> coll)

      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:
        `coll` - 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

    - #### 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, not null
      Returns:
        a new, single use `Iterator`
      Throws:
        `NullPointerException` - if nodeList is null
      Since:
        4.0

    - #### 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, not null
      Returns:
        a new, single use `Iterator`
      Throws:
        `NullPointerException` - if node is null
      Since:
        4.0

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

    - #### 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
      Returns:
        a new iterator

    - #### 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
        `removeCollection` - the collection to remove elements from
      Returns:
        a new iterator

    - #### 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, not 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, not null
      Returns:
        a new, single use `Iterable`
      Throws:
        `NullPointerException` - if iterator 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, not null
      Returns:
        a new, multiple use iterable
      Throws:
        `NullPointerException` - if iterator is null

    - #### 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, not null
      Returns:
        a new iterator
      Throws:
        `NullPointerException` - if iterator parameter is null

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

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

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.