- * ObjectStreams.failable(stream).forEach((m) -> m.invoke(o, args)); + * Streams.failable(stream).forEach((m) -> m.invoke(o, args)); ** Obviously, the second version is much more concise and the spirit of * Lambda expressions is met better than in the first version. @@ -56,309 +57,309 @@ import org.apache.commons.lang3.Functions.FailablePredicate; * @see Functions */ public class Streams { - /** A reduced, and simplified version of a {@link Stream} with - * failable method signatures. - * @param
This is an intermediate operation.
- *
- * @param pPredicate a non-interfering, stateless predicate to apply to each
- * element to determine if it should be included.
- * @return the new stream
- */
- public FailableStream This is an intermediate operation.
+ *
+ * @param pPredicate a non-interfering, stateless predicate to apply to each
+ * element to determine if it should be included.
+ * @return the new stream
+ */
+ public FailableStream This is a terminal operation.
- *
- * The behavior of this operation is explicitly nondeterministic.
- * For parallel stream pipelines, this operation does not
- * guarantee to respect the encounter order of the stream, as doing so
- * would sacrifice the benefit of parallelism. For any given element, the
- * action may be performed at whatever time and in whatever thread the
- * library chooses. If the action accesses shared state, it is
- * responsible for providing the required synchronization.
- *
- * @param pAction a non-interfering action to perform on the elements
- */
- public void forEach(FailableConsumer If the underlying stream is parallel, and the {@code Collector}
- * is concurrent, and either the stream is unordered or the collector is
- * unordered, then a concurrent reduction will be performed
- * (see {@link Collector} for details on concurrent reduction.)
- *
- * This is a terminal operation.
- *
- * When executed in parallel, multiple intermediate results may be
- * instantiated, populated, and merged so as to maintain isolation of
- * mutable data structures. Therefore, even when executed in parallel
- * with non-thread-safe data structures (such as {@code ArrayList}), no
- * additional synchronization is needed for a parallel reduction.
- *
- * \@apiNote
- * The following will accumulate strings into an ArrayList:
- * The following will classify {@code Person} objects by city:
- * The following will classify {@code Person} objects by state and city,
- * cascading two {@code Collector}s together:
- * This is a terminal operation.
+ *
+ * The behavior of this operation is explicitly nondeterministic.
+ * For parallel stream pipelines, this operation does not
+ * guarantee to respect the encounter order of the stream, as doing so
+ * would sacrifice the benefit of parallelism. For any given element, the
+ * action may be performed at whatever time and in whatever thread the
+ * library chooses. If the action accesses shared state, it is
+ * responsible for providing the required synchronization.
+ *
+ * @param pAction a non-interfering action to perform on the elements
+ */
+ public void forEach(FailableConsumer Like {@link #reduce(Object, BinaryOperator)}, {@code collect} operations
- * can be parallelized without requiring additional synchronization.
- *
- * This is a terminal operation.
- *
- * \@apiNote There are many existing classes in the JDK whose signatures are
- * well-suited for use with method references as arguments to {@code collect()}.
- * For example, the following will accumulate strings into an {@code ArrayList}:
- * The following will take a stream of strings and concatenates them into a
- * single string:
- * If the underlying stream is parallel, and the {@code Collector}
+ * is concurrent, and either the stream is unordered or the collector is
+ * unordered, then a concurrent reduction will be performed
+ * (see {@link Collector} for details on concurrent reduction.)
+ *
+ * This is a terminal operation.
+ *
+ * When executed in parallel, multiple intermediate results may be
+ * instantiated, populated, and merged so as to maintain isolation of
+ * mutable data structures. Therefore, even when executed in parallel
+ * with non-thread-safe data structures (such as {@code ArrayList}), no
+ * additional synchronization is needed for a parallel reduction.
+ *
+ * \@apiNote
+ * The following will accumulate strings into an ArrayList:
+ * The following will classify {@code Person} objects by city:
+ * The following will classify {@code Person} objects by state and city,
+ * cascading two {@code Collector}s together:
+ * The {@code identity} value must be an identity for the accumulator
- * function. This means that for all {@code t},
- * {@code accumulator.apply(identity, t)} is equal to {@code t}.
- * The {@code accumulator} function must be an associative function.
- *
- * This is a terminal operation.
- *
- * \@apiNote Sum, min, max, average, and string concatenation are all special
- * cases of reduction. Summing a stream of numbers can be expressed as:
- *
- * While this may seem a more roundabout way to perform an aggregation
- * compared to simply mutating a running total in a loop, reduction
- * operations parallelize more gracefully, without needing additional
- * synchronization and with greatly reduced risk of data races.
- *
- * @param pIdentity the identity value for the accumulating function
- * @param pAccumulator an associative, non-interfering, stateless
- * function for combining two values
- * @return the result of the reduction
- */
- public O reduce(O pIdentity, BinaryOperator Like {@link #reduce(Object, BinaryOperator)}, {@code collect} operations
+ * can be parallelized without requiring additional synchronization.
+ *
+ * This is a terminal operation.
+ *
+ * \@apiNote There are many existing classes in the JDK whose signatures are
+ * well-suited for use with method references as arguments to {@code collect()}.
+ * For example, the following will accumulate strings into an {@code ArrayList}:
+ * The following will take a stream of strings and concatenates them into a
+ * single string:
+ * This is an intermediate operation.
- *
- * @param The {@code identity} value must be an identity for the accumulator
+ * function. This means that for all {@code t},
+ * {@code accumulator.apply(identity, t)} is equal to {@code t}.
+ * The {@code accumulator} function must be an associative function.
+ *
+ * This is a terminal operation.
+ *
+ * \@apiNote Sum, min, max, average, and string concatenation are all special
+ * cases of reduction. Summing a stream of numbers can be expressed as:
+ *
+ * While this may seem a more roundabout way to perform an aggregation
+ * compared to simply mutating a running total in a loop, reduction
+ * operations parallelize more gracefully, without needing additional
+ * synchronization and with greatly reduced risk of data races.
+ *
+ * @param pIdentity the identity value for the accumulating function
+ * @param pAccumulator an associative, non-interfering, stateless
+ * function for combining two values
+ * @return the result of the reduction
+ */
+ public O reduce(O pIdentity, BinaryOperator This is an intermediate operation.
+ *
+ * @param This is a short-circuiting terminal operation.
- *
- * \@apiNote
- * This method evaluates the universal quantification of the
- * predicate over the elements of the stream (for all x P(x)). If the
- * stream is empty, the quantification is said to be vacuously
- * satisfied and is always {@code true} (regardless of P(x)).
- *
- * @param pPredicate A non-interfering, stateless predicate to apply to
- * elements of this stream
- * @return {@code true} If either all elements of the stream match the
- * provided predicate or the stream is empty, otherwise {@code false}.
- */
- public boolean allMatch(FailablePredicate This is a short-circuiting terminal operation.
- *
- * \@apiNote
- * This method evaluates the existential quantification of the
- * predicate over the elements of the stream (for some x P(x)).
- *
- * @param pPredicate A non-interfering, stateless predicate to apply to
- * elements of this stream
- * @return {@code true} if any elements of the stream match the provided
- * predicate, otherwise {@code false}
- */
- public boolean anyMatch(FailablePredicate This is a short-circuiting terminal operation.
+ *
+ * \@apiNote
+ * This method evaluates the universal quantification of the
+ * predicate over the elements of the stream (for all x P(x)). If the
+ * stream is empty, the quantification is said to be vacuously
+ * satisfied and is always {@code true} (regardless of P(x)).
+ *
+ * @param pPredicate A non-interfering, stateless predicate to apply to
+ * elements of this stream
+ * @return {@code true} If either all elements of the stream match the
+ * provided predicate or the stream is empty, otherwise {@code false}.
+ */
+ public boolean allMatch(FailablePredicate This is a short-circuiting terminal operation.
+ *
+ * \@apiNote
+ * This method evaluates the existential quantification of the
+ * predicate over the elements of the stream (for some x P(x)).
+ *
+ * @param pPredicate A non-interfering, stateless predicate to apply to
+ * elements of this stream
+ * @return {@code true} if any elements of the stream match the provided
+ * predicate, otherwise {@code false}
+ */
+ public boolean anyMatch(FailablePredicate{@code
- * List
- *
- * {@code
- * Map
- *
- * {@code
- * Map
- *
- * @param {@code
- * R result = supplier.get();
- * for (T element : this stream)
- * accumulator.accept(result, element);
- * return result;
- * }
- *
- * {@code
- * List
- *
- * {@code
- * String concat = stringStream.collect(StringBuilder::new, StringBuilder::append,
- * StringBuilder::append)
- * .toString();
- * }
- *
- * @param {@code
+ * List
+ *
+ * {@code
+ * Map
+ *
+ * {@code
+ * Map
+ *
+ * @param {@code
- * T result = identity;
- * for (T element : this stream)
- * result = accumulator.apply(result, element)
- * return result;
- * }
- *
- * but is not constrained to execute sequentially.
- *
- * {@code
- * Integer sum = integers.reduce(0, (a, b) -> a+b);
- * }
- *
- * or:
- *
- * {@code
- * Integer sum = integers.reduce(0, Integer::sum);
- * }
- *
- * {@code
+ * R result = supplier.get();
+ * for (T element : this stream)
+ * accumulator.accept(result, element);
+ * return result;
+ * }
+ *
+ * {@code
+ * List
+ *
+ * {@code
+ * String concat = stringStream.collect(StringBuilder::new, StringBuilder::append,
+ * StringBuilder::append)
+ * .toString();
+ * }
+ *
+ * @param {@code
+ * T result = identity;
+ * for (T element : this stream)
+ * result = accumulator.apply(result, element)
+ * return result;
+ * }
+ *
+ * but is not constrained to execute sequentially.
+ *
+ * {@code
+ * Integer sum = integers.reduce(0, (a, b) -> a+b);
+ * }
+ *
+ * or:
+ *
+ * {@code
+ * Integer sum = integers.reduce(0, Integer::sum);
+ * }
+ *
+ *
- * final List<O> list;
- * final Method m;
- * final Function<O,String> mapper = (o) -> {
- * try {
- * return (String) m.invoke(o);
- * } catch (Throwable t) {
- * throw Functions.rethrow(t);
- * }
- * };
- * final List<String> strList = list.stream()
- * .map(mapper).collect(Collectors.toList());
- *
- * as follows:
- *
+ /**
+ * Converts the given {@link Stream stream} into a {@link FailableStream}.
+ * This is basically a simplified, reduced version of the {@link Stream}
+ * class, with the same underlying element stream, except that failable
+ * objects, like {@link FailablePredicate}, {@link FailableFunction}, or
+ * {@link FailableConsumer} may be applied, instead of
+ * {@link Predicate}, {@link Function}, or {@link Consumer}. The idea is
+ * to rewrite a code snippet like this:
+ *
+ * final List<O> list;
+ * final Method m;
+ * final Function<O,String> mapper = (o) -> {
+ * try {
+ * return (String) m.invoke(o);
+ * } catch (Throwable t) {
+ * throw Functions.rethrow(t);
+ * }
+ * };
+ * final List<String> strList = list.stream()
+ * .map(mapper).collect(Collectors.toList());
+ *
+ * as follows:
+ *
* final List<O> list;
* final Method m;
* final List<String> strList = Functions.stream(list.stream())
@@ -369,12 +370,54 @@ public class Streams {
* intermediate objects, of type FailableStream), it is much more
* concise, and readable, and meets the spirit of Lambdas better
* than the first version.
- * @param
+ * final List<O> list;
+ * final Method m;
+ * final Function<O,String> mapper = (o) -> {
+ * try {
+ * return (String) m.invoke(o);
+ * } catch (Throwable t) {
+ * throw Functions.rethrow(t);
+ * }
+ * };
+ * final List<String> strList = list.stream()
+ * .map(mapper).collect(Collectors.toList());
+ *
+ * as follows:
+ *
+ * final List<O> list;
+ * final Method m;
+ * final List<String> strList = Functions.stream(list.stream())
+ * .map((o) -> (String) m.invoke(o)).collect(Collectors.toList());
+ *
+ * While the second version may not be quite as
+ * efficient (because it depends on the creation of additional,
+ * intermediate objects, of type FailableStream), it is much more
+ * concise, and readable, and meets the spirit of Lambdas better
+ * than the first version.
+ * @param