Package org.apache.commons.collections4

Class FluentIterable<E>

java.lang.Object
org.apache.commons.collections4.FluentIterable<E>
Type Parameters:
E - the element type
All Implemented Interfaces:
Iterable<E>
public class FluentIterable<E> extends Object implements 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

    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(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.
    Enumeration<E>
    asEnumeration()
    Returns an Enumeration that will enumerate all elements contained in this iterable.
    FluentIterable<E>
    collate(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(Iterable<? extends E> other, 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 a comparator.
    boolean
    contains(Object object)
    Checks if the object is contained in this iterable.
    void
    copyInto(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.
    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(Iterable<T> iterable)
    Constructs 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(Class<E> arrayClass)
    Returns an array containing all elements of this iterable by traversing its iterator.
    List<E>
    toList()
    Returns a mutable list containing all elements of this iterable by traversing its iterator.
    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(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(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

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Method Details

    • 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(Iterable<T> iterable)
      Constructs 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:
      NullPointerException - if iterable is null

    • 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

    • 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:
      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:
      NullPointerException - if predicate 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(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:
      NullPointerException - if other is null

    • asEnumeration

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

    • collate

      public FluentIterable<E> collate(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:
      NullPointerException - if other is null
      See Also:

    • collate

      public FluentIterable<E> collate(Iterable<? extends E> other, 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 a 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:
      other - the other iterable to collate, may not be null
      comparator - the comparator to define an ordering, may be null, in which case natural ordering will be used
      Returns:
      a new iterable, collating this iterable with the other in natural order
      Throws:
      NullPointerException - if other is null
      See Also:

    • contains

      public boolean contains(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

    • copyInto

      public void copyInto(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:
      NullPointerException - if collection is null

    • 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:
      NullPointerException - if predicate is null

    • 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:
      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:
      IndexOutOfBoundsException - if the provided position is outside the valid range of this iterable: [0, size)

    • isEmpty

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

    • iterator

      public Iterator<E> iterator()
      Specified by:
      iterator in interface Iterable<E>

    • 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:
      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

    • 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

    • 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:
      IllegalArgumentException - if elementsToSkip is negative

    • toArray

      public E[] toArray(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:
      ArrayStoreException - if arrayClass is invalid

    • toList

      public 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 String toString()
      Overrides:
      toString in class Object

    • 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:
      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(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:
      NullPointerException - if other is null

    • zip

      public FluentIterable<E> zip(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:
      NullPointerException - if either of the provided iterables is null