com.aliasi.util
Class Iterators

java.lang.Object
  com.aliasi.util.Iterators

public class Iterators
extends Object

Static utility methods, classes, and abstract classes for iteration.

Since:

LingPipe2.0

Version:

3.8.3

Author:

Bob Carpenter, Mike Ross

Nested Class Summary

static class	Iterators.Array<E> Deprecated. Construct with the static factory method array(Object[]) instead.
static class	Iterators.ArraySlice<E> Deprecated. Use the static factory method arraySlice(Object[],int,int) instead.
static class	Iterators.Buffered<E> An Iterators.Buffered uses a single method to return objects, buffering the result and returning it as the next element if it is non-null.
static class	Iterators.Empty<E> Deprecated. Use the static factory method empty() instead.
static class	Iterators.Filter<E> An Iterators.Filter filters the stream of objects returned by another iterator by subjecting them to an acceptance test.
static class	Iterators.Modifier<E> An Iterator.Modifier uses a single abstract method to operate on the elements returned by an underlying iterator to return modified objects.
static class	Iterators.Pair<E> Deprecated. Use the static factory method pair(Object,Object) instead.
static class	Iterators.PrimitiveInt A Iterators.PrimitiveInt is an integer iterator that also allows objects to be accessed as primitive int values.
static class	Iterators.Sequence<E> Deprecated. Use the static factory method sequence(Iterator,Iterator), sequence(Iterator), or sequence(List) instead.
static class	Iterators.Singleton<E> Deprecated. Use the static factory method singleton(Object) instead.

Method Summary

static <E> Iterator<E>	array(E[] members) Returns an iterator over the specified array of objects.
static <E> Iterator<E>	arraySlice(E[] members, int start, int length) Returns a newly constructed iterator over the specified object array slice.
static <E> Iterator<E>	empty() Returns an iterator that has no elements.
static Iterators.PrimitiveInt	intArray(int[] members) Returns an iterator over the array of primitive integers specified.
static Iterators.PrimitiveInt	intRange(int end) Construct an Integer iterator from 0 (inclusive) the specified end point (exclusive).
static Iterators.PrimitiveInt	intRange(int start, int end) Returns a newly constructed primitive integer iterator that iterates from the start (inclusive) to end (exclusive).
static <E> Iterator<E>	list(E... es) Returns an iterator constructed from the specified variable length argument list of objects.
static <E> Iterator<E>	pair(E e1, E e2) Returns a newly constructed iterator over the specified pair of elements.
static <E> Iterator<E>	sequence(Iterator<? extends E> it1, Iterator<? extends E> it2) Returns an iterator that runs through the first iterator's elements and then runs through the second iterator's elements.
static <E> Iterator<E>	sequence(Iterator<? extends Iterator<? extends E>> iteratorOfIterators)
static <E> Iterator<E>	sequence(List<? extends Iterator<? extends E>> iterators)
static <E> Iterator<E>	singleton(E e) Returns an iterator over the single specified element.
static <E> Iterator<E>	unmodifiable(Iterator<E> it) Returns an unmodifiable view of the specified iterator.

Methods inherited from class java.lang.Object

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

Method Detail

empty

public static <E> Iterator<E> empty()

Returns an iterator that has no elements. Thus hasNext() will always return false and next() will always throw a NoSuchElementException.

Returns:

The empty iterator.

singleton

public static <E> Iterator<E> singleton(E e)

Returns an iterator over the single specified element. Thus next() will return the specified element on the first call, with subsequent calls throwing a NoSuchElementException .

Parameters:

e - The object to return in the iterator.

Returns:

The iterator over the specified object.

pair

public static <E> Iterator<E> pair(E e1,
                                   E e2)

Returns a newly constructed iterator over the specified pair of elements.

Implementation Note: References to the elemenets are removed from iterator after they are returned through next().

Parameters:

e1 - First element returned.

e2 - Second element returned.

Returns:

The iterator over the pair of elements specified.

list

public static <E> Iterator<E> list(E... es)

Returns an iterator constructed from the specified variable length argument list of objects.

Remove is supported, but has no effect on anything as the list from which elements are being deleted is only used for the iterator.

Parameters:

es - Array of objects for iteration.

Returns:

Iterator over list.

unmodifiable

public static <E> Iterator<E> unmodifiable(Iterator<E> it)

Returns an unmodifiable view of the specified iterator. Calls to next() and hasNext() are delegated to the specified iterator as made. Calls to remove() throw unsupported operation exceptions.

Parameters:

it - Iterator to view.

Returns:

Unmodifiable view of specified iterator.

sequence

public static <E> Iterator<E> sequence(Iterator<? extends E> it1,
                                       Iterator<? extends E> it2)

Returns an iterator that runs through the first iterator's elements and then runs through the second iterator's elements.

References to the iterators are freed after it is finished iterating.

Parameters:

it1 - The first iterator in the sequence.

it2 - The second iterator in the sequence.

Returns:

The iterator over the two iterators.

sequence

public static <E> Iterator<E> sequence(List<? extends Iterator<? extends E>> iterators)

sequence

public static <E> Iterator<E> sequence(Iterator<? extends Iterator<? extends E>> iteratorOfIterators)

array

public static <E> Iterator<E> array(E[] members)

Returns an iterator over the specified array of objects.

Warning: The array is not copied, so any changes in the underlying array are reflected in the iterator.

Implementation Note: this class does not automatically free references in the underlying array, because the array may be used elswhere. If reference freeing is critical here, a call to remove() after ever call to next() will free the references in the array.

Parameters:

members - Array of elements over which to iterate.

Returns:

The iterator over the array elements.

arraySlice

public static <E> Iterator<E> arraySlice(E[] members,
                                         int start,
                                         int length)

Returns a newly constructed iterator over the specified object array slice.

The remove() method is not supported.

Warning: The array is not copied, so any changes in the underlying array are reflected in the iterator.

Implementation Note: this class does not automatically free references in the underlying array, because the array may be used elswhere.

Parameters:

members - Array of objects over which to iterate.

start - Index of first object to return.

length - Number of objects to iterate.

Throws:

Illegal - argument exception if start < 0 or start + length > objects.length().

intRange

public static Iterators.PrimitiveInt intRange(int end)

Construct an Integer iterator from 0 (inclusive) the specified end point (exclusive). The returned iterator does not support remove().

Parameters:

end - One plus the last integer returned.

intRange

public static Iterators.PrimitiveInt intRange(int start,
                                              int end)

Returns a newly constructed primitive integer iterator that iterates from the start (inclusive) to end (exclusive).

The returned iterator does not support remove().

Parameters:

start - The first and lowest value to return.

end - One plus the last integer returned.

Throws:

IllegalArgumentException - If start > end.

intArray

public static Iterators.PrimitiveInt intArray(int[] members)

Returns an iterator over the array of primitive integers specified. The result is very much like Iterators.Array, but as a Iterators.PrimitiveInt return for efficient access to the primitive int values.

There are no order restrictions on the array -- its elements may be in any order and may contain duplicates.

The returned iterator does not support remove().

Parameters:

members - Array of members to iterate.