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

In addition to {@code Stream}, which is a stream of object references, * there are primitive specializations for {@link IntStream}, {@link LongStream}, * and {@link DoubleStream}, all of which are referred to as "streams" and * conform to the characteristics and restrictions described here. * *

To perform a computation, stream * operations are composed into a * stream pipeline. A stream pipeline consists of a source (which * might be an array, a collection, a generator function, an I/O channel, * etc), zero or more intermediate operations (which transform a * stream into another stream, such as {@link Stream#filter(Predicate)}), and a * terminal operation (which produces a result or side-effect, such * as {@link Stream#count()} or {@link Stream#forEach(Consumer)}). * Streams are lazy; computation on the source data is only performed when the * terminal operation is initiated, and source elements are consumed only * as needed. * *

Collections and streams, while bearing some superficial similarities, * have different goals. Collections are primarily concerned with the efficient * management of, and access to, their elements. By contrast, streams do not * provide a means to directly access or manipulate their elements, and are * instead concerned with declaratively describing their source and the * computational operations which will be performed in aggregate on that source. * However, if the provided stream operations do not offer the desired * functionality, the {@link #iterator()} and {@link #spliterator()} operations * can be used to perform a controlled traversal. * *

A stream pipeline, like the "widgets" example above, can be viewed as * a query on the stream source. Unless the source was explicitly * designed for concurrent modification (such as a {@link ConcurrentHashMap}), * unpredictable or erroneous behavior may result from modifying the stream * source while it is being queried. * *

Most stream operations accept parameters that describe user-specified * behavior, such as the lambda expression {@code w -> w.getWeight()} passed to * {@code mapToInt} in the example above. To preserve correct behavior, * these behavioral parameters: *

*
• must be non-interfering * (they do not modify the stream source); and
*
• in most cases must be stateless * (their result should not depend on any state that might change during execution * of the stream pipeline).
*

Such parameters are always instances of a * functional interface such * as {@link java.util.function.Function}, and are often lambda expressions or * method references. Unless otherwise specified these parameters must be * non-null. * *

A stream should be operated on (invoking an intermediate or terminal stream * operation) only once. This rules out, for example, "forked" streams, where * the same source feeds two or more pipelines, or multiple traversals of the * same stream. A stream implementation may throw {@link IllegalStateException} * if it detects that the stream is being reused. However, since some stream * operations may return their receiver rather than a new stream object, it may * not be possible to detect reuse in all cases. * *

Streams have a {@link #close()} method and implement {@link AutoCloseable}, * but nearly all stream instances do not actually need to be closed after use. * Generally, only streams whose source is an IO channel (such as those returned * by {@link Files#lines(Path, Charset)}) will require closing. Most streams * are backed by collections, arrays, or generating functions, which require no * special resource management. (If a stream does require closing, it can be * declared as a resource in a {@code try}-with-resources statement.) * *

Stream pipelines may execute either sequentially or in * parallel. This * execution mode is a property of the stream. Streams are created * with an initial choice of sequential or parallel execution. (For example, * {@link Collection#stream() Collection.stream()} creates a sequential stream, * and {@link Collection#parallelStream() Collection.parallelStream()} creates * a parallel one.) This choice of execution mode may be modified by the * {@link #sequential()} or {@link #parallel()} methods, and may be queried with * the {@link #isParallel()} method. * * @param the type of the stream elements * @since 1.8 * @see IntStream * @see LongStream * @see DoubleStream * @see java.util.stream */ public abstract class Stream extends StreamBase, Consumer, List, Nullable, Indexed, Stream> { @SuppressWarnings("rawtypes") private static final Stream EMPTY = new ArrayStream(N.EMPTY_OBJECT_ARRAY, true, OBJECT_COMPARATOR, null); Stream(final boolean sorted, final Comparator cmp, final Collection closeHandlers) { super(sorted, cmp, closeHandlers); } /** * * @param seed initial value to check if the value match the condition. * @param predicate * @return */ public abstract Stream filter(final U seed, final BiPredicate predicate); /** * * @param seed initial value to check if the value match the condition. * @param predicate * @return */ public abstract Stream takeWhile(final U seed, final BiPredicate predicate); /** * * @param seed initial value to check if the value match the condition. * @param predicate * @return */ public abstract Stream dropWhile(final U seed, final BiPredicate predicate); public abstract Stream removeIf(final U seed, final BiPredicate predicate); public abstract Stream removeIf(final U seed, final BiPredicate predicate, final Consumer consumer); /** * Returns a stream consisting of the remaining elements of this stream * after removing and consuming until the specified predicate return false. * If there is no more elements then an empty stream will be returned. * * @param seed * @param predicate * @param consumer * @return {@link #dropWhile(Object, BiPredicate)} */ public abstract Stream removeWhile(final U seed, final BiPredicate predicate, final Consumer consumer); /** * Returns a stream consisting of the results of applying the given * function to the elements of this stream. * *

This is an intermediate * operation. * * @param The element type of the new stream * @param mapper a non-interfering, * stateless * function to apply to each element * @return the new stream */ public abstract Stream map(Function mapper); /** * Returns a stream consisting of the elements in this stream which are * instances of given class. * * @param targetType * @return */ public Stream select(Class targetType) { return (Stream) filter(Fn.instanceOf(targetType)); } public abstract Stream map(U seed, BiFunction mapper); public abstract Stream biMap(BiFunction mapper); /** * Returns a stream consisting of the results of applying the given function * to the every two adjacent elements of this stream. * *

     * 
     * Stream.of("a", "b", "c", "d", "e").biMap((i, j) -> i + "-" + j).println();
     * // print out: [a-b, c-d, e-null]
     * 
     * 

     * 
     * Stream.of("a", "b", "c", "d", "e").triMap((i, j, k) -> i + "-" + j + "-" + k).println();
     * // print out: [a-b-c, d-e-null]
     * 
     * 

     * 
     * Stream.of("a", "ab", "ac", "b", "c", "cb").rangeMap((a, b) -> b.startsWith(a), (a, b) -> a + "->" + b).toList(); // a->ac, b->b, c->cb
     * 
     * 

{@code
     *     orders.flatMap(order -> order.getLineItems().stream())...
     * }

{@code
     *     Stream lines = Files.lines(path, StandardCharsets.UTF_8);
     *     Stream words = lines.flatMap(line -> Stream.of(line.split(" +")));
     * }

     * 
     * // split the number sequence by window 5.
     * Stream.of(1, 2, 3, 5, 7, 9, 10, 11, 19).splitToList(MutableInt.of(5), (e, b) -> e <= b.intValue(), b -> b.addAndGet(5)).forEach(N::println);
     * 
     * 

     * 
     * // split the number sequence by window 5.
     * Stream.of(1, 2, 3, 5, 7, 9, 10, 11, 19).splitToSet(MutableInt.of(5), (e, b) -> e <= b.intValue(), b -> b.addAndGet(5)).forEach(N::println);
     * 
     * 

     * accumulator: (a, b) -> a + b
     * stream: [1, 2, 3, 4, 5]
     * result: [1, 3, 6, 10, 15]
     * 

     * seed:10
     * accumulator: (a, b) -> a + b
     * stream: [1, 2, 3, 4, 5]
     * result: [11, 13, 16, 20, 25]
     * 

{@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;
     * }

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

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

{@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 ? Nullable.of(result) : Nullable.empty();
     * }

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

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

{@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)));
     * }