001// Copyright 2011 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007// http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.func;
016
017import java.util.Comparator;
018import java.util.List;
019import java.util.Set;
020
021/**
022 * @param <T>
023 *            the type of data in the flow
024 * @param <FT>
025 *            the type of flow (either Flow<T> or ZippedFlow<Tuple<T, ?>)
026 * @since 5.3
027 */
028public interface FlowOperations<T, FT> extends Iterable<T>
029{
030    /**
031     * Filters values, keeping only values where the predicate is true, returning a new Flow with
032     * just the retained values.
033     */
034    FT filter(Predicate<? super T> predicate);
035
036    /**
037     * Removes values where the predicate returns true, returning a new Flow with just the remaining
038     * values.
039     */
040    FT remove(Predicate<? super T> predicate);
041
042    /**
043     * Applies the worker to each element in the Flow, then returns the flow for further behaviors.
044     * <p>
045     * Each is a non-lazy operation; it will fully realize the values of the Flow.
046     */
047    FT each(Worker<? super T> worker);
048
049    /**
050     * Converts the Flow into an unmodifiable list of values. This is a non-lazy operation that will
051     * fully realize the values of the Flow.
052     */
053    List<T> toList();
054
055    /**
056     * Converts the Flow into an unmodifiable set of values. This is a non-lazy operation that will
057     * fully realize the values of the Flow.
058     */
059    Set<T> toSet();
060
061    /** Returns a new flow with the same elements but in reverse order. */
062    FT reverse();
063
064    /**
065     * Returns true if the Flow contains no values. This <em>may</em> realize the first value in the
066     * Flow.
067     */
068    boolean isEmpty();
069
070    /**
071     * Returns the first element in the Flow. Returns null for empty flows, but remember that null
072     * is a valid element within a flow, so use {@link #isEmpty()} to determine if a flow is actually
073     * empty. The first element can be realized without realizing the full Flow.
074     */
075    T first();
076
077    /**
078     * Returns a new Flow containing all but the first element in this flow. If this flow has only a
079     * single element, or is empty, this will return an empty Flow.
080     */
081    FT rest();
082
083    /**
084     * Returns the number of values in this flow. This forces the realization of much of the flow
085     * (i.e., because each value will need to be passed through any {@link Predicate}s).
086     */
087    int count();
088
089    /**
090     * Sorts this flow using the comparator, forming a new flow. This is a non-lazy operation; it
091     * will fully realize the elements of the Flow.
092     */
093    FT sort(Comparator<T> comparator);
094
095    /**
096     * Returns a new flow containing just the first elements from this Flow.
097     * 
098     * @param length
099     *            maximum number of values in the Flow
100     */
101    FT take(int length);
102
103    /**
104     * Returns a new flow with the first elements omitted.
105     * 
106     * @param length
107     *            number of values to drop
108     */
109    FT drop(int length);
110
111    /**
112     * Returns a new Flow with the elements in the list appended to this Flow. This is a lazy
113     * operation.
114     */
115    FT concat(List<? extends T> list);
116
117    /**
118     * Applies a Reducer to the values of the Flow. The Reducer is passed the initial value
119     * and the first element from the Flow. The result is captured as the accumulator and passed
120     * to the Reducer with the next value from the Flow, and so on. The final accumulator
121     * value is returned. If the flow is empty, the initial value is returned.
122     * <p>
123     * Reducing is a non-lazy operation; it will fully realize the values of the Flow.
124     */
125    <A> A reduce(Reducer<A, T> reducer, A initial);
126
127    /**
128     * Removes null elements from the flow (null tuples from a ZippedFlow), leaving just the
129     * non-null elements. This is a lazy operation.
130     * 
131     * @since 5.3
132     */
133    FT removeNulls();
134}