BaseStream (abacus API Documentation)

Type Parameters:

T - the type of the stream elements

A - the type of array

P - the type of predicate

C - the type of consumer

PL - the type of PrimitiveList/List

OT - the type of Optional

IT - the type of Indexed

S - the type of of the stream implementing BaseStream

All Superinterfaces:

java.lang.AutoCloseable

All Known Implementing Classes:

ByteStream, CharStream, DoubleStream, DoubleStream.DoubleStreamEx, FloatStream, IntStream, IntStream.IntStreamEx, LongStream, LongStream.LongStreamEx, ShortStream, Stream, Stream.StreamEx
```
public interface BaseStream<T,A,P,C,PL,OT,IT,S extends BaseStream<T,A,P,C,PL,OT,IT,S>>
extends java.lang.AutoCloseable
```
Note: It's copied from OpenJDK at: http://hg.openjdk.java.net/jdk8u/hs-dev/jdk
Base interface for streams, which are sequences of elements supporting sequential and parallel aggregate operations. The following example illustrates an aggregate operation using the stream types Stream and IntStream, computing the sum of the weights of the red widgets:
```
     int sum = widgets.stream()
                      .filter(w -> w.getColor() == RED)
                      .mapToInt(w -> w.getWeight())
                      .sum();
 
```
See the class documentation for Stream and the package documentation for java.util.stream for additional specification of streams, stream operations, stream pipelines, and parallelism, which governs the behavior of all stream types.
Since:

1.8

See Also:

Stream, IntStream, LongStream, DoubleStream, java.util.stream

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class BaseStream.Splitor

Nested Classes
Modifier and Type	Interface and Description
`static class`	`BaseStream.Splitor`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`<R> R`	`__(Function<? super S,R> transfer)`
`boolean`	`allMatch(P predicate)` Returns whether all elements of this stream match the provided predicate.
`boolean`	`anyMatch(P predicate)` Returns whether any elements of this stream match the provided predicate.
`S`	`append(S s)`
`S`	`cached()` This method only run sequentially, even in parallel stream and all elements will be loaded to memory.
`void`	`close()` Closes this stream, causing all close handlers for this stream pipeline to be called.
`long`	`count()` Returns the count of elements in this stream.
`S`	`difference(java.util.Collection<?> c)` This method only run sequentially, even in parallel stream.
`S`	`distinct()` Returns a stream consisting of the distinct elements of this stream.
`Optional<java.util.Map<com.landawn.abacus.util.Percentage,T>>`	`distribution()` All elements will be loaded to memory and sorted if not yet.
`S`	`dropWhile(P predicate)` Remove the elements until the given predicate returns false.
`S`	`filter(P predicate)` Returns a stream consisting of the elements of this stream that match the given predicate.
`OT`	`findAny(P predicate)` Returns an `Optional` describing some element of the stream, or an empty `Optional` if the stream is empty.
`OT`	`findFirst(P predicate)` Returns an `Optional` describing the first element of this stream, or an empty `Optional` if the stream is empty.
`OT`	`findFirstOrLast(P predicateForFirst, P predicateForLast)` Returns the first element which is tested by the specified `predicateForFirst`, or the last element which is tested by the specified `predicateForLast` if the first element is not found.
`OT`	`findLast(P predicate)` Sometimes, `stream.reverse().findFirst(predicate)` has better performance than `stream.findLast(predicate)`.
`OT`	`first()`
`void`	`forEach(C action)` Performs an action for each element of this stream.
`Stream<IT>`	`indexed()` This method only run sequentially, even in parallel stream.
`S`	`intersection(java.util.Collection<?> c)` This method only run sequentially, even in parallel stream.
`boolean`	`isParallel()` Returns whether this stream, if a terminal operation were to be executed, would execute in parallel.
`ImmutableIterator<T>`	`iterator()` Returns an iterator for the elements of this stream.
`java.lang.String`	`join(java.lang.CharSequence delimiter)`
`java.lang.String`	`join(java.lang.CharSequence delimiter, java.lang.CharSequence prefix, java.lang.CharSequence suffix)`
`OT`	`last()`
`S`	`limit(long maxSize)` Returns a stream consisting of the elements of this stream, truncated to be no longer than `maxSize` in length.
`int`	`maxThreadNum()` Return the underlying `maxThreadNum` if the stream is parallel, otherwise `1` is returned.
`S`	`maxThreadNum(int maxThreadNum)` Returns a parallel stream with the specified `maxThreadNum` .
`boolean`	`noneMatch(P predicate)` Returns whether no elements of this stream match the provided predicate.
`S`	`onClose(java.lang.Runnable closeHandler)` Returns an equivalent stream with an additional close handler.
`S`	`parallel()` Returns an equivalent stream that is parallel.
`S`	`parallel(BaseStream.Splitor splitor)` Returns an equivalent stream that is parallel.
`S`	`parallel(int maxThreadNum)` Returns an equivalent stream that is parallel.
`S`	`parallel(int maxThreadNum, BaseStream.Splitor splitor)` Returns an equivalent stream that is parallel.
`S`	`peek(C 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.
`S`	`prepend(S stream)`
`void`	`println()`
`S`	`remove(long n, C consumer)` Returns a stream consisting of the remaining elements of this stream after removing and consuming the first `n` elements of the stream.
`S`	`removeIf(P predicate)`
`S`	`removeIf(P predicate, C consumer)`
`S`	`removeWhile(P predicate, C consumer)` Returns a stream consisting of the remaining elements of this stream after removing and consuming until the specified `predicate` return false.
`S`	`reversed()` This method only run sequentially, even in parallel stream and all elements will be loaded to memory.
`S`	`reverseSorted()`
`S`	`rotated(int distance)` This method only run sequentially, even in parallel stream and all elements will be loaded to memory.
`S`	`sequential()` Returns an equivalent stream that is sequential.
`S`	`shuffled()` This method only run sequentially, even in parallel stream and all elements will be loaded to memory.
`S`	`shuffled(java.util.Random rnd)` This method only run sequentially, even in parallel stream and all elements will be loaded to memory.
`S`	`skip(long n)` Returns a stream consisting of the remaining elements of this stream after discarding the first `n` elements of the stream.
`Stream<S>`	`sliding(int windowSize)`
`Stream<S>`	`sliding(int windowSize, int increment)` `Stream.of(1, 2, 3, 4, 5, 6, 7, 8).sliding(3, 1).forEach(Stream::println)` output: [1, 2, 3] [2, 3, 4] [3, 4, 5] [4, 5, 6] [5, 6, 7] [6, 7, 8] ============================================================================ `Stream.of(1, 2, 3, 4, 5, 6, 7, 8).sliding(3, 3).forEach(Stream::println)` output: [1, 2, 3] [4, 5, 6] [7, 8] ============================================================================ `Stream.of(1, 2, 3, 4, 5, 6, 7, 5).sliding(3, 5).forEach(Stream::println)` output: [1, 2, 3] [6, 7, 8] This method only run sequentially, even in parallel stream.
`Stream<PL>`	`slidingToList(int windowSize)`
`Stream<PL>`	`slidingToList(int windowSize, int increment)`
`S`	`sorted()` Returns a stream consisting of the elements of this stream in sorted order.
`Stream<S>`	`split(int size)` Returns Stream of ByteStream with consecutive sub sequences of the elements, each of the same size (the final sequence may be smaller).
`Stream<S>`	`split(P predicate)` Split the stream by the specified predicate.
`<U> Stream<S>`	`split(U identity, BiFunction<? super T,? super U,java.lang.Boolean> predicate, Consumer<? super U> identityUpdate)` Split the stream by the specified predicate.
`Stream<S>`	`splitAt(int where)` Split the stream into two pieces at `where`
`Stream<S>`	`splitBy(P where)` Split the stream into two pieces at `where`
`BaseStream.Splitor`	`splitor()` Return the underlying `splitor` if the stream is parallel, otherwise the default value `splitor.ITERATOR` is returned.
`S`	`splitor(BaseStream.Splitor splitor)` Returns a parallel stream with the specified `splitor` .
`Stream<PL>`	`splitToList(int size)` Returns Stream of Stream with consecutive sub sequences of the elements, each of the same size (the final sequence may be smaller).
`Stream<PL>`	`splitToList(P predicate)` Split the stream by the specified predicate.
`<U> Stream<PL>`	`splitToList(U identity, BiFunction<? super T,? super U,java.lang.Boolean> predicate, Consumer<? super U> identityUpdate)` Split the stream by the specified predicate.
`S`	`step(long step)`
`S`	`symmetricDifference(java.util.Collection<T> c)` This method only run sequentially, even in parallel stream.
`S`	`takeWhile(P predicate)` Keep the elements until the given predicate returns false.
`A`	`toArray()` Returns an array containing the elements of this stream.
`java.util.List<T>`	`toList()`
`<R extends java.util.List<T>> R`	`toList(Supplier<R> supplier)`
`LongMultiset<T>`	`toLongMultiset()`
`LongMultiset<T>`	`toLongMultiset(Supplier<? extends LongMultiset<T>> supplier)`
`Multiset<T>`	`toMultiset()`
`Multiset<T>`	`toMultiset(Supplier<? extends Multiset<T>> supplier)`
`java.util.Set<T>`	`toSet()`
`<R extends java.util.Set<T>> R`	`toSet(Supplier<R> supplier)`
`Try<S>`	`tried()`

Method Detail

filter
```
S filter(P predicate)
```
Returns a stream consisting of the elements of this stream that match the given predicate.
This is an intermediate operation.

Parameters:

predicate - a non-interfering, stateless predicate to apply to each element to determine if it should be included

Returns:

the new stream

takeWhile
```
S takeWhile(P predicate)
```
Keep the elements until the given predicate returns false. The stream should be sorted, which means if x is the first element: predicate.text(x) returns false, any element y behind x: predicate.text(y) should returns false. In parallel Streams, the elements after the first element which predicate returns false may be tested by predicate too.

Parameters:

predicate -

Returns:

dropWhile
```
S dropWhile(P predicate)
```
Remove the elements until the given predicate returns false. The stream should be sorted, which means if x is the first element: predicate.text(x) returns true, any element y behind x: predicate.text(y) should returns true. In parallel Streams, the elements after the first element which predicate returns false may be tested by predicate too.

Parameters:

predicate -

Returns:

remove
```
S remove(long n,
         C consumer)
```
Returns a stream consisting of the remaining elements of this stream after removing and consuming the first n elements of the stream. If this stream contains fewer than n elements then an empty stream will be returned.

Parameters:

n -

consumer -

Returns:

removeIf
```
S removeIf(P predicate)
```

removeIf

S removeIf(P predicate,
           C consumer)

removeWhile
```
S removeWhile(P predicate,
              C 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.

Parameters:

predicate -

consumer -

Returns:

split
```
Stream<S> split(int size)
```
Returns Stream of ByteStream with consecutive sub sequences of the elements, each of the same size (the final sequence may be smaller).

Parameters:

size -

Returns:

splitToList
```
Stream<PL> splitToList(int size)
```
Returns Stream of Stream with consecutive sub sequences of the elements, each of the same size (the final sequence may be smaller).
This method only run sequentially, even in parallel stream.

Parameters:

size -

Returns:

split
```
Stream<S> split(P predicate)
```
Split the stream by the specified predicate. This stream should be sorted by value which is used to verify the border.
This method only run sequentially, even in parallel stream.

Parameters:

predicate -

Returns:

splitToList
```
Stream<PL> splitToList(P predicate)
```
Split the stream by the specified predicate. This stream should be sorted by value which is used to verify the border.
This method only run sequentially, even in parallel stream.

Parameters:

predicate -

Returns:

split

<U> Stream<S> split(U identity,
                    BiFunction<? super T,? super U,java.lang.Boolean> predicate,
                    Consumer<? super U> identityUpdate)

Split the stream by the specified predicate.

 
 // 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);

This stream should be sorted by value which is used to verify the border.
This method only run sequentially, even in parallel stream.

Parameters:: identity -; predicate -; identityUpdate -
Returns:

splitToList

<U> Stream<PL> splitToList(U identity,
                           BiFunction<? super T,? super U,java.lang.Boolean> predicate,
                           Consumer<? super U> identityUpdate)

Split the stream by the specified predicate.

 
 // 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);

This stream should be sorted by value which is used to verify the border.
This method only run sequentially, even in parallel stream.

Parameters:: identity -; predicate -; identityUpdate -
Returns:

splitAt
```
Stream<S> splitAt(int where)
```
Split the stream into two pieces at where

Parameters:

where -

Returns:

splitBy
```
Stream<S> splitBy(P where)
```
Split the stream into two pieces at where

Parameters:

where -

Returns:

sliding
```
Stream<S> sliding(int windowSize)
```
Parameters:

windowSize -

Returns:

See Also:

sliding(int, int)

slidingToList
```
Stream<PL> slidingToList(int windowSize)
```
Parameters:

windowSize -

Returns:

See Also:

sliding(int, int)

sliding
```
Stream<S> sliding(int windowSize,
                  int increment)
```
Stream.of(1, 2, 3, 4, 5, 6, 7, 8).sliding(3, 1).forEach(Stream::println)
output:
[1, 2, 3]
[2, 3, 4]
[3, 4, 5]
[4, 5, 6]
[5, 6, 7]
[6, 7, 8]

============================================================================
Stream.of(1, 2, 3, 4, 5, 6, 7, 8).sliding(3, 3).forEach(Stream::println)
output:
[1, 2, 3]
[4, 5, 6]
[7, 8]

============================================================================
Stream.of(1, 2, 3, 4, 5, 6, 7, 5).sliding(3, 5).forEach(Stream::println)
output:
[1, 2, 3]
[6, 7, 8]

This method only run sequentially, even in parallel stream.

Parameters:

windowSize -

increment -

Returns:

slidingToList

Stream<PL> slidingToList(int windowSize,
                         int increment)

Parameters:: windowSize -; increment -
Returns:
See Also:: sliding(int, int)

intersection
```
S intersection(java.util.Collection<?> c)
```
This method only run sequentially, even in parallel stream.

Parameters:

c -

Returns:

See Also:

IntList.intersection(IntList)

difference
```
S difference(java.util.Collection<?> c)
```
This method only run sequentially, even in parallel stream.

Parameters:

c -

Returns:

See Also:

IntList.difference(IntList)

symmetricDifference
```
S symmetricDifference(java.util.Collection<T> c)
```
This method only run sequentially, even in parallel stream.

Parameters:

c -

Returns:

See Also:

IntList.symmetricDifference(IntList)

distribution
```
Optional<java.util.Map<com.landawn.abacus.util.Percentage,T>> distribution()
```
All elements will be loaded to memory and sorted if not yet.

Returns:

reversed
```
S reversed()
```
This method only run sequentially, even in parallel stream and all elements will be loaded to memory.

Returns:

shuffled
```
S shuffled()
```
This method only run sequentially, even in parallel stream and all elements will be loaded to memory.

Returns:

shuffled
```
S shuffled(java.util.Random rnd)
```
This method only run sequentially, even in parallel stream and all elements will be loaded to memory.

Returns:

rotated
```
S rotated(int distance)
```
This method only run sequentially, even in parallel stream and all elements will be loaded to memory.

Returns:

distinct
```
S distinct()
```
Returns a stream consisting of the distinct elements of this stream.
This is a stateful intermediate operation.

Returns:

the new stream

sorted
```
S sorted()
```
Returns a stream consisting of the elements of this stream in sorted order.
All elements will be loaded to memory.

Returns:

the new stream

reverseSorted
```
S reverseSorted()
```

append
```
S append(S s)
```

prepend
```
S prepend(S stream)
```

cached
```
S cached()
```
This method only run sequentially, even in parallel stream and all elements will be loaded to memory.

Returns:

indexed
```
Stream<IT> indexed()
```
This method only run sequentially, even in parallel stream.

Returns:

join

java.lang.String join(java.lang.CharSequence delimiter)

join

java.lang.String join(java.lang.CharSequence delimiter,
                      java.lang.CharSequence prefix,
                      java.lang.CharSequence suffix)

skip
```
S skip(long n)
```
Returns a stream consisting of the remaining elements of this stream after discarding the first n elements of the stream. If this stream contains fewer than n elements then an empty stream will be returned.
This is a stateful intermediate operation.

Parameters:

n - the number of leading elements to skip

Returns:

the new stream

Throws:

java.lang.IllegalArgumentException - if n is negative

limit
```
S limit(long maxSize)
```
Returns a stream consisting of the elements of this stream, truncated to be no longer than maxSize in length.
This is a byte-circuiting stateful intermediate operation.

Parameters:

maxSize - the number of elements the stream should be limited to

Returns:

the new stream

Throws:

java.lang.IllegalArgumentException - if maxSize is negative

step
```
S step(long step)
```

count
```
long count()
```
Returns the count of elements in this stream. This is a special case of a reduction and is equivalent to:
```
     return mapToLong(e -> 1L).sum();
 
```
This is a terminal operation.
Returns:

the count of elements in this stream

peek
```
S peek(C 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.

Parameters:

action - a non-interfering action to perform on the elements as they are consumed from the stream

Returns:

this stream or a new stream with same elements.

forEach
```
void forEach(C action)
```
Performs an action for each element of this stream.
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.

Parameters:

action - a non-interfering action to perform on the elements

anyMatch
```
boolean anyMatch(P predicate)
```
Returns whether any elements of this stream match the provided predicate. May not evaluate the predicate on all elements if not necessary for determining the result. If the stream is empty then false is returned and the predicate is not evaluated.
This is a short-circuiting terminal operation.

Parameters:

predicate - a non-interfering, stateless predicate to apply to elements of this stream

Returns:

true if any elements of the stream match the provided predicate, otherwise false

allMatch
```
boolean allMatch(P predicate)
```
Returns whether all elements of this stream match the provided predicate. May not evaluate the predicate on all elements if not necessary for determining the result. If the stream is empty then true is returned and the predicate is not evaluated.
This is a short-circuiting terminal operation.

Parameters:

predicate - a non-interfering, stateless predicate to apply to elements of this stream

Returns:

true if either all elements of the stream match the provided predicate or the stream is empty, otherwise false

noneMatch
```
boolean noneMatch(P predicate)
```
Returns whether no elements of this stream match the provided predicate. May not evaluate the predicate on all elements if not necessary for determining the result. If the stream is empty then true is returned and the predicate is not evaluated.
This is a short-circuiting terminal operation.

Parameters:

predicate - a non-interfering, stateless predicate to apply to elements of this stream

Returns:

true if either no elements of the stream match the provided predicate or the stream is empty, otherwise false

findFirst
```
OT findFirst(P predicate)
```
Returns an Optional describing the first element of this stream, or an empty Optional if the stream is empty. If the stream has no encounter order, then any element may be returned.
This is a short-circuiting terminal operation.

Returns:

an Optional describing the first element of this stream, or an empty Optional if the stream is empty

findLast
```
OT findLast(P predicate)
```
Sometimes, stream.reverse().findFirst(predicate) has better performance than stream.findLast(predicate).

Parameters:

predicate -

Returns:

findFirstOrLast
```
OT findFirstOrLast(P predicateForFirst,
                   P predicateForLast)
```
Returns the first element which is tested by the specified predicateForFirst, or the last element which is tested by the specified predicateForLast if the first element is not found. or an empty Optional if both first and last elements are not found.
This method only run sequentially, even in parallel stream.

Parameters:

predicateForFirst -

predicateForLast -

Returns:

findAny
```
OT findAny(P predicate)
```
Returns an Optional describing some element of the stream, or an empty Optional if the stream is empty.
This is a short-circuiting terminal operation.
The behavior of this operation is explicitly nondeterministic; it is free to select any element in the stream. This is to allow for maximal performance in parallel operations; the cost is that multiple invocations on the same source may not return the same result. (If a stable result is desired, use #findFirst() instead.)

Returns:

an Optional describing some element of this stream, or an empty Optional if the stream is empty

See Also:

#findFirst()

first
```
OT first()
```

last
```
OT last()
```

toArray
```
A toArray()
```
Returns an array containing the elements of this stream.
This is a terminal operation.

Returns:

an array containing the elements of this stream

toList
```
java.util.List<T> toList()
```

toList

<R extends java.util.List<T>> R toList(Supplier<R> supplier)

toSet
```
java.util.Set<T> toSet()
```

toSet

<R extends java.util.Set<T>> R toSet(Supplier<R> supplier)

toMultiset
```
Multiset<T> toMultiset()
```

toMultiset

Multiset<T> toMultiset(Supplier<? extends Multiset<T>> supplier)

toLongMultiset
```
LongMultiset<T> toLongMultiset()
```

toLongMultiset

LongMultiset<T> toLongMultiset(Supplier<? extends LongMultiset<T>> supplier)

iterator
```
ImmutableIterator<T> iterator()
```
Returns an iterator for the elements of this stream.

Returns:

the element iterator for this stream

println
```
void println()
```

isParallel
```
boolean isParallel()
```
Returns whether this stream, if a terminal operation were to be executed, would execute in parallel. Calling this method after invoking an terminal stream operation method may yield unpredictable results.

Returns:

true if this stream would execute in parallel if executed

sequential
```
S sequential()
```
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.

Returns:

a sequential stream

parallel
```
S parallel()
```
Returns an equivalent stream that is parallel. May return itself if the stream was already parallel. Any parallel should be closed by try-catch or call tried before last step.

Returns:

a parallel stream

See Also:

parallel(int, Splitor)

parallel
```
S parallel(int maxThreadNum)
```
Returns an equivalent stream that is parallel. May return itself if the stream was already parallel with the same maxThreadNum as the specified one.

Parameters:

maxThreadNum -

Returns:

See Also:

parallel(int, Splitor)

parallel
```
S parallel(BaseStream.Splitor splitor)
```
Returns an equivalent stream that is parallel. May return itself if the stream was already parallel with the same splitor as the specified one.

Parameters:

splitor -

Returns:

See Also:

parallel(int, Splitor)

parallel

S parallel(int maxThreadNum,
           BaseStream.Splitor splitor)

Returns an equivalent stream that is parallel. May return itself if the stream was already parallel with the same maxThreadNum and splitor as the specified ones.

When to use parallel Streams?

First of all, do NOT and should NOT use parallel Streams if you don't have any problem with sequential Streams, because using parallel Streams has extra cost.
Consider using parallel Streams only when N(the number of elements) * Q(cost per element of F, the per-element function (usually a lambda)) is big enough(e.g. IO involved. Network: DB/web service request..., Reading/Writing file...).
It's easy to test out the differences of performance by sequential Streams and parallel Streams with Profiler:

 
 Profiler.run(1, 1, 3, "sequential", () -> Stream.of(list).operation(F)...).printResult();
 Profiler.run(1, 1, 3, "parallel", () -> Stream.of(list).parallel().operation(F)...).printResult();

Here is a sample performance test with computer: CPU Intel i7-3520M 4-cores 2.9 GHz, JDK 1.8.0_101, Windows 7:

 
 public void test_perf() {
     final String[] strs = new String[10_000];
     N.fill(strs, N.uuid());
 
     final int m = 1;
     final Function mapper = str -> {
         long result = 0;
         for (int i = 0; i < m; i++) {
             result += sum(str.toCharArray()) + 1;
         }
         return result;
     };
 
     final MutableLong sum = MutableLong.of(0);
 
     for (int i = 0, len = strs.length; i < len; i++) {
         sum.add(mapper.apply(strs[i]));
     }
 
     final int threadNum = 1, loopNum = 100, roundNum = 3;
 
     Profiler.run(threadNum, loopNum, roundNum, "For Loop", () -> {
         long result = 0;
         for (int i = 0, len = strs.length; i < len; i++) {
             result += mapper.apply(strs[i]);
         }
         assertEquals(sum.longValue(), result);
     }).printResult();
 
     Profiler.run(threadNum, loopNum, roundNum, "JDK Sequential",
             () -> assertEquals(sum.longValue(), java.util.stream.Stream.of(strs).map(mapper).mapToLong(e -> e).sum())).printResult();
 
     Profiler.run(threadNum, loopNum, roundNum, "JDK Parallel",
             () -> assertEquals(sum.longValue(), java.util.stream.Stream.of(strs).parallel().map(mapper).mapToLong(e -> e).sum())).printResult();
 
     Profiler.run(threadNum, loopNum, roundNum, "Abcus Sequential",
             () -> assertEquals(sum.longValue(), Stream.of(strs).map(mapper).mapToLong(e -> e).sum().longValue())).printResult();
 
     Profiler.run(threadNum, loopNum, roundNum, "Abcus Parallel",
             () -> assertEquals(sum.longValue(), Stream.of(strs).parallel().map(mapper).mapToLong(e -> e).sum().longValue())).printResult();
 }

And test result: Unit is milliseconds. N(the number of elements) is 10_000, Q(cost per element of F, the per-element function (usually a lambda), here is mapper) is calculated by: value of 'For loop' / N(10_000).

	m = 1	m = 10	m = 50	m = 100	m = 500	m = 1000
Q	0.00002	0.0002	0.001	0.002	0.01	0.02
For Loop	0.23	2.3	11	22	110	219
JDK Sequential	0.28	2.3	11	22	114	212
JDK Parallel	0.22	1.3	6	12	66	122
Abcus Sequential	0.3	2	11	22	112	212
Abcus Parallel	11	11	11	16	77	128

Comparison:

Again, do NOT and should NOT use parallel Streams if you don't have any performance problem with sequential Streams, because using parallel Streams has extra cost.
Again, consider using parallel Streams only when N(the number of elements) * Q(cost per element of F, the per-element function (usually a lambda)) is big enough.
The implementation of parallel Streams in Abacus is more than 10 times, slower than parallel Streams in JDK when Q is tiny(here is less than 0.0002 milliseconds by the test):

The implementation of parallel Streams in JDK 8 still can beat the sequential/for loop when Q is tiny(Here is 0.00002 milliseconds by the test). That's amazing, considering the extra cost brought by parallel computation. It's well done.
The implementation of parallel Streams in Abacus is pretty simple and straight forward. The extra cost(starting threads/synchronization/queue...) brought by parallel Streams in Abacus is too bigger to tiny Q(Here is less than 0.001 milliseconds by the test). But it starts to be faster than sequential Streams when Q is big enough(Here is 0.001 milliseconds by the test) and starts to catch the parallel Streams in JDK when Q is bigger(Here is 0.01 milliseconds by the test).
Consider using the parallel Streams in Abacus when Q is big enough, specially when IO involved in F. Because one IO operation(e.g. DB/web service request..., Reading/Writing file...) usually takes 1 to 1000 milliseconds, or even longer. By the parallel Streams APIs in Abacus, it's very simple to specify max thread numbers. Sometimes, it's much faster to execute IO/Network requests with a bit more threads. It's fair to say that the parallel Streams in Abacus is high efficient, may same as or faster than the parallel Streams in JDK when Q is big enough, except F is heavy cpu-used operation. Most of the times, the Q is big enough to consider using parallel Stream is because IO/Network is involved in F.

JDK 7 is supported by the Streams in Abacus. It's perfect to work with retrolambda on Android
All primitive types are supported by Stream APIs in Abacus except boolean

A bit more about Lambdas/Stream APIs, you may heard that Lambdas/Stream APIs is 5 time slower than imperative programming. It's true when Q and F is VERY, VERY tiny, like f = (int a, int b) -> a + b;. But if we look into the samples in the article and think about it: it just takes less than 1 milliseconds to get the max value in 100k numbers. There is potential performance issue only if the "get the max value in 100K numbers" call many, many times in your API or single request. Otherwise, the difference between 0.1 milliseconds to 0.5 milliseconds can be totally ignored. Usually we meet performance issue only if Q and F is big enough. However, the performance of Lambdas/Streams APIs is closed to for loop when Q and F is big enough. No matter in which scenario, We don't need and should not concern the performance of Lambdas/Stream APIs.

Although it's is parallel Streams, it doesn't means all the methods are executed in parallel. Because the sequential way is as fast, or even faster than the parallel way for some methods, or is pretty difficult, if not possible, to implement the method by parallel approach. Here are the methods which are executed sequentially even in parallel Streams.

splitXXX/splitAt/splitBy/slidingXXX/collapse, distinct, reverse, rotate, shuffle, indexed, cached, top, kthLargest, count, toArray, toList, toList, toSet, toMultiset, toLongMultiset, intersection(Collection c), difference(Collection c), symmetricDifference(Collection c), forEach(identity, accumulator, predicate), findFirstOrLast, findFirstAndLast

Parameters:

maxThreadNum - Default value is the number of cpu-cores. Steps/operations will be executed sequentially if maxThreadNum is 1.

splitor - The target array is split by ranges for multiple threads if splitor is splitor.ARRAY and target stream composed by array. It looks like:


 for (int i = 0; i < maxThreadNum; i++) {
     final int sliceIndex = i;
 
     futureList.add(asyncExecutor.execute(new Runnable() {
         public void run() {
             int cursor = fromIndex + sliceIndex * sliceSize;
             final int to = toIndex - cursor > sliceSize ? cursor + sliceSize : toIndex;
             while (cursor < to) {
                 action.accept(elements[cursor++]);
             }
        }
    }));
 }

Otherwise, each thread will get the elements from the target array/iterator in the stream one by one with the target array/iterator synchronized. It looks like:


 for (int i = 0; i < maxThreadNum; i++) {
     futureList.add(asyncExecutor.execute(new Runnable() {
         public void run() {
             T next = null;
 
             while (true) {
                 synchronized (elements) {
                     if (cursor.intValue() < toIndex) {
                         next = elements[cursor.getAndIncrement()];
                     } else {
                         break;
                     }
                 }
 
                 action.accept(next);
             }
         }
     }));
 }

Using splitor.ARRAY only when F (the per-element function (usually a lambda)) is very tiny and the cost of synchronization on the target array/iterator is too big to it. For the F involving IO or taking 'long' to complete, choose splitor.ITERATOR. Default value is splitor.ITERATOR.

Returns:

See Also:

Nth, com.landawn.abacus.util.Profiler#run(int, int, int, String, Runnable), Understanding Parallel Stream Performance in Java SE 8, When to use parallel Streams

maxThreadNum
```
int maxThreadNum()
```
Return the underlying maxThreadNum if the stream is parallel, otherwise 1 is returned.

Returns:

maxThreadNum
```
S maxThreadNum(int maxThreadNum)
```
Returns a parallel stream with the specified maxThreadNum . Or return itself, either because the stream was already parallel with same maxThreadNum, or because it's a sequential stream.

Parameters:

maxThreadNum -

Returns:

splitor
```
BaseStream.Splitor splitor()
```
Return the underlying splitor if the stream is parallel, otherwise the default value splitor.ITERATOR is returned.

Returns:

splitor
```
S splitor(BaseStream.Splitor splitor)
```
Returns a parallel stream with the specified splitor . Or return itself, either because the stream was already parallel with same splitor, or because it's a sequential stream.

Parameters:

splitor -

Returns:

__

<R> R __(Function<? super S,R> transfer)

tried
```
Try<S> tried()
```

onClose
```
S onClose(java.lang.Runnable closeHandler)
```
Returns an equivalent stream with an additional close handler. Close handlers are run when the close() method is called on the stream, and are executed in the order they were added. All close handlers are run, even if earlier close handlers throw exceptions. If any close handler throws an exception, the first exception thrown will be relayed to the caller of close(), with any remaining exceptions added to that exception as suppressed exceptions (unless one of the remaining exceptions is the same exception as the first exception, since an exception cannot suppress itself.) May return itself.
This is an intermediate operation.

Parameters:

closeHandler - A task to execute when the stream is closed

Returns:

a stream with a handler that is run if the stream is closed

close
```
void close()
```
Closes this stream, causing all close handlers for this stream pipeline to be called.

Specified by:

close in interface java.lang.AutoCloseable

See Also:

AutoCloseable.close()

Interface BaseStream<T,A,P,C,PL,OT,IT,S extends BaseStream<T,A,P,C,PL,OT,IT,S>>

Nested Class Summary

Method Summary

Method Detail

filter

takeWhile

dropWhile

remove

removeIf

removeIf

removeWhile

split

splitToList

split

splitToList

split

splitToList

splitAt

splitBy

sliding

slidingToList

sliding

slidingToList

intersection

difference

symmetricDifference

distribution

reversed

shuffled

shuffled

rotated

distinct

sorted

reverseSorted

append

prepend

cached

indexed

join

join

skip

limit

step

count

peek

forEach

anyMatch

allMatch

noneMatch

findFirst

findLast

findFirstOrLast

findAny

first

last

toArray

toList

toList

toSet

toSet

toMultiset

toMultiset

toLongMultiset

toLongMultiset

iterator

println

isParallel

sequential

parallel

parallel

parallel

parallel

maxThreadNum

maxThreadNum

splitor

splitor

__

tried

onClose

close