org.apache.commons.collections
public class IteratorUtils extends Object
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) $
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 ResettableListIterator | loopingListIterator(List list)
Gets an iterator that loops continuously over the supplied list.
|
static Iterator | objectGraphIterator(Object root, Transformer transformer)
Gets an iterator that operates over an object graph.
|
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. |
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.
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.
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
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
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
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
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
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
Parameters: array the array over which to iterate
Returns: a list iterator over the array
Throws: NullPointerException if array is null
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
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
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
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
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
Parameters: iterator the iterator to use, not null
Returns: a new enumeration
Throws: NullPointerException if iterator is null
Parameters: enumeration the enumeration to use
Returns: a new iterator
Parameters: enumeration the enumeration to use removeCollection the collection to remove elements from
Returns: a new iterator
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
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
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
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
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
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
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
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
This iterator is a valid map iterator object that will iterate over nothing.
Returns: a map iterator over nothing
This iterator is a valid iterator object that will iterate over nothing.
Returns: an ordered iterator over nothing
This iterator is a valid map iterator object that will iterate over nothing.
Returns: a map iterator over nothing
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
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
This method can handles objects as follows
Parameters: obj the object to convert to an iterator
Returns: a suitable iterator, never null
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
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
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 -- LeafThe 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
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
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
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
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
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
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
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
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
Parameters: iterator the iterator to make immutable
Returns: an immutable version of the iterator
Parameters: listIterator the iterator to make immutable
Returns: an immutable version of the iterator
Parameters: mapIterator the iterator to make immutable
Returns: an immutable version of the iterator