Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.common.collect
Class Iterators

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

    public final class Iterators

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

Author:
  Kevin Bourrillion, Jared Levy

Method Summary
`static
`<T> boolean`
` | `addAll(Collection<T> addTo, Iterator<? extends T> iterator)` Adds all elements in `iterator` to `collection`.
`static
`<T> boolean`
` | `all(Iterator<T> iterator, Predicate<? super T> predicate)` Returns `true` if every element returned by `iterator` satisfies the given predicate.
`static
`<T> boolean`
` | `any(Iterator<T> iterator, Predicate<? super T> predicate)` Returns `true` if one or more elements returned by `iterator` satisfy the given predicate.
`static
`<T> Enumeration<T>`
` | `asEnumeration(Iterator<T> iterator)` Adapts an `Iterator` to the `Enumeration` interface.
`static
`<T> Iterator<T>`
` | `concat(Iterator<? extends Iterator<? extends T>> inputs)` Combines multiple iterators into a single iterator.
`static
`<T> Iterator<T>`
` | `concat(Iterator<? extends T>... inputs)` Combines multiple iterators into a single iterator.
`static
`<T> Iterator<T>`
` | `concat(Iterator<? extends T> a, Iterator<? extends T> b)` Combines two iterators into a single iterator.
`static
`<T> Iterator<T>`
` | `concat(Iterator<? extends T> a, Iterator<? extends T> b, Iterator<? extends T> c)` Combines three iterators into a single iterator.
`static
`<T> Iterator<T>`
` | `concat(Iterator<? extends T> a, Iterator<? extends T> b, Iterator<? extends T> c, Iterator<? extends T> d)` Combines four iterators into a single iterator.
`static boolean` | `contains(Iterator<?> iterator, Object element)` Returns `true` if `iterator` contains `element`.
`static
`<T> Iterator<T>`
` | `cycle(Iterable<T> iterable)` Returns an iterator that cycles indefinitely over the elements of `iterable`.
`static
`<T> Iterator<T>`
` | `cycle(T... elements)` Returns an iterator that cycles indefinitely over the provided elements.
`static boolean` | `elementsEqual(Iterator<?> iterator1, Iterator<?> iterator2)` Determines whether two iterators contain equal elements in the same order.
`static
`<T> UnmodifiableIterator<T>`
` | `emptyIterator()` Returns the empty iterator.
`static
`<T> UnmodifiableIterator<T>`
` | `filter(Iterator<?> unfiltered, Class<T> type)` Returns all instances of class `type` in `unfiltered`.
`static
`<T> UnmodifiableIterator<T>`
` | `filter(Iterator<T> unfiltered, Predicate<? super T> predicate)` Returns the elements of `unfiltered` that satisfy a predicate.
`static
`<T> T`
` | `find(Iterator<T> iterator, Predicate<? super T> predicate)` Returns the first element in `iterator` that satisfies the given predicate.
`static
`<T> UnmodifiableIterator<T>`
` | `forArray(T... array)` Returns an iterator containing the elements of `array` in order.
`static
`<T> UnmodifiableIterator<T>`
` | `forEnumeration(Enumeration<T> enumeration)` Adapts an `Enumeration` to the `Iterator` interface.
`static int` | `frequency(Iterator<?> iterator, Object element)` Returns the number of elements in the specified iterator that equal the specified object.
`static
`<T> T`
` | `get(Iterator<T> iterator, int position)` Advances `iterator` `position + 1` times, returning the element at the `position`th position.
`static
`<T> T`
` | `getLast(Iterator<T> iterator)` Advances `iterator` to the end, returning the last element.
`static
`<T> T`
` | `getOnlyElement(Iterator<T> iterator)` Returns the single element contained in `iterator`.
`static
`<T> T`
` | `getOnlyElement(Iterator<T> iterator, T defaultValue)` Returns the single element contained in `iterator`, or `defaultValue` if the iterator is empty.
`static
`<T> UnmodifiableIterator<List<T>>`
` | `paddedPartition(Iterator<T> iterator, int size)` Divides an iterator into unmodifiable sublists of the given size, padding the final iterator with null values if necessary.
`static
`<T> UnmodifiableIterator<List<T>>`
` | `partition(Iterator<T> iterator, int size)` Divides an iterator into unmodifiable sublists of the given size (the final list may be smaller).
`static
`<T> PeekingIterator<T>`
` | `peekingIterator(Iterator<? extends T> iterator)` Returns a `PeekingIterator` backed by the given iterator.
`static boolean` | `removeAll(Iterator<?> removeFrom, Collection<?> elementsToRemove)` Traverses an iterator and removes every element that belongs to the provided collection.
`static boolean` | `retainAll(Iterator<?> removeFrom, Collection<?> elementsToRetain)` Traverses an iterator and removes every element that does not belong to the provided collection.
`static
`<T> UnmodifiableIterator<T>`
` | `singletonIterator(T value)` Returns an iterator containing only `value`.
`static int` | `size(Iterator<?> iterator)` Returns the number of elements remaining in `iterator`.
`static
`<T> T[]`
` | `toArray(Iterator<? extends T> iterator, Class<T> type)` Copies an iterator's elements into an array.
`static String` | `toString(Iterator<?> iterator)` Returns a string representation of `iterator`, with the format `[e1, e2, ..., en]`.
`static
`<F,T> Iterator<T>`
` | `transform(Iterator<F> fromIterator, Function<? super F,? extends T> function)` Returns an iterator that applies `function` to each element of `fromIterator`.
`static
`<T> UnmodifiableIterator<T>`
` | `unmodifiableIterator(Iterator<T> iterator)` Returns an unmodifiable view of `iterator`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### emptyIterator

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

  Returns the empty iterator.

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

### unmodifiableIterator

    public static <T> UnmodifiableIterator<T> unmodifiableIterator(Iterator<T> iterator)

  Returns an unmodifiable view of `iterator`.

### size

    public static int size(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(Iterator<?> iterator,
                                   @Nullable
                                   Object element)

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

### removeAll

    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: its `hasNext()` method will return `false`.

  Parameters:
    `removeFrom` - the iterator to (potentially) remove elements from
    `elementsToRemove` - the elements to remove
  Returns:
    `true` if any elements are removed from `iterator`

### retainAll

    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: its `hasNext()` method will return `false`.

  Parameters:
    `removeFrom` - the iterator to (potentially) remove elements from
    `elementsToRetain` - the elements to retain
  Returns:
    `true` if any elements are removed from `iterator`

### elementsEqual

    public static boolean elementsEqual(Iterator<?> iterator1,
                                        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 String toString(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(Iterator<T> iterator)

  Returns the single element contained in `iterator`.

  Throws:
    `NoSuchElementException` - if the iterator is empty
    `IllegalArgumentException` - if the iterator contains multiple elements. The state of the iterator is unspecified.

### getOnlyElement

    public static <T> T getOnlyElement(Iterator<T> iterator,
                                       @Nullable
                                       T defaultValue)

  Returns the single element contained in `iterator`, or `defaultValue` if the iterator is empty.

  Throws:
    `IllegalArgumentException` - if the iterator contains multiple elements. The state of the iterator is unspecified.

### toArray

    public static <T> T[] toArray(Iterator<? extends T> iterator,
                                  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(Collection<T> addTo,
                                     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(Iterator<?> iterator,
                                @Nullable
                                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> Iterator<T> cycle(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> Iterator<T> cycle(T... elements)

  Returns an iterator that cycles indefinitely over the provided elements.

  The returned iterator supports `remove()` if the provided iterator does. After `remove()` is called, subsequent cycles omit the removed element, but `elements` does not change. The iterator's `hasNext()` method returns `true` until all of the original elements have been removed.

  Warning: Typical uses of the resulting iterator may produce an infinite loop. You should use an explicit `break` or be certain that you will eventually remove all the elements.

### concat

    public static <T> 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 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> 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 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> 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 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> Iterator<T> concat(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:
    `NullPointerException` - if any of the provided iterators is null

### concat

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

### partition

    public static <T> UnmodifiableIterator<List<T>> partition(Iterator<T> iterator,
                                                              int size)

  Divides an iterator into unmodifiable sublists of the given size (the final list may be smaller). 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:
    `IllegalArgumentException` - if `size` is nonpositive

### paddedPartition

    public static <T> UnmodifiableIterator<List<T>> paddedPartition(Iterator<T> iterator,
                                                                    int size)

  Divides an iterator into unmodifiable sublists of the given size, padding the final iterator with null values if necessary. 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:
    `IllegalArgumentException` - if `size` is nonpositive

### filter

    public static <T> UnmodifiableIterator<T> filter(Iterator<T> unfiltered,
                                                     Predicate<? super T> predicate)

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

### filter

    public static <T> UnmodifiableIterator<T> filter(Iterator<?> unfiltered,
                                                     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(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(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(Iterator<T> iterator,
                             Predicate<? super T> predicate)

  Returns the first element in `iterator` that satisfies the given predicate. If a matching element is found, the iterator will be left in a state such that calling `iterator.remove()` will remove the found item. If no such element is found, the iterator will be left exhausted: its `hasNext()` method will return `false`.

  Returns:
    the first matching element in `iterator`
  Throws:
    `NoSuchElementException` - if no element in `iterator` matches the given predicate

### transform

    public static <F,T> Iterator<T> transform(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(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:
    `IndexOutOfBoundsException` - if `position` is negative or greater than or equal to the number of elements remaining in `iterator`

### getLast

    public static <T> T getLast(Iterator<T> iterator)

  Advances `iterator` to the end, returning the last element.

  Returns:
    the last element of `iterator`
  Throws:
    `NoSuchElementException` - if the iterator has no remaining elements

### 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[])` or `ImmutableList.of(Object[])`}.

### 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(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)`.

### asEnumeration

    public static <T> Enumeration<T> asEnumeration(Iterator<T> iterator)

  Adapts an `Iterator` to the `Enumeration` interface.

  The `Iterable` equivalent of this method is either `Collections.enumeration(java.util.Collection)` (if you have a `Collection`), or `Iterators.asEnumeration(collection.iterator())`.

### peekingIterator

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD