Class FluentIterable<E>

  • Type Parameters:
    E - the element type
    All Implemented Interfaces:
    java.lang.Iterable<E>

    public class FluentIterable<E>
    extends java.lang.Object
    implements java.lang.Iterable<E>
    A FluentIterable provides a powerful yet simple API for manipulating Iterable instances in a fluent manner.

    A FluentIterable can be created either from an Iterable or from a set of elements. The following types of methods are provided:

    • fluent methods which return a new FluentIterable instance, providing a view of the original iterable (e.g. filter(Predicate));
    • conversion methods which copy the FluentIterable's contents into a new collection or array (e.g. toList());
    • utility methods which answer questions about the FluentIterable's contents (e.g. size(), anyMatch(Predicate)).

    The following example outputs the first 3 even numbers in the range [1, 10] into a list:

     List<String> result =
       FluentIterable
           .of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
           .filter(new Predicate<Integer>() {
                       public boolean evaluate(Integer number) {
                            return number % 2 == 0;
                       }
                  )
           .transform(TransformerUtils.stringValueTransformer())
           .limit(3)
           .toList();
     
    The resulting list will contain the following elements:
    [2, 4, 6]
    Since:
    4.1
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean allMatch​(Predicate<? super E> predicate)
      Checks if all elements contained in this iterable are matching the provided predicate.
      boolean anyMatch​(Predicate<? super E> predicate)
      Checks if this iterable contains any element matching the provided predicate.
      FluentIterable<E> append​(E... elements)
      Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the provided elements.
      FluentIterable<E> append​(java.lang.Iterable<? extends E> other)
      Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the elements of the provided iterable.
      java.util.Enumeration<E> asEnumeration()
      Returns an Enumeration that will enumerate all elements contained in this iterable.
      FluentIterable<E> collate​(java.lang.Iterable<? extends E> other)
      Returns a new FluentIterable whose iterator will traverse the elements of the current and provided iterable in natural order.
      FluentIterable<E> collate​(java.lang.Iterable<? extends E> other, java.util.Comparator<? super E> comparator)
      Returns a new FluentIterable whose iterator will traverse the elements of the current and provided iterable according to the ordering defined by an comparator.
      boolean contains​(java.lang.Object object)
      Checks if the object is contained in this iterable.
      void copyInto​(java.util.Collection<? super E> collection)
      Traverses an iterator of this iterable and adds all elements to the provided collection.
      static <T> FluentIterable<T> empty()
      Creates a new empty FluentIterable.
      FluentIterable<E> eval()
      This method fully traverses an iterator of this iterable and returns a new iterable with the same contents, but without any reference to the originating iterables and/or iterators.
      FluentIterable<E> filter​(Predicate<? super E> predicate)
      Returns a new FluentIterable whose iterator will only return elements from this iterable matching the provided predicate.
      void forEach​(Closure<? super E> closure)
      Applies the closure to all elements contained in this iterable.
      E get​(int position)
      Returns the element at the provided position in this iterable.
      boolean isEmpty()
      Checks if this iterable is empty.
      java.util.Iterator<E> iterator()
      FluentIterable<E> limit​(long maxSize)
      Returns a new FluentIterable whose iterator will return at most the provided maximum number of elements from this iterable.
      FluentIterable<E> loop()
      Returns a new FluentIterable whose iterator will loop infinitely over the elements from this iterable.
      static <T> FluentIterable<T> of​(java.lang.Iterable<T> iterable)
      Construct a new FluentIterable from the provided iterable.
      static <T> FluentIterable<T> of​(T singleton)
      Creates a new FluentIterable of the single provided element.
      static <T> FluentIterable<T> of​(T... elements)
      Creates a new FluentIterable from the provided elements.
      FluentIterable<E> reverse()
      Returns a new FluentIterable whose iterator will traverse the elements from this iterable in reverse order.
      int size()
      Returns the number of elements that are contained in this iterable.
      FluentIterable<E> skip​(long elementsToSkip)
      Returns a new FluentIterable whose iterator will skip the first N elements from this iterable.
      E[] toArray​(java.lang.Class<E> arrayClass)
      Returns an array containing all elements of this iterable by traversing its iterator.
      java.util.List<E> toList()
      Returns a mutable list containing all elements of this iterable by traversing its iterator.
      java.lang.String toString()
      <O> FluentIterable<O> transform​(Transformer<? super E,​? extends O> transformer)
      Returns a new FluentIterable whose iterator will return all elements of this iterable transformed by the provided transformer.
      FluentIterable<E> unique()
      Returns a new FluentIterable whose iterator will return a unique view of this iterable.
      FluentIterable<E> unmodifiable()
      Returns a new FluentIterable whose iterator will return an unmodifiable view of this iterable.
      FluentIterable<E> zip​(java.lang.Iterable<? extends E> other)
      Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterable in alternating order.
      FluentIterable<E> zip​(java.lang.Iterable<? extends E>... others)
      Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterables in alternating order.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
    • Method Detail

      • empty

        public static <T> FluentIterable<T> empty()
        Creates a new empty FluentIterable.
        Type Parameters:
        T - the element type
        Returns:
        a new empty FluentIterable
      • of

        public static <T> FluentIterable<T> of​(T singleton)
        Creates a new FluentIterable of the single provided element.

        The returned iterable's iterator does not support remove().

        Type Parameters:
        T - the element type
        Parameters:
        singleton - the singleton element
        Returns:
        a new FluentIterable containing the singleton
      • of

        public static <T> FluentIterable<T> of​(T... elements)
        Creates a new FluentIterable from the provided elements.

        The returned iterable's iterator does not support remove().

        Type Parameters:
        T - the element type
        Parameters:
        elements - the elements to be contained in the FluentIterable
        Returns:
        a new FluentIterable containing the provided elements
      • of

        public static <T> FluentIterable<T> of​(java.lang.Iterable<T> iterable)
        Construct a new FluentIterable from the provided iterable. If the iterable is already an instance of FluentIterable, the instance will be returned instead.

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

        Type Parameters:
        T - the element type
        Parameters:
        iterable - the iterable to wrap into a FluentIterable, may not be null
        Returns:
        a new FluentIterable wrapping the provided iterable
        Throws:
        java.lang.NullPointerException - if iterable is null
      • append

        public FluentIterable<E> append​(E... elements)
        Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the provided elements.
        Parameters:
        elements - the elements to append to the iterable
        Returns:
        a new iterable, combining this iterable with the elements
      • append

        public FluentIterable<E> append​(java.lang.Iterable<? extends E> other)
        Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the elements of the provided iterable.
        Parameters:
        other - the other iterable to combine, may not be null
        Returns:
        a new iterable, combining this iterable with other
        Throws:
        java.lang.NullPointerException - if other is null
      • collate

        public FluentIterable<E> collate​(java.lang.Iterable<? extends E> other)
        Returns a new FluentIterable whose iterator will traverse the elements of the current and provided iterable in natural order.

        Example: natural ordering

        • this contains elements [1, 3, 5, 7]
        • other contains elements [2, 4, 6, 8]

        The returned iterable will traverse the elements in the following order: [1, 2, 3, 4, 5, 6, 7, 8]

        Parameters:
        other - the other iterable to collate, may not be null
        Returns:
        a new iterable, collating this iterable with the other in natural order
        Throws:
        java.lang.NullPointerException - if other is null
        See Also:
        CollatingIterator
      • collate

        public FluentIterable<E> collate​(java.lang.Iterable<? extends E> other,
                                         java.util.Comparator<? super E> comparator)
        Returns a new FluentIterable whose iterator will traverse the elements of the current and provided iterable according to the ordering defined by an comparator.

        Example: descending order

        • this contains elements [7, 5, 3, 1]
        • other contains elements [8, 6, 4, 2]

        The returned iterable will traverse the elements in the following order: [8, 7, 6, 5, 4, 3, 2, 1]

        Parameters:
        comparator - the comparator to define an ordering, may be null, in which case natural ordering will be used
        other - the other iterable to collate, may not be null
        Returns:
        a new iterable, collating this iterable with the other in natural order
        Throws:
        java.lang.NullPointerException - if other is null
        See Also:
        CollatingIterator
      • eval

        public FluentIterable<E> eval()
        This method fully traverses an iterator of this iterable and returns a new iterable with the same contents, but without any reference to the originating iterables and/or iterators.

        Calling this method is equivalent to:

           FluentIterable<E> someIterable = ...;
           FluentIterable.of(someIterable.toList());
         
        Returns:
        a new iterable with the same contents as this iterable
      • filter

        public FluentIterable<E> filter​(Predicate<? super E> predicate)
        Returns a new FluentIterable whose iterator will only return elements from this iterable matching the provided predicate.
        Parameters:
        predicate - the predicate used to filter elements
        Returns:
        a new iterable, providing a filtered view of this iterable
        Throws:
        java.lang.NullPointerException - if predicate is null
      • limit

        public FluentIterable<E> limit​(long maxSize)
        Returns a new FluentIterable whose iterator will return at most the provided maximum number of elements from this iterable.
        Parameters:
        maxSize - the maximum number of elements
        Returns:
        a new iterable, providing a bounded view of this iterable
        Throws:
        java.lang.IllegalArgumentException - if maxSize is negative
      • loop

        public FluentIterable<E> loop()
        Returns a new FluentIterable whose iterator will loop infinitely over the elements from this iterable.
        Returns:
        a new iterable, providing a looping view of this iterable
      • reverse

        public FluentIterable<E> reverse()
        Returns a new FluentIterable whose iterator will traverse the elements from this iterable in reverse order.
        Returns:
        a new iterable, providing a reversed view of this iterable
      • skip

        public FluentIterable<E> skip​(long elementsToSkip)
        Returns a new FluentIterable whose iterator will skip the first N elements from this iterable.
        Parameters:
        elementsToSkip - the number of elements to skip
        Returns:
        a new iterable, providing a view of this iterable by skipping the first N elements
        Throws:
        java.lang.IllegalArgumentException - if elementsToSkip is negative
      • transform

        public <O> FluentIterable<O> transform​(Transformer<? super E,​? extends O> transformer)
        Returns a new FluentIterable whose iterator will return all elements of this iterable transformed by the provided transformer.
        Type Parameters:
        O - the output element type
        Parameters:
        transformer - the transformer applied to each element
        Returns:
        a new iterable, providing a transformed view of this iterable
        Throws:
        java.lang.NullPointerException - if transformer is null
      • unique

        public FluentIterable<E> unique()
        Returns a new FluentIterable whose iterator will return a unique view of this iterable.
        Returns:
        a new iterable, providing a unique view of this iterable
      • unmodifiable

        public FluentIterable<E> unmodifiable()
        Returns a new FluentIterable whose iterator will return an unmodifiable view of this iterable.
        Returns:
        a new iterable, providing an unmodifiable view of this iterable
      • zip

        public FluentIterable<E> zip​(java.lang.Iterable<? extends E> other)
        Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterable in alternating order.
        Parameters:
        other - the other iterable to interleave, may not be null
        Returns:
        a new iterable, interleaving this iterable with others
        Throws:
        java.lang.NullPointerException - if other is null
      • zip

        public FluentIterable<E> zip​(java.lang.Iterable<? extends E>... others)
        Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterables in alternating order.
        Parameters:
        others - the iterables to interleave, may not be null
        Returns:
        a new iterable, interleaving this iterable with others
        Throws:
        java.lang.NullPointerException - if either of the provided iterables is null
      • iterator

        public java.util.Iterator<E> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<E>
      • asEnumeration

        public java.util.Enumeration<E> asEnumeration()
        Returns an Enumeration that will enumerate all elements contained in this iterable.
        Returns:
        an Enumeration over the elements of this iterable
      • allMatch

        public boolean allMatch​(Predicate<? super E> predicate)
        Checks if all elements contained in this iterable are matching the provided predicate.

        A null or empty iterable returns true.

        Parameters:
        predicate - the predicate to use, may not be null
        Returns:
        true if all elements contained in this iterable match the predicate, false otherwise
        Throws:
        java.lang.NullPointerException - if predicate is null
      • anyMatch

        public boolean anyMatch​(Predicate<? super E> predicate)
        Checks if this iterable contains any element matching the provided predicate.

        A null or empty iterable returns false.

        Parameters:
        predicate - the predicate to use, may not be null
        Returns:
        true if at least one element contained in this iterable matches the predicate, false otherwise
        Throws:
        java.lang.NullPointerException - if predicate is null
      • isEmpty

        public boolean isEmpty()
        Checks if this iterable is empty.
        Returns:
        true if this iterable does not contain any elements, false otherwise
      • contains

        public boolean contains​(java.lang.Object object)
        Checks if the object is contained in this iterable.
        Parameters:
        object - the object to check
        Returns:
        true if the object is contained in this iterable, false otherwise
      • forEach

        public void forEach​(Closure<? super E> closure)
        Applies the closure to all elements contained in this iterable.
        Parameters:
        closure - the closure to apply to each element, may not be null
        Throws:
        java.lang.NullPointerException - if closure is null
      • get

        public E get​(int position)
        Returns the element at the provided position in this iterable. In order to return the element, an iterator needs to be traversed up to the requested position.
        Parameters:
        position - the position of the element to return
        Returns:
        the element
        Throws:
        java.lang.IndexOutOfBoundsException - if the provided position is outside the valid range of this iterable: [0, size)
      • size

        public int size()
        Returns the number of elements that are contained in this iterable. In order to determine the size, an iterator needs to be traversed.
        Returns:
        the size of this iterable
      • copyInto

        public void copyInto​(java.util.Collection<? super E> collection)
        Traverses an iterator of this iterable and adds all elements to the provided collection.
        Parameters:
        collection - the collection to add the elements
        Throws:
        java.lang.NullPointerException - if collection is null
      • toArray

        public E[] toArray​(java.lang.Class<E> arrayClass)
        Returns an array containing all elements of this iterable by traversing its iterator.
        Parameters:
        arrayClass - the class of array to create
        Returns:
        an array of the iterable contents
        Throws:
        java.lang.ArrayStoreException - if arrayClass is invalid
      • toList

        public java.util.List<E> toList()
        Returns a mutable list containing all elements of this iterable by traversing its iterator.

        The returned list is guaranteed to be mutable.

        Returns:
        a list of the iterable contents
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object