Class Iterables


  • @GwtCompatible(emulated=true)
    public final class Iterables
    extends java.lang.Object
    An assortment of mainly legacy static utility methods that operate on or return objects of type Iterable. Except as noted, each method has a corresponding Iterator-based method in the Iterators class.

    Java 8 users: several common uses for this class are now more comprehensively addressed by the new Stream library. Read the method documentation below for comparisons. This class is not being deprecated, but we gently encourage you to migrate to streams.

    Performance notes: Unless otherwise noted, all of the iterables produced in this class are lazy, which means that their iterators only advance the backing iteration when absolutely necessary.

    See the Guava User Guide article on Iterables.

    Since:
    2.0
    Author:
    Kevin Bourrillion, Jared Levy
    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static <T extends @Nullable java.lang.Object>
      boolean
      addAll​(java.util.Collection<T> addTo, java.lang.Iterable<? extends T> elementsToAdd)
      Adds all elements in iterable to collection.
      static <T extends @Nullable java.lang.Object>
      boolean
      all​(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
      Returns true if every element in iterable satisfies the predicate.
      static <T extends @Nullable java.lang.Object>
      boolean
      any​(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
      Returns true if any element in iterable satisfies the predicate.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      concat​(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> inputs)
      Combines multiple iterables into a single iterable.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      concat​(java.lang.Iterable<? extends T>... inputs)
      Combines multiple iterables into a single iterable.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      concat​(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b)
      Combines two iterables into a single iterable.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      concat​(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.Iterable<? extends T> c)
      Combines three iterables into a single iterable.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      concat​(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.Iterable<? extends T> c, java.lang.Iterable<? extends T> d)
      Combines four iterables into a single iterable.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      consumingIterable​(java.lang.Iterable<T> iterable)
      Returns a view of the supplied iterable that wraps each generated Iterator through Iterators.consumingIterator(Iterator).
      static boolean contains​(java.lang.Iterable<? extends @Nullable java.lang.Object> iterable, java.lang.Object element)
      Returns true if iterable contains any element o for which Objects.equals(o, element) would return true.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      cycle​(java.lang.Iterable<T> iterable)
      Returns an iterable whose iterators cycle indefinitely over the elements of iterable.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      cycle​(T... elements)
      Returns an iterable whose iterators cycle indefinitely over the provided elements.
      static boolean elementsEqual​(java.lang.Iterable<?> iterable1, java.lang.Iterable<?> iterable2)
      Determines whether two iterables contain equal elements in the same order.
      static <T> java.lang.Iterable<T> filter​(java.lang.Iterable<?> unfiltered, java.lang.Class<T> desiredType)
      Returns a view of unfiltered containing all elements that are of the type desiredType.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      filter​(java.lang.Iterable<T> unfiltered, Predicate<? super T> retainIfTrue)
      Returns a view of unfiltered containing all elements that satisfy the input predicate retainIfTrue.
      static <T extends @Nullable java.lang.Object>
      T
      find​(java.lang.Iterable<? extends T> iterable, Predicate<? super T> predicate, T defaultValue)
      Returns the first element in iterable that satisfies the given predicate, or defaultValue if none found.
      static <T extends @Nullable java.lang.Object>
      T
      find​(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
      Returns the first element in iterable that satisfies the given predicate; use this method only when such an element is known to exist.
      static int frequency​(java.lang.Iterable<?> iterable, java.lang.Object element)
      Returns the number of elements in the specified iterable that equal the specified object.
      static <T extends @Nullable java.lang.Object>
      T
      get​(java.lang.Iterable<? extends T> iterable, int position, T defaultValue)
      Returns the element at the specified position in an iterable or a default value otherwise.
      static <T extends @Nullable java.lang.Object>
      T
      get​(java.lang.Iterable<T> iterable, int position)
      Returns the element at the specified position in an iterable.
      static <T extends @Nullable java.lang.Object>
      T
      getFirst​(java.lang.Iterable<? extends T> iterable, T defaultValue)
      Returns the first element in iterable or defaultValue if the iterable is empty.
      static <T extends @Nullable java.lang.Object>
      T
      getLast​(java.lang.Iterable<? extends T> iterable, T defaultValue)
      Returns the last element of iterable or defaultValue if the iterable is empty.
      static <T extends @Nullable java.lang.Object>
      T
      getLast​(java.lang.Iterable<T> iterable)
      Returns the last element of iterable.
      static <T extends @Nullable java.lang.Object>
      T
      getOnlyElement​(java.lang.Iterable<? extends T> iterable, T defaultValue)
      Returns the single element contained in iterable, or defaultValue if the iterable is empty.
      static <T extends @Nullable java.lang.Object>
      T
      getOnlyElement​(java.lang.Iterable<T> iterable)
      Returns the single element contained in iterable.
      static <T extends @Nullable java.lang.Object>
      int
      indexOf​(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
      Returns the index in iterable of the first element that satisfies the provided predicate, or -1 if the Iterable has no such elements.
      static boolean isEmpty​(java.lang.Iterable<?> iterable)
      Determines if the given iterable contains no elements.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      limit​(java.lang.Iterable<T> iterable, int limitSize)
      Returns a view of iterable containing its first limitSize elements.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      mergeSorted​(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> iterables, java.util.Comparator<? super T> comparator)
      Returns an iterable over the merged contents of all given iterables.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<java.util.List<@Nullable T>>
      paddedPartition​(java.lang.Iterable<T> iterable, int size)
      Divides an iterable into unmodifiable sublists of the given size, padding the final iterable with null values if necessary.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<java.util.List<T>>
      partition​(java.lang.Iterable<T> iterable, int size)
      Divides an iterable into unmodifiable sublists of the given size (the final iterable may be smaller).
      static boolean removeAll​(java.lang.Iterable<?> removeFrom, java.util.Collection<?> elementsToRemove)
      Removes, from an iterable, every element that belongs to the provided collection.
      static <T extends @Nullable java.lang.Object>
      boolean
      removeIf​(java.lang.Iterable<T> removeFrom, Predicate<? super T> predicate)
      Removes, from an iterable, every element that satisfies the provided predicate.
      static boolean retainAll​(java.lang.Iterable<?> removeFrom, java.util.Collection<?> elementsToRetain)
      Removes, from an iterable, every element that does not belong to the provided collection.
      static int size​(java.lang.Iterable<?> iterable)
      Returns the number of elements in iterable.
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      skip​(java.lang.Iterable<T> iterable, int numberToSkip)
      Returns a view of iterable that skips its first numberToSkip elements.
      static <T> @Nullable T[] toArray​(java.lang.Iterable<? extends @Nullable T> iterable, java.lang.Class<T> type)
      Copies an iterable's elements into an array.
      static java.lang.String toString​(java.lang.Iterable<?> iterable)
      Returns a string representation of iterable, with the format [e1, e2, ..., en] (that is, identical to Arrays .toString(Iterables.toArray(iterable))).
      static <F extends @Nullable java.lang.Object,​T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      transform​(java.lang.Iterable<F> fromIterable, Function<? super F,​? extends T> function)
      Returns a view containing the result of applying function to each element of fromIterable.
      static <T> Optional<T> tryFind​(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
      Returns an Optional containing the first element in iterable that satisfies the given predicate, if such an element exists.
      static <E> java.lang.Iterable<E> unmodifiableIterable​(ImmutableCollection<E> iterable)
      Deprecated.
      no need to use this
      static <T extends @Nullable java.lang.Object>
      java.lang.Iterable<T>
      unmodifiableIterable​(java.lang.Iterable<? extends T> iterable)
      Returns an unmodifiable view of iterable.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • unmodifiableIterable

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> unmodifiableIterable​(java.lang.Iterable<? extends T> iterable)
        Returns an unmodifiable view of iterable.
      • unmodifiableIterable

        @Deprecated
        public static <E> java.lang.Iterable<E> unmodifiableIterable​(ImmutableCollection<E> iterable)
        Deprecated.
        no need to use this
        Simply returns its argument.
        Since:
        10.0
      • size

        public static int size​(java.lang.Iterable<?> iterable)
        Returns the number of elements in iterable.
      • contains

        public static boolean contains​(java.lang.Iterable<? extends @Nullable java.lang.Object> iterable,
                                       @CheckForNull
                                       java.lang.Object element)
        Returns true if iterable contains any element o for which Objects.equals(o, element) would return true. Otherwise returns false, even in cases where Collection.contains(java.lang.Object) might throw NullPointerException or ClassCastException.
      • removeAll

        @CanIgnoreReturnValue
        public static boolean removeAll​(java.lang.Iterable<?> removeFrom,
                                        java.util.Collection<?> elementsToRemove)
        Removes, from an iterable, every element that belongs to the provided collection.

        This method calls Collection.removeAll(java.util.Collection<?>) if iterable is a collection, and Iterators.removeAll(java.util.Iterator<?>, java.util.Collection<?>) otherwise.

        Parameters:
        removeFrom - the iterable to (potentially) remove elements from
        elementsToRemove - the elements to remove
        Returns:
        true if any element was removed from iterable
      • retainAll

        @CanIgnoreReturnValue
        public static boolean retainAll​(java.lang.Iterable<?> removeFrom,
                                        java.util.Collection<?> elementsToRetain)
        Removes, from an iterable, every element that does not belong to the provided collection.

        This method calls Collection.retainAll(java.util.Collection<?>) if iterable is a collection, and Iterators.retainAll(java.util.Iterator<?>, java.util.Collection<?>) otherwise.

        Parameters:
        removeFrom - the iterable to (potentially) remove elements from
        elementsToRetain - the elements to retain
        Returns:
        true if any element was removed from iterable
      • removeIf

        @CanIgnoreReturnValue
        public static <T extends @Nullable java.lang.Object> boolean removeIf​(java.lang.Iterable<T> removeFrom,
                                                                              Predicate<? super T> predicate)
        Removes, from an iterable, every element that satisfies the provided predicate.

        Removals may or may not happen immediately as each element is tested against the predicate. The behavior of this method is not specified if predicate is dependent on removeFrom.

        Parameters:
        removeFrom - the iterable 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 iterable
        Throws:
        java.lang.UnsupportedOperationException - if the iterable does not support remove().
        Since:
        2.0
      • elementsEqual

        public static boolean elementsEqual​(java.lang.Iterable<?> iterable1,
                                            java.lang.Iterable<?> iterable2)
        Determines whether two iterables contain equal elements in the same order. More specifically, this method returns true if iterable1 and iterable2 contain the same number of elements and every element of iterable1 is equal to the corresponding element of iterable2.
      • toString

        public static java.lang.String toString​(java.lang.Iterable<?> iterable)
        Returns a string representation of iterable, with the format [e1, e2, ..., en] (that is, identical to Arrays .toString(Iterables.toArray(iterable))). Note that for most implementations of Collection, collection.toString() also gives the same result, but that behavior is not generally guaranteed.
      • getOnlyElement

        public static <T extends @Nullable java.lang.Object> T getOnlyElement​(java.lang.Iterable<T> iterable)
        Returns the single element contained in iterable.

        Java 8 users: the Stream equivalent to this method is stream.collect(MoreCollectors.onlyElement()).

        Throws:
        java.util.NoSuchElementException - if the iterable is empty
        java.lang.IllegalArgumentException - if the iterable contains multiple elements
      • getOnlyElement

        public static <T extends @Nullable java.lang.Object> T getOnlyElement​(java.lang.Iterable<? extends T> iterable,
                                                                              T defaultValue)
        Returns the single element contained in iterable, or defaultValue if the iterable is empty.

        Java 8 users: the Stream equivalent to this method is stream.collect(MoreCollectors.toOptional()).orElse(defaultValue).

        Throws:
        java.lang.IllegalArgumentException - if the iterator contains multiple elements
      • toArray

        @GwtIncompatible
        public static <T> @Nullable T[] toArray​(java.lang.Iterable<? extends @Nullable T> iterable,
                                                java.lang.Class<T> type)
        Copies an iterable's elements into an array.
        Parameters:
        iterable - the iterable to copy
        type - the type of the elements
        Returns:
        a newly-allocated array into which all the elements of the iterable have been copied
      • addAll

        @CanIgnoreReturnValue
        public static <T extends @Nullable java.lang.Object> boolean addAll​(java.util.Collection<T> addTo,
                                                                            java.lang.Iterable<? extends T> elementsToAdd)
        Adds all elements in iterable to collection.
        Returns:
        true if collection was modified as a result of this operation.
      • frequency

        public static int frequency​(java.lang.Iterable<?> iterable,
                                    @CheckForNull
                                    java.lang.Object element)
        Returns the number of elements in the specified iterable that equal the specified object. This implementation avoids a full iteration when the iterable is a Multiset or Set.

        Java 8 users: In most cases, the Stream equivalent of this method is stream.filter(element::equals).count(). If element might be null, use stream.filter(Predicate.isEqual(element)).count() instead.

        See Also:
        Collections.frequency(Collection, Object)
      • cycle

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> cycle​(java.lang.Iterable<T> iterable)
        Returns an iterable whose iterators cycle indefinitely over the elements of iterable.

        That iterator supports remove() if iterable.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.

        To cycle over the iterable n times, use the following: Iterables.concat(Collections.nCopies(n, iterable))

        Java 8 users: The Stream equivalent of this method is Stream.generate(() -> iterable).flatMap(Streams::stream).

      • cycle

        @SafeVarargs
        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> cycle​(T... elements)
        Returns an iterable whose iterators cycle indefinitely over the provided elements.

        After remove is invoked on a generated iterator, the removed element will no longer appear in either that iterator or any other iterator created from the same source iterable. That is, this method behaves exactly as Iterables.cycle(Lists.newArrayList(elements)). 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.

        To cycle over the elements n times, use the following: Iterables.concat(Collections.nCopies(n, Arrays.asList(elements)))

        Java 8 users: If passing a single element e, the Stream equivalent of this method is Stream.generate(() -> e). Otherwise, put the elements in a collection and use Stream.generate(() -> collection).flatMap(Collection::stream).

      • concat

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat​(java.lang.Iterable<? extends T> a,
                                                                                          java.lang.Iterable<? extends T> b)
        Combines two iterables into a single iterable. The returned iterable has an iterator that traverses the elements in a, followed by the elements in b. The source iterators are not polled until necessary.

        The returned iterable's iterator supports remove() when the corresponding input iterator supports it.

        Java 8 users: The Stream equivalent of this method is Stream.concat(a, b).

      • concat

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat​(java.lang.Iterable<? extends T> a,
                                                                                          java.lang.Iterable<? extends T> b,
                                                                                          java.lang.Iterable<? extends T> c)
        Combines three iterables into a single iterable. The returned iterable has an iterator that traverses 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 iterable's iterator supports remove() when the corresponding input iterator supports it.

        Java 8 users: The Stream equivalent of this method is Streams.concat(a, b, c).

      • concat

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat​(java.lang.Iterable<? extends T> a,
                                                                                          java.lang.Iterable<? extends T> b,
                                                                                          java.lang.Iterable<? extends T> c,
                                                                                          java.lang.Iterable<? extends T> d)
        Combines four iterables into a single iterable. The returned iterable has an iterator that traverses 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 iterable's iterator supports remove() when the corresponding input iterator supports it.

        Java 8 users: The Stream equivalent of this method is Streams.concat(a, b, c, d).

      • concat

        @SafeVarargs
        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat​(java.lang.Iterable<? extends T>... inputs)
        Combines multiple iterables into a single iterable. The returned iterable has an iterator that traverses the elements of each iterable in inputs. The input iterators are not polled until necessary.

        The returned iterable's iterator supports remove() when the corresponding input iterator supports it.

        Java 8 users: The Stream equivalent of this method is Streams.concat(...).

        Throws:
        java.lang.NullPointerException - if any of the provided iterables is null
      • concat

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> concat​(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> inputs)
        Combines multiple iterables into a single iterable. The returned iterable has an iterator that traverses the elements of each iterable in inputs. The input iterators are not polled until necessary.

        The returned iterable's iterator supports remove() when the corresponding input iterator supports it. The methods of the returned iterable may throw NullPointerException if any of the input iterators is null.

        Java 8 users: The Stream equivalent of this method is streamOfStreams.flatMap(s -> s).

      • partition

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<java.util.List<T>> partition​(java.lang.Iterable<T> iterable,
                                                                                                             int size)
        Divides an iterable into unmodifiable sublists of the given size (the final iterable may be smaller). For example, partitioning an iterable containing [a, b, c, d, e] with a partition size of 3 yields [[a, b, c], [d, e]] -- an outer iterable containing two inner lists of three and two elements, all in the original order.

        Iterators returned by the returned iterable do not support the Iterator.remove() method. The returned lists implement RandomAccess, whether or not the input list does.

        Note: The current implementation eagerly allocates storage for size elements. As a consequence, passing values like Integer.MAX_VALUE can lead to OutOfMemoryError.

        Note: if iterable is a List, use Lists.partition(List, int) instead.

        Parameters:
        iterable - the iterable to return a partitioned view of
        size - the desired size of each partition (the last may be smaller)
        Returns:
        an iterable of unmodifiable lists containing the elements of iterable divided into partitions
        Throws:
        java.lang.IllegalArgumentException - if size is nonpositive
      • paddedPartition

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<java.util.List<@Nullable T>> paddedPartition​(java.lang.Iterable<T> iterable,
                                                                                                                             int size)
        Divides an iterable into unmodifiable sublists of the given size, padding the final iterable with null values if necessary. For example, partitioning an iterable containing [a, b, c, d, e] with a partition size of 3 yields [[a, b, c], [d, e, null]] -- an outer iterable containing two inner lists of three elements each, all in the original order.

        Iterators returned by the returned iterable do not support the Iterator.remove() method.

        Parameters:
        iterable - the iterable to return a partitioned view of
        size - the desired size of each partition
        Returns:
        an iterable of unmodifiable lists containing the elements of iterable divided into partitions (the final iterable may have trailing null elements)
        Throws:
        java.lang.IllegalArgumentException - if size is nonpositive
      • filter

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> filter​(java.lang.Iterable<T> unfiltered,
                                                                                          Predicate<? super T> retainIfTrue)
        Returns a view of unfiltered containing all elements that satisfy the input predicate retainIfTrue. The returned iterable's iterator does not support remove().

        Stream equivalent: Stream#filter.

      • filter

        @GwtIncompatible
        public static <T> java.lang.Iterable<T> filter​(java.lang.Iterable<?> unfiltered,
                                                       java.lang.Class<T> desiredType)
        Returns a view of unfiltered containing all elements that are of the type desiredType. The returned iterable's iterator does not support remove().

        Stream equivalent: stream.filter(type::isInstance).map(type::cast). This does perform a little more work than necessary, so another option is to insert an unchecked cast at some later point:

         @SuppressWarnings("unchecked") // safe because of ::isInstance check
         ImmutableList<NewType> result =
             (ImmutableList) stream.filter(NewType.class::isInstance).collect(toImmutableList());
         
      • any

        public static <T extends @Nullable java.lang.Object> boolean any​(java.lang.Iterable<T> iterable,
                                                                         Predicate<? super T> predicate)
        Returns true if any element in iterable satisfies the predicate.

        Stream equivalent: Stream#anyMatch.

      • all

        public static <T extends @Nullable java.lang.Object> boolean all​(java.lang.Iterable<T> iterable,
                                                                         Predicate<? super T> predicate)
        Returns true if every element in iterable satisfies the predicate. If iterable is empty, true is returned.

        Stream equivalent: Stream#allMatch.

      • find

        @CheckForNull
        public static <T extends @Nullable java.lang.Object> T find​(java.lang.Iterable<? extends T> iterable,
                                                                    Predicate<? super T> predicate,
                                                                    @CheckForNull
                                                                    T defaultValue)
        Returns the first element in iterable that satisfies the given predicate, or defaultValue if none found. Note that this can usually be handled more naturally using tryFind(iterable, predicate).or(defaultValue).

        Stream equivalent: stream.filter(predicate).findFirst().orElse(defaultValue)

        Since:
        7.0
      • tryFind

        public static <T> Optional<T> tryFind​(java.lang.Iterable<T> iterable,
                                              Predicate<? super T> predicate)
        Returns an Optional containing the first element in iterable that satisfies the given predicate, if such an element exists.

        Warning: avoid using a predicate that matches null. If null is matched in iterable, a NullPointerException will be thrown.

        Stream equivalent: stream.filter(predicate).findFirst()

        Since:
        11.0
      • indexOf

        public static <T extends @Nullable java.lang.Object> int indexOf​(java.lang.Iterable<T> iterable,
                                                                         Predicate<? super T> predicate)
        Returns the index in iterable of the first element that satisfies the provided predicate, or -1 if the Iterable has no such elements.

        More formally, returns the lowest index i such that predicate.apply(Iterables.get(iterable, i)) returns true, or -1 if there is no such index.

        Since:
        2.0
      • get

        public static <T extends @Nullable java.lang.Object> T get​(java.lang.Iterable<T> iterable,
                                                                   int position)
        Returns the element at the specified position in an iterable.

        Stream equivalent: stream.skip(position).findFirst().get() (throws NoSuchElementException if out of bounds)

        Parameters:
        position - position of the element to return
        Returns:
        the element at the specified position in iterable
        Throws:
        java.lang.IndexOutOfBoundsException - if position is negative or greater than or equal to the size of iterable
      • get

        public static <T extends @Nullable java.lang.Object> T get​(java.lang.Iterable<? extends T> iterable,
                                                                   int position,
                                                                   T defaultValue)
        Returns the element at the specified position in an iterable or a default value otherwise.

        Stream equivalent: stream.skip(position).findFirst().orElse(defaultValue) (returns the default value if the index is out of bounds)

        Parameters:
        position - position of the element to return
        defaultValue - the default value to return if position is greater than or equal to the size of the iterable
        Returns:
        the element at the specified position in iterable or defaultValue if iterable contains fewer than position + 1 elements.
        Throws:
        java.lang.IndexOutOfBoundsException - if position is negative
        Since:
        4.0
      • getFirst

        public static <T extends @Nullable java.lang.Object> T getFirst​(java.lang.Iterable<? extends T> iterable,
                                                                        T defaultValue)
        Returns the first element in iterable or defaultValue if the iterable is empty. The Iterators analog to this method is Iterators.getNext(java.util.Iterator<? extends T>, T).

        If no default value is desired (and the caller instead wants a NoSuchElementException to be thrown), it is recommended that iterable.iterator().next() is used instead.

        To get the only element in a single-element Iterable, consider using getOnlyElement(Iterable) or getOnlyElement(Iterable, Object) instead.

        Stream equivalent: stream.findFirst().orElse(defaultValue)

        Parameters:
        defaultValue - the default value to return if the iterable is empty
        Returns:
        the first element of iterable or the default value
        Since:
        7.0
      • getLast

        public static <T extends @Nullable java.lang.Object> T getLast​(java.lang.Iterable<T> iterable)
        Returns the last element of iterable. If iterable is a List with RandomAccess support, then this operation is guaranteed to be O(1).

        Stream equivalent: Streams.findLast(stream).get()

        Returns:
        the last element of iterable
        Throws:
        java.util.NoSuchElementException - if the iterable is empty
      • getLast

        public static <T extends @Nullable java.lang.Object> T getLast​(java.lang.Iterable<? extends T> iterable,
                                                                       T defaultValue)
        Returns the last element of iterable or defaultValue if the iterable is empty. If iterable is a List with RandomAccess support, then this operation is guaranteed to be O(1).

        Stream equivalent: Streams.findLast(stream).orElse(defaultValue)

        Parameters:
        defaultValue - the value to return if iterable is empty
        Returns:
        the last element of iterable or the default value
        Since:
        3.0
      • skip

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> skip​(java.lang.Iterable<T> iterable,
                                                                                        int numberToSkip)
        Returns a view of iterable that skips its first numberToSkip elements. If iterable contains fewer than numberToSkip elements, the returned iterable skips all of its elements.

        Modifications to the underlying Iterable before a call to iterator() are reflected in the returned iterator. That is, the iterator skips the first numberToSkip elements that exist when the Iterator is created, not when skip() is called.

        The returned iterable's iterator supports remove() if the iterator of the underlying iterable supports it. Note that it is not possible to delete the last skipped element by immediately calling remove() on that iterator, as the Iterator contract states that a call to remove() before a call to next() will throw an IllegalStateException.

        Stream equivalent: Stream#skip

        Since:
        3.0
      • limit

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> limit​(java.lang.Iterable<T> iterable,
                                                                                         int limitSize)
        Returns a view of iterable containing its first limitSize elements. If iterable contains fewer than limitSize elements, the returned view contains all of its elements. The returned iterable's iterator supports remove() if iterable's iterator does.

        Stream equivalent: Stream#limit

        Parameters:
        iterable - the iterable to limit
        limitSize - the maximum number of elements in the returned iterable
        Throws:
        java.lang.IllegalArgumentException - if limitSize is negative
        Since:
        3.0
      • consumingIterable

        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> consumingIterable​(java.lang.Iterable<T> iterable)
        Returns a view of the supplied iterable that wraps each generated Iterator through Iterators.consumingIterator(Iterator).

        Note: If iterable is a Queue, the returned iterable will instead use Collection.isEmpty() and Queue.remove(), since Queue's iteration order is undefined. Calling Iterator.hasNext() on a generated iterator from the returned iterable may cause an item to be immediately dequeued for return on a subsequent call to Iterator.next().

        Whether the input iterable is a Queue or not, the returned Iterable is not thread-safe.

        Parameters:
        iterable - the iterable to wrap
        Returns:
        a view of the supplied iterable that wraps each generated iterator through Iterators.consumingIterator(Iterator); for queues, an iterable that generates iterators that return and consume the queue's elements in queue order
        Since:
        2.0
        See Also:
        Iterators.consumingIterator(Iterator)
      • isEmpty

        public static boolean isEmpty​(java.lang.Iterable<?> iterable)
        Determines if the given iterable contains no elements.

        There is no precise Iterator equivalent to this method, since one can only ask an iterator whether it has any elements remaining (which one does using Iterator.hasNext()).

        Stream equivalent: !stream.findAny().isPresent()

        Returns:
        true if the iterable contains no elements
      • mergeSorted

        @Beta
        public static <T extends @Nullable java.lang.Object> java.lang.Iterable<T> mergeSorted​(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> iterables,
                                                                                               java.util.Comparator<? super T> comparator)
        Returns an iterable over the merged contents of all given iterables. Equivalent entries will not be de-duplicated.

        Callers must ensure that the source iterables are in non-descending order as this method does not sort its input.

        For any equivalent elements across all iterables, it is undefined which element is returned first.

        Since:
        11.0