Class Iterators
- java.lang.Object
-
- com.google.common.collect.Iterators
-
@GwtCompatible(emulated=true) public final class Iterators extends Object
This class contains static utility methods that operate on or return objects of typeIterator
. Except as noted, each method has a correspondingIterable
-based method in theIterables
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
.- Since:
- 2.0
- Author:
- Kevin Bourrillion, Jared Levy
-
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static <T extends @Nullable Object>
booleanaddAll(Collection<T> addTo, Iterator<? extends T> iterator)
Adds all elements initerator
tocollection
.static int
advance(Iterator<?> iterator, int numberToAdvance)
Callsnext()
oniterator
, eithernumberToAdvance
times or untilhasNext()
returnsfalse
, whichever comes first.static <T extends @Nullable Object>
booleanall(Iterator<T> iterator, Predicate<? super T> predicate)
Returnstrue
if every element returned byiterator
satisfies the given predicate.static <T extends @Nullable Object>
booleanany(Iterator<T> iterator, Predicate<? super T> predicate)
Returnstrue
if one or more elements returned byiterator
satisfy the given predicate.static <T extends @Nullable Object>
Enumeration<T>asEnumeration(Iterator<T> iterator)
Adapts anIterator
to theEnumeration
interface.static <T extends @Nullable Object>
Iterator<T>concat(Iterator<? extends Iterator<? extends T>> inputs)
Combines multiple iterators into a single iterator.static <T extends @Nullable Object>
Iterator<T>concat(Iterator<? extends T>... inputs)
Combines multiple iterators into a single iterator.static <T extends @Nullable Object>
Iterator<T>concat(Iterator<? extends T> a, Iterator<? extends T> b)
Combines two iterators into a single iterator.static <T extends @Nullable Object>
Iterator<T>concat(Iterator<? extends T> a, Iterator<? extends T> b, Iterator<? extends T> c)
Combines three iterators into a single iterator.static <T extends @Nullable Object>
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 extends @Nullable Object>
Iterator<T>consumingIterator(Iterator<T> iterator)
Returns a view of the suppliediterator
that removes each element from the suppliediterator
as it is returned.static boolean
contains(Iterator<?> iterator, Object element)
Returnstrue
ifiterator
containselement
.static <T extends @Nullable Object>
Iterator<T>cycle(Iterable<T> iterable)
Returns an iterator that cycles indefinitely over the elements ofiterable
.static <T extends @Nullable Object>
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 ofunfiltered
containing all elements that are of the typedesiredType
.static <T extends @Nullable Object>
UnmodifiableIterator<T>filter(Iterator<T> unfiltered, Predicate<? super T> retainIfTrue)
Returns a view ofunfiltered
containing all elements that satisfy the input predicateretainIfTrue
.static <T extends @Nullable Object>
Tfind(Iterator<? extends T> iterator, Predicate<? super T> predicate, T defaultValue)
Returns the first element initerator
that satisfies the given predicate.static <T extends @Nullable Object>
Tfind(Iterator<T> iterator, Predicate<? super T> predicate)
Returns the first element initerator
that satisfies the given predicate; use this method only when such an element is known to exist.static <T extends @Nullable Object>
UnmodifiableIterator<T>forArray(T... array)
Returns an iterator containing the elements ofarray
in order.static <T extends @Nullable Object>
UnmodifiableIterator<T>forEnumeration(Enumeration<T> enumeration)
Adapts anEnumeration
to theIterator
interface.static int
frequency(Iterator<?> iterator, Object element)
Returns the number of elements in the specified iterator that equal the specified object.static <T extends @Nullable Object>
Tget(Iterator<? extends T> iterator, int position, T defaultValue)
Advancesiterator
position + 1
times, returning the element at theposition
th position ordefaultValue
otherwise.static <T extends @Nullable Object>
Tget(Iterator<T> iterator, int position)
Advancesiterator
position + 1
times, returning the element at theposition
th position.static <T extends @Nullable Object>
TgetLast(Iterator<? extends T> iterator, T defaultValue)
Advancesiterator
to the end, returning the last element ordefaultValue
if the iterator is empty.static <T extends @Nullable Object>
TgetLast(Iterator<T> iterator)
Advancesiterator
to the end, returning the last element.static <T extends @Nullable Object>
TgetNext(Iterator<? extends T> iterator, T defaultValue)
Returns the next element initerator
ordefaultValue
if the iterator is empty.static <T extends @Nullable Object>
TgetOnlyElement(Iterator<? extends T> iterator, T defaultValue)
Returns the single element contained initerator
, ordefaultValue
if the iterator is empty.static <T extends @Nullable Object>
TgetOnlyElement(Iterator<T> iterator)
Returns the single element contained initerator
.static <T extends @Nullable Object>
intindexOf(Iterator<T> iterator, Predicate<? super T> predicate)
Returns the index initerator
of the first element that satisfies the providedpredicate
, or-1
if the Iterator has no such elements.static <T extends @Nullable Object>
Iterator<T>limit(Iterator<T> iterator, int limitSize)
Returns a view containing the firstlimitSize
elements ofiterator
.static <T extends @Nullable Object>
UnmodifiableIterator<T>mergeSorted(Iterable<? extends Iterator<? extends T>> iterators, Comparator<? super T> comparator)
Returns an iterator over the merged contents of all giveniterators
, traversing every element of the input iterators.static <T extends @Nullable Object>
UnmodifiableIterator<List<@Nullable 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 extends @Nullable Object>
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 extends @Nullable Object>
PeekingIterator<T>peekingIterator(PeekingIterator<T> iterator)
Deprecated.no need to use thisstatic <T extends @Nullable Object>
PeekingIterator<T>peekingIterator(Iterator<? extends T> iterator)
Returns aPeekingIterator
backed by the given iterator.static boolean
removeAll(Iterator<?> removeFrom, Collection<?> elementsToRemove)
Traverses an iterator and removes every element that belongs to the provided collection.static <T extends @Nullable Object>
booleanremoveIf(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 extends @Nullable Object>
UnmodifiableIterator<T>singletonIterator(T value)
Returns an iterator containing onlyvalue
.static int
size(Iterator<?> iterator)
Returns the number of elements remaining initerator
.static <T> @Nullable T[]
toArray(Iterator<? extends @Nullable T> iterator, Class<T> type)
Copies an iterator's elements into an array.static String
toString(Iterator<?> iterator)
Returns a string representation ofiterator
, with the format[e1, e2, ..., en]
.static <F extends @Nullable Object,T extends @Nullable Object>
Iterator<T>transform(Iterator<F> fromIterator, Function<? super F,? extends T> function)
Returns a view containing the result of applyingfunction
to each element offromIterator
.static <T> Optional<T>
tryFind(Iterator<T> iterator, Predicate<? super T> predicate)
Returns anOptional
containing the first element initerator
that satisfies the given predicate, if such an element exists.static <T extends @Nullable Object>
UnmodifiableIterator<T>unmodifiableIterator(UnmodifiableIterator<T> iterator)
Deprecated.no need to use thisstatic <T extends @Nullable Object>
UnmodifiableIterator<T>unmodifiableIterator(Iterator<? extends T> iterator)
Returns an unmodifiable view ofiterator
.
-
-
-
Method Detail
-
unmodifiableIterator
public static <T extends @Nullable Object> UnmodifiableIterator<T> unmodifiableIterator(Iterator<? extends T> iterator)
Returns an unmodifiable view ofiterator
.
-
unmodifiableIterator
@Deprecated public static <T extends @Nullable Object> UnmodifiableIterator<T> unmodifiableIterator(UnmodifiableIterator<T> iterator)
Deprecated.no need to use thisSimply returns its argument.- Since:
- 10.0
-
size
public static int size(Iterator<?> iterator)
Returns the number of elements remaining initerator
. The iterator will be left exhausted: itshasNext()
method will returnfalse
.
-
contains
public static boolean contains(Iterator<?> iterator, @CheckForNull Object element)
Returnstrue
ifiterator
containselement
.
-
removeAll
@CanIgnoreReturnValue public static boolean removeAll(Iterator<?> removeFrom, Collection<?> elementsToRemove)
Traverses an iterator and removes every element that belongs to the provided collection. The iterator will be left exhausted: itshasNext()
method will returnfalse
.- Parameters:
removeFrom
- the iterator to (potentially) remove elements fromelementsToRemove
- the elements to remove- Returns:
true
if any element was removed fromiterator
-
removeIf
@CanIgnoreReturnValue public static <T extends @Nullable Object> boolean removeIf(Iterator<T> removeFrom, Predicate<? super T> predicate)
Removes every element that satisfies the provided predicate from the iterator. The iterator will be left exhausted: itshasNext()
method will returnfalse
.- Parameters:
removeFrom
- the iterator to (potentially) remove elements frompredicate
- a predicate that determines whether an element should be removed- Returns:
true
if any elements were removed from the iterator- Since:
- 2.0
-
retainAll
@CanIgnoreReturnValue public static boolean retainAll(Iterator<?> removeFrom, Collection<?> elementsToRetain)
Traverses an iterator and removes every element that does not belong to the provided collection. The iterator will be left exhausted: itshasNext()
method will returnfalse
.- Parameters:
removeFrom
- the iterator to (potentially) remove elements fromelementsToRetain
- the elements to retain- Returns:
true
if any element was removed fromiterator
-
elementsEqual
public static boolean elementsEqual(Iterator<?> iterator1, Iterator<?> iterator2)
Determines whether two iterators contain equal elements in the same order. More specifically, this method returnstrue
ifiterator1
anditerator2
contain the same number of elements and every element ofiterator1
is equal to the corresponding element ofiterator2
.Note that this will modify the supplied iterators, since they will have been advanced some number of elements forward.
-
toString
public static String toString(Iterator<?> iterator)
Returns a string representation ofiterator
, with the format[e1, e2, ..., en]
. The iterator will be left exhausted: itshasNext()
method will returnfalse
.
-
getOnlyElement
public static <T extends @Nullable Object> T getOnlyElement(Iterator<T> iterator)
Returns the single element contained initerator
.- Throws:
NoSuchElementException
- if the iterator is emptyIllegalArgumentException
- if the iterator contains multiple elements. The state of the iterator is unspecified.
-
getOnlyElement
public static <T extends @Nullable Object> T getOnlyElement(Iterator<? extends T> iterator, T defaultValue)
Returns the single element contained initerator
, ordefaultValue
if the iterator is empty.- Throws:
IllegalArgumentException
- if the iterator contains multiple elements. The state of the iterator is unspecified.
-
toArray
@GwtIncompatible public static <T> @Nullable T[] toArray(Iterator<? extends @Nullable T> iterator, Class<T> type)
Copies an iterator's elements into an array. The iterator will be left exhausted: itshasNext()
method will returnfalse
.- Parameters:
iterator
- the iterator to copytype
- the type of the elements- Returns:
- a newly-allocated array into which all the elements of the iterator have been copied
-
addAll
@CanIgnoreReturnValue public static <T extends @Nullable Object> boolean addAll(Collection<T> addTo, Iterator<? extends T> iterator)
Adds all elements initerator
tocollection
. The iterator will be left exhausted: itshasNext()
method will returnfalse
.- Returns:
true
ifcollection
was modified as a result of this operation
-
frequency
public static int frequency(Iterator<?> iterator, @CheckForNull Object element)
Returns the number of elements in the specified iterator that equal the specified object. The iterator will be left exhausted: itshasNext()
method will returnfalse
.
-
cycle
public static <T extends @Nullable Object> Iterator<T> cycle(Iterable<T> iterable)
Returns an iterator that cycles indefinitely over the elements ofiterable
.The returned iterator supports
remove()
if the provided iterator does. Afterremove()
is called, subsequent cycles omit the removed element, which is no longer initerable
. The iterator'shasNext()
method returnstrue
untiliterable
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.
-
cycle
@SafeVarargs public static <T extends @Nullable Object> Iterator<T> cycle(T... elements)
Returns an iterator that cycles indefinitely over the provided elements.The returned iterator supports
remove()
. Afterremove()
is called, subsequent cycles omit the removed element, butelements
does not change. The iterator'shasNext()
method returnstrue
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.
-
concat
public static <T extends @Nullable Object> Iterator<T> concat(Iterator<? extends T> a, Iterator<? extends T> b)
Combines two iterators into a single iterator. The returned iterator iterates across the elements ina
, followed by the elements inb
. The source iterators are not polled until necessary.The returned iterator supports
remove()
when the corresponding input iterator supports it.
-
concat
public static <T extends @Nullable Object> Iterator<T> concat(Iterator<? extends T> a, Iterator<? extends T> b, Iterator<? extends T> c)
Combines three iterators into a single iterator. The returned iterator iterates across the elements ina
, followed by the elements inb
, followed by the elements inc
. The source iterators are not polled until necessary.The returned iterator supports
remove()
when the corresponding input iterator supports it.
-
concat
public static <T extends @Nullable Object> 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. The returned iterator iterates across the elements ina
, followed by the elements inb
, followed by the elements inc
, followed by the elements ind
. The source iterators are not polled until necessary.The returned iterator supports
remove()
when the corresponding input iterator supports it.
-
concat
public static <T extends @Nullable Object> Iterator<T> concat(Iterator<? extends T>... inputs)
Combines multiple iterators into a single iterator. The returned iterator iterates across the elements of each iterator ininputs
. The input iterators are not polled until necessary.The returned iterator supports
remove()
when the corresponding input iterator supports it.- Throws:
NullPointerException
- if any of the provided iterators is null
-
concat
public static <T extends @Nullable Object> Iterator<T> concat(Iterator<? extends Iterator<? extends T>> inputs)
Combines multiple iterators into a single iterator. The returned iterator iterates across the elements of each iterator ininputs
. 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 throwNullPointerException
if any of the input iterators is null.
-
partition
public static <T extends @Nullable Object> 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). For example, partitioning an iterator containing[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
.- Parameters:
iterator
- the iterator to return a partitioned view ofsize
- the desired size of each partition (the last may be smaller)- Returns:
- an iterator of immutable lists containing the elements of
iterator
divided into partitions - Throws:
IllegalArgumentException
- ifsize
is nonpositive
-
paddedPartition
public static <T extends @Nullable Object> UnmodifiableIterator<List<@Nullable 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. For example, partitioning an iterator containing[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
.- Parameters:
iterator
- the iterator to return a partitioned view ofsize
- the desired size of each partition- Returns:
- an iterator of immutable lists containing the elements of
iterator
divided into partitions (the final iterable may have trailing null elements) - Throws:
IllegalArgumentException
- ifsize
is nonpositive
-
filter
public static <T extends @Nullable Object> UnmodifiableIterator<T> filter(Iterator<T> unfiltered, Predicate<? super T> retainIfTrue)
Returns a view ofunfiltered
containing all elements that satisfy the input predicateretainIfTrue
.
-
filter
@GwtIncompatible public static <T> UnmodifiableIterator<T> filter(Iterator<?> unfiltered, Class<T> desiredType)
Returns a view ofunfiltered
containing all elements that are of the typedesiredType
.
-
any
public static <T extends @Nullable Object> boolean any(Iterator<T> iterator, Predicate<? super T> predicate)
Returnstrue
if one or more elements returned byiterator
satisfy the given predicate.
-
all
public static <T extends @Nullable Object> boolean all(Iterator<T> iterator, Predicate<? super T> predicate)
Returnstrue
if every element returned byiterator
satisfies the given predicate. Ifiterator
is empty,true
is returned.
-
find
public static <T extends @Nullable Object> T find(Iterator<T> iterator, Predicate<? super T> predicate)
Returns the first element initerator
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: itshasNext()
method will returnfalse
. If it is possible that no element will match, usetryFind(java.util.Iterator<T>, com.google.common.base.Predicate<? super T>)
orfind(Iterator, Predicate, Object)
instead.- Throws:
NoSuchElementException
- if no element initerator
matches the given predicate
-
find
@CheckForNull public static <T extends @Nullable Object> T find(Iterator<? extends T> iterator, Predicate<? super T> predicate, @CheckForNull T defaultValue)
Returns the first element initerator
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: itshasNext()
method will returnfalse
. Note that this can usually be handled more naturally usingtryFind(iterator, predicate).or(defaultValue)
.- Since:
- 7.0
-
tryFind
public static <T> Optional<T> tryFind(Iterator<T> iterator, Predicate<? super T> predicate)
Returns anOptional
containing the first element initerator
that satisfies the given predicate, if such an element exists. If no such element is found, an emptyOptional
will be returned from this method and the iterator will be left exhausted: itshasNext()
method will returnfalse
.Warning: avoid using a
predicate
that matchesnull
. Ifnull
is matched initerator
, a NullPointerException will be thrown.- Since:
- 11.0
-
indexOf
public static <T extends @Nullable Object> int indexOf(Iterator<T> iterator, Predicate<? super T> predicate)
Returns the index initerator
of the first element that satisfies the providedpredicate
, or-1
if the Iterator has no such elements.More formally, returns the lowest index
i
such thatpredicate.apply(Iterators.get(iterator, i))
returnstrue
, or-1
if there is no such index.If -1 is returned, the iterator will be left exhausted: its
hasNext()
method will returnfalse
. Otherwise, the iterator will be set to the element which satisfies thepredicate
.- Since:
- 2.0
-
transform
public static <F extends @Nullable Object,T extends @Nullable Object> Iterator<T> transform(Iterator<F> fromIterator, Function<? super F,? extends T> function)
Returns a view containing the result of applyingfunction
to each element offromIterator
.The returned iterator supports
remove()
iffromIterator
does. After a successfulremove()
call,fromIterator
no longer contains the corresponding element.
-
get
public static <T extends @Nullable Object> T get(Iterator<T> iterator, int position)
Advancesiterator
position + 1
times, returning the element at theposition
th position.- Parameters:
position
- position of the element to return- Returns:
- the element at the specified position in
iterator
- Throws:
IndexOutOfBoundsException
- ifposition
is negative or greater than or equal to the number of elements remaining initerator
-
get
public static <T extends @Nullable Object> T get(Iterator<? extends T> iterator, int position, T defaultValue)
Advancesiterator
position + 1
times, returning the element at theposition
th position ordefaultValue
otherwise.- Parameters:
position
- position of the element to returndefaultValue
- the default value to return if the iterator is empty or ifposition
is greater than the number of elements remaining initerator
- Returns:
- the element at the specified position in
iterator
ordefaultValue
ifiterator
produces fewer thanposition + 1
elements. - Throws:
IndexOutOfBoundsException
- ifposition
is negative- Since:
- 4.0
-
getNext
public static <T extends @Nullable Object> T getNext(Iterator<? extends T> iterator, T defaultValue)
Returns the next element initerator
ordefaultValue
if the iterator is empty. TheIterables
analog to this method isIterables.getFirst(java.lang.Iterable<? extends T>, T)
.- Parameters:
defaultValue
- the default value to return if the iterator is empty- Returns:
- the next element of
iterator
or the default value - Since:
- 7.0
-
getLast
public static <T extends @Nullable Object> T getLast(Iterator<T> iterator)
Advancesiterator
to the end, returning the last element.- Returns:
- the last element of
iterator
- Throws:
NoSuchElementException
- if the iterator is empty
-
getLast
public static <T extends @Nullable Object> T getLast(Iterator<? extends T> iterator, T defaultValue)
Advancesiterator
to the end, returning the last element ordefaultValue
if the iterator is empty.- Parameters:
defaultValue
- the default value to return if the iterator is empty- Returns:
- the last element of
iterator
- Since:
- 3.0
-
advance
@CanIgnoreReturnValue public static int advance(Iterator<?> iterator, int numberToAdvance)
Callsnext()
oniterator
, eithernumberToAdvance
times or untilhasNext()
returnsfalse
, whichever comes first.- Returns:
- the number of elements the iterator was advanced
- Since:
- 13.0 (since 3.0 as
Iterators.skip
)
-
limit
public static <T extends @Nullable Object> Iterator<T> limit(Iterator<T> iterator, int limitSize)
Returns a view containing the firstlimitSize
elements ofiterator
. Ifiterator
contains fewer thanlimitSize
elements, the returned view contains all of its elements. The returned iterator supportsremove()
ifiterator
does.- Parameters:
iterator
- the iterator to limitlimitSize
- the maximum number of elements in the returned iterator- Throws:
IllegalArgumentException
- iflimitSize
is negative- Since:
- 3.0
-
consumingIterator
public static <T extends @Nullable Object> Iterator<T> consumingIterator(Iterator<T> iterator)
Returns a view of the suppliediterator
that removes each element from the suppliediterator
as it is returned.The provided iterator must support
Iterator.remove()
or else the returned iterator will fail on the first call tonext
.- Parameters:
iterator
- the iterator to remove and return elements from- Returns:
- an iterator that removes and returns elements from the supplied iterator
- Since:
- 2.0
-
forArray
@SafeVarargs public static <T extends @Nullable Object> UnmodifiableIterator<T> forArray(T... array)
Returns an iterator containing the elements ofarray
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 eitherArrays.asList(Object[])
,ImmutableList.copyOf(Object[])
}, orImmutableList.of()
.
-
singletonIterator
public static <T extends @Nullable Object> UnmodifiableIterator<T> singletonIterator(T value)
Returns an iterator containing onlyvalue
.The
Iterable
equivalent of this method isCollections.singleton(T)
.
-
forEnumeration
public static <T extends @Nullable Object> UnmodifiableIterator<T> forEnumeration(Enumeration<T> enumeration)
Adapts anEnumeration
to theIterator
interface.This method has no equivalent in
Iterables
because viewing anEnumeration
as anIterable
is impossible. However, the contents can be copied into a collection usingCollections.list(java.util.Enumeration<T>)
.Java 9 users: use
enumeration.asIterator()
instead, unless it is important to return anUnmodifiableIterator
instead of a plainIterator
.
-
asEnumeration
public static <T extends @Nullable Object> Enumeration<T> asEnumeration(Iterator<T> iterator)
Adapts anIterator
to theEnumeration
interface.The
Iterable
equivalent of this method is eitherCollections.enumeration(java.util.Collection<T>)
(if you have aCollection
), orIterators.asEnumeration(collection.iterator())
.
-
peekingIterator
public static <T extends @Nullable Object> PeekingIterator<T> peekingIterator(Iterator<? extends T> iterator)
Returns aPeekingIterator
backed by the given iterator.Calls to the
peek
method with no intervening calls tonext
do not affect the iteration, and hence return the same object each time. A subsequent call tonext
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 ofPeekingIterator
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.- Parameters:
iterator
- the backing iterator. ThePeekingIterator
assumes ownership of this iterator, so users should cease making direct calls to it after calling this method.- Returns:
- a peeking iterator backed by that iterator. Apart from the additional
PeekingIterator.peek()
method, this iterator behaves exactly the same asiterator
.
-
peekingIterator
@Deprecated public static <T extends @Nullable Object> PeekingIterator<T> peekingIterator(PeekingIterator<T> iterator)
Deprecated.no need to use thisSimply returns its argument.- Since:
- 10.0
-
mergeSorted
@Beta public static <T extends @Nullable Object> UnmodifiableIterator<T> mergeSorted(Iterable<? extends Iterator<? extends T>> iterators, Comparator<? super T> comparator)
Returns an iterator over the merged contents of all giveniterators
, 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.- Since:
- 11.0
-
-