org.apache.commons.collections

Class 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 incompatabilities 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: Commons Collections 2.1

Version: $Revision: 405920 $ $Date: 2006-05-12 23:48:04 +0100 (Fri, 12 May 2006) $

Author: Stephen Colebourne Phil Steitz

Field Summary
static ResettableIteratorEMPTY_ITERATOR
An iterator over no elements.
static ResettableListIteratorEMPTY_LIST_ITERATOR
A list iterator over no elements.
static MapIteratorEMPTY_MAP_ITERATOR
A map iterator over no elements.
static OrderedIteratorEMPTY_ORDERED_ITERATOR
An ordered iterator over no elements.
static OrderedMapIteratorEMPTY_ORDERED_MAP_ITERATOR
An ordered map iterator over no elements.
Constructor Summary
IteratorUtils()
IteratorUtils is not normally instantiated.
Method Summary
static ResettableIteratorarrayIterator(Object[] array)
Gets an iterator over an object array.
static ResettableIteratorarrayIterator(Object array)
Gets an iterator over an object or primitive array.
static ResettableIteratorarrayIterator(Object[] array, int start)
Gets an iterator over the end part of an object array.
static ResettableIteratorarrayIterator(Object array, int start)
Gets an iterator over the end part of an object or primitive array.
static ResettableIteratorarrayIterator(Object[] array, int start, int end)
Gets an iterator over part of an object array.
static ResettableIteratorarrayIterator(Object array, int start, int end)
Gets an iterator over part of an object or primitive array.
static ResettableListIteratorarrayListIterator(Object[] array)
Gets a list iterator over an object array.
static ResettableListIteratorarrayListIterator(Object array)
Gets a list iterator over an object or primitive array.
static ResettableListIteratorarrayListIterator(Object[] array, int start)
Gets a list iterator over the end part of an object array.
static ResettableListIteratorarrayListIterator(Object array, int start)
Gets a list iterator over the end part of an object or primitive array.
static ResettableListIteratorarrayListIterator(Object[] array, int start, int end)
Gets a list iterator over part of an object array.
static ResettableListIteratorarrayListIterator(Object array, int start, int end)
Gets a list iterator over part of an object or primitive array.
static EnumerationasEnumeration(Iterator iterator)
Gets an enumeration that wraps an iterator.
static IteratorasIterator(Enumeration enumeration)
Gets an iterator that provides an iterator view of the given enumeration.
static IteratorasIterator(Enumeration enumeration, Collection removeCollection)
Gets an iterator that provides an iterator view of the given enumeration that will remove elements from the specified collection.
static IteratorchainedIterator(Iterator iterator1, Iterator iterator2)
Gets an iterator that iterates through two Iterators one after another.
static IteratorchainedIterator(Iterator[] iterators)
Gets an iterator that iterates through an array of Iterators one after another.
static IteratorchainedIterator(Collection iterators)
Gets an iterator that iterates through a collections of Iterators one after another.
static IteratorcollatedIterator(Comparator comparator, Iterator iterator1, Iterator iterator2)
Gets an iterator that provides an ordered iteration over the elements contained in a collection of ordered Iterators.
static IteratorcollatedIterator(Comparator comparator, Iterator[] iterators)
Gets an iterator that provides an ordered iteration over the elements contained in an array of Iterators.
static IteratorcollatedIterator(Comparator comparator, Collection iterators)
Gets an iterator that provides an ordered iteration over the elements contained in a collection of Iterators.
static ResettableIteratoremptyIterator()
Gets an empty iterator.
static ResettableListIteratoremptyListIterator()
Gets an empty list iterator.
static MapIteratoremptyMapIterator()
Gets an empty map iterator.
static OrderedIteratoremptyOrderedIterator()
Gets an empty ordered iterator.
static OrderedMapIteratoremptyOrderedMapIterator()
Gets an empty ordered map iterator.
static IteratorfilteredIterator(Iterator iterator, Predicate predicate)
Gets an iterator that filters another iterator.
static ListIteratorfilteredListIterator(ListIterator listIterator, Predicate predicate)
Gets a list iterator that filters another list iterator.
static IteratorgetIterator(Object obj)
Gets a suitable Iterator for the given object.
static ResettableIteratorloopingIterator(Collection coll)
Gets an iterator that loops continuously over the supplied collection.
static ResettableListIteratorloopingListIterator(List list)
Gets an iterator that loops continuously over the supplied list.
static IteratorobjectGraphIterator(Object root, Transformer transformer)
Gets an iterator that operates over an object graph.
static ResettableIteratorsingletonIterator(Object object)
Gets a singleton iterator.
static ListIteratorsingletonListIterator(Object object)
Gets a singleton list iterator.
static Object[]toArray(Iterator iterator)
Gets an array based on an iterator.
static Object[]toArray(Iterator iterator, Class arrayClass)
Gets an array based on an iterator.
static ListtoList(Iterator iterator)
Gets a list based on an iterator.
static ListtoList(Iterator iterator, int estimatedSize)
Gets a list based on an iterator.
static ListIteratortoListIterator(Iterator iterator)
Gets a list iterator based on a simple iterator.
static IteratortransformedIterator(Iterator iterator, Transformer transform)
Gets an iterator that transforms the elements of another iterator.
static IteratorunmodifiableIterator(Iterator iterator)
Gets an immutable version of an Iterator.
static ListIteratorunmodifiableListIterator(ListIterator listIterator)
Gets an immutable version of a ListIterator.
static MapIteratorunmodifiableMapIterator(MapIterator mapIterator)
Gets an immutable version of a MapIterator.

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 compatability 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 compatability with Commons Collections 2.1.1.

EMPTY_MAP_ITERATOR

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

EMPTY_ORDERED_ITERATOR

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

EMPTY_ORDERED_MAP_ITERATOR

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

Constructor Detail

IteratorUtils

public IteratorUtils()
IteratorUtils is not normally instantiated.

Method Detail

arrayIterator

public static ResettableIterator arrayIterator(Object[] 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 compatability.

Parameters: array the array over which to iterate

Returns: an iterator over the array

Throws: NullPointerException if array is null

arrayIterator

public static ResettableIterator 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.

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 ResettableIterator arrayIterator(Object[] 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 compatability.

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

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 ResettableIterator arrayIterator(Object[] 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 compatability.

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

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 IndexOutOfBoundsException if array bounds are invalid IllegalArgumentException if end is before start NullPointerException if array is null

arrayListIterator

public static ResettableListIterator arrayListIterator(Object[] array)
Gets a list iterator over an object array.

Parameters: array the array over which to iterate

Returns: a list iterator over the array

Throws: NullPointerException if array is null

arrayListIterator

public static ResettableListIterator 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.

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 ResettableListIterator arrayListIterator(Object[] array, int start)
Gets a list iterator over the end part of an object array.

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

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 ResettableListIterator arrayListIterator(Object[] array, int start, int end)
Gets a list iterator over part of an object array.

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

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 IndexOutOfBoundsException if array bounds are invalid IllegalArgumentException if end is before start NullPointerException if array is null

asEnumeration

public static Enumeration asEnumeration(Iterator iterator)
Gets an enumeration that wraps an iterator.

Parameters: iterator the iterator to use, not null

Returns: a new enumeration

Throws: NullPointerException if iterator is null

asIterator

public static Iterator asIterator(Enumeration enumeration)
Gets an iterator that provides an iterator view of the given enumeration.

Parameters: enumeration the enumeration to use

Returns: a new iterator

asIterator

public static Iterator asIterator(Enumeration enumeration, Collection removeCollection)
Gets an iterator that provides an iterator view of the given enumeration that will remove elements from the specified collection.

Parameters: enumeration the enumeration to use removeCollection the collection to remove elements from

Returns: a new iterator

chainedIterator

public static Iterator chainedIterator(Iterator iterator1, Iterator iterator2)
Gets an iterator that iterates through two Iterators one after another.

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

chainedIterator

public static Iterator chainedIterator(Iterator[] iterators)
Gets an iterator that iterates through an array of Iterators one after another.

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 Iterator chainedIterator(Collection iterators)
Gets an iterator that iterates through a collections of Iterators one after another.

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 Iterator collatedIterator(Comparator comparator, Iterator iterator1, Iterator 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.

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 Iterator collatedIterator(Comparator comparator, Iterator[] 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.

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

collatedIterator

public static Iterator collatedIterator(Comparator comparator, Collection 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.

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

emptyIterator

public static ResettableIterator 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 compatability with Commons Collections 2.1.1.

Returns: an iterator over nothing

emptyListIterator

public static ResettableListIterator 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 compatability with Commons Collections 2.1.1.

Returns: a list iterator over nothing

emptyMapIterator

public static MapIterator emptyMapIterator()
Gets an empty map iterator.

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

Returns: a map iterator over nothing

emptyOrderedIterator

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

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

Returns: an ordered iterator over nothing

emptyOrderedMapIterator

public static OrderedMapIterator emptyOrderedMapIterator()
Gets an empty ordered map iterator.

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

Returns: a map iterator over nothing

filteredIterator

public static Iterator filteredIterator(Iterator iterator, Predicate predicate)
Gets an iterator that filters another iterator.

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

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 ListIterator filteredListIterator(ListIterator listIterator, Predicate predicate)
Gets a list iterator that filters another list iterator.

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

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

getIterator

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

This method can handles objects as follows

Parameters: obj the object to convert to an iterator

Returns: a suitable iterator, never null

loopingIterator

public static ResettableIterator loopingIterator(Collection 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.

Parameters: coll the collection to iterate over, not null

Returns: a new looping iterator

Throws: NullPointerException if the collection is null

loopingListIterator

public static ResettableListIterator loopingListIterator(List 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.

Parameters: list the list to iterate over, not null

Returns: a new looping iterator

Throws: NullPointerException if the list is null

Since: Commons Collections 3.2

objectGraphIterator

public static Iterator objectGraphIterator(Object root, Transformer 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.

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: Commons Collections 3.1

singletonIterator

public static ResettableIterator singletonIterator(Object 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 compatability.

Parameters: object the single object over which to iterate

Returns: a singleton iterator over the object

singletonListIterator

public static ListIterator singletonListIterator(Object object)
Gets a singleton list iterator.

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

Parameters: object the single object over which to iterate

Returns: a singleton list iterator over the object

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 Object[] toArray(Iterator iterator, Class 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.

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 is null NullPointerException if arrayClass is null ClassCastException if the arrayClass is invalid

toList

public static List toList(Iterator 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.

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 List toList(Iterator 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.

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 ListIterator toListIterator(Iterator 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.

Parameters: iterator the iterator to use, not null

Returns: a new iterator

Throws: NullPointerException if iterator parameter is null

transformedIterator

public static Iterator transformedIterator(Iterator iterator, Transformer 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.

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

unmodifiableIterator

public static Iterator unmodifiableIterator(Iterator iterator)
Gets an immutable version of an Iterator. The returned object will always throw an UnsupportedOperationException for the Iterator#remove method.

Parameters: iterator the iterator to make immutable

Returns: an immutable version of the iterator

unmodifiableListIterator

public static ListIterator unmodifiableListIterator(ListIterator listIterator)
Gets an immutable version of a ListIterator. The returned object will always throw an UnsupportedOperationException for the Iterator#remove, ListIterator#add and ListIterator#set methods.

Parameters: listIterator the iterator to make immutable

Returns: an immutable version of the iterator

unmodifiableMapIterator

public static MapIterator unmodifiableMapIterator(MapIterator mapIterator)
Gets an immutable version of a MapIterator. The returned object will always throw an UnsupportedOperationException for the Iterator#remove, setValue methods.

Parameters: mapIterator the iterator to make immutable

Returns: an immutable version of the iterator

Copyright © 2001-2008 Apache Software Foundation. All Rights Reserved.