java.lang.Object
- com.google.common.collect.Iterators

```
@GwtCompatible(emulated=true)
public final class Iterators
extends java.lang.Object
```
This class contains static utility methods that operate on or return objects of type 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.

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 java.lang.Object> boolean`	`addAll(java.util.Collection<T> addTo, java.util.Iterator<? extends T> iterator)`	Adds all elements in `iterator` to `collection`.
`static int`	`advance(java.util.Iterator<?> iterator, int numberToAdvance)`	Calls `next()` on `iterator`, either `numberToAdvance` times or until `hasNext()` returns `false`, whichever comes first.
`static <T extends @Nullable java.lang.Object> boolean`	`all(java.util.Iterator<T> iterator, Predicate<? super T> predicate)`	Returns `true` if every element returned by `iterator` satisfies the given predicate.
`static <T extends @Nullable java.lang.Object> boolean`	`any(java.util.Iterator<T> iterator, Predicate<? super T> predicate)`	Returns `true` if one or more elements returned by `iterator` satisfy the given predicate.
`static <T extends @Nullable java.lang.Object> java.util.Enumeration<T>`	`asEnumeration(java.util.Iterator<T> iterator)`	Adapts an `Iterator` to the `Enumeration` interface.
`static <T extends @Nullable java.lang.Object> java.util.Iterator<T>`	`concat(java.util.Iterator<? extends java.util.Iterator<? extends T>> inputs)`	Combines multiple iterators into a single iterator.
`static <T extends @Nullable java.lang.Object> java.util.Iterator<T>`	`concat(java.util.Iterator<? extends T>... inputs)`	Combines multiple iterators into a single iterator.
`static <T extends @Nullable java.lang.Object> java.util.Iterator<T>`	`concat(java.util.Iterator<? extends T> a, java.util.Iterator<? extends T> b)`	Combines two iterators into a single iterator.
`static <T extends @Nullable java.lang.Object> java.util.Iterator<T>`	`concat(java.util.Iterator<? extends T> a, java.util.Iterator<? extends T> b, java.util.Iterator<? extends T> c)`	Combines three iterators into a single iterator.
`static <T extends @Nullable java.lang.Object> java.util.Iterator<T>`	`concat(java.util.Iterator<? extends T> a, java.util.Iterator<? extends T> b, java.util.Iterator<? extends T> c, java.util.Iterator<? extends T> d)`	Combines four iterators into a single iterator.
`static <T extends @Nullable java.lang.Object> java.util.Iterator<T>`	`consumingIterator(java.util.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(java.util.Iterator<?> iterator, java.lang.Object element)`	Returns `true` if `iterator` contains `element`.
`static <T extends @Nullable java.lang.Object> java.util.Iterator<T>`	`cycle(java.lang.Iterable<T> iterable)`	Returns an iterator that cycles indefinitely over the elements of `iterable`.
`static <T extends @Nullable java.lang.Object> java.util.Iterator<T>`	`cycle(T... elements)`	Returns an iterator that cycles indefinitely over the provided elements.
`static boolean`	`elementsEqual(java.util.Iterator<?> iterator1, java.util.Iterator<?> iterator2)`	Determines whether two iterators contain equal elements in the same order.
`static <T> UnmodifiableIterator<T>`	`filter(java.util.Iterator<?> unfiltered, java.lang.Class<T> desiredType)`	Returns a view of `unfiltered` containing all elements that are of the type `desiredType`.
`static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T>`	`filter(java.util.Iterator<T> unfiltered, Predicate<? super T> retainIfTrue)`	Returns a view of `unfiltered` containing all elements that satisfy the input predicate `retainIfTrue`.
`static <T extends @Nullable java.lang.Object> T`	`find(java.util.Iterator<? extends T> iterator, Predicate<? super T> predicate, T defaultValue)`	Returns the first element in `iterator` that satisfies the given predicate.
`static <T extends @Nullable java.lang.Object> T`	`find(java.util.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 extends @Nullable java.lang.Object> UnmodifiableIterator<T>`	`forArray(T... array)`	Returns an iterator containing the elements of `array` in order.
`static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T>`	`forEnumeration(java.util.Enumeration<T> enumeration)`	Adapts an `Enumeration` to the `Iterator` interface.
`static int`	`frequency(java.util.Iterator<?> iterator, java.lang.Object element)`	Returns the number of elements in the specified iterator that equal the specified object.
`static <T extends @Nullable java.lang.Object> T`	`get(java.util.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 extends @Nullable java.lang.Object> T`	`get(java.util.Iterator<T> iterator, int position)`	Advances `iterator` `position + 1` times, returning the element at the `position`th position.
`static <T extends @Nullable java.lang.Object> T`	`getLast(java.util.Iterator<? extends T> iterator, T defaultValue)`	Advances `iterator` to the end, returning the last element or `defaultValue` if the iterator is empty.
`static <T extends @Nullable java.lang.Object> T`	`getLast(java.util.Iterator<T> iterator)`	Advances `iterator` to the end, returning the last element.
`static <T extends @Nullable java.lang.Object> T`	`getNext(java.util.Iterator<? extends T> iterator, T defaultValue)`	Returns the next element in `iterator` or `defaultValue` if the iterator is empty.
`static <T extends @Nullable java.lang.Object> T`	`getOnlyElement(java.util.Iterator<? extends T> iterator, T defaultValue)`	Returns the single element contained in `iterator`, or `defaultValue` if the iterator is empty.
`static <T extends @Nullable java.lang.Object> T`	`getOnlyElement(java.util.Iterator<T> iterator)`	Returns the single element contained in `iterator`.
`static <T extends @Nullable java.lang.Object> int`	`indexOf(java.util.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 extends @Nullable java.lang.Object> java.util.Iterator<T>`	`limit(java.util.Iterator<T> iterator, int limitSize)`	Returns a view containing the first `limitSize` elements of `iterator`.
`static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T>`	`mergeSorted(java.lang.Iterable<? extends java.util.Iterator<? extends T>> iterators, java.util.Comparator<? super T> comparator)`	Returns an iterator over the merged contents of all given `iterators`, traversing every element of the input iterators.
`static <T extends @Nullable java.lang.Object> UnmodifiableIterator<java.util.List<@Nullable T>>`	`paddedPartition(java.util.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 java.lang.Object> UnmodifiableIterator<java.util.List<T>>`	`partition(java.util.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 java.lang.Object> PeekingIterator<T>`	`peekingIterator(PeekingIterator<T> iterator)`	Deprecated. no need to use this
`static <T extends @Nullable java.lang.Object> PeekingIterator<T>`	`peekingIterator(java.util.Iterator<? extends T> iterator)`	Returns a `PeekingIterator` backed by the given iterator.
`static boolean`	`removeAll(java.util.Iterator<?> removeFrom, java.util.Collection<?> elementsToRemove)`	Traverses an iterator and removes every element that belongs to the provided collection.
`static <T extends @Nullable java.lang.Object> boolean`	`removeIf(java.util.Iterator<T> removeFrom, Predicate<? super T> predicate)`	Removes every element that satisfies the provided predicate from the iterator.
`static boolean`	`retainAll(java.util.Iterator<?> removeFrom, java.util.Collection<?> elementsToRetain)`	Traverses an iterator and removes every element that does not belong to the provided collection.
`static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T>`	`singletonIterator(T value)`	Returns an iterator containing only `value`.
`static int`	`size(java.util.Iterator<?> iterator)`	Returns the number of elements remaining in `iterator`.
`static <T> @Nullable T[]`	`toArray(java.util.Iterator<? extends @Nullable T> iterator, java.lang.Class<T> type)`	Copies an iterator's elements into an array.
`static java.lang.String`	`toString(java.util.Iterator<?> iterator)`	Returns a string representation of `iterator`, with the format `[e1, e2, ..., en]`.
`static <F extends @Nullable java.lang.Object,T extends @Nullable java.lang.Object> java.util.Iterator<T>`	`transform(java.util.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(java.util.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 extends @Nullable java.lang.Object> UnmodifiableIterator<T>`	`unmodifiableIterator(UnmodifiableIterator<T> iterator)`	Deprecated. no need to use this
`static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T>`	`unmodifiableIterator(java.util.Iterator<? extends 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
  - unmodifiableIterator
```
public static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T> unmodifiableIterator(java.util.Iterator<? extends T> iterator)
```
    Returns an unmodifiable view of iterator.
  - unmodifiableIterator
```
@Deprecated
public static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T> unmodifiableIterator(UnmodifiableIterator<T> iterator)
```
    Deprecated.
    no need to use this
    
    Simply returns its argument.
    
    Since:
    
    10.0
  - size
```
public static int size(java.util.Iterator<?> iterator)
```
    Returns the number of elements remaining in iterator. The iterator will be left exhausted: its hasNext() method will return false.
  - contains
```
public static boolean contains(java.util.Iterator<?> iterator,
                               @CheckForNull
                               java.lang.Object element)
```
    Returns true if iterator contains element.
  - removeAll
```
@CanIgnoreReturnValue
public static boolean removeAll(java.util.Iterator<?> removeFrom,
                                java.util.Collection<?> elementsToRemove)
```
    Traverses an iterator and removes every element that belongs to the provided collection. The iterator will be left exhausted: its hasNext() method will return false.
    
    Parameters:
    
    removeFrom - the iterator to (potentially) remove elements from
    
    elementsToRemove - the elements to remove
    
    Returns:
    
    true if any element was removed from iterator
  - removeIf
```
@CanIgnoreReturnValue
public static <T extends @Nullable java.lang.Object> boolean removeIf(java.util.Iterator<T> removeFrom,
                                                                      Predicate<? super T> predicate)
```
    Removes every element that satisfies the provided predicate from the iterator. The iterator will be left exhausted: its hasNext() method will return false.
    
    Parameters:
    
    removeFrom - the iterator to (potentially) remove elements from
    
    predicate - 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(java.util.Iterator<?> removeFrom,
                                java.util.Collection<?> elementsToRetain)
```
    Traverses an iterator and removes every element that does not belong to the provided collection. The iterator will be left exhausted: its hasNext() method will return false.
    
    Parameters:
    
    removeFrom - the iterator to (potentially) remove elements from
    
    elementsToRetain - the elements to retain
    
    Returns:
    
    true if any element was removed from iterator
  - elementsEqual
```
public static boolean elementsEqual(java.util.Iterator<?> iterator1,
                                    java.util.Iterator<?> iterator2)
```
    Determines whether two iterators contain equal elements in the same order. More specifically, this method returns 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.
  - toString
```
public static java.lang.String toString(java.util.Iterator<?> iterator)
```
    Returns a string representation of iterator, with the format [e1, e2, ..., en]. The iterator will be left exhausted: its hasNext() method will return false.
  - getOnlyElement
```
public static <T extends @Nullable java.lang.Object> T getOnlyElement(java.util.Iterator<T> iterator)
```
    Returns the single element contained in iterator.
    
    Throws:
    
    java.util.NoSuchElementException - if the iterator is empty
    
    java.lang.IllegalArgumentException - if the iterator contains multiple elements. The state of the iterator is unspecified.
  - getOnlyElement
```
public static <T extends @Nullable java.lang.Object> T getOnlyElement(java.util.Iterator<? extends T> iterator,
                                                                      T defaultValue)
```
    Returns the single element contained in iterator, or defaultValue if the iterator is empty.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the iterator contains multiple elements. The state of the iterator is unspecified.
  - toArray
```
@GwtIncompatible
public static <T> @Nullable T[] toArray(java.util.Iterator<? extends @Nullable T> iterator,
                                        java.lang.Class<T> type)
```
    Copies an iterator's elements into an array. The iterator will be left exhausted: its hasNext() method will return false.
    
    Parameters:
    
    iterator - the iterator to copy
    
    type - 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 java.lang.Object> boolean addAll(java.util.Collection<T> addTo,
                                                                    java.util.Iterator<? extends T> iterator)
```
    Adds all elements in iterator to collection. The iterator will be left exhausted: its hasNext() method will return false.
    
    Returns:
    
    true if collection was modified as a result of this operation
  - frequency
```
public static int frequency(java.util.Iterator<?> iterator,
                            @CheckForNull
                            java.lang.Object element)
```
    Returns the number of elements in the specified iterator that equal the specified object. The iterator will be left exhausted: its hasNext() method will return false.
    
    See Also:
    
    Collections.frequency(java.util.Collection<?>, java.lang.Object)
  - cycle
```
public static <T extends @Nullable java.lang.Object> java.util.Iterator<T> cycle(java.lang.Iterable<T> iterable)
```
    Returns an iterator that cycles indefinitely over the elements of 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.
  - cycle
```
@SafeVarargs
public static <T extends @Nullable java.lang.Object> java.util.Iterator<T> cycle(T... elements)
```
    Returns an iterator that cycles indefinitely over the provided 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.
  - concat
```
public static <T extends @Nullable java.lang.Object> java.util.Iterator<T> concat(java.util.Iterator<? extends T> a,
                                                                                  java.util.Iterator<? extends T> b)
```
    Combines two iterators into a single iterator. The returned iterator iterates across the elements in 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.
  - concat
```
public static <T extends @Nullable java.lang.Object> java.util.Iterator<T> concat(java.util.Iterator<? extends T> a,
                                                                                  java.util.Iterator<? extends T> b,
                                                                                  java.util.Iterator<? extends T> c)
```
    Combines three iterators into a single iterator. The returned iterator iterates across the elements in 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.
  - concat
```
public static <T extends @Nullable java.lang.Object> java.util.Iterator<T> concat(java.util.Iterator<? extends T> a,
                                                                                  java.util.Iterator<? extends T> b,
                                                                                  java.util.Iterator<? extends T> c,
                                                                                  java.util.Iterator<? extends T> d)
```
    Combines four iterators into a single iterator. The returned iterator iterates across the elements in 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.
  - concat
```
public static <T extends @Nullable java.lang.Object> java.util.Iterator<T> concat(java.util.Iterator<? extends T>... inputs)
```
    Combines multiple iterators into a single iterator. The returned iterator iterates across the elements of each iterator in inputs. The input iterators are not polled until necessary.
    The returned iterator supports remove() when the corresponding input iterator supports it.
    
    Throws:
    
    java.lang.NullPointerException - if any of the provided iterators is null
  - concat
```
public static <T extends @Nullable java.lang.Object> java.util.Iterator<T> concat(java.util.Iterator<? extends java.util.Iterator<? extends T>> inputs)
```
    Combines multiple iterators into a single iterator. The returned iterator iterates across the elements of each iterator in 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.
  - partition
```
public static <T extends @Nullable java.lang.Object> UnmodifiableIterator<java.util.List<T>> partition(java.util.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.
    Note: The current implementation eagerly allocates storage for size elements. As a consequence, passing values like Integer.MAX_VALUE can lead to OutOfMemoryError.
    
    Parameters:
    
    iterator - the iterator to return a partitioned view of
    
    size - 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:
    
    java.lang.IllegalArgumentException - if size is nonpositive
  - paddedPartition
```
public static <T extends @Nullable java.lang.Object> UnmodifiableIterator<java.util.List<@Nullable T>> paddedPartition(java.util.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 of
    
    size - 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:
    
    java.lang.IllegalArgumentException - if size is nonpositive
  - filter
```
public static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T> filter(java.util.Iterator<T> unfiltered,
                                                                                    Predicate<? super T> retainIfTrue)
```
    Returns a view of unfiltered containing all elements that satisfy the input predicate retainIfTrue.
  - filter
```
@GwtIncompatible
public static <T> UnmodifiableIterator<T> filter(java.util.Iterator<?> unfiltered,
                                                 java.lang.Class<T> desiredType)
```
    Returns a view of unfiltered containing all elements that are of the type desiredType.
  - any
```
public static <T extends @Nullable java.lang.Object> boolean any(java.util.Iterator<T> iterator,
                                                                 Predicate<? super T> predicate)
```
    Returns true if one or more elements returned by iterator satisfy the given predicate.
  - all
```
public static <T extends @Nullable java.lang.Object> boolean all(java.util.Iterator<T> iterator,
                                                                 Predicate<? super T> predicate)
```
    Returns true if every element returned by iterator satisfies the given predicate. If iterator is empty, true is returned.
  - find
```
public static <T extends @Nullable java.lang.Object> T find(java.util.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. 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.
    
    Throws:
    
    java.util.NoSuchElementException - if no element in iterator matches the given predicate
  - find
```
@CheckForNull
public static <T extends @Nullable java.lang.Object> T find(java.util.Iterator<? extends T> iterator,
                                                            Predicate<? super T> predicate,
                                                            @CheckForNull
                                                            T defaultValue)
```
    Returns the first element in 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).
    
    Since:
    
    7.0
  - tryFind
```
public static <T> Optional<T> tryFind(java.util.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. 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.
    
    Since:
    
    11.0
  - indexOf
```
public static <T extends @Nullable java.lang.Object> int indexOf(java.util.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.
    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.
    
    Since:
    
    2.0
  - transform
```
public static <F extends @Nullable java.lang.Object,T extends @Nullable java.lang.Object> java.util.Iterator<T> transform(java.util.Iterator<F> fromIterator,
                                                                                                                                Function<? super F,? extends T> function)
```
    Returns a view containing the result of applying 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.
  - get
```
public static <T extends @Nullable java.lang.Object> T get(java.util.Iterator<T> iterator,
                                                           int position)
```
    Advances iterator position + 1 times, returning the element at the positionth position.
    
    Parameters:
    
    position - position of the element to return
    
    Returns:
    
    the element at the specified position in iterator
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if position is negative or greater than or equal to the number of elements remaining in iterator
  - get
```
public static <T extends @Nullable java.lang.Object> T get(java.util.Iterator<? extends T> iterator,
                                                           int position,
                                                           T defaultValue)
```
    Advances iterator position + 1 times, returning the element at the positionth position or defaultValue otherwise.
    
    Parameters:
    
    position - position of the element to return
    
    defaultValue - the default value to return if the iterator is empty or if position is greater than the number of elements remaining in iterator
    
    Returns:
    
    the element at the specified position in iterator or defaultValue if iterator produces fewer than position + 1 elements.
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if position is negative
    
    Since:
    
    4.0
  - getNext
```
public static <T extends @Nullable java.lang.Object> T getNext(java.util.Iterator<? extends T> iterator,
                                                               T defaultValue)
```
    Returns the next element in iterator or defaultValue if the iterator is empty. The Iterables analog to this method is Iterables.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 java.lang.Object> T getLast(java.util.Iterator<T> iterator)
```
    Advances iterator to the end, returning the last element.
    
    Returns:
    
    the last element of iterator
    
    Throws:
    
    java.util.NoSuchElementException - if the iterator is empty
  - getLast
```
public static <T extends @Nullable java.lang.Object> T getLast(java.util.Iterator<? extends T> iterator,
                                                               T defaultValue)
```
    Advances iterator to the end, returning the last element or defaultValue 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(java.util.Iterator<?> iterator,
                          int numberToAdvance)
```
    Calls next() on iterator, either numberToAdvance times or until hasNext() returns false, 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 java.lang.Object> java.util.Iterator<T> limit(java.util.Iterator<T> iterator,
                                                                                 int limitSize)
```
    Returns a view containing the first 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.
    
    Parameters:
    
    iterator - the iterator to limit
    
    limitSize - the maximum number of elements in the returned iterator
    
    Throws:
    
    java.lang.IllegalArgumentException - if limitSize is negative
    
    Since:
    
    3.0
  - consumingIterator
```
public static <T extends @Nullable java.lang.Object> java.util.Iterator<T> consumingIterator(java.util.Iterator<T> iterator)
```
    Returns a view of the supplied 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. The returned Iterator is also not thread-safe.
    
    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 java.lang.Object> UnmodifiableIterator<T> forArray(T... array)
```
    Returns an iterator containing the elements of 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().
  - singletonIterator
```
public static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T> singletonIterator(T value)
```
    Returns an iterator containing only value.
    The Iterable equivalent of this method is Collections.singleton(T).
  - forEnumeration
```
public static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T> forEnumeration(java.util.Enumeration<T> enumeration)
```
    Adapts an 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>).
    Java 9 users: use enumeration.asIterator() instead, unless it is important to return an UnmodifiableIterator instead of a plain Iterator.
  - asEnumeration
```
public static <T extends @Nullable java.lang.Object> java.util.Enumeration<T> asEnumeration(java.util.Iterator<T> iterator)
```
    Adapts an 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()).
  - peekingIterator
```
public static <T extends @Nullable java.lang.Object> PeekingIterator<T> peekingIterator(java.util.Iterator<? extends T> iterator)
```
    Returns a 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.
    Parameters:
    
    iterator - the backing iterator. The PeekingIterator 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 as iterator.
  - peekingIterator
```
@Deprecated
public static <T extends @Nullable java.lang.Object> PeekingIterator<T> peekingIterator(PeekingIterator<T> iterator)
```
    Deprecated.
    no need to use this
    
    Simply returns its argument.
    
    Since:
    
    10.0
  - mergeSorted
```
public static <T extends @Nullable java.lang.Object> UnmodifiableIterator<T> mergeSorted(java.lang.Iterable<? extends java.util.Iterator<? extends T>> iterators,
                                                                                         java.util.Comparator<? super T> comparator)
```
    Returns an iterator over the merged contents of all given 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.
    
    Since:
    
    11.0

Class Iterators

Method Summary

Methods inherited from class java.lang.Object

Method Detail

unmodifiableIterator

unmodifiableIterator

size

contains

removeAll

removeIf

retainAll

elementsEqual

toString

getOnlyElement

getOnlyElement

toArray

addAll

frequency

cycle

cycle

concat

concat

concat

concat

concat

partition

paddedPartition

filter

filter

any

all

find

find

tryFind

indexOf

transform

get

get

getNext

getLast

getLast

advance

limit

consumingIterator

forArray

singletonIterator

forEnumeration

asEnumeration

peekingIterator

peekingIterator

mergeSorted