@GwtCompatible(emulated=true) public final class Iterators extends Object
Iterator
. Except as noted, each method has a corresponding
Iterable
-based method in the Iterables
class.
Performance notes: Unless otherwise noted, all of the iterators produced in this class are lazy, which means that they only advance the backing iteration when absolutely necessary.
See the Guava User Guide section on
Iterators
.
Modifier and Type | Method and Description |
---|---|
static <T> boolean |
addAll(Collection<T> addTo,
Iterator<? extends T> iterator)
Adds all elements in
iterator to collection . |
static int |
advance(Iterator<?> iterator,
int numberToAdvance)
Calls
next() on iterator , either numberToAdvance times
or until hasNext() returns false , whichever comes first. |
static <T> boolean |
all(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns
true if every element returned by iterator
satisfies the given predicate. |
static <T> boolean |
any(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns
true if one or more elements returned by iterator
satisfy the given predicate. |
static <T> Enumeration<T> |
asEnumeration(Iterator<T> iterator)
Adapts an
Iterator to the Enumeration interface. |
static <T> Iterator<T> |
concat(Iterator<? extends Iterator<? extends T>> inputs)
Combines multiple iterators into a single iterator.
|
static <T> Iterator<T> |
concat(Iterator<? extends T>... inputs)
Combines multiple iterators into a single iterator.
|
static <T> Iterator<T> |
concat(Iterator<? extends T> a,
Iterator<? extends T> b)
Combines two iterators into a single iterator.
|
static <T> Iterator<T> |
concat(Iterator<? extends T> a,
Iterator<? extends T> b,
Iterator<? extends T> c)
Combines three iterators into a single iterator.
|
static <T> Iterator<T> |
concat(Iterator<? extends T> a,
Iterator<? extends T> b,
Iterator<? extends T> c,
Iterator<? extends T> d)
Combines four iterators into a single iterator.
|
static <T> Iterator<T> |
consumingIterator(Iterator<T> iterator)
Returns a view of the supplied
iterator that removes each element
from the supplied iterator as it is returned. |
static boolean |
contains(Iterator<?> iterator,
Object element)
Returns
true if iterator contains element . |
static <T> Iterator<T> |
cycle(Iterable<T> iterable)
Returns an iterator that cycles indefinitely over the elements of
iterable . |
static <T> Iterator<T> |
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 <T> UnmodifiableIterator<T> |
filter(Iterator<?> unfiltered,
Class<T> desiredType)
Returns a view of
unfiltered containing all elements that are of
the type desiredType . |
static <T> UnmodifiableIterator<T> |
filter(Iterator<T> unfiltered,
Predicate<? super T> retainIfTrue)
Returns a view of
unfiltered containing all elements that satisfy
the input predicate retainIfTrue . |
static <T> T |
find(Iterator<? extends T> iterator,
Predicate<? super T> predicate,
T defaultValue)
Returns the first element in
iterator that satisfies the given
predicate. |
static <T> T |
find(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns the first element in
iterator that satisfies the given
predicate; use this method only when such an element is known to exist. |
static <T> UnmodifiableIterator<T> |
forArray(T... array)
Returns an iterator containing the elements of
array in order. |
static <T> UnmodifiableIterator<T> |
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 <T> T |
get(Iterator<? extends T> iterator,
int position,
T defaultValue)
Advances
iterator position + 1 times, returning the
element at the position th position or defaultValue
otherwise. |
static <T> T |
get(Iterator<T> iterator,
int position)
Advances
iterator position + 1 times, returning the
element at the position th position. |
static <T> T |
getLast(Iterator<? extends T> iterator,
T defaultValue)
Advances
iterator to the end, returning the last element or
defaultValue if the iterator is empty. |
static <T> T |
getLast(Iterator<T> iterator)
Advances
iterator to the end, returning the last element. |
static <T> T |
getNext(Iterator<? extends T> iterator,
T defaultValue)
Returns the next element in
iterator or defaultValue if
the iterator is empty. |
static <T> T |
getOnlyElement(Iterator<? extends T> iterator,
T defaultValue)
Returns the single element contained in
iterator , or defaultValue if the iterator is empty. |
static <T> T |
getOnlyElement(Iterator<T> iterator)
Returns the single element contained in
iterator . |
static <T> int |
indexOf(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns the index in
iterator of the first element that satisfies
the provided predicate , or -1 if the Iterator has no such
elements. |
static <T> Iterator<T> |
limit(Iterator<T> iterator,
int limitSize)
Returns a view containing the first
limitSize elements of iterator . |
static <T> UnmodifiableIterator<T> |
mergeSorted(Iterable<? extends Iterator<? extends T>> iterators,
Comparator<? super T> comparator)
Returns an iterator over the merged contents of all given
iterators , traversing every element of the input iterators. |
static <T> UnmodifiableIterator<List<T>> |
paddedPartition(Iterator<T> iterator,
int size)
Divides an iterator into unmodifiable sublists of the given size, padding
the final iterator with null values if necessary.
|
static <T> UnmodifiableIterator<List<T>> |
partition(Iterator<T> iterator,
int size)
Divides an iterator into unmodifiable sublists of the given size (the final
list may be smaller).
|
static <T> PeekingIterator<T> |
peekingIterator(Iterator<? extends T> iterator)
Returns a
PeekingIterator backed by the given iterator. |
static <T> PeekingIterator<T> |
peekingIterator(PeekingIterator<T> iterator)
Deprecated.
no need to use this
|
static boolean |
removeAll(Iterator<?> removeFrom,
Collection<?> elementsToRemove)
Traverses an iterator and removes every element that belongs to the
provided collection.
|
static <T> boolean |
removeIf(Iterator<T> removeFrom,
Predicate<? super T> predicate)
Removes every element that satisfies the provided predicate from the
iterator.
|
static boolean |
retainAll(Iterator<?> removeFrom,
Collection<?> elementsToRetain)
Traverses an iterator and removes every element that does not belong to the
provided collection.
|
static <T> UnmodifiableIterator<T> |
singletonIterator(T value)
Returns an iterator containing only
value . |
static int |
size(Iterator<?> iterator)
Returns the number of elements remaining in
iterator . |
static <T> T[] |
toArray(Iterator<? extends T> iterator,
Class<T> type)
Copies an iterator's elements into an array.
|
static String |
toString(Iterator<?> iterator)
Returns a string representation of
iterator , with the format
[e1, e2, ..., en] . |
static <F,T> Iterator<T> |
transform(Iterator<F> fromIterator,
Function<? super F,? extends T> function)
Returns a view containing the result of applying
function to each
element of fromIterator . |
static <T> Optional<T> |
tryFind(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns an
Optional containing the first element in iterator that satisfies the given predicate, if such an element exists. |
static <T> UnmodifiableIterator<T> |
unmodifiableIterator(Iterator<? extends T> iterator)
Returns an unmodifiable view of
iterator . |
static <T> UnmodifiableIterator<T> |
unmodifiableIterator(UnmodifiableIterator<T> iterator)
Deprecated.
no need to use this
|
public static <T> UnmodifiableIterator<T> unmodifiableIterator(Iterator<? extends T> iterator)
iterator
.@Deprecated public static <T> UnmodifiableIterator<T> unmodifiableIterator(UnmodifiableIterator<T> 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 removeAll(Iterator<?> removeFrom, Collection<?> elementsToRemove)
hasNext()
method will return false
.removeFrom
- the iterator to (potentially) remove elements fromelementsToRemove
- the elements to removetrue
if any element was removed from iterator
public static <T> boolean removeIf(Iterator<T> removeFrom, Predicate<? super T> predicate)
hasNext()
method will return false
.removeFrom
- the iterator to (potentially) remove elements frompredicate
- a predicate that determines whether an element should
be removedtrue
if any elements were removed from the iteratorpublic static boolean retainAll(Iterator<?> removeFrom, Collection<?> elementsToRetain)
hasNext()
method will return false
.removeFrom
- the iterator to (potentially) remove elements fromelementsToRetain
- the elements to retaintrue
if any element was 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 emptyIllegalArgumentException
- if the iterator contains multiple
elements. The state of the iterator is unspecified.@Nullable public static <T> T getOnlyElement(Iterator<? extends 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.@GwtIncompatible public static <T> T[] toArray(Iterator<? extends T> iterator, Class<T> type)
hasNext()
method will return false
.iterator
- the iterator to copytype
- the type of the elementspublic static <T> boolean addAll(Collection<T> addTo, 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
.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.
@SafeVarargs public static <T> Iterator<T> cycle(T... elements)
The returned iterator supports remove()
. 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> a, Iterator<? extends T> b, Iterator<? extends T> c)
a
, followed by the elements in
b
, followed by the elements in c
. 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> a, Iterator<? extends T> b, Iterator<? extends T> c, Iterator<? extends T> d)
a
, followed by the elements in
b
, followed by the elements in c
, followed by the elements
in d
. 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 is null.
public static <T> UnmodifiableIterator<List<T>> partition(Iterator<T> iterator, int size)
[a, b, c, d, e]
with a partition size of 3 yields [[a, b, c], [d, e]]
-- an outer iterator containing two inner lists of
three and two elements, all in the original order.
The returned lists implement RandomAccess
.
iterator
- the iterator to return a partitioned view ofsize
- the desired size of each partition (the last may be smaller)iterator
divided into partitionsIllegalArgumentException
- if size
is nonpositivepublic static <T> UnmodifiableIterator<List<T>> paddedPartition(Iterator<T> iterator, int size)
[a, b, c, d, e]
with a partition size of 3
yields [[a, b, c], [d, e, null]]
-- an outer iterator containing
two inner lists of three elements each, all in the original order.
The returned lists implement RandomAccess
.
iterator
- the iterator to return a partitioned view ofsize
- the desired size of each partitioniterator
divided into partitions (the final iterable may have
trailing null elements)IllegalArgumentException
- if size
is nonpositivepublic static <T> UnmodifiableIterator<T> filter(Iterator<T> unfiltered, Predicate<? super T> retainIfTrue)
unfiltered
containing all elements that satisfy
the input predicate retainIfTrue
.@GwtIncompatible public static <T> UnmodifiableIterator<T> filter(Iterator<?> unfiltered, Class<T> desiredType)
unfiltered
containing all elements that are of
the type desiredType
.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 <T> T find(Iterator<T> iterator, Predicate<? super T> predicate)
iterator
that satisfies the given
predicate; use this method only when such an element is known to exist. If
no such element is found, the iterator will be left exhausted: its hasNext()
method will return false
. If it is possible that
no element will match, use tryFind(java.util.Iterator<T>, com.google.common.base.Predicate<? super T>)
or find(Iterator, Predicate, Object)
instead.NoSuchElementException
- if no element in iterator
matches
the given predicate@Nullable public static <T> T find(Iterator<? extends T> iterator, Predicate<? super T> predicate, @Nullable T defaultValue)
iterator
that satisfies the given
predicate. If no such element is found, defaultValue
will be
returned from this method and the iterator will be left exhausted: its
hasNext()
method will return false
. Note that this can
usually be handled more naturally using tryFind(iterator, predicate).or(defaultValue)
.public static <T> Optional<T> tryFind(Iterator<T> iterator, Predicate<? super T> predicate)
Optional
containing the first element in iterator
that satisfies the given predicate, if such an element exists. If
no such element is found, an empty Optional
will be returned from
this method and the iterator will be left exhausted: its hasNext()
method will return false
.
Warning: avoid using a predicate
that matches null
. If null
is matched in iterator
, a
NullPointerException will be thrown.
public static <T> int indexOf(Iterator<T> iterator, Predicate<? super T> predicate)
iterator
of the first element that satisfies
the provided predicate
, or -1
if the Iterator has no such
elements.
More formally, returns the lowest index i
such that
predicate.apply(Iterators.get(iterator, i))
returns true
,
or -1
if there is no such index.
If -1 is returned, the iterator will be left exhausted: its
hasNext()
method will return false
. Otherwise,
the iterator will be set to the element which satisfies the
predicate
.
public 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 fromIterator
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 returniterator
IndexOutOfBoundsException
- if position
is negative or
greater than or equal to the number of elements remaining in
iterator
@Nullable public static <T> T get(Iterator<? extends T> iterator, int position, @Nullable T defaultValue)
iterator
position + 1
times, returning the
element at the position
th position or defaultValue
otherwise.position
- position of the element to returndefaultValue
- the default value to return if the iterator is empty
or if position
is greater than the number of elements
remaining in iterator
iterator
or
defaultValue
if iterator
produces fewer than
position + 1
elements.IndexOutOfBoundsException
- if position
is negative@Nullable public static <T> T getNext(Iterator<? extends T> iterator, @Nullable T defaultValue)
iterator
or defaultValue
if
the iterator is empty. The Iterables
analog to this method is
Iterables.getFirst(java.lang.Iterable<? extends T>, T)
.defaultValue
- the default value to return if the iterator is emptyiterator
or the default valuepublic static <T> T getLast(Iterator<T> iterator)
iterator
to the end, returning the last element.iterator
NoSuchElementException
- if the iterator is empty@Nullable public static <T> T getLast(Iterator<? extends T> iterator, @Nullable T defaultValue)
iterator
to the end, returning the last element or
defaultValue
if the iterator is empty.defaultValue
- the default value to return if the iterator is emptyiterator
public static int advance(Iterator<?> iterator, int numberToAdvance)
next()
on iterator
, either numberToAdvance
times
or until hasNext()
returns false
, whichever comes first.Iterators.skip
)public static <T> Iterator<T> limit(Iterator<T> iterator, int limitSize)
limitSize
elements of iterator
. If iterator
contains fewer than limitSize
elements, the returned view contains all of its elements. The returned
iterator supports remove()
if iterator
does.iterator
- the iterator to limitlimitSize
- the maximum number of elements in the returned iteratorIllegalArgumentException
- if limitSize
is negativepublic static <T> Iterator<T> consumingIterator(Iterator<T> iterator)
iterator
that removes each element
from the supplied iterator
as it is returned.
The provided iterator must support Iterator.remove()
or
else the returned iterator will fail on the first call to next
.
iterator
- the iterator to remove and return elements from@SafeVarargs public static <T> UnmodifiableIterator<T> forArray(T... array)
array
in order. The
returned iterator is a view of the array; subsequent changes to the array
will be reflected in the iterator.
Note: It is often preferable to represent your data using a
collection type, for example using Arrays.asList(Object[])
, making
this method unnecessary.
The Iterable
equivalent of this method is either Arrays.asList(Object[])
, ImmutableList.copyOf(Object[])
},
or ImmutableList.of()
.
public static <T> UnmodifiableIterator<T> singletonIterator(@Nullable T value)
value
.
The Iterable
equivalent of this method is Collections.singleton(T)
.
public static <T> UnmodifiableIterator<T> forEnumeration(Enumeration<T> enumeration)
Enumeration
to the Iterator
interface.
This method has no equivalent in Iterables
because viewing an
Enumeration
as an Iterable
is impossible. However, the
contents can be copied into a collection using Collections.list(java.util.Enumeration<T>)
.
public static <T> Enumeration<T> asEnumeration(Iterator<T> iterator)
Iterator
to the Enumeration
interface.
The Iterable
equivalent of this method is either Collections.enumeration(java.util.Collection<T>)
(if you have a Collection
), or
Iterators.asEnumeration(collection.iterator())
.
public static <T> PeekingIterator<T> peekingIterator(Iterator<? extends T> iterator)
PeekingIterator
backed by the given iterator.
Calls to the peek
method with no intervening calls to next
do not affect the iteration, and hence return the same object each
time. A subsequent call to next
is guaranteed to return the same
object again. For example:
PeekingIterator<String> peekingIterator =
Iterators.peekingIterator(Iterators.forArray("a", "b"));
String a1 = peekingIterator.peek(); // returns "a"
String a2 = peekingIterator.peek(); // also returns "a"
String a3 = peekingIterator.next(); // also returns "a"
Any structural changes to the underlying iteration (aside from those
performed by the iterator's own PeekingIterator.remove()
method)
will leave the iterator in an undefined state.
The returned iterator does not support removal after peeking, as
explained by PeekingIterator.remove()
.
Note: If the given iterator is already a PeekingIterator
,
it might be returned to the caller, although this is neither
guaranteed to occur nor required to be consistent. For example, this
method might choose to pass through recognized implementations of
PeekingIterator
when the behavior of the implementation is
known to meet the contract guaranteed by this method.
There is no Iterable
equivalent to this method, so use this
method to wrap each individual iterator as it is generated.
iterator
- the backing iterator. The PeekingIterator
assumes
ownership of this iterator, so users should cease making direct calls
to it after calling this method.PeekingIterator.peek()
method, this iterator behaves
exactly the same as iterator
.@Deprecated public static <T> PeekingIterator<T> peekingIterator(PeekingIterator<T> iterator)
@Beta public static <T> UnmodifiableIterator<T> mergeSorted(Iterable<? extends Iterator<? extends T>> iterators, Comparator<? super T> comparator)
iterators
, traversing every element of the input iterators.
Equivalent entries will not be de-duplicated.
Callers must ensure that the source iterators
are in
non-descending order as this method does not sort its input.
For any equivalent elements across all iterators
, it is
undefined which element is returned first.
Copyright © 2010-2017. All Rights Reserved.