Top Description Fields Constructors Methods
org.apache.commons.collections4

public Class FluentIterable<E>

extends Object
implements Iterable<E>
Class Inheritance
All Implemented Interfaces
java.lang.Iterable
Known Direct Subclasses
org.apache.commons.collections4.IterableUtils.UnmodifiableIterable
Type Parameters
<E>
the element type
Imports
java.util.Arrays, .Collection, .Comparator, .Enumeration, .Iterator, .List, org.apache.commons.collections4.iterators.SingletonIterator

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:

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

Field Summary

Modifier and TypeField and Description
private final Iterable<E>
iterable

A reference to the wrapped iterable.

Constructor Summary

AccessConstructor and Description
pack-priv
FluentIterable()

Package-private constructor, used by IterableUtils.

private
FluentIterable(final Iterable<E>
the iterable to wrap
iterable
)

Create a new FluentIterable by wrapping the provided iterable.

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if all elements contained in this iterable match the predicate, false otherwise
allMatch
(final Predicate<? super E>
the predicate to use, may not be null
predicate
)

Checks if all elements contained in this iterable are matching the provided predicate.

public boolean

Returns:

true if at least one element contained in this iterable matches the predicate, false otherwise
anyMatch
(final Predicate<? super E>
the predicate to use, may not be null
predicate
)

Checks if this iterable contains any element matching the provided predicate.

public FluentIterable<E>

Returns:

a new iterable, combining this iterable with the elements
append
(final E...
the elements to append to the iterable
elements
)

Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the provided elements.

public FluentIterable<E>

Returns:

a new iterable, combining this iterable with other
append
(final Iterable<? extends E>
the other iterable to combine, may not be null
other
)

Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the elements of the provided iterable.

public Enumeration<E>

Returns:

an Enumeration over the elements of this iterable
asEnumeration
()

Returns an Enumeration that will enumerate all elements contained in this iterable.

public FluentIterable<E>

Returns:

a new iterable, collating this iterable with the other in natural order
collate
(final Iterable<? extends E>
the other iterable to collate, may not be null
other
)

Returns a new FluentIterable whose iterator will traverse the elements of the current and provided iterable in natural order.

public FluentIterable<E>

Returns:

a new iterable, collating this iterable with the other in natural order
collate
(final Iterable<? extends E>
the other iterable to collate, may not be null
other
,
final Comparator<? super E>
the comparator to define an ordering, may be null, in which case natural ordering will be used
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.

public boolean

Returns:

true if the object is contained in this iterable, false otherwise
contains
(final Object
the object to check
object
)

Checks if the object is contained in this iterable.

public void
copyInto(final Collection<? super E>
the collection to add the elements
collection
)

Traverses an iterator of this iterable and adds all elements to the provided collection.

public static <
the element type
T
>
FluentIterable<T>

Returns:

a new empty FluentIterable
empty
()

Creates a new empty FluentIterable.

public FluentIterable<E>

Returns:

a new iterable with the same contents as this iterable
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.

public FluentIterable<E>

Returns:

a new iterable, providing a filtered view of this iterable
filter
(final Predicate<? super E>
the predicate used to filter elements
predicate
)

Returns a new FluentIterable whose iterator will only return elements from this iterable matching the provided predicate.

public void
forEach(final Closure<? super E>
the closure to apply to each element, may not be null
closure
)

Applies the closure to all elements contained in this iterable.

public E

Returns:

the element
get
(final int
the position of the element to return
position
)

Returns the element at the provided position in this iterable.

public boolean

Returns:

true if this iterable does not contain any elements, false otherwise
isEmpty
()

Checks if this iterable is empty.

public Iterator<E>
iterator()

Implements java.lang.Iterable.iterator.

Returns an iterator over elements of type T.
public FluentIterable<E>

Returns:

a new iterable, providing a bounded view of this iterable
limit
(final long
the maximum number of elements
maxSize
)

Returns a new FluentIterable whose iterator will return at most the provided maximum number of elements from this iterable.

public FluentIterable<E>

Returns:

a new iterable, providing a looping view of this iterable
loop
()

Returns a new FluentIterable whose iterator will loop infinitely over the elements from this iterable.

public static <
the element type
T
>
FluentIterable<T>

Returns:

a new FluentIterable containing the singleton
of
(final T
the singleton element
singleton
)

Creates a new FluentIterable of the single provided element.

public static <
the element type
T
>
FluentIterable<T>

Returns:

a new FluentIterable containing the provided elements
of
(final T...
the elements to be contained in the FluentIterable
elements
)

Creates a new FluentIterable from the provided elements.

public static <
the element type
T
>
FluentIterable<T>

Returns:

a new FluentIterable wrapping the provided iterable
of
(final Iterable<T>
the iterable to wrap into a FluentIterable, may not be null
iterable
)

Construct a new FluentIterable from the provided iterable.

public FluentIterable<E>

Returns:

a new iterable, providing a reversed view of this iterable
reverse
()

Returns a new FluentIterable whose iterator will traverse the elements from this iterable in reverse order.

public int

Returns:

the size of this iterable
size
()

Returns the number of elements that are contained in this iterable.

public FluentIterable<E>

Returns:

a new iterable, providing a view of this iterable by skipping the first N elements
skip
(final long
the number of elements to skip
elementsToSkip
)

Returns a new FluentIterable whose iterator will skip the first N elements from this iterable.

public E[]

Returns:

an array of the iterable contents
toArray
(final Class<E>
the class of array to create
arrayClass
)

Returns an array containing all elements of this iterable by traversing its iterator.

public List<E>

Returns:

a list of the iterable contents
toList
()

Returns a mutable list containing all elements of this iterable by traversing its iterator.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
public <
the output element type
O
>
FluentIterable<O>

Returns:

a new iterable, providing a transformed view of this iterable
transform
(final Transformer<? super E, ? extends O>
the transformer applied to each element
transformer
)

Returns a new FluentIterable whose iterator will return all elements of this iterable transformed by the provided transformer.

public FluentIterable<E>

Returns:

a new iterable, providing a unique view of this iterable
unique
()

Returns a new FluentIterable whose iterator will return a unique view of this iterable.

public FluentIterable<E>

Returns:

a new iterable, providing an unmodifiable view of this iterable
unmodifiable
()

Returns a new FluentIterable whose iterator will return an unmodifiable view of this iterable.

public FluentIterable<E>

Returns:

a new iterable, interleaving this iterable with others
zip
(final Iterable<? extends E>
the other iterable to interleave, may not be null
other
)

Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterable in alternating order.

public FluentIterable<E>

Returns:

a new iterable, interleaving this iterable with others
zip
(final Iterable<? extends E>...
the iterables to interleave, may not be null
others
)

Returns a new FluentIterable whose iterator will traverse the elements of this iterable and the other iterables in alternating order.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

iterableback to summary
private final Iterable<E> iterable

A reference to the wrapped iterable.

Constructor Detail

FluentIterableback to summary
pack-priv FluentIterable()

Package-private constructor, used by IterableUtils.

FluentIterableback to summary
private FluentIterable(final Iterable<E> iterable)

Create a new FluentIterable by wrapping the provided iterable.

Parameters
iterable:Iterable<E>

the iterable to wrap

Method Detail

allMatchback to summary
public boolean allMatch(final 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:Predicate<? super E>

the predicate to use, may not be null

Returns:boolean

true if all elements contained in this iterable match the predicate, false otherwise

Exceptions
NullPointerException:
if predicate is null
anyMatchback to summary
public boolean anyMatch(final Predicate<? super E> predicate)

Checks if this iterable contains any element matching the provided predicate.

A null or empty iterable returns false.

Parameters
predicate:Predicate<? super E>

the predicate to use, may not be null

Returns:boolean

true if at least one element contained in this iterable matches the predicate, false otherwise

Exceptions
NullPointerException:
if predicate is null
appendback to summary
public FluentIterable<E> append(final E... elements)

Returns a new FluentIterable whose iterator will first traverse the elements of the current iterable, followed by the provided elements.

Parameters
elements:E[]

the elements to append to the iterable

Returns:FluentIterable<E>

a new iterable, combining this iterable with the elements

appendback to summary
public FluentIterable<E> append(final 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:Iterable<? extends E>

the other iterable to combine, may not be null

Returns:FluentIterable<E>

a new iterable, combining this iterable with other

Exceptions
NullPointerException:
if other is null
asEnumerationback to summary
public Enumeration<E> asEnumeration()

Returns an Enumeration that will enumerate all elements contained in this iterable.

Returns:Enumeration<E>

an Enumeration over the elements of this iterable

collateback to summary
public FluentIterable<E> collate(final 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:Iterable<? extends E>

the other iterable to collate, may not be null

Returns:FluentIterable<E>

a new iterable, collating this iterable with the other in natural order

Exceptions
NullPointerException:
if other is null
See Also
org.apache.commons.collections4.iterators.CollatingIterator
collateback to summary
public FluentIterable<E> collate(final Iterable<? extends E> other, final 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
other:Iterable<? extends E>

the other iterable to collate, may not be null

comparator:Comparator<? super E>

the comparator to define an ordering, may be null, in which case natural ordering will be used

Returns:FluentIterable<E>

a new iterable, collating this iterable with the other in natural order

Exceptions
NullPointerException:
if other is null
See Also
org.apache.commons.collections4.iterators.CollatingIterator
containsback to summary
public boolean contains(final Object object)

Checks if the object is contained in this iterable.

Parameters
object:Object

the object to check

Returns:boolean

true if the object is contained in this iterable, false otherwise

copyIntoback to summary
public void copyInto(final Collection<? super E> collection)

Traverses an iterator of this iterable and adds all elements to the provided collection.

Parameters
collection:Collection<? super E>

the collection to add the elements

Exceptions
NullPointerException:
if collection is null
emptyback to summary
public static <T> FluentIterable<T> empty()

Creates a new empty FluentIterable.

Parameters
<T>
the element type
Returns:FluentIterable<T>

a new empty FluentIterable

evalback to summary
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:FluentIterable<E>

a new iterable with the same contents as this iterable

filterback to summary
public FluentIterable<E> filter(final Predicate<? super E> predicate)

Returns a new FluentIterable whose iterator will only return elements from this iterable matching the provided predicate.

Parameters
predicate:Predicate<? super E>

the predicate used to filter elements

Returns:FluentIterable<E>

a new iterable, providing a filtered view of this iterable

Exceptions
NullPointerException:
if predicate is null
forEachback to summary
public void forEach(final Closure<? super E> closure)

Applies the closure to all elements contained in this iterable.

Parameters
closure:Closure<? super E>

the closure to apply to each element, may not be null

Exceptions
NullPointerException:
if closure is null
getback to summary
public E get(final 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:int

the position of the element to return

Returns:E

the element

Exceptions
IndexOutOfBoundsException:
if the provided position is outside the valid range of this iterable: [0, size)
isEmptyback to summary
public boolean isEmpty()

Checks if this iterable is empty.

Returns:boolean

true if this iterable does not contain any elements, false otherwise

iteratorback to summary
public Iterator<E> iterator()

Implements java.lang.Iterable.iterator.

Doc from java.lang.Iterable.iterator.

Returns an iterator over elements of type T.

Returns:Iterator<E>

an Iterator.

Annotations
@Override
limitback to summary
public FluentIterable<E> limit(final long maxSize)

Returns a new FluentIterable whose iterator will return at most the provided maximum number of elements from this iterable.

Parameters
maxSize:long

the maximum number of elements

Returns:FluentIterable<E>

a new iterable, providing a bounded view of this iterable

Exceptions
IllegalArgumentException:
if maxSize is negative
loopback to summary
public FluentIterable<E> loop()

Returns a new FluentIterable whose iterator will loop infinitely over the elements from this iterable.

Returns:FluentIterable<E>

a new iterable, providing a looping view of this iterable

ofback to summary
public static <T> FluentIterable<T> of(final T singleton)

Creates a new FluentIterable of the single provided element.

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

Parameters
<T>
the element type
singleton:T

the singleton element

Returns:FluentIterable<T>

a new FluentIterable containing the singleton

ofback to summary
public static <T> FluentIterable<T> of(final T... elements)

Creates a new FluentIterable from the provided elements.

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

Parameters
<T>
the element type
elements:T[]

the elements to be contained in the FluentIterable

Returns:FluentIterable<T>

a new FluentIterable containing the provided elements

ofback to summary
public static <T> FluentIterable<T> of(final 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.

Parameters
<T>
the element type
iterable:Iterable<T>

the iterable to wrap into a FluentIterable, may not be null

Returns:FluentIterable<T>

a new FluentIterable wrapping the provided iterable

Exceptions
NullPointerException:
if iterable is null
reverseback to summary
public FluentIterable<E> reverse()

Returns a new FluentIterable whose iterator will traverse the elements from this iterable in reverse order.

Returns:FluentIterable<E>

a new iterable, providing a reversed view of this iterable

sizeback to summary
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:int

the size of this iterable

skipback to summary
public FluentIterable<E> skip(final long elementsToSkip)

Returns a new FluentIterable whose iterator will skip the first N elements from this iterable.

Parameters
elementsToSkip:long

the number of elements to skip

Returns:FluentIterable<E>

a new iterable, providing a view of this iterable by skipping the first N elements

Exceptions
IllegalArgumentException:
if elementsToSkip is negative
toArrayback to summary
public E[] toArray(final Class<E> arrayClass)

Returns an array containing all elements of this iterable by traversing its iterator.

Parameters
arrayClass:Class<E>

the class of array to create

Returns:E[]

an array of the iterable contents

Exceptions
ArrayStoreException:
if arrayClass is invalid
toListback to summary
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:List<E>

a list of the iterable contents

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
transformback to summary
public <O> FluentIterable<O> transform(final Transformer<? super E, ? extends O> transformer)

Returns a new FluentIterable whose iterator will return all elements of this iterable transformed by the provided transformer.

Parameters
<O>
the output element type
transformer:Transformer<? super E, ? extends O>

the transformer applied to each element

Returns:FluentIterable<O>

a new iterable, providing a transformed view of this iterable

Exceptions
NullPointerException:
if transformer is null
uniqueback to summary
public FluentIterable<E> unique()

Returns a new FluentIterable whose iterator will return a unique view of this iterable.

Returns:FluentIterable<E>

a new iterable, providing a unique view of this iterable

unmodifiableback to summary
public FluentIterable<E> unmodifiable()

Returns a new FluentIterable whose iterator will return an unmodifiable view of this iterable.

Returns:FluentIterable<E>

a new iterable, providing an unmodifiable view of this iterable

zipback to summary
public FluentIterable<E> zip(final 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:Iterable<? extends E>

the other iterable to interleave, may not be null

Returns:FluentIterable<E>

a new iterable, interleaving this iterable with others

Exceptions
NullPointerException:
if other is null
zipback to summary
public FluentIterable<E> zip(final 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:Iterable<? extends E>[]

the iterables to interleave, may not be null

Returns:FluentIterable<E>

a new iterable, interleaving this iterable with others

Exceptions
NullPointerException:
if either of the provided iterables is null