⇒ Index (Frames) |  ⇒ Index (No Frames) |  ⇒ Package |  ⇒ Package Tree |  ⇒ Full Tree 
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 iterators subpackage.
Since:
Commons Collections 2.1
Authors:
Stephen Colebourne
Phil Steitz

Field Summary

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

Constructor Summary

IteratorUtils()

IteratorUtils is not normally instantiated.

Method Summary

static ResettableIterator

arrayIterator(Object[] array)

Gets an iterator over an object array.

static ResettableIterator

arrayIterator(Object array)

Gets an iterator over an object or primitive array.

static ResettableIterator

arrayIterator(Object[] array, int start)

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

static ResettableIterator

arrayIterator(Object array, int start)

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

static ResettableIterator

arrayIterator(Object[] array, int start, int end)

Gets an iterator over part of an object array.

static ResettableIterator

arrayIterator(Object array, int start, int end)

Gets an iterator over part of an object or primitive array.

static ResettableListIterator

arrayListIterator(Object[] array)

Gets a list iterator over an object array.

static ResettableListIterator

arrayListIterator(Object array)

Gets a list iterator over an object or primitive array.

static ResettableListIterator

arrayListIterator(Object[] array, int start)

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

static ResettableListIterator

arrayListIterator(Object array, int start)

Gets a list iterator over the end part of an object or primitive array.

static ResettableListIterator

arrayListIterator(Object[] array, int start, int end)

Gets a list iterator over part of an object array.

static ResettableListIterator

arrayListIterator(Object array, int start, int end)

Gets a list iterator over part of an object or primitive array.

static Enumeration

asEnumeration(Iterator iterator)

Gets an enumeration that wraps an iterator.

static Iterator

asIterator(Enumeration enumeration)

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

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.

static Iterator

chainedIterator(Iterator iterator1, Iterator iterator2)

Gets an iterator that iterates through two Iterators one after another.

static Iterator

chainedIterator(Iterator[] iterators)

Gets an iterator that iterates through an array of Iterators one after another.

static Iterator

chainedIterator(Collection iterators)

Gets an iterator that iterates through a collections of Iterators one after another.

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.

static Iterator

collatedIterator(Comparator comparator, Iterator[] iterators)

Gets an iterator that provides an ordered iteration over the elements contained in an array of Iterators.

static Iterator

collatedIterator(Comparator comparator, Collection iterators)

Gets an iterator that provides an ordered iteration over the elements contained in a collection of Iterators.

static ResettableIterator

emptyIterator()

Gets an empty iterator.

static ResettableListIterator

emptyListIterator()

Gets an empty list iterator.

static MapIterator

emptyMapIterator()

Gets an empty map iterator.

static OrderedIterator

emptyOrderedIterator()

Gets an empty ordered iterator.

static OrderedMapIterator

emptyOrderedMapIterator()

Gets an empty ordered map iterator.

static Iterator

filteredIterator(Iterator iterator, Predicate predicate)

Gets an iterator that filters another iterator.

static ListIterator

filteredListIterator(ListIterator listIterator, Predicate predicate)

Gets a list iterator that filters another list iterator.

static Iterator

getIterator(Object obj)

Gets a suitable Iterator for the given object.

static ResettableIterator

loopingIterator(Collection coll)

Gets an iterator that loops continuously over the supplied collection.

static ResettableIterator

singletonIterator(Object object)

Gets a singleton iterator.

static ListIterator

singletonListIterator(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 List

toList(Iterator iterator)

Gets a list based on an iterator.

static List

toList(Iterator iterator, int estimatedSize)

Gets a list based on an iterator.

static ListIterator

toListIterator(Iterator iterator)

Gets a list iterator based on a simple iterator.

static Iterator

transformedIterator(Iterator iterator, Transformer transform)

Gets an iterator that transforms the elements of another iterator.

static Iterator

unmodifiableIterator(Iterator iterator)

Gets an immutable version of an Iterator.

static ListIterator

unmodifiableListIterator(ListIterator listIterator)

Gets an immutable version of a ListIterator.

static MapIterator

unmodifiableMapIterator(MapIterator mapIterator)

Gets an immutable version of a MapIterator.

Field Details

EMPTY_ITERATOR

public static final ResettableIterator EMPTY_ITERATOR

An iterator over no elements


EMPTY_LIST_ITERATOR

public static final ResettableListIterator EMPTY_LIST_ITERATOR

A list iterator over no elements


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

IteratorUtils

public IteratorUtils()

IteratorUtils is not normally instantiated.

Method Details

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:
- if the array is not an array
- if array bounds are invalid
- if end is before start
- 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:
- if the array is not an array
- if start is less than zero or greater than the length of the array
- 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:
- if the array is not an array
- if array is null

arrayIterator

public static ResettableIterator arrayIterator(Object[] array, int start, int end)

Gets an 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:
an iterator over part of the array
Throws:
- if array bounds are invalid
- if end is before start
- if array is null

arrayIterator

public static ResettableIterator arrayIterator(Object[] array, int start)

Gets an 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:
an iterator over part of the array
Throws:
- if start is less than zero or greater than the length of the array
- if array is null

arrayIterator

public static ResettableIterator arrayIterator(Object[] array)

Gets an iterator over an object array.

Parameters:
array - the array over which to iterate
Returns:
an iterator over the array
Throws:
- 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:
- if the array is not an array
- if array bounds are invalid
- if end is before start
- 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:
- if the array is not an array
- if start is less than zero
- 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:
- if the array is not an array
- 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:
- if array bounds are invalid
- if end is before start
- 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:
- if start is less than zero
- 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:
- 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
Throws:
- if iterator is null

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

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

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:
- if iterators collection is null or contains a null
- if the iterators collection contains the wrong object type

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:
- 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:
- 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:
- if iterators collection is null or contains a null
- 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:
- 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:
- if iterators array is null or contains a null

emptyIterator

public static ResettableIterator emptyIterator()

Gets an empty iterator.

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

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.

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

  • 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

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
Throws:
- if the collection is null

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.

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, 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:
- if iterator parameter is null
- if arrayClass is null
- if the arrayClass is invalid

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
Throws:
- 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
Throws:
- if iterator parameter is null
- if the size is less than 1

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
Throws:
- if iterator parameter is null

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
Throws:
- 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
Throws:
- 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, MapIterator.setValue(Object) methods.

Parameters:
mapIterator - the iterator to make immutable
Returns:
an immutable version of the iterator