org.apache.tapestry5.func
Interface Flow<T>

All Superinterfaces:

java.lang.Iterable<T>

public interface Flow<T>
extends java.lang.Iterable<T>

A Flow is a a functional interface for working with an ordered collection of values. A given Flow contains only values of a particular type. Standard operations allow for filtering the Flow, or appending values to the Flow. Since Flows are immutable, all operations on Flows return new immutable Flows. Flows are thread safe (to the extent that the Mappers, Predicate s, Workers and Reducers applied to the Flow are). Flows are lazy: filtering, mapping, and concatenating Flows will do so with no, or a minimum, of evaluation. However, converting a Flow into a List will force a realization of the entire Flow.

In some cases, a Flow may be an infinite, lazily evaluated sequence. Operations that iterate over all values (such as count() or reduce(Reducer, Object)) may become infinite loops.

Using Flows allows for a very fluid interface.

Flows are initially created using F.flow(java.util.Collection) or F.flow(Object...).

Since:

5.2.0

See Also:

F.lazy(LazyFunction)

Method Summary

<V extends T> Flow<T>	append(V... values) Appends any number of type compatible values to the end of this Flow.
Flow<T>	concat(Flow<? extends T> other) Returns a new Flow with the other Flow's elements appended to this Flow's.
Flow<T>	concat(java.util.List<? extends T> list) Returns a new Flow with the values in the list appended to this Flow.
int	count() Returns the number of values in the Flow.
Flow<T>	drop(int length) Returns a new Flow with the first values omitted.
Flow<T>	each(Worker<? super T> worker) Applies the worker to each value in the Flow, then returns the flow for further behaviors.
Flow<T>	filter(Predicate<? super T> predicate) Filters values, keeping only values where the predicate is true, returning a new Flow with just the retained values.
T	first() Returns the first value in the Flow.
boolean	isEmpty() Returns true if the Flow contains no values.
<X> Flow<X>	map(Mapper<T,X> mapper) Maps a Flow into a new Flow with different type values.
<X,Y> Flow<Y>	map(Mapper2<T,X,Y> mapper, Flow<? extends X> flow) Combines two Flows using a two-parameter Mapper.
<X> Flow<X>	mapcat(Mapper<T,Flow<X>> mapper) Given a Mapper that maps a T to a Flow, this method will lazily concatenate all the output flows into a single Flow.
<A> A	reduce(Reducer<A,T> reducer, A initial) Applies a Reducer to the values of the Flow.
Flow<T>	remove(Predicate<? super T> predicate) Removes values where the predicate returns true, returning a new Flow with just the remaining values.
Flow<T>	rest() Returns a new Flow containing all but the first value in this Flow.
Flow<T>	reverse() Returns a new flow with the same elements but in reverse order.
Flow<T>	sort() Sorts this Flow, forming a new Flow.
Flow<T>	sort(java.util.Comparator<? super T> comparator) Sorts this Flow using the comparator, forming a new Flow.
Flow<T>	take(int length) Returns a new Flow containing just the first values from this Flow.
T[]	toArray(java.lang.Class<T> type) Converts the Flow into an array of values (due to type erasure, you have to remind the Flow about the type).
java.util.List<T>	toList() Converts the Flow into an unmodifiable list of values.
java.util.Set<T>	toSet() Converts the Flow into an unmodifiable set of values.

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

map

<X> Flow<X> map(Mapper<T,X> mapper)

Maps a Flow into a new Flow with different type values. Mapping is a lazy operation.

map

<X,Y> Flow<Y> map(Mapper2<T,X,Y> mapper,
                  Flow<? extends X> flow)

Combines two Flows using a two-parameter Mapper. Each value of this Flow, and the corresponding value of the other flow are passed through the Mapper to provide the values of the output Flow. The length of the result Flow is the smaller of the lengths of the two input Flows. Mapping is a lazy operation.

mapcat

<X> Flow<X> mapcat(Mapper<T,Flow<X>> mapper)

Given a Mapper that maps a T to a Flow, this method will lazily concatenate all the output flows into a single Flow.

filter

Flow<T> filter(Predicate<? super T> predicate)

Filters values, keeping only values where the predicate is true, returning a new Flow with just the retained values.

remove

Flow<T> remove(Predicate<? super T> predicate)

Removes values where the predicate returns true, returning a new Flow with just the remaining values.

reduce

<A> A reduce(Reducer<A,T> reducer,
             A initial)

Applies a Reducer to the values of the Flow. The Reducer is passed the initial value and the first value from the Flow. The result is captured as the accumulator and passed to the Reducer with the next value from the Flow, and so on. The final accumulator value is returned. If the flow is empty, the initial value is returned.

Reducing is a non-lazy operation; it will fully realize the values of the Flow.

each

Flow<T> each(Worker<? super T> worker)

Applies the worker to each value in the Flow, then returns the flow for further behaviors.

Each is a non-lazy operation; it will fully realize the values of the Flow.

toList

java.util.List<T> toList()

Converts the Flow into an unmodifiable list of values. This is a non-lazy operation that will fully realize the values of the Flow.

toSet

java.util.Set<T> toSet()

Converts the Flow into an unmodifiable set of values. This is a non-lazy operation that will fully realize the values of the Flow.

toArray

T[] toArray(java.lang.Class<T> type)

Converts the Flow into an array of values (due to type erasure, you have to remind the Flow about the type).

reverse

Flow<T> reverse()

Returns a new flow with the same elements but in reverse order.

isEmpty

boolean isEmpty()

Returns true if the Flow contains no values. This may realize the first value in the Flow.

concat

Flow<T> concat(Flow<? extends T> other)

Returns a new Flow with the other Flow's elements appended to this Flow's. This is a lazy operation.

concat

Flow<T> concat(java.util.List<? extends T> list)

Returns a new Flow with the values in the list appended to this Flow. This is a lazy operation.

append

<V extends T> Flow<T> append(V... values)

Appends any number of type compatible values to the end of this Flow. This is a lazy operation.

sort

Flow<T> sort()

Sorts this Flow, forming a new Flow. This is a non-lazy operation; it will fully realize the values of the Flow.

Throws:

java.lang.ClassCastException - if type does not extend Comparable

sort

Flow<T> sort(java.util.Comparator<? super T> comparator)

Sorts this Flow using the comparator, forming a new Flow. This is a non-lazy operation; it will fully realize the values of the Flow.

first

T first()

Returns the first value in the Flow. Returns null for empty flows, but remember that null is a valid value within a flow, so use {@link #isEmpty() to determine if a flow is actually empty. The first value can be realized without realizing the full Flow.

rest

Flow<T> rest()

Returns a new Flow containing all but the first value in this Flow. If this Flow has only a single item, or is empty, this will return an empty Flow.

count

int count()

Returns the number of values in the Flow. This forces the realization of much of the Flow (i.e., because each value will need to be passed through any Predicates).

take

Flow<T> take(int length)

Returns a new Flow containing just the first values from this Flow.

Parameters:

length - maximum number of values in the Flow

drop

Flow<T> drop(int length)

Returns a new Flow with the first values omitted.

Parameters:

length - number of values to drop