IteratorUtils (Jakarta Commons Collections Package)

Overview

Package

Class

Index

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.commons.collections
Class IteratorUtils

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

public class IteratorUtils
extends 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 2002/10/12 22:15:18 scolebourne Exp $
Author:: Stephen Colebourne

Field Summary

static Iterator EMPTY_ITERATOR
          An iterator over no elements

static ListIterator EMPTY_LIST_ITERATOR
          A list iterator over no elements

Method Summary

static Iterator arrayIterator(Object[] array)
          Gets an iterator over an array.

static Iterator arrayIterator(Object[] array, int start)
          Gets an iterator over the end part of an array.

static Iterator arrayIterator(Object[] array, int start, int end)
          Gets an iterator over part of an 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(Collection iterators)
          Gets an iterator that iterates through a collections of 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(Iterator iterator1, Iterator iterator2)
          Gets an iterator that iterates through two Iterators one after another.

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 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, Iterator iterator1, Iterator iterator2)
          Gets an iterator that provides an ordered iteration over the elements contained in a collection of ordered Iterators.

static Iterator emptyIterator()
          Gets an empty iterator.

static ListIterator emptyListIterator()
          Gets an empty list 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 Iterator 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.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_ITERATOR

public static final Iterator EMPTY_ITERATOR

An iterator over no elements

EMPTY_LIST_ITERATOR

public static final ListIterator EMPTY_LIST_ITERATOR

A list iterator over no elements

Method Detail

arrayIterator

public static Iterator arrayIterator(Object[] array)

Gets an iterator over an array.

Parameters:: array - the array over which to iterate
Returns:: an iterator over the array
Throws:: NullPointerException - if array is null

arrayIterator

public static Iterator arrayIterator(Object[] array,
                                     int 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:: IllegalArgumentException - if array bounds are invalid; NullPointerException - if array is null

arrayIterator

public static Iterator arrayIterator(Object[] array,
                                     int start,
                                     int 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:: IllegalArgumentException - if array bounds are invalid; 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
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

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

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

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

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

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,
                                        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

emptyIterator

public static Iterator 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 ListIterator 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

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

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

singletonIterator

public static Iterator 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)

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

Overview

Package

Class

Index

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Field Summary
`static Iterator`	`EMPTY_ITERATOR` An iterator over no elements
`static ListIterator`	`EMPTY_LIST_ITERATOR` A list iterator over no elements

Method Summary
`static Iterator`	`arrayIterator(Object[] array)` Gets an iterator over an array.
`static Iterator`	`arrayIterator(Object[] array, int start)` Gets an iterator over the end part of an array.
`static Iterator`	`arrayIterator(Object[] array, int start, int end)` Gets an iterator over part of an 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(Collection iterators)` Gets an iterator that iterates through a collections of `Iterator`s one after another.
`static Iterator`	`chainedIterator(Iterator[] iterators)` Gets an iterator that iterates through an array of `Iterator`s one after another.
`static Iterator`	`chainedIterator(Iterator iterator1, Iterator iterator2)` Gets an iterator that iterates through two `Iterator`s one after another.
`static Iterator`	`collatedIterator(Comparator comparator, Collection iterators)` Gets an iterator that provides an ordered iteration over the elements contained in a collection of `Iterator`s.
`static Iterator`	`collatedIterator(Comparator comparator, Iterator[] iterators)` Gets an iterator that provides an ordered iteration over the elements contained in an array of `Iterator`s.
`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 `Iterator`s.
`static Iterator`	`emptyIterator()` Gets an empty iterator.
`static ListIterator`	`emptyListIterator()` Gets an empty list 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 Iterator`	`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.

org.apache.commons.collections Class IteratorUtils

EMPTY_ITERATOR

EMPTY_LIST_ITERATOR

arrayIterator

arrayIterator

arrayIterator

asEnumeration

asIterator

asIterator

chainedIterator

chainedIterator

chainedIterator

collatedIterator

collatedIterator

collatedIterator

emptyIterator

emptyListIterator

filteredIterator

filteredListIterator

getIterator

singletonIterator

singletonListIterator

toArray

toArray

toList

toList

toListIterator

transformedIterator

org.apache.commons.collections
Class IteratorUtils