com.landawn.abacus.util.stream.Stream Maven / Gradle / Ivy

For ordered streams, the sort is stable. For unordered streams, no * stability guarantees are made. * *

This is a stateful * intermediate operation. * * @param comparator a non-interfering, * stateless * {@code Comparator} to be used to compare stream elements * @return the new stream */ @ParallelSupported public abstract Stream sorted(Comparator comparator); @SuppressWarnings("rawtypes") @ParallelSupported public abstract Stream sortedBy(Function keyExtractor); @ParallelSupported public abstract Stream sortedByInt(ToIntFunction keyExtractor); @ParallelSupported public abstract Stream sortedByLong(ToLongFunction keyExtractor); @ParallelSupported public abstract Stream sortedByDouble(ToDoubleFunction keyExtractor); @ParallelSupported public abstract void forEach(Try.Consumer action) throws E; @ParallelSupported public abstract void forEachPair(final Try.BiConsumer action) throws E; /** * Slide with windowSize = 2 and the specified increment, then consume by the specified mapper. * * @param mapper * @param increment * @return */ @ParallelSupported public abstract void forEachPair(final Try.BiConsumer action, final int increment) throws E; @ParallelSupported public abstract void forEachTriple(final Try.TriConsumer action) throws E; /** * Slide with windowSize = 3 and the specified increment, then consume by the specified mapper. * * @param mapper * @param increment * @return */ @ParallelSupported public abstract void forEachTriple(final Try.TriConsumer action, final int increment) throws E; @ParallelSupported public abstract boolean anyMatch(Try.Predicate predicate) throws E; @ParallelSupported public abstract boolean allMatch(Try.Predicate predicate) throws E; @ParallelSupported public abstract boolean noneMatch(Try.Predicate predicate) throws E; @ParallelSupported public abstract Optional findFirst(Try.Predicate predicate) throws E; @ParallelSupported public abstract Optional findLast(Try.Predicate predicate) throws E; @SequentialOnly public abstract Optional findFirstOrLast(Try.Predicate predicateForFirst, Try.Predicate predicateForLast) throws E, E2; @ParallelSupported public abstract Optional findAny(Try.Predicate predicate) throws E; /** * * @param seed * @param predicate * @return */ @ParallelSupported public abstract Optional findFirst(final U seed, final Try.BiPredicate predicate) throws E; /** * * @param seed * @param predicate * @return */ @ParallelSupported public abstract Optional findLast(final U seed, final Try.BiPredicate predicate) throws E; /** * * @param seed * @param predicate * @return */ @ParallelSupported public abstract Optional findAny(final U seed, final Try.BiPredicate predicate) throws E; /** *
* This method only run sequentially, even in parallel stream. * * @param seed * @param predicateForFirst * @param predicateForLast * @return */ @SequentialOnly public abstract Optional findFirstOrLast(final U seed, final Try.BiPredicate predicateForFirst, final Try.BiPredicate predicateForLast) throws E, E2; /** *
* This method only run sequentially, even in parallel stream. * * @param preFunc * @param predicateForFirst * @param predicateForLast * @return */ @SequentialOnly public abstract Optional findFirstOrLast(final Function preFunc, final Try.BiPredicate predicateForFirst, final Try.BiPredicate predicateForLast) throws E, E2; @ParallelSupported public abstract boolean anyMatch(final U seed, final Try.BiPredicate predicate) throws E; @ParallelSupported public abstract boolean allMatch(final U seed, final Try.BiPredicate predicate) throws E; @ParallelSupported public abstract boolean noneMatch(final U seed, final Try.BiPredicate predicate) throws E; @SequentialOnly public abstract boolean containsAll(T... a); @SequentialOnly public abstract boolean containsAll(Collection c); /** * Returns an array containing the elements of this stream, using the * provided {@code generator} function to allocate the returned array, as * well as any additional arrays that might be required for a partitioned * execution or for resizing. * *

This is a terminal * operation. * * @apiNote * The generator function takes an integer, which is the size of the * desired array, and produces an array of the desired size. This can be * concisely expressed with an array constructor reference: *

{@code
     *     Person[] men = people.stream()
     *                          .filter(p -> p.getGender() == MALE)
     *                          .toArray(Person[]::new);
     * }

{@code
     *     T result = identity;
     *     for (T element : this stream)
     *         result = accumulator.apply(result, element)
     *     return result;
     * }

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: * *

{@code
     *     Integer sum = integers.reduce(0, (a, b) -> a+b);
     * }

{@code
     *     Integer sum = integers.reduce(0, Integer::sum);
     * }

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 identity the identity value for the accumulating function * @param accumulator an associative, * non-interfering, * stateless * function for combining two values * @return the result of the reduction */ @ParallelSupported public abstract T reduce(T identity, BinaryOperator accumulator); /** * Performs a reduction on the * elements of this stream, using an * associative accumulation * function, and returns an {@code Optional} describing the reduced value, * if any. This is equivalent to: *

{@code
     *     boolean foundAny = false;
     *     T result = null;
     *     for (T element : this stream) {
     *         if (!foundAny) {
     *             foundAny = true;
     *             result = element;
     *         }
     *         else
     *             result = accumulator.apply(result, element);
     *     }
     *     return foundAny ? Optional.of(result) : Optional.empty();
     * }

The {@code accumulator} function must be an * associative function. * *

This is a terminal * operation. * * @param accumulator an associative, * non-interfering, * stateless * function for combining two values * @return an {@link Optional} describing the result of the reduction * @see #reduce(Object, BinaryOperator) * @see #min(Comparator) * @see #max(Comparator) */ @ParallelSupported public abstract Optional reduce(BinaryOperator accumulator); /** * Performs a reduction on the * elements of this stream, using the provided identity, accumulation and * combining functions. This is equivalent to: *

{@code
     *     U result = identity;
     *     for (T element : this stream)
     *         result = accumulator.apply(result, element)
     *     return result;
     * }

The {@code identity} value must be an identity for the zipFunction * function. This means that for all {@code u}, {@code zipFunction(identity, u)} * is equal to {@code u}. Additionally, the {@code zipFunction} function * must be compatible with the {@code accumulator} function; for all * {@code u} and {@code t}, the following must hold: *

{@code
     *     zipFunction.apply(u, accumulator.apply(identity, t)) == accumulator.apply(u, t)
     * }

This is a terminal * operation. * * @apiNote Many reductions using this form can be represented more simply * by an explicit combination of {@code map} and {@code reduce} operations. * The {@code accumulator} function acts as a fused mapper and accumulator, * which can sometimes be more efficient than separate mapping and reduction, * such as when knowing the previously reduced value allows you to avoid * some computation. * * @param The type of the result * @param identity the identity value for the zipFunction function * @param accumulator an associative, * non-interfering, * stateless * function for incorporating an additional element into a result * @param combiner an associative, * non-interfering, * stateless * function for combining two values, which must be * compatible with the accumulator function * @return the result of the reduction * @see #reduce(BinaryOperator) * @see #reduce(Object, BinaryOperator) */ @ParallelSupported public abstract U reduce(U identity, BiFunction accumulator, BinaryOperator combiner); /** * The result will be merged by: a.addAll(b) if result container is Collection/Multiset/LongMultiset/IntList/CharList/..., * or a.putAll(b) if result container is Map/Multimap/Sheet, * or a.append(b) if result container is StringBuilder, * or N.concat(a, b) if result container is array: boolean[]/char[]/int[]/.../Object[] when it's necessary in Parallel Stream. * * @param identity * @param accumulator * @return * @throws RuntimeException if the result container can't be merged by default when it's necessary in Parallel Stream. * @deprecated */ @Deprecated @ParallelSupported public abstract U reduce(U identity, BiFunction accumulator); /** * Performs a mutable * reduction operation on the elements of this stream. A mutable * reduction is one in which the reduced value is a mutable result container, * such as an {@code ArrayList}, and elements are incorporated by updating * the state of the result rather than by replacing the result. This * produces a result equivalent to: *

{@code
     *     R result = supplier.get();
     *     for (T element : this stream)
     *         accumulator.accept(result, element);
     *     return result;
     * }

{@code
     *     List asList = stringStream.collect(ArrayList::new, ArrayList::add,
     *                                                ArrayList::addAll);
     * }

{@code
     *     String concat = stringStream.collect(StringBuilder::new, StringBuilder::append,
     *                                          StringBuilder::append)
     *                                 .toString();
     * }

{@code
     *     List asList = stringStream.collect(Collectors.toList());
     * }

{@code
     *     Map> peopleByCity
     *         = personStream.collect(Collectors.groupingBy(Person::getCity));
     * }

{@code
     *     Map>> peopleByStateAndCity
     *         = personStream.collect(Collectors.groupingBy(Person::getState,
     *                                                      Collectors.groupingBy(Person::getCity)));
     * }

     * 
     * Stream.of(1, 2, 3).combinations().forEach(Fn.println());
     * // output
     * []
     * [1]
     * [2]
     * [3]
     * [1, 2]
     * [1, 3]
     * [2, 3]
     * [1, 2, 3]
     * 
     * 

     * 
     * Stream.of(1, 2, 3).combinations(2).forEach(Fn.println());
     * // output
     * [1, 2]
     * [1, 3]
     * [2, 3]
     * 
     * 

     * 
     * Stream.of(1, 2, 3).combinations(2, true).forEach(Fn.println());
     * // output
     * [1, 1]
     * [1, 2]
     * [1, 3]
     * [2, 1]
     * [2, 2]
     * [2, 3]
     * [3, 1]
     * [3, 2]
     * [3, 3]
     * 
     * 

     * 
     * Stream.of(1, 2, 3).permutations().forEach(Fn.println());
     * // output
     * [1, 2, 3]
     * [1, 3, 2]
     * [3, 1, 2]
     * [3, 2, 1]
     * [2, 3, 1]
     * [2, 1, 3]
     * 
     * 

     * 
     * Stream.of(1, 2, 3).orderedPermutations().forEach(Fn.println());
     * // output
     * [1, 2, 3]
     * [1, 3, 2]
     * [2, 1, 3]
     * [2, 3, 1]
     * [3, 1, 2]
     * [3, 2, 1]
     * 
     *