|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectcom.google.common.collect.Iterators
public final class Iterators
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.
| Method Summary | ||
|---|---|---|
static
|
addAll(Collection<T> addTo,
Iterator<? extends T> iterator)
Adds all elements in iterator to collection. |
|
static
|
all(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns true if every element returned by iterator
satisfies the given predicate. |
|
static
|
any(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns true if one or more elements returned by iterator
satisfy the given predicate. |
|
static
|
asEnumeration(Iterator<T> iterator)
Adapts an Iterator to the Enumeration interface. |
|
static
|
concat(Iterator<? extends Iterator<? extends T>> inputs)
Combines multiple iterators into a single iterator. |
|
static
|
concat(Iterator<? extends T>... inputs)
Combines multiple iterators into a single iterator. |
|
static
|
concat(Iterator<? extends T> a,
Iterator<? extends T> b)
Combines two iterators into a single iterator. |
|
static
|
concat(Iterator<? extends T> a,
Iterator<? extends T> b,
Iterator<? extends T> c)
Combines three iterators into a single iterator. |
|
static
|
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
|
cycle(Iterable<T> iterable)
Returns an iterator that cycles indefinitely over the elements of iterable. |
|
static
|
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
|
emptyIterator()
Returns the empty iterator. |
|
static
|
filter(Iterator<?> unfiltered,
Class<T> type)
Returns all instances of class type in unfiltered. |
|
static
|
filter(Iterator<T> unfiltered,
Predicate<? super T> predicate)
Returns the elements of unfiltered that satisfy a predicate. |
|
static
|
find(Iterator<T> iterator,
Predicate<? super T> predicate)
Returns the first element in iterator that satisfies the given
predicate. |
|
static
|
forArray(T... array)
Returns an iterator containing the elements of array in order. |
|
static
|
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
|
get(Iterator<T> iterator,
int position)
Advances iterator position + 1 times, returning the element
at the positionth position. |
|
static
|
getLast(Iterator<T> iterator)
Advances iterator to the end, returning the last element. |
|
static
|
getOnlyElement(Iterator<T> iterator)
Returns the single element contained in iterator. |
|
static
|
getOnlyElement(Iterator<T> iterator,
T defaultValue)
Returns the single element contained in iterator, or defaultValue if the iterator is empty. |
|
static
|
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
|
partition(Iterator<T> iterator,
int size)
Divides an iterator into unmodifiable sublists of the given size (the final list may be smaller). |
|
static
|
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
|
singletonIterator(T value)
Returns an iterator containing only value. |
|
static int |
size(Iterator<?> iterator)
Returns the number of elements remaining in iterator. |
|
static
|
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
|
transform(Iterator<F> fromIterator,
Function<? super F,? extends T> function)
Returns an iterator that applies function to each element of fromIterator. |
|
static
|
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 |
|---|
public static <T> UnmodifiableIterator<T> emptyIterator()
The Iterable equivalent of this method is Collections.emptySet().
public static <T> UnmodifiableIterator<T> unmodifiableIterator(Iterator<T> iterator)
iterator.
public static int size(Iterator<?> iterator)
iterator. The iterator
will be left exhausted: its hasNext() method will return
false.
public static boolean contains(Iterator<?> iterator,
@Nullable
Object element)
true if iterator contains element.
public static boolean removeAll(Iterator<?> removeFrom,
Collection<?> elementsToRemove)
hasNext() method will return false.
removeFrom - the iterator to (potentially) remove elements fromelementsToRemove - the elements to remove
true if any elements are removed from iterator
public static boolean retainAll(Iterator<?> removeFrom,
Collection<?> elementsToRetain)
hasNext() method will return false.
removeFrom - the iterator to (potentially) remove elements fromelementsToRetain - the elements to retain
true if any elements are removed from iterator
public static boolean elementsEqual(Iterator<?> iterator1,
Iterator<?> iterator2)
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.
public static String toString(Iterator<?> iterator)
iterator, with the format
[e1, e2, ..., en]. The iterator will be left exhausted: its
hasNext() method will return false.
public static <T> T getOnlyElement(Iterator<T> iterator)
iterator.
NoSuchElementException - if the iterator is empty
IllegalArgumentException - if the iterator contains multiple
elements. The state of the iterator is unspecified.
public static <T> T getOnlyElement(Iterator<T> iterator,
@Nullable
T defaultValue)
iterator, or defaultValue if the iterator is empty.
IllegalArgumentException - if the iterator contains multiple
elements. The state of the iterator is unspecified.
public static <T> T[] toArray(Iterator<? extends T> iterator,
Class<T> type)
hasNext() method will return false.
iterator - the iterator to copytype - the type of the elements
public static <T> boolean addAll(Collection<T> addTo,
Iterator<? extends T> iterator)
iterator to collection. The iterator
will be left exhausted: its hasNext() method will return
false.
true if collection was modified as a result of this
operation
public static int frequency(Iterator<?> iterator,
@Nullable
Object element)
hasNext() method will return false.
Collections.frequency(java.util.Collection>, java.lang.Object)public static <T> Iterator<T> cycle(Iterable<T> iterable)
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.
public static <T> Iterator<T> cycle(T... 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.
public static <T> Iterator<T> concat(Iterator<? extends T> a,
Iterator<? extends T> b)
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.
public static <T> Iterator<T> concat(Iterator<? extends T> a,
Iterator<? extends T> b,
Iterator<? extends T> c)
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.
public static <T> Iterator<T> concat(Iterator<? extends T> a,
Iterator<? extends T> b,
Iterator<? extends T> c,
Iterator<? extends T> d)
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.
public static <T> Iterator<T> concat(Iterator<? extends T>... inputs)
inputs. The input
iterators are not polled until necessary.
The returned iterator supports remove() when the corresponding
input iterator supports it.
NullPointerException - if any of the provided iterators is nullpublic static <T> Iterator<T> concat(Iterator<? extends Iterator<? extends T>> inputs)
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.
public static <T> UnmodifiableIterator<List<T>> partition(Iterator<T> iterator,
int size)
[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.
iterator - the iterator to return a partitioned view ofsize - the desired size of each partition (the last may be smaller)
iterator divided into partitions
IllegalArgumentException - if size is nonpositive
public static <T> UnmodifiableIterator<List<T>> paddedPartition(Iterator<T> iterator,
int size)
[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.
iterator - the iterator to return a partitioned view ofsize - the desired size of each partition
iterator divided into partitions (the final iterable may have
trailing null elements)
IllegalArgumentException - if size is nonpositive
public static <T> UnmodifiableIterator<T> filter(Iterator<T> unfiltered,
Predicate<? super T> predicate)
unfiltered that satisfy a predicate.
public static <T> UnmodifiableIterator<T> filter(Iterator<?> unfiltered,
Class<T> type)
type in unfiltered. The
returned iterator has elements whose class is type or a subclass of
type.
unfiltered - an iterator containing objects of any typetype - the type of elements desired
public static <T> boolean any(Iterator<T> iterator,
Predicate<? super T> predicate)
true if one or more elements returned by iterator
satisfy the given predicate.
public static <T> boolean all(Iterator<T> iterator,
Predicate<? super T> predicate)
true if every element returned by iterator
satisfies the given predicate. If iterator is empty, true
is returned.
public static <T> T find(Iterator<T> iterator,
Predicate<? super T> predicate)
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.
iterator
NoSuchElementException - if no element in iterator matches
the given predicate
public static <F,T> Iterator<T> transform(Iterator<F> fromIterator,
Function<? super F,? extends T> function)
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.
public static <T> T get(Iterator<T> iterator,
int position)
iterator position + 1 times, returning the element
at the positionth position.
position - position of the element to return
iterator
IndexOutOfBoundsException - if position is negative or
greater than or equal to the number of elements remaining in
iteratorpublic static <T> T getLast(Iterator<T> iterator)
iterator to the end, returning the last element.
iterator
NoSuchElementException - if the iterator has no remaining elementspublic static <T> UnmodifiableIterator<T> forArray(T... array)
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[])}.
public static <T> UnmodifiableIterator<T> singletonIterator(@Nullable
T value)
value.
The Iterable equivalent of this method is Collections.singleton(T).
public static <T> UnmodifiableIterator<T> forEnumeration(Enumeration<T> enumeration)
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.
public static <T> Enumeration<T> asEnumeration(Iterator<T> iterator)
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()).
public static <T> PeekingIterator<T> peekingIterator(Iterator<? extends T> iterator)
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.
iterator - the backing iterator. The PeekingIterator assumes
ownership of this iterator, so users should cease making direct calls
to it after calling this method.
PeekingIterator.peek() method, this iterator behaves
exactly the same as iterator.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||