|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.google.common.collect.Iterators
public final class Iterators
This class contains static utility methods that operate on or return objects
of type Iterator
. Also see the parallel implementations in Iterables
.
Method Summary | ||
---|---|---|
static
|
addAll(Collection<T> collection,
Iterator<? extends T> iterator)
Adds all elements in iterator to collection . |
|
static
|
all(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns true if every element returned by iterator
satisfies the given predicate. |
|
static
|
any(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns true if one or more elements returned by iterator
satisfy the given predicate. |
|
static
|
asEnumeration(Iterator<T> iterator)
Adapts an Iterator to the Enumeration interface. |
|
static
|
concat(Iterator<? extends Iterator<? extends T>> inputs)
Combines multiple iterators into a single iterator. |
|
static
|
concat(Iterator<? extends T>... inputs)
Combines multiple iterators into a single iterator. |
|
static
|
concat(Iterator<? extends T> a,
Iterator<? extends T> b)
Combines two iterators into a single iterator. |
|
static boolean |
contains(Iterator<?> iterator,
Object element)
Returns true if iterator contains element . |
|
static boolean |
containsNull(Iterator<?> iterator)
Returns true if iterator contains at least one null
element. |
|
static
|
cycle(Iterable<T> iterable)
Returns an iterator that cycles indefinitely over the elements of iterable . |
|
static
|
cycle(T... elements)
Returns an iterator that cycles indefinitely over the provided elements. |
|
static boolean |
elementsEqual(Iterator<?> iterator1,
Iterator<?> iterator2)
Determines whether two iterators contain equal elements in the same order. |
|
static
|
emptyIterator()
Returns the empty Iterator . |
|
static
|
emptyListIterator()
Returns the empty ListIterator . |
|
static
|
filter(Iterator<?> unfiltered,
Class<T> type)
Returns all instances of class type in unfiltered . |
|
static
|
filter(Iterator<T> unfiltered,
Predicate<? super T> predicate)
Returns the elements of unfiltered that satisfy a predicate. |
|
static
|
find(Iterator<E> iterator,
Predicate<? super E> predicate)
Returns the first element in iterator that satisfies the given
predicate. |
|
static
|
forArray(T[] array,
int offset,
int length)
Returns an iterator containing the elements in the specified range of array in order. |
|
static
|
forEnumeration(Enumeration<T> enumeration)
Adapts an Enumeration to the Iterator interface. |
|
static int |
frequency(Iterator<?> iterator,
Object element)
Returns the number of elements in the specified iterator that equal the specified object. |
|
static
|
get(Iterator<T> iterator,
int position)
Advances iterator position + 1 times, returning the element
at the position th position. |
|
static
|
getLast(Iterator<T> iterator)
Advances iterator to the end, returning the last element. |
|
static
|
getOnlyElement(Iterator<T> iterator)
Returns the single element contained in iterator . |
|
static
|
getOnlyElement(Iterator<T> iterator,
T defaultValue)
Returns the single element contained in iterator , or defaultValue if the iterator is empty. |
|
static
|
limit(Iterator<T> iterator,
int limitSize)
Creates an iterator returning the first limitSize elements of the
given iterator. |
|
static
|
newArray(Iterator<? extends T> iterator,
Class<T> type)
Copies an iterator's elements into an array. |
|
static
|
partition(Iterator<? extends T> iterator,
int partitionSize,
boolean padToSize)
Partition an iterator into sub-iterators of the given size. |
|
static
|
peekingIterator(Iterator<? extends T> iterator)
Wraps the supplied iterator in a PeekingIterator . |
|
static boolean |
removeAll(Iterator<?> iterator,
Collection<?> c)
Traverses an iterator and removes every element that belongs to the provided collection. |
|
static boolean |
retainAll(Iterator<?> iterator,
Collection<?> c)
Traverses an iterator and removes every element that does not belong to the provided collection. |
|
static int |
size(Iterator<?> iterator)
Returns the number of elements remaining in iterator . |
|
static
|
skip(Iterator<T> iterator,
int numberToSkip)
Calls next() on iterator , either numberToSkip times
or until hasNext() returns false , whichever comes first. |
|
static String |
toString(Iterator<?> iterator)
Returns a string representation of iterator , with the format
[e1, e2, ..., en] . |
|
static
|
transform(Iterator<F> fromIterator,
Function<? super F,? extends T> function)
Returns an iterator that applies function to each element of fromIterator . |
|
static
|
unmodifiableIterator(Iterator<T> iterator)
Returns an unmodifiable view of iterator . |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
---|
public static <T> Iterator<T> emptyIterator()
Iterator
.
public static <T> ListIterator<T> emptyListIterator()
ListIterator
.
public static <T> Iterator<T> unmodifiableIterator(Iterator<T> iterator)
iterator
.
public static int size(Iterator<?> iterator)
iterator
. The iterator
will be left exhausted: its hasNext()
method will return
false
.
public static boolean contains(Iterator<?> iterator, @Nullable Object element)
true
if iterator
contains element
.
public static boolean containsNull(Iterator<?> iterator)
true
if iterator
contains at least one null
element.
public static boolean removeAll(Iterator<?> iterator, Collection<?> c)
hasNext()
method will return false
.
iterator
- the iterator to (potentially) remove elements fromc
- the elements to remove
true
if any elements are removed from iterator
public static boolean retainAll(Iterator<?> iterator, Collection<?> c)
hasNext()
method will return false
.
iterator
- the iterator to (potentially) remove elements fromc
- the elements to retain
true
if any elements are removed from iterator
public static boolean elementsEqual(Iterator<?> iterator1, Iterator<?> iterator2)
true
if iterator1
and iterator2
contain the same number of elements and every element
of iterator1
is equal to the corresponding element of
iterator2
.
Note that this will modify the supplied iterators, since they will have been advanced some number of elements forward.
public static String toString(Iterator<?> iterator)
iterator
, with the format
[e1, e2, ..., en]
. The iterator will be left exhausted: its
hasNext()
method will return false
.
public static <T> T getOnlyElement(Iterator<T> iterator)
iterator
.
NoSuchElementException
- if the iterator is empty
IllegalArgumentException
- if the iterator contains multiple
elements. The state of the iterator is unspecified.public static <T> T getOnlyElement(Iterator<T> iterator, @Nullable T defaultValue)
iterator
, or defaultValue
if the iterator is empty.
IllegalArgumentException
- if the iterator contains multiple
elements. The state of the iterator is unspecified.public static <T> T[] newArray(Iterator<? extends T> iterator, Class<T> type)
hasNext()
method will return false
.
iterator
- the iterator to copytype
- the type of the elements
public static <T> boolean addAll(Collection<T> collection, Iterator<? extends T> iterator)
iterator
to collection
. The iterator
will be left exhausted: its hasNext()
method will return
false
.
true
if collection
was modified as a result of this
operationpublic static int frequency(Iterator<?> iterator, @Nullable Object element)
hasNext()
method will return false
.
Collections.frequency(java.util.Collection>, java.lang.Object)
public static <T> Iterator<T> cycle(Iterable<T> iterable)
iterable
.
The returned iterator supports remove()
if the provided iterator
does. After remove()
is called, subsequent cycles omit the removed
element, which is no longer in iterable
. The iterator's
hasNext()
method returns true
until iterable
is
empty.
Warning: Typical uses of the resulting iterator may produce an
infinite loop. You should use an explicit break
or be certain that
you will eventually remove all the elements.
public static <T> Iterator<T> cycle(T... elements)
The returned iterator supports remove()
if the provided iterator
does. After remove()
is called, subsequent cycles omit the removed
element, but elements
does not change. The iterator's
hasNext()
method returns true
until all of the original
elements have been removed.
Warning: Typical uses of the resulting iterator may produce an
infinite loop. You should use an explicit break
or be certain that
you will eventually remove all the elements.
public static <T> Iterator<T> concat(Iterator<? extends T> a, Iterator<? extends T> b)
a
, followed by the elements in
b
. The source iterators are not polled until necessary.
The returned iterator supports remove()
when the corresponding
input iterator supports it.
public static <T> Iterator<T> concat(Iterator<? extends T>... inputs)
inputs
. The input
iterators are not polled until necessary.
The returned iterator supports remove()
when the corresponding
input iterator supports it.
NullPointerException
- if any of the provided iterators is nullpublic static <T> Iterator<T> concat(Iterator<? extends Iterator<? extends T>> inputs)
inputs
. The input
iterators are not polled until necessary.
The returned iterator supports remove()
when the corresponding
input iterator supports it. The methods of the returned iterator may throw
NullPointerException
if any of the input iterators are null.
public static <T> Iterator<Iterator<T>> partition(Iterator<? extends T> iterator, int partitionSize, boolean padToSize)
{A, B, C, D, E, F}
with partition size 3 yields
{A, B, C}
and {D, E, F}
. The returned
iterators do not support remove()
.
After next()
is called on the returned iterator, the iterators
from prior next()
calls become invalid.
iterator
- the iterator to partitionpartitionSize
- the size of each partitionpadToSize
- whether to pad the last partition to the partition size
with null
public static <T> Iterator<T> filter(Iterator<T> unfiltered, Predicate<? super T> predicate)
unfiltered
that satisfy a predicate. The
resulting iterator does not support remove()
.
public static <T> Iterator<T> filter(Iterator<?> unfiltered, Class<T> type)
type
in unfiltered
. The
returned iterator has elements whose class is type
or a subclass of
type
. The returned iterator does not support remove()
.
unfiltered
- an iterator containing objects of any typetype
- the type of elements desired
public static <T> boolean any(Iterator<T> iterator, Predicate<? super T> predicate)
true
if one or more elements returned by iterator
satisfy the given predicate.
public static <T> boolean all(Iterator<T> iterator, Predicate<? super T> predicate)
true
if every element returned by iterator
satisfies the given predicate. If iterator
is empty, true
is returned.
public static <E> E find(Iterator<E> iterator, Predicate<? super E> predicate)
iterator
that satisfies the given
predicate. If a matching element is found, the iterator will be left in a
state such that calling iterator.remove()
will remove the found
item. If no such element is found, the iterator will be left exhausted: its
hasNext()
method will return false
.
iterator
NoSuchElementException
- if no element in iterator
matches
the given predicatepublic static <F,T> Iterator<T> transform(Iterator<F> fromIterator, Function<? super F,? extends T> function)
function
to each element of fromIterator
.
The returned iterator supports remove()
if the provided iterator
does. After a successful remove()
call, fromIterator
no
longer contains the corresponding element.
public static <T> T get(Iterator<T> iterator, int position)
iterator
position + 1
times, returning the element
at the position
th position.
position
- position of the element to return
iterator
IndexOutOfBoundsException
- if position
is negative or
greater than or equal to the number of elements remaining in
iterator
public static <T> T getLast(Iterator<T> iterator)
iterator
to the end, returning the last element.
iterator
NoSuchElementException
- if the iterator has no remaining elementspublic static <T> int skip(Iterator<T> iterator, int numberToSkip)
next()
on iterator
, either numberToSkip
times
or until hasNext()
returns false
, whichever comes first.
public static <T> Iterator<T> limit(Iterator<T> iterator, int limitSize)
limitSize
elements of the
given iterator. If the original iterator does not contain that many
elements, the returned iterator will have the same behavior as the original
iterator. The returned iterator supports remove()
if the original
iterator does.
iterator
- the iterator to limitlimitSize
- the maximum number of elements in the returned iterator
IllegalArgumentException
- if limitSize
is negativepublic static <T> Iterator<T> forArray(T[] array, int offset, int length)
array
in order.
array
- array to read elements out ofoffset
- index of first array element to retrieve
IndexOutOfBoundsException
- if offset
is negative,
length
is negative, or offset + length > array.length
public static <T> Iterator<T> forEnumeration(Enumeration<T> enumeration)
Enumeration
to the Iterator
interface. The
returned iterator does not support remove()
.
public static <T> Enumeration<T> asEnumeration(Iterator<T> iterator)
Iterator
to the Enumeration
interface.
Collections.enumeration(Collection)
public static <T> PeekingIterator<T> peekingIterator(Iterator<? extends T> iterator)
PeekingIterator
. The
PeekingIterator
assumes ownership of the supplied iterator, so
users should cease making direct calls to it after calling this method.
If the PeekingIterator.peek()
method of the constructed
PeekingIterator
is never called, the returned iterator will
behave exactly the same as the supplied iterator.
Subsequent calls to peek()
with no intervening calls to
next()
do not affect the iteration, and hence return the same
object each time. After a call to peek()
, the next call to
next()
is guaranteed to return the same object that the
peek()
call returned. For example:
PeekingIterator<E> peekingIterator = ...; // Either the next three calls will each throw // NoSuchElementExceptions, or... E e1 = peekingIterator.peek(); E e2 = peekingIterator.peek(); // e2 is the same as e1 E e3 = peekingIterator.next(); // e3 is the same as e1/e2
Calling Iterator.remove()
after PeekingIterator.peek()
is unsupported by the returned iterator and will throw an
IllegalStateException
.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |