com.tangosol.util.stream.RemoteStream Maven / Gradle / Ivy
Show all versions of coherence Show documentation
/*
* Copyright (c) 2000, 2022, Oracle and/or its affiliates.
*
* Licensed under the Universal Permissive License v 1.0 as shown at
* https://oss.oracle.com/licenses/upl.
*/
package com.tangosol.util.stream;
import com.tangosol.internal.util.invoke.Lambdas;
import com.tangosol.internal.util.stream.StreamSupport;
import com.tangosol.util.Filters;
import com.tangosol.util.InvocableMap;
import com.tangosol.util.ValueExtractor;
import com.tangosol.util.comparator.ExtractorComparator;
import com.tangosol.util.comparator.InverseComparator;
import com.tangosol.util.function.Remote;
import java.util.Collections;
import java.util.Comparator;
import java.util.List;
import java.util.Optional;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.BinaryOperator;
import java.util.function.Consumer;
import java.util.function.DoubleConsumer;
import java.util.function.Function;
import java.util.function.IntConsumer;
import java.util.function.IntFunction;
import java.util.function.LongConsumer;
import java.util.function.Predicate;
import java.util.function.Supplier;
import java.util.function.ToDoubleFunction;
import java.util.function.ToIntFunction;
import java.util.function.ToLongFunction;
import java.util.stream.Collector;
import java.util.stream.DoubleStream;
import java.util.stream.IntStream;
import java.util.stream.LongStream;
import java.util.stream.Stream;
/**
* This interface is an extension of {@code java.util.stream.Stream} that captures
* lambdas used as method arguments as serializable lambdas.
*
* @param the type of the stream elements
*
* @author as 2014.08.11
* @since 12.2.1
*
* @see RemoteIntStream
* @see RemoteLongStream
* @see RemoteDoubleStream
* @see com.tangosol.util.stream
*/
public interface RemoteStream
extends Stream, BaseRemoteStream>
{
/**
* Create a {@link RemoteStream} of specified map's entries.
*
* @param map the map to create a remote stream for
* @param the type of map keys
* @param the type of map values
*
* @return a {@link RemoteStream} of specified map's entries
*/
public static RemoteStream> entrySet(InvocableMap map)
{
return StreamSupport
.entryStream(map, true, null, Filters.always());
}
/**
* Create a {@link RemoteStream} of specified map's keys.
*
* @param map the map to create a remote stream for
* @param the type of map keys
* @param the type of map values
*
* @return a {@link RemoteStream} of specified map's keys
*/
public static RemoteStream keySet(InvocableMap map)
{
return StreamSupport
.entryStream(map, true, null, Filters.always())
.map(InvocableMap.Entry::getKey);
}
/**
* Create a {@link RemoteStream} of specified map's values.
*
* @param map the map to create a remote stream for
* @param the type of map keys
* @param the type of map values
*
* @return a {@link RemoteStream} of specified map's values
*/
public static RemoteStream values(InvocableMap map)
{
return StreamSupport
.entryStream(map, true, null, Filters.always())
.map(InvocableMap.Entry::getValue);
}
/**
* Returns an equivalent stream that is sequential. May return itself,
* either because the stream was already sequential, or because the
* underlying stream state was modified to be sequential.
*
* This is an intermediate operation.
*
* @return a sequential stream
*/
RemoteStream sequential();
/**
* Returns an equivalent stream that is parallel. May return itself, either
* because the stream was already parallel, or because the underlying stream
* state was modified to be parallel.
*
* This is an intermediate operation.
*
* @return a parallel stream
*/
RemoteStream parallel();
/**
* Returns an equivalent stream that is unordered.
* May return itself, either because the stream was already unordered, or
* because the underlying stream state670G was modified to be unordered.
*
* This is an intermediate operation.
*
* @return an unordered stream
*/
RemoteStream unordered();
/**
* Returns a stream consisting of the elements of this stream that match the
* given predicate.
*
* This is an intermediate operation.
*
* @param predicate a non-interfering, stateless predicate to apply to each
* element to determine if it should be included
*
* @return the new stream
*/
RemoteStream filter(Predicate predicate);
/**
* Returns a stream consisting of the elements of this stream that match the
* given predicate.
*
* This is an intermediate operation.
*
* @param predicate a non-interfering, stateless predicate to apply to each
* element to determine if it should be included
*
* @return the new stream
*/
default RemoteStream filter(Remote.Predicate predicate)
{
return filter((Predicate) predicate);
}
/**
* Returns a stream consisting of the results of applying the given function
* to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
RemoteStream map(Function mapper);
/**
* 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 type of resulting stream elements
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteStream map(Remote.Function mapper)
{
return map((Function) mapper);
}
/**
* Returns a stream consisting of the results of applying the given extractor
* to the elements of this stream.
*
* This is an intermediate operation.
*
* @param the type of resulting stream elements
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteStream map(ValueExtractor mapper)
{
return map((Function) Lambdas.ensureRemotable(mapper));
}
/**
* Returns an {@code IntStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
RemoteIntStream mapToInt(ToIntFunction mapper);
/**
* Returns an {@code IntStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteIntStream mapToInt(Remote.ToIntFunction mapper)
{
return mapToInt((ToIntFunction) mapper);
}
/**
* Returns an {@code IntStream} consisting of the results of applying the
* given extractor to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteIntStream mapToInt(ValueExtractor mapper)
{
return mapToInt((ToIntFunction) Lambdas.ensureRemotable(mapper));
}
/**
* Returns a {@code LongStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
RemoteLongStream mapToLong(ToLongFunction mapper);
/**
* Returns a {@code LongStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteLongStream mapToLong(Remote.ToLongFunction mapper)
{
return mapToLong((ToLongFunction) mapper);
}
/**
* Returns an {@code LongStream} consisting of the results of applying the
* given extractor to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteLongStream mapToLong(ValueExtractor mapper)
{
return mapToLong((ToLongFunction) Lambdas.ensureRemotable(mapper));
}
/**
* Returns a {@code DoubleStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
RemoteDoubleStream mapToDouble(ToDoubleFunction mapper);
/**
* Returns a {@code DoubleStream} consisting of the results of applying the
* given function to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteDoubleStream mapToDouble(Remote.ToDoubleFunction mapper)
{
return mapToDouble((ToDoubleFunction) mapper);
}
/**
* Returns an {@code DoubleStream} consisting of the results of applying the
* given extractor to the elements of this stream.
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element
*
* @return the new stream
*/
default RemoteDoubleStream mapToDouble(ValueExtractor mapper)
{
return mapToDouble((ToDoubleFunction) Lambdas.ensureRemotable(mapper));
}
/**
* Returns a stream consisting of the results of replacing each element of
* this stream with the contents of a mapped stream produced by applying
* the provided mapping function to each element. Each mapped stream is
* {@link BaseRemoteStream#close() closed} after its contents have been placed
* into this stream. (If a mapped stream is {@code null} an empty stream
* is used, instead.)
*
* 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 which produces a stream
* of new values
*
* @return the new stream
*/
RemoteStream flatMap(Function> mapper);
/**
* Returns a stream consisting of the results of replacing each element of
* this stream with the contents of a mapped stream produced by applying
* the provided mapping function to each element. Each mapped stream is
* {@link BaseRemoteStream#close() closed} after its contents have been placed
* into this stream. (If a mapped stream is {@code null} an empty stream
* is used, instead.)
*
* 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 which produces a stream
* of new values
*
* @return the new stream
*/
default RemoteStream flatMap(Remote.Function> mapper)
{
Function> safeMapper =
Remote.function(t -> t == null ? null : mapper.apply(t));
return flatMap(safeMapper);
}
/**
* Returns an {@code IntStream} consisting of the results of replacing each
* element of this stream with the contents of a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
RemoteIntStream flatMapToInt(Function mapper);
/**
* Returns an {@code IntStream} consisting of the results of replacing each
* element of this stream with the contents of a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
default RemoteIntStream flatMapToInt(Remote.Function mapper)
{
Function safeMapper =
Remote.function(t -> t == null ? null : mapper.apply(t));
return flatMapToInt(safeMapper);
}
/**
* Returns an {@code LongStream} consisting of the results of replacing each
* element of this stream with the contents of a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
RemoteLongStream flatMapToLong(Function mapper);
/**
* Returns an {@code LongStream} consisting of the results of replacing each
* element of this stream with the contents of a mapped stream produced by
* applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
default RemoteLongStream flatMapToLong(Remote.Function mapper)
{
Function safeMapper =
Remote.function(t -> t == null ? null : mapper.apply(t));
return flatMapToLong(safeMapper);
}
/**
* Returns an {@code DoubleStream} consisting of the results of replacing
* each element of this stream with the contents of a mapped stream produced
* by applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
RemoteDoubleStream flatMapToDouble(Function mapper);
/**
* Returns an {@code DoubleStream} consisting of the results of replacing
* each element of this stream with the contents of a mapped stream produced
* by applying the provided mapping function to each element. Each mapped
* stream is {@link BaseRemoteStream#close() closed} after its contents have been
* placed into this stream. (If a mapped stream is {@code null} an empty
* stream is used, instead.)
*
* This is an intermediate operation.
*
* @param mapper a non-interfering, stateless
* function to apply to each element which produces a stream
* of new values
*
* @return the new stream
*
* @see #flatMap(Function)
*/
default RemoteDoubleStream flatMapToDouble(Remote.Function mapper)
{
Function safeMapper =
Remote.function(t -> t == null ? null : mapper.apply(t));
return flatMapToDouble(safeMapper);
}
/**
* Returns a stream consisting of the results of replacing each element of
* this stream with multiple elements, specifically zero or more elements.
* Replacement is performed by applying the provided mapping function to
* each element in conjunction with a {@linkplain Consumer consumer}
* argument that accepts replacement elements. The mapping function calls
* the consumer zero or more times to provide the replacement elements.
*
*
This is an intermediate operation.
*
*
If the {@linkplain Consumer consumer} argument is used outside the
* scope of its application to the mapping function, the results are undefined.
*
* @param mapper a non-interfering, stateless function
* that generates replacement elements
*
* @return the new stream
*
* @since 22.09
*/
@Override
RemoteStream mapMulti(BiConsumer> mapper);
/**
* Returns a stream consisting of the results of replacing each element of
* this stream with multiple elements, specifically zero or more elements.
* Replacement is performed by applying the provided mapping function to
* each element in conjunction with a {@linkplain Consumer consumer}
* argument that accepts replacement elements. The mapping function calls
* the consumer zero or more times to provide the replacement elements.
*
* This is an intermediate operation.
*
*
If the {@linkplain Consumer consumer} argument is used outside the
* scope of its application to the mapping function, the results are undefined.
*
* @param mapper a non-interfering, stateless function
* that generates replacement elements
*
* @return the new stream
*
* @since 22.09
*/
default RemoteStream mapMulti(Remote.BiConsumer> mapper)
{
return mapMulti((BiConsumer>) mapper);
}
/**
* Returns an {@code IntStream} consisting of the results of replacing each
* element of this stream with multiple elements, specifically zero or more
* elements. Replacement is performed by applying the provided mapping
* function to each element in conjunction with a
* {@linkplain IntConsumer consumer} argument that accepts replacement
* elements. The mapping function calls the consumer zero or more times to
* provide the replacement elements.
*
* This is an intermediate operation.
*
*
If the {@linkplain IntConsumer consumer} argument is used outside the
* scope of its application to the mapping function, the results are undefined.
*
* @param mapper a non-interfering, stateless
* function that generates replacement elements
*
* @return the new stream
*
* @since 22.09
*/
@Override
RemoteIntStream mapMultiToInt(BiConsumer mapper);
/**
* Returns an {@code IntStream} consisting of the results of replacing each
* element of this stream with multiple elements, specifically zero or more
* elements. Replacement is performed by applying the provided mapping
* function to each element in conjunction with a
* {@linkplain IntConsumer consumer} argument that accepts replacement
* elements. The mapping function calls the consumer zero or more times to
* provide the replacement elements.
*
*
This is an intermediate operation.
*
*
If the {@linkplain IntConsumer consumer} argument is used outside the
* scope of its application to the mapping function, the results are undefined.
*
* @param mapper a non-interfering, stateless
* function that generates replacement elements
*
* @return the new stream
*
* @since 22.09
*/
default RemoteIntStream mapMultiToInt(Remote.BiConsumer mapper)
{
return mapMultiToInt((BiConsumer) mapper);
}
/**
* Returns a {@code LongStream} consisting of the results of replacing each
* element of this stream with multiple elements, specifically zero or more
* elements. Replacement is performed by applying the provided mapping
* function to each element in conjunction with a
* {@linkplain LongConsumer consumer} argument that accepts replacement
* elements. The mapping function calls the consumer zero or more times to
* provide the replacement elements.
*
*
This is an intermediate operation.
*
*
If the {@linkplain LongConsumer consumer} argument is used outside the
* scope of its application to the mapping function, the results are undefined.
*
* @param mapper a non-interfering, stateless
* function that generates replacement elements
*
* @return the new stream
*
* @since 22.09
*/
@Override
RemoteLongStream mapMultiToLong(BiConsumer mapper);
/**
* Returns a {@code LongStream} consisting of the results of replacing each
* element of this stream with multiple elements, specifically zero or more
* elements. Replacement is performed by applying the provided mapping
* function to each element in conjunction with a
* {@linkplain LongConsumer consumer} argument that accepts replacement
* elements. The mapping function calls the consumer zero or more times to
* provide the replacement elements.
*
*
This is an intermediate operation.
*
*
If the {@linkplain LongConsumer consumer} argument is used outside the
* scope of its application to the mapping function, the results are undefined.
*
* @param mapper a non-interfering, stateless
* function that generates replacement elements
*
* @return the new stream
*
* @since 22.09
*/
default RemoteLongStream mapMultiToLong(Remote.BiConsumer mapper)
{
return mapMultiToLong((BiConsumer) mapper);
}
/**
* Returns a {@code DoubleStream} consisting of the results of replacing
* each element of this stream with multiple elements, specifically zero or
* more elements. Replacement is performed by applying the provided mapping
* function to each element in conjunction with a
* {@linkplain DoubleConsumer consumer} argument that accepts replacement
* elements. The mapping function calls the consumer zero or more times to
* provide the replacement elements.
*
*
This is an intermediate operation.
*
*
If the {@linkplain DoubleConsumer consumer} argument is used outside the
* scope of its application to the mapping function, the results are undefined.
*
* @param mapper a non-interfering, stateless
* function that generates replacement elements
*
* @return the new stream
*
* @since 22.09
*/
@Override
RemoteDoubleStream mapMultiToDouble(BiConsumer mapper);
/**
* Returns a {@code DoubleStream} consisting of the results of replacing
* each element of this stream with multiple elements, specifically zero or
* more elements. Replacement is performed by applying the provided mapping
* function to each element in conjunction with a
* {@linkplain DoubleConsumer consumer} argument that accepts replacement
* elements. The mapping function calls the consumer zero or more times to
* provide the replacement elements.
*
*
This is an intermediate operation.
*
*
If the {@linkplain DoubleConsumer consumer} argument is used outside the
* scope of its application to the mapping function, the results are undefined.
*
* @param mapper a non-interfering, stateless
* function that generates replacement elements
*
* @return the new stream
*
* @since 22.09
*/
default RemoteDoubleStream mapMultiToDouble(Remote.BiConsumer mapper)
{
return mapMultiToDouble((BiConsumer) mapper);
}
/**
* Returns a stream consisting of the elements of this stream, additionally
* performing the provided action on each element as elements are consumed
* from the resulting stream.
*
* This is an intermediate operation.
*
* For parallel stream pipelines, the action may be called at whatever
* time and in whatever thread the element is made available by the upstream
* operation. If the action modifies shared state, it is responsible for
* providing the required synchronization.
*
* @param action a non-interfering action to perform on the elements as they
* are consumed from the stream
*
* @return the new stream
*/
RemoteStream peek(Consumer action);
/**
* Returns a stream consisting of the elements of this stream, additionally
* performing the provided action on each element as elements are consumed
* from the resulting stream.
*
* This is an intermediate operation.
*
* For parallel stream pipelines, the action may be called at whatever
* time and in whatever thread the element is made available by the upstream
* operation. If the action modifies shared state, it is responsible for
* providing the required synchronization.
*
* @param action a non-interfering action to perform on the elements as they
* are consumed from the stream
*
* @return the new stream
*/
default RemoteStream peek(Remote.Consumer action)
{
return peek((Consumer) action);
}
/**
* Returns a stream consisting of the elements of this stream, truncated to
* be no longer than {@code maxSize} in length.
*
* This is a short-circuiting stateful intermediate operation.
*
* @param maxSize the number of elements the stream should be limited to
*
* @return the new stream
*
* @throws IllegalArgumentException if {@code maxSize} is negative
*/
Stream limit(long maxSize);
/**
* Returns a stream consisting of the remaining elements of this stream
* after discarding the first {@code n} elements of the stream.
* If this stream contains fewer than {@code n} elements then an
* empty stream will be returned.
*
* This is a stateful intermediate operation.
*
* @param n the number of leading elements to skip
*
* @return the new stream
*
* @throws IllegalArgumentException if {@code n} is negative
*/
Stream skip(long n);
/**
* Returns, if this stream is ordered, a stream consisting of the longest
* prefix of elements taken from this stream that match the given predicate.
* Otherwise returns, if this stream is unordered, a stream consisting of a
* subset of elements taken from this stream that match the given
* predicate.
*
* If this stream is ordered then the longest prefix is a contiguous
* sequence of elements of this stream that match the given predicate. The
* first element of the sequence is the first element of this stream, and
* the element immediately following the last element of the sequence does
* not match the given predicate.
*
*
If this stream is unordered, and some (but not all) elements of this
* stream match the given predicate, then the behavior of this operation is
* nondeterministic; it is free to take any subset of matching elements
* (which includes the empty set).
*
*
Independent of whether this stream is ordered or unordered if all
* elements of this stream match the given predicate then this operation
* takes all elements (the result is the same as the input), or if no
* elements of the stream match the given predicate then no elements are
* taken (the result is an empty stream).
*
*
This is a short-circuiting stateful intermediate operation.
*
* @param predicate a non-interfering,
* stateless
* predicate to apply to elements to determine the longest
* prefix of elements.
*
* @return the new stream
*
* @implSpec The default implementation obtains the
* {@link #spliterator() spliterator} of this stream, wraps that spliterator
* so as to support the semantics of this operation on traversal, and
* returns a new stream associated with the wrapped spliterator. The
* returned stream preserves the execution characteristics of this stream
* (namely parallel or sequential execution as per {@link #isParallel()})
* but the wrapped spliterator may choose to not support splitting. When
* the returned stream is closed, the close handlers for both the returned
* and this stream are invoked.
* @apiNote While {@code takeWhile()} is generally a cheap operation on
* sequential stream pipelines, it can be quite expensive on ordered
* parallel pipelines, since the operation is constrained to return not just
* any valid prefix, but the longest prefix of elements in the encounter
* order. Using an unordered stream source (such as
* {@link #generate(Supplier)}) or removing the ordering constraint with
* {@link #unordered()} may result in significant speedups of
* {@code takeWhile()} in parallel pipelines, if the semantics of your
* situation permit. If consistency with encounter order is required, and
* you are experiencing poor performance or memory utilization with
* {@code takeWhile()} in parallel pipelines, switching to sequential
* execution with {@link #sequential()} may improve performance.
* @since 9
*/
@Override
default Stream takeWhile(Predicate predicate)
{
return Stream.super.takeWhile(predicate);
}
/**
* Returns, if this stream is ordered, a stream consisting of the remaining
* elements of this stream after dropping the longest prefix of elements
* that match the given predicate. Otherwise returns, if this stream is
* unordered, a stream consisting of the remaining elements of this stream
* after dropping a subset of elements that match the given predicate.
*
* If this stream is ordered then the longest prefix is a contiguous
* sequence of elements of this stream that match the given predicate. The
* first element of the sequence is the first element of this stream, and
* the element immediately following the last element of the sequence does
* not match the given predicate.
*
*
If this stream is unordered, and some (but not all) elements of this
* stream match the given predicate, then the behavior of this operation is
* nondeterministic; it is free to drop any subset of matching elements
* (which includes the empty set).
*
*
Independent of whether this stream is ordered or unordered if all
* elements of this stream match the given predicate then this operation
* drops all elements (the result is an empty stream), or if no elements of
* the stream match the given predicate then no elements are dropped (the
* result is the same as the input).
*
*
This is a stateful intermediate operation.
*
* @param predicate a non-interfering,
* stateless
* predicate to apply to elements to determine the longest
* prefix of elements.
*
* @return the new stream
*
* @implSpec The default implementation obtains the
* {@link #spliterator() spliterator} of this stream, wraps that spliterator
* so as to support the semantics of this operation on traversal, and
* returns a new stream associated with the wrapped spliterator. The
* returned stream preserves the execution characteristics of this stream
* (namely parallel or sequential execution as per {@link #isParallel()})
* but the wrapped spliterator may choose to not support splitting. When
* the returned stream is closed, the close handlers for both the returned
* and this stream are invoked.
* @apiNote While {@code dropWhile()} is generally a cheap operation on
* sequential stream pipelines, it can be quite expensive on ordered
* parallel pipelines, since the operation is constrained to return not just
* any valid prefix, but the longest prefix of elements in the encounter
* order. Using an unordered stream source (such as
* {@link #generate(Supplier)}) or removing the ordering constraint with
* {@link #unordered()} may result in significant speedups of
* {@code dropWhile()} in parallel pipelines, if the semantics of your
* situation permit. If consistency with encounter order is required, and
* you are experiencing poor performance or memory utilization with
* {@code dropWhile()} in parallel pipelines, switching to sequential
* execution with {@link #sequential()} may improve performance.
* @since 9
*/
@Override
default Stream dropWhile(Predicate predicate)
{
return Stream.super.dropWhile(predicate);
}
/**
* Returns a stream consisting of the distinct elements (according to
* {@link Object#equals(Object)}) of this stream.
*
* For ordered streams, the selection of distinct elements is stable
* (for duplicated elements, the element appearing first in the encounter
* order is preserved.) For unordered streams, no stability guarantees
* are made.
*
* This is a stateful intermediate operation.
*
* @return the new stream
*/
Stream distinct();
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to natural order. If the elements of this stream are not
* {@code Comparable}, a {@code java.lang.ClassCastException} may be thrown
* when the terminal operation is executed.
*
* For ordered streams, the sort is stable. For unordered streams, no
* stability guarantees are made.
*
* This is a stateful intermediate operation.
*
* @return the new stream
*/
RemoteStream sorted();
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to the provided {@code Comparator}.
*
* 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
*/
RemoteStream sorted(Comparator comparator);
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to the provided {@code Comparator}.
*
* 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
*/
default RemoteStream sorted(Remote.Comparator comparator)
{
return sorted(comparator, false);
}
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to the provided {@code Comparator}.
*
* 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
* @param fInverse a flag specifying whether to invert the sort order
*
* @return the new stream
*/
default RemoteStream sorted(Remote.Comparator comparator, boolean fInverse)
{
Comparator c = fInverse ? new InverseComparator<>(comparator) : comparator;
return sorted(c);
}
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to attribute extracted by the provided {@code ValueExtractor}.
*
* For ordered streams, the sort is stable. For unordered streams, no
* stability guarantees are made.
*
*
This is a stateful
* intermediate operation.
*
* @param a super type of the value to extract from
* @param extractor a non-interfering, stateless
* {@code ValueExtractor} to be used to extract the attribute
* that should be used to compare stream elements
*
* @return the new stream
*/
default RemoteStream sorted(ValueExtractor extractor)
{
return sorted(extractor, false);
}
/**
* Returns a stream consisting of the elements of this stream, sorted
* according to attribute extracted by the provided {@code ValueExtractor}.
*
* For ordered streams, the sort is stable. For unordered streams, no
* stability guarantees are made.
*
*
This is a stateful
* intermediate operation.
*
* @param the super type of value to extract from
* @param extractor a non-interfering, stateless
* {@code ValueExtractor} to be used to extract the attribute
* that should be used to compare stream elements
* @param fInverse a flag specifying whether to invert natural sort order
*
* @return the new stream
*/
default RemoteStream sorted(ValueExtractor extractor, boolean fInverse)
{
Comparator comparator = new ExtractorComparator(extractor);
if (fInverse)
{
comparator = new InverseComparator<>(comparator);
}
return sorted(comparator);
}
/**
* Performs an action for each element of this stream.
*
* This is a terminal operation.
*
* @param action a non-interfering action to perform on the elements
*/
void forEach(Consumer action);
/**
* Performs an action for each element of this stream, in the encounter
* order of the stream if the stream has a defined encounter order.
*
* This is a terminal operation.
*
* This operation processes the elements one at a time, in encounter
* order if one exists. Performing the action for one element
* happens-before performing the action for subsequent elements,
* but for any given element, the action may be performed in whatever thread
* the library chooses.
*
* @param action a non-interfering action to perform on the elements
*
* @see #forEach(Consumer)
*/
void forEachOrdered(Consumer action);
/**
* Returns an array containing the elements of this stream.
*
* This is a terminal operation.
*
* @return an array containing the elements of this stream
*/
Object[] toArray();
/**
* 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.
*