Package org.docx4j.com.google.common.collect

Class Iterators

java.lang.Object
org.docx4j.com.google.common.collect.Iterators
@GwtCompatible(emulated=true) 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
Author:
Kevin Bourrillion, Jared Levy

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> boolean
    addAll(Collection<T> addTo, Iterator<? extends T> iterator)
    Adds all elements in iterator to collection.
    static int
    advance(Iterator<?> iterator, int numberToAdvance)
    Calls next() on iterator, either numberToAdvance times or until hasNext() returns false, whichever comes first.
    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>
    consumingIterator(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(Iterator<?> iterator, @Nullable Object element)
    Returns true if iterator contains element.
    static boolean
    elementsEqual(Iterator<?> iterator1, Iterator<?> iterator2)
    Determines whether two iterators contain equal elements in the same order.
    static <T> @Nullable T
    find(Iterator<? extends T> iterator, Predicate<? super T> predicate, @Nullable T defaultValue)
    Returns the first element in iterator that satisfies the given predicate.
    static <T> T
    find(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(Enumeration<T> enumeration)
    Adapts an Enumeration to the Iterator interface.
    static int
    frequency(Iterator<?> iterator, @Nullable Object element)
    Returns the number of elements in the specified iterator that equal the specified object.
    static <T> @Nullable T
    get(Iterator<? extends T> iterator, int position, @Nullable T defaultValue)
    Advances iterator position + 1 times, returning the element at the positionth position or defaultValue otherwise.
    static <T> T
    get(Iterator<T> iterator, int position)
    Advances iterator position + 1 times, returning the element at the positionth position.
    static <T> @Nullable T
    getLast(Iterator<? extends T> iterator, @Nullable T defaultValue)
    Advances iterator to the end, returning the last element or defaultValue if the iterator is empty.
    static <T> T
    getLast(Iterator<T> iterator)
    Advances iterator to the end, returning the last element.
    static <T> @Nullable T
    getNext(Iterator<? extends T> iterator, @Nullable T defaultValue)
    Returns the next element in iterator or defaultValue if the iterator is empty.
    static <T> @Nullable T
    getOnlyElement(Iterator<? extends T> iterator, @Nullable T defaultValue)
    Returns the single element contained in iterator, or defaultValue if the iterator is empty.
    static <T> T
    getOnlyElement(Iterator<T> iterator)
    Returns the single element contained in iterator.
    static <T> int
    indexOf(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> Iterator<T>
    limit(Iterator<T> iterator, int limitSize)
    Returns a view containing the first limitSize elements of iterator.
    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 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 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(@Nullable T value)
    Returns an iterator containing only value.
    static int
    size(Iterator<?> iterator)
    Returns the number of elements remaining in iterator.
    static String
    toString(Iterator<?> iterator)
    Returns a string representation of iterator, with the format [e1, e2, ..., en].
    static <T> UnmodifiableIterator<T>
    unmodifiableIterator(Iterator<? extends 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 Details

    • unmodifiableIterator

      public static <T> UnmodifiableIterator<T> unmodifiableIterator(Iterator<? extends 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(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

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

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

    • retainAll

      @CanIgnoreReturnValue 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 element was 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> @Nullable T getOnlyElement(Iterator<? extends 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.

    • addAll

      @CanIgnoreReturnValue 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:

    • 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

    • 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; 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 or find(Iterator, Predicate, Object) instead.
      Throws:
      NoSuchElementException - if no element in iterator matches the given predicate

    • find

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

    • indexOf

      public static <T> int indexOf(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

    • get

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

    • get

      public static <T> @Nullable T get(Iterator<? extends T> iterator, int position, @Nullable 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:
      IndexOutOfBoundsException - if position is negative
      Since:
      4.0

    • getNext

      public static <T> @Nullable T getNext(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.
      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(Iterator<T> iterator)
      Advances iterator to the end, returning the last element.
      Returns:
      the last element of iterator
      Throws:
      NoSuchElementException - if the iterator is empty

    • getLast

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

      @CanIgnoreReturnValue public static int advance(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> Iterator<T> limit(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:
      IllegalArgumentException - if limitSize is negative
      Since:
      3.0

    • consumingIterator

      public static <T> Iterator<T> consumingIterator(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

      @SafeVarargs 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(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> 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<T>) (if you have a Collection), or Iterators.asEnumeration(collection.iterator()).