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

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> 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 Iterators one after another.
static <E> Iterator<E>	chainedIterator(Iterator<? extends E>... iterators) Gets an iterator that iterates through an array of Iterators one after another.
static <E> Iterator<E>	chainedIterator(Iterator<? extends E> iterator1, Iterator<? extends E> iterator2) Gets an iterator that iterates through two Iterators 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 Iterators.
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 Iterators.
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 Iterators.
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> 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 <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> 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.
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 Detail

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 Detail

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

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.

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.

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.

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.

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

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

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

Given two ordered Iterators 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 Iterators.

Given two ordered Iterators 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 Iterators.

Given two ordered Iterators 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, may not be 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, may not be 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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