Package org.apache.tapestry5.func

# Interface Flow<T>

All Superinterfaces:
  `FlowOperations<T,Flow<T>>`, `Iterable<T>`

public interface Flow<T> extends FlowOperations<T,Flow<T>>
A flow is a a functional interface for working with an ordered collection of elements. A given Flow contains only elements of a particular type. Standard operations allow for filtering the flow, or appending elements to the Flow. Since flows are immutable, all operations on flows return new immutable flows. Flows are thread safe (to the extent that the `Mapper` , `Predicate` , `Worker` and `Reducer` objects 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` (or other collection) 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 elements (such as `FlowOperations.count()` or `FlowOperations.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)`, `F.flow(Object...)` or `F.flow(Iterable)`.

Since:
  5.2.0
See Also:
  - `F.lazy(LazyFunction)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<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>`
  `interleave(Flow<T>... otherFlows)`
  "Stripes" together a group of flows.
  `<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<X>`, this method will lazily concatenate all the output flows into a single `Flow<X>`.
  `Flow<T>`
  `sort()`
  Sorts this Flow, forming a new Flow.
  `T[]`
  `toArray(Class<T> type)`
  Converts the Flow into an array of values (due to type erasure, you have to remind the Flow about the type).
  `<X> ZippedFlow<T,X>`
  `zipWith(Flow<X> otherFlow)`
  Zips this Flow together with another flow to form a Flow of `Tuple`s.

  ### Methods inherited from interface org.apache.tapestry5.func.FlowOperations

  `concat, count, drop, each, filter, first, isEmpty, reduce, remove, removeNulls, rest, reverse, sort, take, toList, toSet`

  ### Methods inherited from interface java.lang.Iterable

  `forEach, iterator, spliterator`

- ## Method Details

  - ### 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 element of this Flow, and the corresponding element of the other flow are passed through the Mapper to provide the elements 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<X>`, this method will lazily concatenate all the output flows into a single `Flow<X>`.

  - ### toArray

    T[] toArray(Class<T> type)
    Converts the Flow into an array of values (due to type erasure, you have to remind the Flow about the type).

  - ### 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.

  - ### 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:
      `ClassCastException` - if type T does not extend `Comparable`

  - ### zipWith

    <X> ZippedFlow<T,X> zipWith(Flow<X> otherFlow)
    Zips this Flow together with another flow to form a Flow of `Tuple`s. The resulting flow is the length of the shorter of the two input flows. Zipping flows together is a lazy operation. The elements of this flow become the Tuple.first value in each Tuple, the elements of the other flow become the Tuple.second value in each Tuple.
    Type Parameters:
      `X` - type of element stored in the other flow
    Parameters:
      `otherFlow` - contains elements to match with elements in this flow
    Returns:
      flow of tuples combining values from this flow with values form the other flow
    Since:
      5.3

  - ### interleave

    Flow<T> interleave(Flow<T>... otherFlows)
    "Stripes" together a group of flows. The output flow contains the first value from this flow, then the first value from each of the other flows, in turn, then the second value from this flow, etc. The resulting flow ends when this or any of the other flows runs out of values.
    Returns:
      combined flow