net.sf.staccatocommons.collections.iterable
Class Iterables

java.lang.Object
  net.sf.staccatocommons.collections.iterable.Iterables

public class Iterables
extends Object

Class methods that complement the Collections functionality, providing common algorithms for collections and iterables. With no exception, all these methods are eager, that is, processing is completely performed on method evaluation. Otherwise stated, null collections, functors and iterables are prohibited as parameter, but empty collections and iterables are allowed. Iterables class contains only side-effect-free methods that do not modify any of its arguments, and thus can be used with immutable collections. For algorithms that modify the state of the input collections, see ModifiableIterables. However, Stacatto-commons-collection API recommends to avoid those methods when possible, as will fail with unmodifiable collections.

Author:

flbulgarelli

Constructor Summary

Iterables()

Method Summary

static <A> boolean	all(Iterable<A> iterable, Evaluable<? super A> predicate) Tests if all the elements of the given Iterable satisfy the given predicate
static <A> boolean	allEqual(Iterable<A> iterable) Answers if all elements in the collection are equal.
static <A> boolean	allEquivBy(Iterable<A> iterable, Evaluable2<? super A,? super A> equivTest) Answers if all elements in the collection are equivalent using the given equivTest.
static <A> boolean	allSame(Iterable<A> iterable) Answers if all elements in the collection are the same object.
static <A> A	any(Iterable<A> iterable) Returns any element from this iterable, or throws a NoSuchElementException it iterable is empty.
static <A> boolean	any(Iterable<A> iterable, Evaluable<? super A> predicate) Tests if any of the elements of the given Iterable satisfy the given predicate
static <A> Option<A>	anyOrNone(Iterable<A> iterable) Gets any element of the given collection.
static <A> boolean	containsBefore(Iterable<A> iterable, A element, A next) Answers if element is contained by the given iterable, and its first occurrence is before the first occurrence of the second one, if any.
static <A> boolean	containsBeforeIndex(Iterable<A> iterable, A element, int index) Answers if element is contained by the given iterable, and its first occurrence is before the given index.
static <A> int	countOf(Iterable<A> iterable, Evaluable<? super A> predicate) Answers the number of element that satisfy the given predicate
static <A,B> List<Tuple2<A,B>>	cross(Collection<A> collection1, Collection<B> collection2) Answers the Cartesian product of the two given Collections.
static <A,B> List<Tuple2<A,B>>	cross(Iterable<A> iterable1, Iterable<B> iterable2) Answers the Cartesian product of the two given Iterables.
static <A> boolean	equiv(Iterable<? extends A> iterable1, Iterable<? extends A> iterable2) Test that the elements of both iterables are equal, and in the same order.
static <A> boolean	equivBy(Iterable<? extends A> iterable1, Iterable<? extends A> iterable2, Evaluable2<? super A,? super A> equivTest) Test that the elements of of both iterables are equal, and in the same order, using the given equalityTest for determining equality of elements.
static <A> List<A>	filter(Iterable<A> iterable, Evaluable<? super A> predicate) Selects all elements that evaluate to true.
static <A> A	find(Iterable<A> iterable, Evaluable<? super A> predicate) Alternative version of findOrNone(Iterable, Evaluable), where the element is returned if found, or a NoSuchElementException is thrown otherwise
static <A> Option<A>	findOrNone(Iterable<A> iterable, Evaluable<? super A> predicate) Looks for a object that matches the given predicate.
static <A,B> List<B>	flatMap(Iterable<A> iterable, Applicable<? super A,? extends Iterable<B>> function) Maps the given iterable into a list of iterables using the given function, and flattens the result, concatenating all the resulting iterables into a List
static <A,B> B	fold(Iterable<A> iterable, B initial, Applicable2<? super B,? super A,? extends B> function) Answers the result of aggregating the given initial value and the Iterable elements using the given function As a particular case, if iterable is empty, this method returns the initial value.
static <A> A	get(Iterable<A> iterable, int n) Gets the zero-based, n-th element of the given Iterable, according to its iteration order.
static <A> int	indexOf(Iterable<A> iterable, A element) The zero-based index of a given element in the iterable when iterating over it
static <A> boolean	isBefore(Iterable<A> iterable, A previous, A next) Whether an element is before another when iterating through the given iterable.
static <A> boolean	isEmpty(Iterable<A> iterable) Answers if the given Iterable is empty or not, that is, if its iterator returns at least one element.
static <A> boolean	isNullOrEmpty(Collection<A> collection) Answers if the given Collection is empty or null
static <A> boolean	isNullOrEmpty(Iterable<A> iterable) Answers if the given Iterable is empty or null
static <A,B> List<B>	map(Collection<A> collection, Applicable<? super A,? extends B> function) Maps the given Collection into a new List, using the given function The resulting list contains contains the result of applying the given function to each element retrieved from the original iterable
static <A,B> List<B>	map(Iterable<A> iterable, Applicable<? super A,? extends B> function) Maps the given Iterable into a new list, using the given function.
static <A> Tuple2<List<A>,List<A>>	partition(Iterable<A> iterable, Evaluable<? super A> predicate) Splits the given iterable by returning two Lists, the first one containing those elements that satisfy the given predicate, and the second one containing those elements that do not satisfy it.
static <A> A	product(Iterable<A> iterable, NumberType<A> type) Answers the product of the numeric elements of the given Iterable, using the given NumberType to implement the multiplication.
static <A> A	reduce(Iterable<A> iterable, Applicable2<? super A,? super A,? extends A> function) Answers the result of aggregating the given iterable elements using the given function.
static <A,B> B	reduce(Iterable<A> iterable, Reduction<? super A,B> reduction) Answers the result of aggregating the given iterable using the given reduction
static <A> A	single(Collection<A> collection) Returns the single element of the given collection.
static int	size(Iterable<?> iterable) Answers the size of the given iterable, that is, the number of elements it retrieves
static <A> A	sum(Iterable<A> iterable, NumberType<A> type) Answers the sum of the numeric elements of the given Iterable, using the given NumberType to implement the addition.
static <A> List<A>	take(Iterable<A> iterable, int amountOfElements) Selects at most the fist N elements from the iterable, according to its iteration order.
static <A> List<A>	toList(Collection<A> collection) Converts the given collection into a List.
static <A> List<A>	toList(Iterable<A> iterable) Converts the given iterable into a List.
static <A> Set<A>	toSet(A... elements) Converts the given elements into a Set.
static <A> Set<A>	toSet(Collection<A> collection) Converts the given collection into a Set.
static <A> Set<A>	toSet(Iterable<A> iterable) Converts the given Iterable into a Set.
static <A> List<A>	toSortedList(Iterable<A> iterable, Comparator<? super A> comparator) Sorts a the given iterable into a new list, using the given comparator.
static <A extends Comparable<A>> SortedSet<A>	toSortedSet(Iterable<A> iterable) Sorts a given iterable using its natural ordering
static <A> SortedSet<A>	toSortedSet(Iterable<A> iterable, Comparator<? super A> comparator) Sorts a given iterable using the given Comparator into a new SortedSet
static <A,B> List<Tuple2<A,B>>	zip(Iterable<A> iterable1, Iterable<B> iterable2) Returns a List formed by Tuple2 of elements from the two iterables.
static <A,B,C> List<C>	zip(Iterable<A> iterable1, Iterable<B> iterable2, Applicable2<A,B,C> function) Returns a List formed by the result of applying the given function to each Tuple2 of elements from the two iterables given.

Methods inherited from class java.lang.Object

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

Constructor Detail

Iterables

public Iterables()

Method Detail

filter

@NonNull
public static <A> List<A> filter(@NonNull
                                         Iterable<A> iterable,
                                         @NonNull
                                         Evaluable<? super A> predicate)

Selects all elements that evaluate to true.

Type Parameters:

A -

Parameters:

iterable -

predicate -

Returns:

a list containing only elements from the original iterable that evaluate to true

take

@NonNull
public static <A> List<A> take(@NonNull
                                       Iterable<A> iterable,
                                       @NotNegative
                                       int amountOfElements)

Selects at most the fist N elements from the iterable, according to its iteration order.

Type Parameters:

A -

Parameters:

iterable -

amountOfElements -

Returns:

a new list containing at most the first N elements from original iterable.

reduce

@NonNull
public static <A> A reduce(@NonNull
                                   Iterable<A> iterable,
                                   @NonNull
                                   Applicable2<? super A,? super A,? extends A> function)

Answers the result of aggregating the given iterable elements using the given function.

Type Parameters:

A - the Iterable's elements type

Parameters:

iterable -

function - the aggregation Applicable

Returns:

the result of aggregating the iterable's element

Throws:

NoSuchElementException - if the given Iterable is empty.

fold

@NonNull
public static <A,B> B fold(@NonNull
                                   Iterable<A> iterable,
                                   B initial,
                                   @NonNull
                                   Applicable2<? super B,? super A,? extends B> function)

Answers the result of aggregating the given initial value and the Iterable elements using the given function As a particular case, if iterable is empty, this method returns the initial value.

Type Parameters:

A - the Iterable's elements type

B - the aggregated value type

Parameters:

iterable -

initial -

function - the aggregation Applicable

Returns:

the result of aggregating the initial value and the given iterable's elements.

reduce

@NonNull
public static <A,B> B reduce(@NonNull
                                     Iterable<A> iterable,
                                     @NonNull
                                     Reduction<? super A,B> reduction)

Answers the result of aggregating the given iterable using the given reduction

Type Parameters:

A - the Iterable's elements type

B - the aggregated value type

Parameters:

iterable - the iterable to aggregate

function - the Reduction to apply to this iterable

Returns:

the result of aggregating the initial value and the given iterable's elements.

find

public static <A> A find(@NonNull
                         Iterable<A> iterable,
                         @NonNull
                         Evaluable<? super A> predicate)

Alternative version of findOrNone(Iterable, Evaluable), where the element is returned if found, or a NoSuchElementException is thrown otherwise

Type Parameters:

A -

Parameters:

iterable -

predicate -

Returns:

the element if found

Throws:

NoSuchElementException - if no element matches the predicate

findOrNone

@NonNull
public static <A> Option<A> findOrNone(@NonNull
                                               Iterable<A> iterable,
                                               @NonNull
                                               Evaluable<? super A> predicate)

Looks for a object that matches the given predicate. If such element does not exist, or collection is empty, returns Option.none(). Otherwise returns Option.some(Object), for the first object found

Type Parameters:

A -

Parameters:

iterable - non null

predicate - non null

Returns:

None if no element matches the predicate or collection is empty, or some(element) if at least one exists

single

public static <A> A single(@Size(value=1)
                           Collection<A> collection)

Returns the single element of the given collection. It must be of size 1, otherwise, throws an IllegalArgumentException.

Type Parameters:

A - the collection type

Parameters:

collection - a single element (size==1) collection

Returns:

The unique element of the collection

any

public static <A> A any(@NonNull
                        Iterable<A> iterable)

Returns any element from this iterable, or throws a NoSuchElementException it iterable is empty. Notice that any does not mean random, it may return always the same element - for example the first for a list -, but the exact element returned from the iterable unspecified.

Type Parameters:

A -

Parameters:

iterable -

Returns:

an element contained in the given iterable. This is nullable, if the iterables's iterator may return null.

Throws:

NoSuchElementException - if the iterable is empty

anyOrNone

@NonNull
public static <A> Option<A> anyOrNone(@NonNull
                                              Iterable<A> iterable)

Gets any element of the given collection. Returns Option.some(element) if not empty, or Option.none(), if empty.

Type Parameters:

A -

Parameters:

iterable -

Returns:

some(element) if not empty, or none, otherwise.

all

public static <A> boolean all(@NonNull
                              Iterable<A> iterable,
                              @NonNull
                              Evaluable<? super A> predicate)

Tests if all the elements of the given Iterable satisfy the given predicate

Type Parameters:

A -

Parameters:

iterable -

predicate - the predicate that will be used to evaluate each element

Returns:

true if all the elements satisfy the given predicate, false otherwise. As a particular case of this rule, this method will return true for empty iterables, regardless of the predicate.

allEquivBy

public static <A> boolean allEquivBy(@NonNull
                                     Iterable<A> iterable,
                                     Evaluable2<? super A,? super A> equivTest)

Answers if all elements in the collection are equivalent using the given equivTest.

Type Parameters:

A -

Parameters:

iterable - May be empty.

equivTest - a predicate used to determine if two elements are equivalent

Returns:

trueif all element are the same object. false otherwise. As a particular case of this rule, if this collection is empty or has only one element, it will return true.

allEqual

public static <A> boolean allEqual(@NonNull
                                   Iterable<A> iterable)

Answers if all elements in the collection are equal.

Type Parameters:

A -

Parameters:

iterable - non null. May be empty.

Returns:

trueif all element are equal. false otherwise. As a particular case of this rule, if this collection is empty or has only one element, it will return true.

allSame

public static <A> boolean allSame(@NonNull
                                  Iterable<A> iterable)

Answers if all elements in the collection are the same object.

Type Parameters:

A -

Parameters:

iterable - non null. May be empty.

Returns:

trueif all element are the same object. false otherwise. As a particular case of this rule, if this collection is empty or has only one element, it will return true.

any

public static <A> boolean any(@NonNull
                              Iterable<A> iterable,
                              Evaluable<? super A> predicate)

Tests if any of the elements of the given Iterable satisfy the given predicate

Type Parameters:

A -

Parameters:

iterable -

predicate - the predicate that will be used to evaluate each element

Returns:

true if at least one element satisfies the given predicate, false otherwise. As a particular case of this rule, this method will return false for empty iterables, regardless of the predicate.

isEmpty

public static <A> boolean isEmpty(@NonNull
                                  Iterable<A> iterable)

Answers if the given Iterable is empty or not, that is, if its iterator returns at least one element.

Type Parameters:

A - the iterable element type

Parameters:

iterable -

Returns:

if the iterable is empty or not

isNullOrEmpty

public static <A> boolean isNullOrEmpty(Iterable<A> iterable)

Answers if the given Iterable is empty or null

Type Parameters:

A - the iterable element type

Parameters:

iterable -

Returns:

if the iterable is null or empty

See Also:

isEmpty(Iterable)

isNullOrEmpty

public static <A> boolean isNullOrEmpty(Collection<A> collection)

Answers if the given Collection is empty or null

Type Parameters:

A - the collection element type

Parameters:

collection -

Returns:

if the collection is null or empty

size

public static int size(@NonNull
                       Iterable<?> iterable)

Answers the size of the given iterable, that is, the number of elements it retrieves

Parameters:

iterable -

Returns:

the number of elements in the given Iterable

countOf

public static <A> int countOf(@NonNull
                              Iterable<A> iterable,
                              Evaluable<? super A> predicate)

Answers the number of element that satisfy the given predicate

Parameters:

predicate -

Returns:

filter(predicate).size()

Since:

2.1

equiv

public static <A> boolean equiv(@NonNull
                                Iterable<? extends A> iterable1,
                                @NonNull
                                Iterable<? extends A> iterable2)

Test that the elements of both iterables are equal, and in the same order.

Type Parameters:

A -

Parameters:

iterable1 - first iterable

iterable2 - second iterable

Returns:

true if iterable1 has the same number of elements that iterable2, and each Tuple2 formed by elements of both iterables at same position are equal. false otherwise

equivBy

public static <A> boolean equivBy(@NonNull
                                  Iterable<? extends A> iterable1,
                                  @NonNull
                                  Iterable<? extends A> iterable2,
                                  Evaluable2<? super A,? super A> equivTest)

Test that the elements of of both iterables are equal, and in the same order, using the given equalityTest for determining equality of elements.

Parameters:

equivTest -

equalityTest -

Returns:

true if iterable1 has the same number of elements that iterable2, and each Tuple2 formed by elements of both iterables at same position are equivalent using the given eqivTest. false otherwise

map

@NonNull
public static <A,B> List<B> map(@NonNull
                                        Collection<A> collection,
                                        @NonNull
                                        Applicable<? super A,? extends B> function)

Maps the given Collection into a new List, using the given function The resulting list contains contains the result of applying the given function to each element retrieved from the original iterable

Type Parameters:

A - the element type of the given collection

B - the element type of the resulting list

Parameters:

collection - the source of the mapping.

function - an Applicable applied to each element of the source collection.

Returns:

a new, non null List. As a particular case, this method will return an empty list if the given collection is empty, regardless of the given Applicable

map

@NonNull
public static <A,B> List<B> map(@NonNull
                                        Iterable<A> iterable,
                                        @NonNull
                                        Applicable<? super A,? extends B> function)

Maps the given Iterable into a new list, using the given function. The returned list contains contains the result of applying the given function to each element retrieved from the original iterable

Type Parameters:

A - the element type of the given iterables

B - the element type of the resulting list

Parameters:

iterable - the source of the mapping.

function - the function applied to each element of the source iterable.

Returns:

a new, non null List. As a particular case, this method will return an empty list if the given iterable is empty

flatMap

@NonNull
public static <A,B> List<B> flatMap(@NonNull
                                            Iterable<A> iterable,
                                            @NonNull
                                            Applicable<? super A,? extends Iterable<B>> function)

Maps the given iterable into a list of iterables using the given function, and flattens the result, concatenating all the resulting iterables into a List

Type Parameters:

A -

B -

Parameters:

iterable -

function -

Returns:

a new List

toSortedList

@NonNull
public static <A> List<A> toSortedList(@NonNull
                                               Iterable<A> iterable,
                                               @NonNull
                                               Comparator<? super A> comparator)

Sorts a the given iterable into a new list, using the given comparator.

Type Parameters:

A -

Parameters:

iterable - the the collection.

comparator -

Returns:

a new list containing all the original colleciton elements, sorted using the given criteria, or an empty mutable list, if the original Iterable was empty.

toSortedSet

@NonNull
public static <A> SortedSet<A> toSortedSet(@NonNull
                                                   Iterable<A> iterable,
                                                   @NonNull
                                                   Comparator<? super A> comparator)

Sorts a given iterable using the given Comparator into a new SortedSet

Type Parameters:

A -

Parameters:

iterable - the Iterable to sort

comparator -

Returns:

a sorted set containing the iterables elements sorted using the given comparator

toSortedSet

@NonNull
public static <A extends Comparable<A>> SortedSet<A> toSortedSet(@NonNull
                                                                         Iterable<A> iterable)

Sorts a given iterable using its natural ordering

Type Parameters:

A -

Parameters:

iterable - the Iterable to sort

Returns:

a sorted set containing the iterables elements sorted using the given comparator

toSet

public static <A> Set<A> toSet(A... elements)

Converts the given elements into a Set.

Type Parameters:

A -

Parameters:

elements -

Returns:

a new Set that contains the elements given without repetitions

toSet

public static <A> Set<A> toSet(Collection<A> collection)

Converts the given collection into a Set. If the collection is already a set, it just returns it

Type Parameters:

A -

Parameters:

collection -

Returns:

a new Set that contains all the elements from the given collection, or the given collection, if it is already a set

toSet

@NonNull
public static <A> Set<A> toSet(@NonNull
                                       Iterable<A> iterable)

Converts the given Iterable into a Set. If the iterable is already a set, it just returns it

Type Parameters:

A -

Parameters:

iterable -

Returns:

a new Set that contains all the elements from the given iterable, or the given iterable, if it is already a set

toList

public static <A> List<A> toList(@NonNull
                                 Collection<A> collection)

Converts the given collection into a List. If the collection is already a list, it just returns it

Type Parameters:

A -

Parameters:

collection -

Returns:

a new List that contains all the elements from the given collection, or the given collection, if it is already a list

toList

public static <A> List<A> toList(Iterable<A> iterable)

Converts the given iterable into a List. If the iterable is already a list, it just returns it

Type Parameters:

A -

Parameters:

iterable -

Returns:

a new List that contains all the elements from the given iterable, or the given collection, if it is already a list

partition

public static <A> Tuple2<List<A>,List<A>> partition(@NonNull
                                                    Iterable<A> iterable,
                                                    Evaluable<? super A> predicate)

Splits the given iterable by returning two Lists, the first one containing those elements that satisfy the given predicate, and the second one containing those elements that do not satisfy it. For example, the following code:

 Iterables.partition(Arrays.asList(4, 8, 5, 20, 1), Predicate.greaterThan(5));
 

will return a Tuple2 equal to:

 _(Arrays.asList(8, 20), Arrays.asList(4, 5, 1))
 

Type Parameters:

A -

Parameters:

iterable -

predicate - the Evaluable used to determine if an elements goes into the first or second list

Returns:

a Tuple2 of lists

get

public static <A> A get(@NonNull
                        Iterable<A> iterable,
                        int n)
             throws IndexOutOfBoundsException

Gets the zero-based, n-th element of the given Iterable, according to its iteration order.

Type Parameters:

A -

Parameters:

iterable -

n -

Returns:

the n-th element

Throws:

IndexOutOfBoundsException - if n is greater or equal than the size of the iterable

indexOf

public static <A> int indexOf(@NonNull
                              Iterable<A> iterable,
                              A element)

The zero-based index of a given element in the iterable when iterating over it

Type Parameters:

A -

Parameters:

iterable -

element -

Returns:

the index of the element in the given iterable, or -1 if it is not contained on it

isBefore

public static <A> boolean isBefore(@NonNull
                                   Iterable<A> iterable,
                                   A previous,
                                   A next)

Whether an element is before another when iterating through the given iterable.

Type Parameters:

A -

Parameters:

iterable -

previous - the element to test if exist in the iterable and is be before next

next - the element to test if exists in the iterable and is after previous

Returns:

true if both elements are contained by the given iterable, and first element is before second one

containsBefore

public static <A> boolean containsBefore(@NonNull
                                         Iterable<A> iterable,
                                         A element,
                                         A next)

Answers if element is contained by the given iterable, and its first occurrence is before the first occurrence of the second one, if any.

This message is similar to #isBefore(Object, Object), but may be true even if the reference is not present at the iterable. It will be always true if both element and reference are equal, too.

Examples:

  List