org.apache.commons.collections
Class IteratorUtils

java.lang.Object
  |
  +--org.apache.commons.collections.IteratorUtils

public class IteratorUtils

extends java.lang.Object

Provides static utility methods and decorators for Iterator instances. The implementations are provided in the org.apache.commons.collections.iterators subpackage.

Since:

2.1

Version:

$Id: IteratorUtils.java,v 1.4.2.2 2004/05/22 12:14:01 scolebourne Exp $

Author:

Stephen Colebourne

Field Summary

static java.util.Iterator	EMPTY_ITERATOR Deprecated. Use EmptyIterator.INSTANCE
static java.util.ListIterator	EMPTY_LIST_ITERATOR Deprecated. Use EmptyListIterator.INSTANCE

Method Summary

static java.util.Iterator	arrayIterator(java.lang.Object[] array) Deprecated. Use new ArrayIterator(array)
static java.util.Iterator	arrayIterator(java.lang.Object[] array, int start) Deprecated. Use new ArrayIterator(array,start)
static java.util.Iterator	arrayIterator(java.lang.Object[] array, int start, int end) Deprecated. Use new ArrayIterator(array,start,end)
static java.util.Enumeration	asEnumeration(java.util.Iterator iterator) Gets an enumeration that wraps an iterator.
static java.util.Iterator	asIterator(java.util.Enumeration enumeration) Gets an iterator that provides an iterator view of the given enumeration.
static java.util.Iterator	asIterator(java.util.Enumeration enumeration, java.util.Collection removeCollection) Gets an iterator that provides an iterator view of the given enumeration that will remove elements from the specified collection.
static java.util.Iterator	chainedIterator(java.util.Collection iterators) Gets an iterator that iterates through a collections of Iterators one after another.
static java.util.Iterator	chainedIterator(java.util.Iterator[] iterators) Gets an iterator that iterates through an array of Iterators one after another.
static java.util.Iterator	chainedIterator(java.util.Iterator iterator1, java.util.Iterator iterator2) Gets an iterator that iterates through two Iterators one after another.
static java.util.Iterator	collatedIterator(java.util.Comparator comparator, java.util.Collection iterators) Gets an iterator that provides an ordered iteration over the elements contained in a collection of Iterators.
static java.util.Iterator	collatedIterator(java.util.Comparator comparator, java.util.Iterator[] iterators) Gets an iterator that provides an ordered iteration over the elements contained in an array of Iterators.
static java.util.Iterator	collatedIterator(java.util.Comparator comparator, java.util.Iterator iterator1, java.util.Iterator iterator2) Gets an iterator that provides an ordered iteration over the elements contained in a collection of ordered Iterators.
static java.util.Iterator	emptyIterator() Deprecated. Use EmptyIterator.INSTANCE
static java.util.ListIterator	emptyListIterator() Deprecated. Use EmptyListIterator.INSTANCE
static java.util.Iterator	filteredIterator(java.util.Iterator iterator, Predicate predicate) Gets an iterator that filters another iterator.
static java.util.ListIterator	filteredListIterator(java.util.ListIterator listIterator, Predicate predicate) Gets a list iterator that filters another list iterator.
static java.util.Iterator	getIterator(java.lang.Object obj) Gets a suitable Iterator for the given object.
static java.util.Iterator	singletonIterator(java.lang.Object object) Deprecated. Use new SingletonIterator(object)
static java.util.ListIterator	singletonListIterator(java.lang.Object object) Gets a singleton list iterator.
static java.lang.Object[]	toArray(java.util.Iterator iterator) Gets an array based on an iterator.
static java.lang.Object[]	toArray(java.util.Iterator iterator, java.lang.Class arrayClass) Gets an array based on an iterator.
static java.util.List	toList(java.util.Iterator iterator) Gets a list based on an iterator.
static java.util.List	toList(java.util.Iterator iterator, int estimatedSize) Gets a list based on an iterator.
static java.util.ListIterator	toListIterator(java.util.Iterator iterator) Gets a list iterator based on a simple iterator.
static java.util.Iterator	transformedIterator(java.util.Iterator iterator, Transformer transform) Gets an iterator that transforms the elements of another iterator.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMPTY_ITERATOR

public static final java.util.Iterator EMPTY_ITERATOR

Deprecated. Use EmptyIterator.INSTANCE

An iterator over no elements.

EMPTY_LIST_ITERATOR

public static final java.util.ListIterator EMPTY_LIST_ITERATOR

Deprecated. Use EmptyListIterator.INSTANCE

A list iterator over no elements

Method Detail

emptyIterator

public static java.util.Iterator emptyIterator()

Deprecated. Use EmptyIterator.INSTANCE

Gets an empty iterator.

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

Returns:

an iterator over nothing

emptyListIterator

public static java.util.ListIterator emptyListIterator()

Deprecated. Use EmptyListIterator.INSTANCE

Gets an empty list iterator.

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

Returns:

a list iterator over nothing

singletonIterator

public static java.util.Iterator singletonIterator(java.lang.Object object)

Deprecated. Use new SingletonIterator(object)

Gets a singleton iterator.

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

Parameters:

object - the single object over which to iterate

Returns:

a singleton iterator over the object

singletonListIterator

public static java.util.ListIterator singletonListIterator(java.lang.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

arrayIterator

public static java.util.Iterator arrayIterator(java.lang.Object[] array)

Deprecated. Use new ArrayIterator(array)

Gets an iterator over an array.

Parameters:

array - the array over which to iterate

Returns:

an iterator over the array

Throws:

java.lang.NullPointerException - if array is null

arrayIterator

public static java.util.Iterator arrayIterator(java.lang.Object[] array,
                                               int start)

Deprecated. Use new ArrayIterator(array,start)

Gets an iterator over the end part of an array.

Parameters:

array - the array over which to iterate

start - the index to start iterating at

Returns:

an iterator over part of the array

Throws:

java.lang.IllegalArgumentException - if array bounds are invalid

java.lang.NullPointerException - if array is null

arrayIterator

public static java.util.Iterator arrayIterator(java.lang.Object[] array,
                                               int start,
                                               int end)

Deprecated. Use new ArrayIterator(array,start,end)

Gets an iterator over part of an array.

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:

java.lang.IllegalArgumentException - if array bounds are invalid

java.lang.NullPointerException - if array is null

chainedIterator

public static java.util.Iterator chainedIterator(java.util.Iterator iterator1,
                                                 java.util.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:

java.lang.NullPointerException - if either iterator is null

chainedIterator

public static java.util.Iterator chainedIterator(java.util.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:

java.lang.NullPointerException - if iterators array is null or contains a null

chainedIterator

public static java.util.Iterator chainedIterator(java.util.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:

java.lang.NullPointerException - if iterators collection is null or contains a null

java.lang.ClassCastException - if the iterators collection contains the wrong object type

collatedIterator

public static java.util.Iterator collatedIterator(java.util.Comparator comparator,
                                                  java.util.Iterator iterator1,
                                                  java.util.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:

java.lang.NullPointerException - if either iterator is null

collatedIterator

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

java.lang.NullPointerException - if iterators array is null or contains a null

collatedIterator

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

java.lang.NullPointerException - if iterators collection is null or contains a null

java.lang.ClassCastException - if the iterators collection contains the wrong object type

transformedIterator

public static java.util.Iterator transformedIterator(java.util.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

Throws:

java.lang.NullPointerException - if either parameter is null

filteredIterator

public static java.util.Iterator filteredIterator(java.util.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

Throws:

java.lang.NullPointerException - if either parameter is null

filteredListIterator

public static java.util.ListIterator filteredListIterator(java.util.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

Throws:

java.lang.NullPointerException - if either parameter is null

asIterator

public static java.util.Iterator asIterator(java.util.Enumeration enumeration)

Gets an iterator that provides an iterator view of the given enumeration.

Parameters:

enumeration - the enumeration to use

asIterator

public static java.util.Iterator asIterator(java.util.Enumeration enumeration,
                                            java.util.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

asEnumeration

public static java.util.Enumeration asEnumeration(java.util.Iterator iterator)

Gets an enumeration that wraps an iterator.

Parameters:

iterator - the iterator to use, not null

Throws:

java.lang.NullPointerException - if iterator is null

toListIterator

public static java.util.ListIterator toListIterator(java.util.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

Throws:

java.lang.NullPointerException - if iterator parameter is null

toArray

public static java.lang.Object[] toArray(java.util.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

Throws:

java.lang.NullPointerException - if iterator parameter is null

toArray

public static java.lang.Object[] toArray(java.util.Iterator iterator,
                                         java.lang.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

Throws:

java.lang.NullPointerException - if iterator parameter is null

java.lang.NullPointerException - if arrayClass is null

java.lang.ClassCastException - if the arrayClass is invalid

toList

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

Throws:

java.lang.NullPointerException - if iterator parameter is null

toList

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

Throws:

java.lang.NullPointerException - if iterator parameter is null

java.lang.IllegalArgumentException - if the size is less than 1

getIterator

public static java.util.Iterator getIterator(java.lang.Object obj)

Gets a suitable Iterator for the given object.

This method can handles 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

Parameters:

obj - the object to convert to an iterator

Returns:

a suitable iterator, never null