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