jaggregate
Class Iterables

java.lang.Object
  jaggregate.Iterables

public class Iterables
extends Object

Functions that offer Collection-like functionality for Iterables.

Version:

$Id: Iterables.java,v 1.8 2008/10/03 19:01:23 pholser Exp $

Author:

Paul Holser

Method Summary

static <E> boolean	allSatisfy(Iterable<? extends E> items, UnaryCondition<? super E> discriminator) Answers true if the given discriminator answers true for every element yielded by the given iterable, or if the iterable yields no elements; otherwise answers false.
static <E> boolean	anySatisfy(Iterable<? extends E> items, UnaryCondition<? super E> discriminator) Answers true if the given discriminator answers true for any element yielded by the given iterable; answers false otherwise, or if the iterable yields no elements.
static <E,R> Iterable<R>	collect(Iterable<? extends E> items, UnaryFunctor<? super E,? extends R> transformer) Wraps the given iterable with another iterable whose iterator will transform items using the given functor.
static <E> E	detect(Iterable<? extends E> items, UnaryCondition<? super E> discriminator) Answers the first element yielded by the given iterable for which the given discriminator answers true when given that element as an argument.
static <E,R> R	inject(Iterable<? extends E> items, R initialValue, BinaryFunctor<? super R,? super E,? extends R> operation) Answers the final result of evaluating the given operation using each element of the given iterable and the previous evaluation result as the parameters.
static <E> int	occurrencesOf(Iterable<? extends E> items, E target) Answers the number of elements yielded by the given iterable which are equivalent to the given target.
static <E> boolean	removeIf(Iterable<? extends E> items, UnaryCondition<? super E> discriminator) Removes items from the given iterable which match the given predicate.
static <E> boolean	retainIf(Iterable<? extends E> items, UnaryCondition<? super E> discriminator) Removes items from the given iterable which do not match the given predicate.
static <E> Iterable<E>	select(Iterable<? extends E> items, UnaryCondition<? super E> discriminator) Wraps the given iterable with another iterable whose iterator will filter out items which do not match the given predicate.

Methods inherited from class java.lang.Object

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

Method Detail

allSatisfy

public static <E> boolean allSatisfy(Iterable<? extends E> items,
                                     UnaryCondition<? super E> discriminator)

Answers true if the given discriminator answers true for every element yielded by the given iterable, or if the iterable yields no elements; otherwise answers false.

It is unspecified whether discriminator will be evaluated with every element that the iterable yields.

Type Parameters:

E - type of the items to iterate over

Parameters:

items - the items to iterate over

discriminator - the discriminator to evaluate

Returns:

whether discriminator is true for every element

Throws:

NullPointerException - if items or discriminator is null

See Also:

Collection.allSatisfy(UnaryCondition)

anySatisfy

public static <E> boolean anySatisfy(Iterable<? extends E> items,
                                     UnaryCondition<? super E> discriminator)

Answers true if the given discriminator answers true for any element yielded by the given iterable; answers false otherwise, or if the iterable yields no elements.

It is unspecified whether discriminator will be evaluated with every element that the iterable yields.

Type Parameters:

E - type of the items to iterate over

Parameters:

items - the items to iterate over

discriminator - the discriminator to evaluate

Returns:

whether discriminator is true for any element

Throws:

NullPointerException - if items or discriminator is null

See Also:

Collection.anySatisfy(UnaryCondition)

collect

public static <E,R> Iterable<R> collect(Iterable<? extends E> items,
                                        UnaryFunctor<? super E,? extends R> transformer)

Wraps the given iterable with another iterable whose iterator will transform items using the given functor.

Type Parameters:

E - type of the items to iterate over

R - type of the transformed iterated items

Parameters:

items - the iterable to wrap

transformer - functor used to transform elements

Returns:

the wrapping, transforming iterable

Throws:

NullPointerException - if items or transformer is null

See Also:

Collection.collect(UnaryFunctor)

detect

public static <E> E detect(Iterable<? extends E> items,
                           UnaryCondition<? super E> discriminator)

Answers the first element yielded by the given iterable for which the given discriminator answers true when given that element as an argument.

discriminator will only be evaluated until such an object is found or until the iterable yields no elements to use as arguments. That is, there may be elements that the iterable yields that are never used as arguments to discriminator.

Type Parameters:

E - type of the items to iterate over

Parameters:

items - the items to iterate over

discriminator - the discriminator to evaluate

Returns:

the first item that satisfies discriminator

Throws:

NoSuchElementException - if no item satisfies discriminator

NullPointerException - if items or discriminator is null

occurrencesOf

public static <E> int occurrencesOf(Iterable<? extends E> items,
                                    E target)

Answers the number of elements yielded by the given iterable which are equivalent to the given target.

Type Parameters:

E - type of the items to iterate over

Parameters:

items - the items to iterate over

target - the object to compare against

Returns:

the number of occurrences of equivalent objects yielded by the iterable

Throws:

NullPointerException - if items is null

inject

public static <E,R> R inject(Iterable<? extends E> items,
                             R initialValue,
                             BinaryFunctor<? super R,? super E,? extends R> operation)

Answers the final result of evaluating the given operation using each element of the given iterable and the previous evaluation result as the parameters.

The first evaluation of operation is performed with the given initial value as the first parameter, and the first element of the iterable as the second parameter. Subsequent evaluations are done with the result of the previous evaluation as the first parameter, and the next element as the second parameter. The result of the last evaluation is answered.

Type Parameters:

E - type of the items to iterate over

R - type of the initial value, intermediate results, and final result

Parameters:

items - the items to iterate over

initialValue - first parameter for the first evaluation

operation - the operation to evaluate

Returns:

the result of the last evaluation

Throws:

NullPointerException - if items or operation is null

See Also:

Collection.inject(Object, BinaryFunctor)

removeIf

public static <E> boolean removeIf(Iterable<? extends E> items,
                                   UnaryCondition<? super E> discriminator)

Removes items from the given iterable which match the given predicate.

Type Parameters:

E - type of the items to iterate over

Parameters:

items - items to iterate over

discriminator - tells which items should be removed

Returns:

true if any removals occurred

Throws:

NullPointerException - if items or discriminator is null

UnsupportedOperationException - if items's iterator does not support removal

See Also:

ExtensibleCollection.removeIf(UnaryCondition)

retainIf

public static <E> boolean retainIf(Iterable<? extends E> items,
                                   UnaryCondition<? super E> discriminator)

Removes items from the given iterable which do not match the given predicate.

Type Parameters:

E - type of the items to iterate over

Parameters:

items - items to iterate over

discriminator - tells which items should be retained

Returns:

true if any removals occurred

Throws:

NullPointerException - if items or discriminator is null

UnsupportedOperationException - if items's iterator does not support removal

See Also:

ExtensibleCollection.retainIf(UnaryCondition)

select

public static <E> Iterable<E> select(Iterable<? extends E> items,
                                     UnaryCondition<? super E> discriminator)

Wraps the given iterable with another iterable whose iterator will filter out items which do not match the given predicate.

Type Parameters:

E - type of the items to iterate over

Parameters:

items - the iterable to wrap

discriminator - predicate used to filter elements

Returns:

the wrapping, filtering iterable

Throws:

NullPointerException - if items or discriminator is null

See Also:

Collection.select(UnaryCondition)