Iterators
Date: 2016-05-24

com.google.common.collect

## Class Iterators

- 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

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> 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> 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> 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> java.util.Enumeration<T>` | `asEnumeration(java.util.Iterator<T> iterator)` Adapts an `Iterator` to the `Enumeration` interface.
    `static <T> java.util.Iterator<T>` | `concat(java.util.Iterator<? extends java.util.Iterator<? extends T>> inputs)` Combines multiple iterators into a single iterator.
    `static <T> java.util.Iterator<T>` | `concat(java.util.Iterator<? extends T>... inputs)` Combines multiple iterators into a single iterator.
    `static <T> 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> 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> 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> 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> java.util.Iterator<T>` | `cycle(java.lang.Iterable<T> iterable)` Returns an iterator that cycles indefinitely over the elements of `iterable`.
    `static <T> 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>` | `emptyIterator()` Deprecated. Use `ImmutableSet.<T>of().iterator()` instead; or for Java 7 or later, `Collections.emptyIterator()`. This method is scheduled for removal in May 2016.
    `static <T> UnmodifiableIterator<T>` | `filter(java.util.Iterator<?> unfiltered, java.lang.Class<T> type)` Returns all instances of class `type` in `unfiltered`.
    `static <T> UnmodifiableIterator<T>` | `filter(java.util.Iterator<T> unfiltered, Predicate<? super T> predicate)` Returns the elements of `unfiltered` that satisfy a predicate.
    `static <T> 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> 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> UnmodifiableIterator<T>` | `forArray(T... array)` Returns an iterator containing the elements of `array` in order.
    `static <T> 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> 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> T` | `get(java.util.Iterator<T> iterator, int position)` Advances `iterator` `position + 1` times, returning the element at the `position`th position.
    `static <T> 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> T` | `getLast(java.util.Iterator<T> iterator)` Advances `iterator` to the end, returning the last element.
    `static <T> 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> 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> T` | `getOnlyElement(java.util.Iterator<T> iterator)` Returns the single element contained in `iterator`.
    `static <T> 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> java.util.Iterator<T>` | `limit(java.util.Iterator<T> iterator, int limitSize)` Creates an iterator returning the first `limitSize` elements of the given iterator.
    `static <T> 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> UnmodifiableIterator<java.util.List<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> 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> PeekingIterator<T>` | `peekingIterator(java.util.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(java.util.Iterator<?> removeFrom, java.util.Collection<?> elementsToRemove)` Traverses an iterator and removes every element that belongs to the provided collection.
    `static <T> 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> 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> T[]` | `toArray(java.util.Iterator<? extends 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,T> java.util.Iterator<T>` | `transform(java.util.Iterator<F> fromIterator, Function<? super F,? extends T> function)` Returns an iterator that applies `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> UnmodifiableIterator<T>` | `unmodifiableIterator(java.util.Iterator<T> iterator)` Returns an unmodifiable view of `iterator`.
    `static <T> UnmodifiableIterator<T>` | `unmodifiableIterator(UnmodifiableIterator<T> iterator)` Deprecated. no need to use this

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### emptyIterator

          @Deprecated
          public static <T> UnmodifiableIterator<T> emptyIterator()

      Deprecated. Use `ImmutableSet.<T>of().iterator()` instead; or for Java 7 or later, `Collections.emptyIterator()`. This method is scheduled for removal in May 2016.
      Returns the empty iterator.

      The `Iterable` equivalent of this method is `ImmutableSet.of()`.

    - #### unmodifiableIterator

          public static <T> UnmodifiableIterator<T> unmodifiableIterator(java.util.Iterator<T> iterator)

      Returns an unmodifiable view of `iterator`.

    - #### unmodifiableIterator

          @Deprecated
          public static <T> 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,
                         @Nullable
                         java.lang.Object element)

      Returns `true` if `iterator` contains `element`.

    - #### removeAll

          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

          public static <T> 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

          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> 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

          @Nullable
          public static <T> T getOnlyElement(java.util.Iterator<? extends T> iterator,
                                      @Nullable
                                      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(value="Array.newInstance(Class, int)")
          public static <T> T[] toArray(java.util.Iterator<? extends 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

          public static <T> 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,
                      @Nullable
                      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> 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

          public static <T> 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> 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.

      Note: the current implementation is not suitable for nested concatenated iterators, i.e. the following should be avoided when in a loop: `iterator = Iterators.concat(iterator, suffix);`, since iteration over the resulting iterator has a cubic complexity to the depth of the nesting.

    - #### concat

          public static <T> 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.

      Note: the current implementation is not suitable for nested concatenated iterators, i.e. the following should be avoided when in a loop: `iterator = Iterators.concat(iterator, suffix);`, since iteration over the resulting iterator has a cubic complexity to the depth of the nesting.

    - #### concat

          public static <T> 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.

      Note: the current implementation is not suitable for nested concatenated iterators, i.e. the following should be avoided when in a loop: `iterator = Iterators.concat(iterator, suffix);`, since iteration over the resulting iterator has a cubic complexity to the depth of the nesting.

    - #### concat

          public static <T> 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.

      Note: the current implementation is not suitable for nested concatenated iterators, i.e. the following should be avoided when in a loop: `iterator = Iterators.concat(iterator, suffix);`, since iteration over the resulting iterator has a cubic complexity to the depth of the nesting.

      Throws:
        `java.lang.NullPointerException` - if any of the provided iterators is null

    - #### concat

          public static <T> 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.

      Note: the current implementation is not suitable for nested concatenated iterators, i.e. the following should be avoided when in a loop: `iterator = Iterators.concat(iterator, suffix);`, since iteration over the resulting iterator has a cubic complexity to the depth of the nesting.

    - #### partition

          public static <T> 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`.

      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> UnmodifiableIterator<java.util.List<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

          @CheckReturnValue
          public static <T> UnmodifiableIterator<T> filter(java.util.Iterator<T> unfiltered,
                                                            Predicate<? super T> predicate)

      Returns the elements of `unfiltered` that satisfy a predicate.

    - #### filter

          @GwtIncompatible(value="Class.isInstance")
          @CheckReturnValue
          public static <T> UnmodifiableIterator<T> filter(java.util.Iterator<?> unfiltered,
                                                                                 java.lang.Class<T> type)

      Returns all instances of class `type` in `unfiltered`. The returned iterator has elements whose class is `type` or a subclass of `type`.
      Parameters:
        `unfiltered` - an iterator containing objects of any type
        `type` - the type of elements desired
      Returns:
        an unmodifiable iterator containing all elements of the original iterator that were of the requested type

    - #### any

          public static <T> 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> 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> 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

          @Nullable
          public static <T> T find(java.util.Iterator<? extends T> iterator,
                            Predicate<? super T> predicate,
                            @Nullable
                            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> 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,T> java.util.Iterator<T> transform(java.util.Iterator<F> fromIterator,
                                              Function<? super F,? extends T> function)

      Returns an iterator that applies `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.

    - #### get

          public static <T> T get(java.util.Iterator<T> iterator,
                  int position)

      Advances `iterator` `position + 1` times, returning the element at the `position`th 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

          @Nullable
          public static <T> T get(java.util.Iterator<? extends T> iterator,
                           int position,
                           @Nullable
                           T defaultValue)

      Advances `iterator` `position + 1` times, returning the element at the `position`th 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

          @Nullable
          public static <T> T getNext(java.util.Iterator<? extends T> iterator,
                               @Nullable
                               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> 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

          @Nullable
          public static <T> T getLast(java.util.Iterator<? extends T> iterator,
                               @Nullable
                               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

          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> java.util.Iterator<T> limit(java.util.Iterator<T> iterator,
                                        int limitSize)

      Creates an iterator returning the first `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.
      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> 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`.

      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

          public static <T> 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> UnmodifiableIterator<T> singletonIterator(@Nullable
                                                      T value)

      Returns an iterator containing only `value`.

      The `Iterable` equivalent of this method is `Collections.singleton(T)`.

    - #### forEnumeration

          public static <T> 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>)`.

    - #### asEnumeration

          public static <T> 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> 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> PeekingIterator<T> peekingIterator(PeekingIterator<T> iterator)

      Deprecated. no need to use this
      Simply returns its argument.
      Since:
        10.0

    - #### mergeSorted

          @Beta
          public static <T> 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