Iterators (Jersey 2.43 API)

java.lang.Object
- org.glassfish.jersey.internal.guava.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.

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 (imported from Google Collections Library)

Author:

Kevin Bourrillion, Jared Levy

Method Summary

All Methods Static Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static <T> boolean`	`addAll(Collection<T> addTo, Iterator<? extends T> iterator)` Adds all elements in `iterator` to `collection`.
`static <T> boolean`	`all(Iterator<T> iterator, Predicate<? super T> predicate)` Returns `true` if every element returned by `iterator` satisfies the given predicate.
`static boolean`	`elementsEqual(Iterator<?> iterator1, 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>`	`forArray(T... array)` Returns an iterator containing the elements of `array` in order.
`static <T> T`	`getNext(Iterator<? extends T> iterator, T defaultValue)` Returns the next element in `iterator` or `defaultValue` if the iterator is empty.
`static <T> 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 <T> boolean`	`removeIf(Iterator<T> removeFrom, Predicate<? super T> predicate)` Removes every element that satisfies the provided predicate from the iterator.
`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 <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
```
@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(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.
  - 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 element was removed from iterator
  - removeIf
```
public static <T> boolean removeIf(Iterator<T> removeFrom,
                                   Predicate<? super T> predicate)
```
    Removes every element that satisfies the provided predicate from the iterator. The iterator will be left exhausted: 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
  - 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.
  - 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
  - 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.
  - 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.
  - getNext
```
public static <T> T getNext(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
  - 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(T value)
```
    Returns an iterator containing only value.
    
    The Iterable equivalent of this method is Collections.singleton(T).
  - 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:
```
   
 <p>
   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.

Class Iterators

Method Summary

Methods inherited from class java.lang.Object

Method Detail

emptyIterator

unmodifiableIterator

size

removeAll

removeIf

elementsEqual

addAll

all

transform

getNext

forArray

singletonIterator

peekingIterator