|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.commons.collections4.IteratorUtils
public class IteratorUtils
Provides static utility methods and decorators for Iterator
instances. The implementations are provided in the iterators subpackage.
WARNING: Due to human error certain binary incompatibilities 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.
Field Summary | |
---|---|
static ResettableIterator<Object> |
EMPTY_ITERATOR
An iterator over no elements. |
static ResettableListIterator<Object> |
EMPTY_LIST_ITERATOR
A list iterator over no elements. |
static MapIterator<Object,Object> |
EMPTY_MAP_ITERATOR
A map iterator over no elements. |
static OrderedIterator<Object> |
EMPTY_ORDERED_ITERATOR
An ordered iterator over no elements. |
static OrderedMapIterator<Object,Object> |
EMPTY_ORDERED_MAP_ITERATOR
An ordered map iterator over no elements. |
Method Summary | ||
---|---|---|
static
|
arrayIterator(E... array)
Gets an iterator over an object array. |
|
static
|
arrayIterator(E[] array,
int start)
Gets an iterator over the end part of an object array. |
|
static
|
arrayIterator(E[] array,
int start,
int end)
Gets an iterator over part of an object array. |
|
static
|
arrayIterator(Object array)
Gets an iterator over an object or primitive array. |
|
static
|
arrayIterator(Object array,
int start)
Gets an iterator over the end part of an object or primitive array. |
|
static
|
arrayIterator(Object array,
int start,
int end)
Gets an iterator over part of an object or primitive array. |
|
static
|
arrayListIterator(E... array)
Gets a list iterator over an object array. |
|
static
|
arrayListIterator(E[] array,
int start)
Gets a list iterator over the end part of an object array. |
|
static
|
arrayListIterator(E[] array,
int start,
int end)
Gets a list iterator over part of an object array. |
|
static
|
arrayListIterator(Object array)
Gets a list iterator over an object or primitive array. |
|
static
|
arrayListIterator(Object array,
int start)
Gets a list iterator over the end part of an object or primitive array. |
|
static
|
arrayListIterator(Object array,
int start,
int end)
Gets a list iterator over part of an object or primitive array. |
|
static
|
asEnumeration(Iterator<? extends E> iterator)
Gets an enumeration that wraps an iterator. |
|
static
|
asIterable(Iterator<? extends E> iterator)
Gets an Iterable that wraps an iterator. |
|
static
|
asIterator(Enumeration<? extends E> enumeration)
Gets an iterator that provides an iterator view of the given enumeration. |
|
static
|
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
|
asMultipleUseIterable(Iterator<? extends E> iterator)
Gets an iterable that wraps an iterator. |
|
static
|
chainedIterator(Collection<Iterator<? extends E>> iterators)
Gets an iterator that iterates through a collections of Iterator s
one after another. |
|
static
|
chainedIterator(Iterator<? extends E>... iterators)
Gets an iterator that iterates through an array of Iterator s
one after another. |
|
static
|
chainedIterator(Iterator<? extends E> iterator1,
Iterator<? extends E> iterator2)
Gets an iterator that iterates through two Iterator s
one after another. |
|
static
|
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 Iterator s. |
|
static
|
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 Iterator s. |
|
static
|
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 Iterator s. |
|
static
|
emptyIterator()
Gets an empty iterator. |
|
static
|
emptyListIterator()
Gets an empty list iterator. |
|
static
|
emptyMapIterator()
Gets an empty map iterator. |
|
static
|
emptyOrderedIterator()
Gets an empty ordered iterator. |
|
static
|
emptyOrderedMapIterator()
Gets an empty ordered map iterator. |
|
static
|
filteredIterator(Iterator<? extends E> iterator,
Predicate<? super E> predicate)
Gets an iterator that filters another iterator. |
|
static
|
filteredListIterator(ListIterator<? extends E> listIterator,
Predicate<? super E> predicate)
Gets a list iterator that filters another list iterator. |
|
static Iterator<?> |
getIterator(Object obj)
Gets a suitable Iterator for the given object. |
|
static
|
loopingIterator(Collection<? extends E> coll)
Gets an iterator that loops continuously over the supplied collection. |
|
static
|
loopingListIterator(List<E> list)
Gets an iterator that loops continuously over the supplied list. |
|
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
|
objectGraphIterator(E root,
Transformer<? super E,? extends E> transformer)
Gets an iterator that operates over an object graph. |
|
static
|
peekingIterator(Iterator<? extends E> iterator)
Gets an iterator that supports one-element lookahead. |
|
static
|
pushbackIterator(Iterator<? extends E> iterator)
Gets an iterator that supports pushback of elements. |
|
static
|
singletonIterator(E object)
Gets a singleton iterator. |
|
static
|
singletonListIterator(E object)
Gets a singleton list iterator. |
|
static Object[] |
toArray(Iterator<?> iterator)
Gets an array based on an iterator. |
|
static
|
toArray(Iterator<? extends E> iterator,
Class<E> arrayClass)
Gets an array based on an iterator. |
|
static
|
toList(Iterator<? extends E> iterator)
Gets a list based on an iterator. |
|
static
|
toList(Iterator<? extends E> iterator,
int estimatedSize)
Gets a list based on an iterator. |
|
static
|
toListIterator(Iterator<? extends E> iterator)
Gets a list iterator based on a simple iterator. |
|
static
|
transformedIterator(Iterator<? extends I> iterator,
Transformer<? super I,? extends O> transform)
Gets an iterator that transforms the elements of another iterator. |
|
static
|
unmodifiableIterator(Iterator<E> iterator)
Gets an immutable version of an Iterator . |
|
static
|
unmodifiableListIterator(ListIterator<E> listIterator)
Gets an immutable version of a ListIterator . |
|
static
|
unmodifiableMapIterator(MapIterator<K,V> mapIterator)
Gets an immutable version of a MapIterator . |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final ResettableIterator<Object> EMPTY_ITERATOR
WARNING: This constant is binary incompatible with Commons Collections 2.1 and 2.1.1.
Use EmptyIterator.INSTANCE
for compatibility with Commons Collections 2.1.1.
public static final ResettableListIterator<Object> EMPTY_LIST_ITERATOR
WARNING: This constant is binary incompatible with Commons Collections 2.1 and 2.1.1.
Use EmptyListIterator.INSTANCE
for compatibility with Commons Collections 2.1.1.
public static final OrderedIterator<Object> EMPTY_ORDERED_ITERATOR
public static final MapIterator<Object,Object> EMPTY_MAP_ITERATOR
public static final OrderedMapIterator<Object,Object> EMPTY_ORDERED_MAP_ITERATOR
Method Detail |
---|
public static <E> ResettableIterator<E> emptyIterator()
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 compatibility with Commons Collections 2.1.1.
E
- the element type
public static <E> ResettableListIterator<E> emptyListIterator()
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 compatibility with Commons Collections 2.1.1.
E
- the element type
public static <E> OrderedIterator<E> emptyOrderedIterator()
This iterator is a valid iterator object that will iterate over nothing.
E
- the element type
public static <K,V> MapIterator<K,V> emptyMapIterator()
This iterator is a valid map iterator object that will iterate over nothing.
K
- the key typeV
- the value type
public static <K,V> OrderedMapIterator<K,V> emptyOrderedMapIterator()
This iterator is a valid map iterator object that will iterate over nothing.
K
- the key typeV
- the value type
public static <E> ResettableIterator<E> singletonIterator(E object)
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 compatibility.
E
- the element typeobject
- the single object over which to iterate
public static <E> ListIterator<E> singletonListIterator(E object)
This iterator is a valid list iterator object that will iterate over the specified object.
E
- the element typeobject
- the single object over which to iterate
public static <E> ResettableIterator<E> arrayIterator(E... array)
WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1.
Use new ArrayIterator(array)
for compatibility.
E
- the element typearray
- the array over which to iterate
NullPointerException
- if array is nullpublic static <E> ResettableIterator<E> arrayIterator(Object array)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
E
- the element typearray
- the array over which to iterate
IllegalArgumentException
- if the array is not an array
NullPointerException
- if array is nullpublic static <E> ResettableIterator<E> arrayIterator(E[] array, int start)
WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1.
Use new ArrayIterator(array,start)
for compatibility.
E
- the element typearray
- the array over which to iteratestart
- the index to start iterating at
IndexOutOfBoundsException
- if start is less than zero or greater
than the length of the array
NullPointerException
- if array is nullpublic static <E> ResettableIterator<E> arrayIterator(Object array, int start)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
E
- the element typearray
- the array over which to iteratestart
- the index to start iterating at
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 nullpublic static <E> ResettableIterator<E> arrayIterator(E[] array, int start, int end)
WARNING: This method is binary incompatible with Commons Collections 2.1 and 2.1.1.
Use new ArrayIterator(array,start,end)
for compatibility.
E
- the element typearray
- the array over which to iteratestart
- the index to start iterating atend
- the index to finish iterating at
IndexOutOfBoundsException
- if array bounds are invalid
IllegalArgumentException
- if end is before start
NullPointerException
- if array is nullpublic static <E> ResettableIterator<E> arrayIterator(Object array, int start, int end)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
E
- the element typearray
- the array over which to iteratestart
- the index to start iterating atend
- the index to finish iterating at
IllegalArgumentException
- if the array is not an array or end is before start
IndexOutOfBoundsException
- if array bounds are invalid
NullPointerException
- if array is nullpublic static <E> ResettableListIterator<E> arrayListIterator(E... array)
E
- the element typearray
- the array over which to iterate
NullPointerException
- if array is nullpublic static <E> ResettableListIterator<E> arrayListIterator(Object array)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
E
- the element typearray
- the array over which to iterate
IllegalArgumentException
- if the array is not an array
NullPointerException
- if array is nullpublic static <E> ResettableListIterator<E> arrayListIterator(E[] array, int start)
E
- the element typearray
- the array over which to iteratestart
- the index to start iterating at
IndexOutOfBoundsException
- if start is less than zero
NullPointerException
- if array is nullpublic static <E> ResettableListIterator<E> arrayListIterator(Object array, int start)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
E
- the element typearray
- the array over which to iteratestart
- the index to start iterating at
IllegalArgumentException
- if the array is not an array
IndexOutOfBoundsException
- if start is less than zero
NullPointerException
- if array is nullpublic static <E> ResettableListIterator<E> arrayListIterator(E[] array, int start, int end)
E
- the element typearray
- the array over which to iteratestart
- the index to start iterating atend
- the index to finish iterating at
IndexOutOfBoundsException
- if array bounds are invalid
IllegalArgumentException
- if end is before start
NullPointerException
- if array is nullpublic static <E> ResettableListIterator<E> arrayListIterator(Object array, int start, int end)
This method will handle primitive arrays as well as object arrays. The primitives will be wrapped in the appropriate wrapper class.
E
- the element typearray
- the array over which to iteratestart
- the index to start iterating atend
- the index to finish iterating at
IllegalArgumentException
- if the array is not an array or end is before start
IndexOutOfBoundsException
- if array bounds are invalid
NullPointerException
- if array is nullpublic static <E> Iterator<E> unmodifiableIterator(Iterator<E> iterator)
Iterator
. The returned object
will always throw an UnsupportedOperationException
for
the Iterator.remove()
method.
E
- the element typeiterator
- the iterator to make immutable
public static <E> ListIterator<E> unmodifiableListIterator(ListIterator<E> listIterator)
ListIterator
. The returned object
will always throw an UnsupportedOperationException
for
the Iterator.remove()
, ListIterator.add(E)
and
ListIterator.set(E)
methods.
E
- the element typelistIterator
- the iterator to make immutable
public static <K,V> MapIterator<K,V> unmodifiableMapIterator(MapIterator<K,V> mapIterator)
MapIterator
. The returned object
will always throw an UnsupportedOperationException
for
the Iterator.remove()
, MapIterator.setValue(Object)
methods.
K
- the key typeV
- the value typemapIterator
- the iterator to make immutable
public static <E> Iterator<E> chainedIterator(Iterator<? extends E> iterator1, Iterator<? extends E> iterator2)
Iterator
s
one after another.
E
- the element typeiterator1
- the first iterator to use, not nulliterator2
- the second iterator to use, not null
NullPointerException
- if either iterator is nullpublic static <E> Iterator<E> chainedIterator(Iterator<? extends E>... iterators)
Iterator
s
one after another.
E
- the element typeiterators
- the iterators to use, not null or empty or contain nulls
NullPointerException
- if iterators array is null or contains a nullpublic static <E> Iterator<E> chainedIterator(Collection<Iterator<? extends E>> iterators)
Iterator
s
one after another.
E
- the element typeiterators
- the iterators to use, not null or empty or contain nulls
NullPointerException
- if iterators collection is null or contains a null
ClassCastException
- if the iterators collection contains the wrong object typepublic static <E> Iterator<E> collatedIterator(Comparator<? super E> comparator, Iterator<? extends E> iterator1, Iterator<? extends E> iterator2)
Iterator
s.
Given two ordered Iterator
s 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.
E
- the element typecomparator
- the comparator to use, may be null for natural orderiterator1
- the first iterators to use, not nulliterator2
- the first iterators to use, not null
NullPointerException
- if either iterator is nullpublic static <E> Iterator<E> collatedIterator(Comparator<? super E> comparator, Iterator<? extends E>... iterators)
Iterator
s.
Given two ordered Iterator
s 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.
E
- the element typecomparator
- the comparator to use, may be null for natural orderiterators
- the iterators to use, not null or empty or contain nulls
NullPointerException
- if iterators array is null or contains a null valuepublic static <E> Iterator<E> collatedIterator(Comparator<? super E> comparator, Collection<Iterator<? extends E>> iterators)
Iterator
s.
Given two ordered Iterator
s 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.
E
- the element typecomparator
- the comparator to use, may be null for natural orderiterators
- the iterators to use, not null or empty or contain nulls
NullPointerException
- if iterators collection is null or contains a null
ClassCastException
- if the iterators collection contains the wrong object typepublic static <E> Iterator<E> objectGraphIterator(E root, Transformer<? super E,? extends E> transformer)
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.
E
- the element typeroot
- the root object to start iterating from, null results in an empty iteratortransformer
- the transformer to use, see above, null uses no effect transformer
public static <I,O> Iterator<O> transformedIterator(Iterator<? extends I> iterator, Transformer<? super I,? extends O> transform)
The transformation occurs during the next() method and the underlying iterator is unaffected by the transformation.
I
- the input typeO
- the output typeiterator
- the iterator to use, not nulltransform
- the transform to use, not null
NullPointerException
- if either parameter is nullpublic static <E> Iterator<E> filteredIterator(Iterator<? extends E> iterator, Predicate<? super E> predicate)
The returned iterator will only return objects that match the specified filtering predicate.
E
- the element typeiterator
- the iterator to use, not nullpredicate
- the predicate to use as a filter, not null
NullPointerException
- if either parameter is nullpublic static <E> ListIterator<E> filteredListIterator(ListIterator<? extends E> listIterator, Predicate<? super E> predicate)
The returned iterator will only return objects that match the specified filtering predicate.
E
- the element typelistIterator
- the list iterator to use, not nullpredicate
- the predicate to use as a filter, not null
NullPointerException
- if either parameter is nullpublic static <E> ResettableIterator<E> loopingIterator(Collection<? extends E> coll)
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.
E
- the element typecoll
- the collection to iterate over, not null
NullPointerException
- if the collection is nullpublic static <E> ResettableListIterator<E> loopingListIterator(List<E> 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.
E
- the element typelist
- the list to iterate over, not null
NullPointerException
- if the list is nullpublic static NodeListIterator nodeListIterator(NodeList nodeList)
Iterator
that wraps the specified NodeList
.
The returned Iterator
can be used for a single iteration.
nodeList
- the node list to use, not null
Iterator
NullPointerException
- if nodeList is nullpublic static NodeListIterator nodeListIterator(Node node)
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)) { ... }
node
- the node to use, not null
Iterator
NullPointerException
- if node is nullpublic static <E> Iterator<E> peekingIterator(Iterator<? extends E> iterator)
E
- the element typeiterator
- the iterator to decorate, not null
NullPointerException
- if the iterator is nullpublic static <E> Iterator<E> pushbackIterator(Iterator<? extends E> iterator)
E
- the element typeiterator
- the iterator to decorate, not null
NullPointerException
- if the iterator is nullpublic static <E> Iterator<E> asIterator(Enumeration<? extends E> enumeration)
E
- the element typeenumeration
- the enumeration to use
public static <E> Iterator<E> asIterator(Enumeration<? extends E> enumeration, Collection<? super E> removeCollection)
E
- the element typeenumeration
- the enumeration to useremoveCollection
- the collection to remove elements from
public static <E> Enumeration<E> asEnumeration(Iterator<? extends E> iterator)
E
- the element typeiterator
- the iterator to use, not null
NullPointerException
- if iterator is nullpublic static <E> Iterable<E> asIterable(Iterator<? extends E> iterator)
Iterable
that wraps an iterator. The returned Iterable
can be
used for a single iteration.
E
- the element typeiterator
- the iterator to use, not null
Iterable
NullPointerException
- if iterator is nullpublic static <E> Iterable<E> asMultipleUseIterable(Iterator<? extends E> iterator)
E
- the element typeiterator
- the iterator to use, not null
NullPointerException
- if iterator is nullpublic static <E> ListIterator<E> toListIterator(Iterator<? extends E> iterator)
As the wrapped Iterator is traversed, a LinkedList of its values is cached, permitting all required operations of ListIterator.
E
- the element typeiterator
- the iterator to use, not null
NullPointerException
- if iterator parameter is nullpublic static Object[] toArray(Iterator<?> iterator)
As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, this is converted to an array.
iterator
- the iterator to use, not null
NullPointerException
- if iterator parameter is nullpublic static <E> E[] toArray(Iterator<? extends E> iterator, Class<E> arrayClass)
As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, this is converted to an array.
E
- the element typeiterator
- the iterator to use, not nullarrayClass
- the class of array to create
NullPointerException
- if iterator parameter or arrayClass is null
ClassCastException
- if the arrayClass is invalidpublic static <E> List<E> toList(Iterator<? extends E> iterator)
As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, the list is returned.
E
- the element typeiterator
- the iterator to use, not null
NullPointerException
- if iterator parameter is nullpublic static <E> List<E> toList(Iterator<? extends E> iterator, int estimatedSize)
As the wrapped Iterator is traversed, an ArrayList of its values is created. At the end, the list is returned.
E
- the element typeiterator
- the iterator to use, not nullestimatedSize
- the initial size of the ArrayList
NullPointerException
- if iterator parameter is null
IllegalArgumentException
- if the size is less than 1public static Iterator<?> getIterator(Object obj)
This method can handle objects as follows
obj
- the object to convert to an iterator
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |