29 | * "Compatible" is defined as follows: 30 | *
31 | * Method: Its signature (i.e. name and parameters), and return type will 32 | * remain. 33 | *
34 | * Interface: Its name and all its declared methods with its return type and 35 | * signature and static fields will remain. New methods and static field might 36 | * be added. 37 | *
38 | * Enum: Its elements will remain and their individual order will remain. New
39 | * elements might be added.
40 | *
41 | * @author pemi
42 | */
43 | @Api(version = "2.2", snapshot = false)
44 | @Retention(value = RetentionPolicy.RUNTIME)
45 | @Target({ElementType.METHOD, ElementType.TYPE, ElementType.CONSTRUCTOR})
46 | public @interface Api {
47 |
48 | /**
49 | * Returns the current API version.
50 | *
51 | * @return the current API version.
52 | */
53 | String version();
54 |
55 | /**
56 | * Returns if this API version is a snapshot, i.e. it is not yet "frozen"
57 | * and may change within the given API version.
58 | *
59 | * @return true if this API version is a snapshot, false otherwise.
60 | */
61 | boolean snapshot() default false;
62 | }
63 |
--------------------------------------------------------------------------------
/src/main/java/com/speedment/util/CollectorUtil.java:
--------------------------------------------------------------------------------
1 | /**
2 | *
3 | * Copyright (c) 2006-2016, Speedment, Inc. All Rights Reserved.
4 | *
5 | * Licensed under the Apache License, Version 2.0 (the "License"); You may not
6 | * use this file except in compliance with the License. You may obtain a copy of
7 | * the License at:
8 | *
9 | * http://www.apache.org/licenses/LICENSE-2.0
10 | *
11 | * Unless required by applicable law or agreed to in writing, software
12 | * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13 | * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14 | * License for the specific language governing permissions and limitations under
15 | * the License.
16 | */
17 | package com.speedment.util;
18 |
19 | import com.speedment.annotation.Api;
20 | import com.speedment.stream.MapStream;
21 | import java.util.ArrayList;
22 | import java.util.Collections;
23 | import java.util.HashMap;
24 | import java.util.List;
25 | import java.util.Map;
26 | import java.util.Set;
27 | import java.util.function.BiConsumer;
28 | import java.util.function.BinaryOperator;
29 | import java.util.function.Function;
30 | import java.util.function.Supplier;
31 | import java.util.stream.Collector;
32 | import static com.speedment.util.StaticClassUtil.instanceNotAllowed;
33 |
34 | /**
35 | * Utility methods for collecting Speedment streams in various ways.
36 | *
37 | * @author pemi
38 | * @author Emil Forslund
39 | * @since 2.1
40 | */
41 | @Api(version = "2.2")
42 | public final class CollectorUtil {
43 |
44 | /**
45 | * Returns a new {@link MapStream} where the elements have been grouped together using
46 | * the specified function.
47 | *
48 | * @param
101 | * This is equivalent to writing:
102 | * {@code MapStream.of(map.entrySet().stream());}
103 | *
104 | * @param
209 | * This is an intermediate operation.
210 | *
211 | * @param predicate a non-interfering, stateless predicate to apply to each
212 | * element to determine if it should be included
213 | * @return the new stream
214 | */
215 | @Override
216 | public MapStream
225 | * This is an intermediate operation.
226 | *
227 | * @param predicate a non-interfering, stateless predicate to apply to each
228 | * key-value pair to determine if it should be included
229 | * @return the new stream
230 | */
231 | public MapStream
239 | * This is an intermediate operation.
240 | *
241 | * @param predicate a non-interfering, stateless predicate to apply to each
242 | * key to determine if the entry should be included
243 | * @return the new stream
244 | */
245 | public MapStream
253 | * This is an intermediate operation.
254 | *
255 | * @param predicate a non-interfering, stateless predicate to apply to each
256 | * value to determine if the entry should be included
257 | * @return the new stream
258 | */
259 | public MapStream
267 | * This is an intermediate operation.
268 | *
269 | * @param
283 | * This is an intermediate operation.
284 | *
285 | * @param
298 | * This is an intermediate operation.
299 | *
300 | * @param
318 | * This is an intermediate operation.
319 | *
320 | * @param
338 | * This is an intermediate operation.
339 | *
340 | * @param
358 | * This is an intermediate operation.
359 | *
360 | * @param
378 | * This is an intermediate operation.
379 | *
380 | * @param mapper a non-interfering, stateless function to apply to each
381 | * element
382 | * @return the new stream
383 | */
384 | @Override
385 | public IntStream mapToInt(ToIntFunction> mapper) {
386 | return inner.mapToInt(mapper);
387 | }
388 |
389 | /**
390 | * Returns an {@code IntStream} consisting of the results of applying the
391 | * given function to the elements of this stream.
392 | *
393 | * This is an intermediate operation.
394 | *
395 | * @param mapper a non-interfering, stateless function to apply to each
396 | * element
397 | * @return the new stream
398 | */
399 | public IntStream mapToInt(ToIntBiFunction mapper) {
400 | return inner.mapToInt(e -> mapper.applyAsInt(e.getKey(), e.getValue()));
401 | }
402 |
403 | /**
404 | * Returns a {@code LongStream} consisting of the results of applying the
405 | * given function to the elements of this stream.
406 | *
407 | * This is an intermediate operation.
408 | *
409 | * @param mapper a non-interfering, stateless function to apply to each
410 | * element
411 | * @return the new stream
412 | */
413 | @Override
414 | public LongStream mapToLong(ToLongFunction> mapper) {
415 | return inner.mapToLong(mapper);
416 | }
417 |
418 | /**
419 | * Returns a {@code LongStream} consisting of the results of applying the
420 | * given function to the elements of this stream.
421 | *
422 | * This is an intermediate operation.
423 | *
424 | * @param mapper a non-interfering, stateless function to apply to each
425 | * element
426 | * @return the new stream
427 | */
428 | public LongStream mapToLong(ToLongBiFunction mapper) {
429 | return inner.mapToLong(e -> mapper.applyAsLong(e.getKey(), e.getValue()));
430 | }
431 |
432 | /**
433 | * Returns a {@code DoubleStream} consisting of the results of applying the
434 | * given function to the elements of this stream.
435 | *
436 | * This is an intermediate operation.
437 | *
438 | * @param mapper a non-interfering, stateless function to apply to each
439 | * element
440 | * @return the new stream
441 | */
442 | @Override
443 | public DoubleStream mapToDouble(ToDoubleFunction> mapper) {
444 | return inner.mapToDouble(mapper);
445 | }
446 |
447 | /**
448 | * Returns a {@code DoubleStream} consisting of the results of applying the
449 | * given function to the elements of this stream.
450 | *
451 | * This is an intermediate operation.
452 | *
453 | * @param mapper a non-interfering, stateless function to apply to each
454 | * element
455 | * @return the new stream
456 | */
457 | public DoubleStream mapToDouble(ToDoubleBiFunction mapper) {
458 | return inner.mapToDouble(e -> mapper.applyAsDouble(e.getKey(), e.getValue()));
459 | }
460 |
461 | /**
462 | * Returns a stream consisting of the results of replacing each element of
463 | * this stream with the contents of a mapped stream produced by applying
464 | * the provided mapping function to each element. Each mapped stream is
465 | * {@link java.util.stream.BaseStream#close() closed} after its contents
466 | * have been placed into this stream. (If a mapped stream is {@code null}
467 | * an empty stream is used, instead.)
468 | *
469 | * This is an intermediate operation.
470 | *
471 | *
472 | * The {@code flatMap()} operation has the effect of applying a one-to-many
473 | * transformation to the elements of the stream, and then flattening the
474 | * resulting elements into a new stream.
475 | *
476 | * Examples.
477 | *
478 | * If {@code orders} is a stream of purchase orders, and each purchase
479 | * order contains a collection of line items, then the following produces a
480 | * stream containing all the line items in all the orders:
481 | *
485 | * If {@code path} is the path to a file, then the following produces a
486 | * stream of the {@code words} contained in that file:
487 | *
513 | * This is an intermediate operation.
514 | *
515 | *
516 | * The {@code flatMap()} operation has the effect of applying a one-to-many
517 | * transformation to the elements of the stream, and then flattening the
518 | * resulting elements into a new stream.
519 | *
520 | * Examples.
521 | *
522 | * If {@code orders} is a stream of purchase orders, and each purchase
523 | * order contains a collection of line items, then the following produces a
524 | * stream containing all the line items in all the orders:
525 | *
529 | * If {@code path} is the path to a file, then the following produces a
530 | * stream of the {@code words} contained in that file:
531 | *
555 | * This is an intermediate operation.
556 | *
557 | *
558 | * The {@code flatMap()} operation has the effect of applying a one-to-many
559 | * transformation to the elements of the stream, and then flattening the
560 | * resulting elements into a new stream.
561 | *
562 | * @param
586 | * This is an intermediate operation.
587 | *
588 | *
589 | * The {@code flatMap()} operation has the effect of applying a one-to-many
590 | * transformation to the elements of the stream, and then flattening the
591 | * resulting elements into a new stream.
592 | *
593 | * @param
618 | * This is an intermediate operation.
619 | *
620 | *
621 | * The {@code flatMap()} operation has the effect of applying a one-to-many
622 | * transformation to the elements of the stream, and then flattening the
623 | * resulting elements into a new stream.
624 | *
625 | * @param
650 | * This is an intermediate operation.
651 | *
652 | *
653 | * The {@code flatMap()} operation has the effect of applying a one-to-many
654 | * transformation to the elements of the stream, and then flattening the
655 | * resulting elements into a new stream.
656 | *
657 | * @param
682 | * This is an intermediate operation.
683 | *
684 | * @param mapper a non-interfering, stateless function to apply to each
685 | * element which produces a stream of new elements
686 | * @return the new stream
687 | *
688 | * @see #flatMap(Function)
689 | */
690 | @Override
691 | public IntStream flatMapToInt(Function, ? extends IntStream> mapper) {
692 | return inner.flatMapToInt(mapper);
693 | }
694 |
695 | /**
696 | * Returns an {@code IntStream} consisting of the results of replacing each
697 | * key-value pair of this stream with the contents of a mapped stream
698 | * produced by applying the provided mapping function to each element. Each
699 | * mapped stream is {@link java.util.stream.BaseStream#close() closed} after
700 | * its contents have been placed into this stream. (If a mapped stream is
701 | * {@code null} an empty stream is used, instead.)
702 | *
703 | * This is an intermediate operation.
704 | *
705 | * @param mapper a non-interfering, stateless function to apply to each
706 | * key-value pair which produces a stream of new elements
707 | * @return the new stream
708 | *
709 | * @see #flatMap(Function)
710 | */
711 | public IntStream flatMapToInt(BiFunction mapper) {
712 | return inner.flatMapToInt(e -> mapper.apply(e.getKey(), e.getValue()));
713 | }
714 |
715 | /**
716 | * Returns an {@code LongStream} consisting of the results of replacing each
717 | * element of this stream with the contents of a mapped stream produced by
718 | * applying the provided mapping function to each element. Each mapped
719 | * stream is {@link java.util.stream.BaseStream#close() closed} after its
720 | * contents have been placed into this stream. (If a mapped stream is
721 | * {@code null} an empty stream is used, instead.)
722 | *
723 | * This is an intermediate operation.
724 | *
725 | * @param mapper a non-interfering, stateless function to apply to each
726 | * element which produces a stream of new elements
727 | * @return the new stream
728 | *
729 | * @see #flatMap(Function)
730 | */
731 | @Override
732 | public LongStream flatMapToLong(Function, ? extends LongStream> mapper) {
733 | return inner.flatMapToLong(mapper);
734 | }
735 |
736 | /**
737 | * Returns an {@code LongStream} consisting of the results of replacing each
738 | * key-value pair of this stream with the contents of a mapped stream
739 | * produced by applying the provided mapping function to each element. Each
740 | * mapped stream is {@link java.util.stream.BaseStream#close() closed} after
741 | * its contents have been placed into this stream. (If a mapped stream is
742 | * {@code null} an empty stream is used, instead.)
743 | *
744 | * This is an intermediate operation.
745 | *
746 | * @param mapper a non-interfering, stateless function to apply to each
747 | * key-value pair which produces a stream of new elements
748 | * @return the new stream
749 | *
750 | * @see #flatMap(Function)
751 | */
752 | public LongStream flatMapToLong(BiFunction mapper) {
753 | return inner.flatMapToLong(e -> mapper.apply(e.getKey(), e.getValue()));
754 | }
755 |
756 | /**
757 | * Returns an {@code DoubleStream} consisting of the results of replacing
758 | * each element of this stream with the contents of a mapped stream produced
759 | * by applying the provided mapping function to each element. Each mapped
760 | * stream is {@link java.util.stream.BaseStream#close() closed} after its
761 | * contents have placed been into this stream. (If a mapped stream is
762 | * {@code null} an empty stream is used, instead.)
763 | *
764 | * This is an intermediate operation.
765 | *
766 | * @param mapper a non-interfering, stateless function to apply to each
767 | * element which produces a stream of new elements
768 | * @return the new stream
769 | *
770 | * @see #flatMap(Function)
771 | */
772 | @Override
773 | public DoubleStream flatMapToDouble(Function, ? extends DoubleStream> mapper) {
774 | return inner.flatMapToDouble(mapper);
775 | }
776 |
777 | /**
778 | * Returns an {@code DoubleStream} consisting of the results of replacing
779 | * each key-value pair of this stream with the contents of a mapped stream
780 | * produced by applying the provided mapping function to each element. Each
781 | * mapped stream is {@link java.util.stream.BaseStream#close() closed} after
782 | * its contents have placed been into this stream. (If a mapped stream is
783 | * {@code null} an empty stream is used, instead.)
784 | *
785 | * This is an intermediate operation.
786 | *
787 | * @param mapper a non-interfering, stateless function to apply to each
788 | * key-value pair which produces a stream of new elements
789 | * @return the new stream
790 | *
791 | * @see #flatMap(Function)
792 | */
793 | public DoubleStream flatMapToDouble(BiFunction mapper) {
794 | return inner.flatMapToDouble(e -> mapper.apply(e.getKey(), e.getValue()));
795 | }
796 |
797 | /**
798 | * Returns a stream of only the keys in this {@code MapStream}.
799 | *
800 | * This is an intermediate operation.
801 | *
802 | * @return a new stream of all keys
803 | */
804 | public Stream
811 | * This is an intermediate operation.
812 | *
813 | * @return a new stream of all values
814 | */
815 | public Stream
823 | * For ordered streams, the selection of distinct elements is stable
824 | * (for duplicated elements, the element appearing first in the encounter
825 | * order is preserved.) For unordered streams, no stability guarantees
826 | * are made.
827 | *
828 | * This is a stateful intermediate operation.
829 | *
830 | *
831 | * Preserving stability for {@code distinct()} in parallel pipelines is
832 | * relatively expensive (requires that the operation act as a full barrier,
833 | * with substantial buffering overhead), and stability is often not needed.
834 | * Using an unordered stream source (such as {@link #generate(Supplier)})
835 | * or removing the ordering constraint with {@link #unordered()} may result
836 | * in significantly more efficient execution for {@code distinct()} in parallel
837 | * pipelines, if the semantics of your situation permit. If consistency
838 | * with encounter order is required, and you are experiencing poor performance
839 | * or memory utilization with {@code distinct()} in parallel pipelines,
840 | * switching to sequential execution with {@link #sequential()} may improve
841 | * performance.
842 | *
843 | * @return the new stream
844 | */
845 | @Override
846 | public MapStream
857 | * This is a stateful intermediate operation.
858 | *
859 | * @return the new stream
860 | */
861 | public MapStream
879 | * This is a stateful intermediate operation.
880 | *
881 | * @return the new stream
882 | */
883 | public MapStream
901 | * This operation will consume the wrapped stream and produce a new one. The
902 | * complexity of this operation is therefore O(n).
903 | *
904 | * This is a stateful intermediate operation.
905 | *
906 | * @param merger the merging operation to use
907 | * @return the new stream
908 | */
909 | public MapStream
927 | * This operation will consume the wrapped stream and produce a new one. The
928 | * complexity of this operation is therefore O(n).
929 | *
930 | * This is a stateful intermediate operation.
931 | *
932 | * @param merger the merging operation to use
933 | * @return the new stream
934 | */
935 | public MapStream
953 | * For ordered streams, the sort is stable. For unordered streams, no
954 | * stability guarantees are made.
955 | *
956 | * This is a stateful intermediate operation.
957 | *
958 | * @return the new stream
959 | */
960 | @Override
961 | public MapStream
985 | * For ordered streams, the sort is stable. For unordered streams, no
986 | * stability guarantees are made.
987 | *
988 | * This is a stateful intermediate operation.
989 | *
990 | * @param comparator a non-interfering, stateless {@code Comparator} to be
991 | * used to compare stream elements
992 | * @return the new stream
993 | */
994 | @Override
995 | public MapStream
1005 | * For ordered streams, the sort is stable. For unordered streams, no
1006 | * stability guarantees are made.
1007 | *
1008 | * This is a stateful intermediate operation.
1009 | *
1010 | * @param comparator a non-interfering, stateless {@code Comparator} to be
1011 | * used to compare entity keys
1012 | * @return the new stream
1013 | */
1014 | public MapStream
1024 | * For ordered streams, the sort is stable. For unordered streams, no
1025 | * stability guarantees are made.
1026 | *
1027 | * This is a stateful intermediate operation.
1028 | *
1029 | * @param comparator a non-interfering, stateless {@code Comparator} to be
1030 | * used to compare entity values
1031 | * @return the new stream
1032 | */
1033 | public MapStream
1043 | * This is an intermediate operation.
1044 | *
1045 | * For parallel stream pipelines, the action may be called at
1046 | * whatever time and in whatever thread the element is made available by the
1047 | * upstream operation. If the action modifies shared state,
1048 | * it is responsible for providing the required synchronization.
1049 | *
1050 | * This method exists mainly to support debugging, where you want
1051 | * to see the elements as they flow past a certain point in a pipeline:
1052 | *
1076 | * This is an intermediate operation.
1077 | *
1078 | * For parallel stream pipelines, the action may be called at
1079 | * whatever time and in whatever thread the element is made available by the
1080 | * upstream operation. If the action modifies shared state,
1081 | * it is responsible for providing the required synchronization.
1082 | *
1083 | * This method exists mainly to support debugging, where you want
1084 | * to see the elements as they flow past a certain point in a pipeline:
1085 | *
1107 | * This is a short-circuiting stateful intermediate operation.
1108 | *
1109 | *
1110 | * While {@code limit()} is generally a cheap operation on sequential
1111 | * stream pipelines, it can be quite expensive on ordered parallel pipelines,
1112 | * especially for large values of {@code maxSize}, since {@code limit(n)}
1113 | * is constrained to return not just any n elements, but the
1114 | * first n elements in the encounter order. Using an unordered
1115 | * stream source (such as {@link #generate(Supplier)}) or removing the
1116 | * ordering constraint with {@link #unordered()} may result in significant
1117 | * speedups of {@code limit()} in parallel pipelines, if the semantics of
1118 | * your situation permit. If consistency with encounter order is required,
1119 | * and you are experiencing poor performance or memory utilization with
1120 | * {@code limit()} in parallel pipelines, switching to sequential execution
1121 | * with {@link #sequential()} may improve performance.
1122 | *
1123 | * @param maxSize the number of elements the stream should be limited to
1124 | * @return the new stream
1125 | * @throws IllegalArgumentException if {@code maxSize} is negative
1126 | */
1127 | @Override
1128 | public MapStream
1139 | * This is a stateful intermediate operation.
1140 | *
1141 | *
1142 | * While {@code skip()} is generally a cheap operation on sequential
1143 | * stream pipelines, it can be quite expensive on ordered parallel pipelines,
1144 | * especially for large values of {@code n}, since {@code skip(n)}
1145 | * is constrained to skip not just any n elements, but the
1146 | * first n elements in the encounter order. Using an unordered
1147 | * stream source (such as {@link #generate(Supplier)}) or removing the
1148 | * ordering constraint with {@link #unordered()} may result in significant
1149 | * speedups of {@code skip()} in parallel pipelines, if the semantics of
1150 | * your situation permit. If consistency with encounter order is required,
1151 | * and you are experiencing poor performance or memory utilization with
1152 | * {@code skip()} in parallel pipelines, switching to sequential execution
1153 | * with {@link #sequential()} may improve performance.
1154 | *
1155 | * @param n the number of leading elements to skip
1156 | * @return the new stream
1157 | * @throws IllegalArgumentException if {@code n} is negative
1158 | */
1159 | @Override
1160 | public MapStream
1168 | * This is a terminal operation.
1169 | *
1170 | * The behavior of this operation is explicitly nondeterministic.
1171 | * For parallel stream pipelines, this operation does not
1172 | * guarantee to respect the encounter order of the stream, as doing so
1173 | * would sacrifice the benefit of parallelism. For any given element, the
1174 | * action may be performed at whatever time and in whatever thread the
1175 | * library chooses. If the action accesses shared state, it is
1176 | * responsible for providing the required synchronization.
1177 | *
1178 | * @param action a non-interfering action to perform on the elements
1179 | */
1180 | @Override
1181 | public void forEach(Consumer> action) {
1182 | inner.forEach(action);
1183 | }
1184 |
1185 | /**
1186 | * Performs an action for each key-value pair of this stream.
1187 | *
1188 | * This is a terminal operation.
1189 | *
1190 | * The behavior of this operation is explicitly nondeterministic.
1191 | * For parallel stream pipelines, this operation does not
1192 | * guarantee to respect the encounter order of the stream, as doing so
1193 | * would sacrifice the benefit of parallelism. For any given element, the
1194 | * action may be performed at whatever time and in whatever thread the
1195 | * library chooses. If the action accesses shared state, it is
1196 | * responsible for providing the required synchronization.
1197 | *
1198 | * @param action a non-interfering action to perform on the key-value pairs
1199 | */
1200 | public void forEach(BiConsumer action) {
1201 | inner.forEach(e -> action.accept(e.getKey(), e.getValue()));
1202 | }
1203 |
1204 | /**
1205 | * Performs an action for each element of this stream, in the encounter
1206 | * order of the stream if the stream has a defined encounter order.
1207 | *
1208 | * This is a terminal operation.
1209 | *
1210 | * This operation processes the elements one at a time, in encounter
1211 | * order if one exists. Performing the action for one element
1212 | * happens-before performing the action for subsequent elements, but
1213 | * for any given element, the action may be performed in whatever thread the
1214 | * library chooses.
1215 | *
1216 | * @param action a non-interfering action to perform on the elements
1217 | * @see #forEach(Consumer)
1218 | */
1219 | @Override
1220 | public void forEachOrdered(Consumer> action) {
1221 | inner.forEachOrdered(action);
1222 | }
1223 |
1224 | /**
1225 | * Performs an action for each key-value pair of this stream, in the
1226 | * encounter order of the stream if the stream has a defined encounter
1227 | * order.
1228 | *
1229 | * This is a terminal operation.
1230 | *
1231 | * This operation processes the key-value pairs one at a time, in encounter
1232 | * order if one exists. Performing the action for one element
1233 | * happens-before performing the action for subsequent key-value
1234 | * pairs, but for any given element, the action may be performed in whatever
1235 | * thread the library chooses.
1236 | *
1237 | * @param action a non-interfering action to perform on the key-value pairs
1238 | * @see #forEach(Consumer)
1239 | */
1240 | public void forEachOrdered(BiConsumer action) {
1241 | inner.forEachOrdered(e -> action.accept(e.getKey(), e.getValue()));
1242 | }
1243 |
1244 | /**
1245 | * Returns an array containing the elements of this stream.
1246 | *
1247 | * This is a terminal operation.
1248 | *
1249 | * @return an array containing the elements of this stream
1250 | */
1251 | @Override
1252 | public Object[] toArray() {
1253 | return inner.toArray();
1254 | }
1255 |
1256 | /**
1257 | * Returns an array containing the elements of this stream, using the
1258 | * provided {@code generator} function to allocate the returned array, as
1259 | * well as any additional arrays that might be required for a partitioned
1260 | * execution or for resizing.
1261 | *
1262 | * This is a terminal operation.
1263 | *
1264 | *
1265 | * The generator function takes an integer, which is the size of the
1266 | * desired array, and produces an array of the desired size. This can be
1267 | * concisely expressed with an array constructor reference:
1268 | *
1300 | * The {@code identity} value must be an identity for the accumulator
1301 | * function. This means that for all {@code t},
1302 | * {@code accumulator.apply(identity, t)} is equal to {@code t}.
1303 | * The {@code accumulator} function must be an associative function.
1304 | *
1305 | * This is a terminal operation.
1306 | *
1307 | * Sum, min, max, average, and string concatenation are all special
1308 | * cases of reduction. Summing a stream of numbers can be expressed as:
1309 | *
1310 | *
1320 | * While this may seem a more roundabout way to perform an aggregation
1321 | * compared to simply mutating a running total in a loop, reduction
1322 | * operations parallelize more gracefully, without needing additional
1323 | * synchronization and with greatly reduced risk of data races.
1324 | *
1325 | * @param identity the identity value for the accumulating function
1326 | * @param accumulator an associative, non-interfering stateless function
1327 | * for combining two values
1328 | * @return the result of the reduction
1329 | */
1330 | @Override
1331 | public Map.Entry
1355 | * The {@code accumulator} function must be an associative function.
1356 | *
1357 | * This is a terminal operation.
1358 | *
1359 | * @param accumulator an associative, non-interfering, stateless function
1360 | * for combining two values
1361 | * @return an {@link Optional} describing the result of the
1362 | * reduction
1363 | * @throws NullPointerException if the result of the reduction is null
1364 | *
1365 | * @see #reduce(Object, BinaryOperator)
1366 | * @see #min(Comparator)
1367 | * @see #max(Comparator)
1368 | */
1369 | @Override
1370 | public Optional
1386 | * The {@code identity} value must be an identity for the combiner
1387 | * function. This means that for all {@code u}, {@code combiner(identity, u)}
1388 | * is equal to {@code u}. Additionally, the {@code combiner} function
1389 | * must be compatible with the {@code accumulator} function; for all
1390 | * {@code u} and {@code t}, the following must hold:
1391 | *
1395 | * This is a terminal operation.
1396 | *
1397 | * Many reductions using this form can be represented more simply
1398 | * by an explicit combination of {@code map} and {@code reduce} operations.
1399 | * The {@code accumulator} function acts as a fused mapper and accumulator,
1400 | * which can sometimes be more efficient than separate mapping and reduction,
1401 | * such as when knowing the previously reduced value allows you to avoid
1402 | * some computation.
1403 | *
1404 | * @param the type of the result
1405 | * @param identity the identity value for the combiner function
1406 | * @param accumulator an associative, non-interfering, stateless function
1407 | * for incorporating an additional element into a result
1408 | * @param combiner an associative, non-interfering, stateless
1409 | * function for combining two values, which must be
1410 | * compatible with the accumulator function
1411 | * @return the result of the reduction
1412 | *
1413 | * @see #reduce(BinaryOperator)
1414 | * @see #reduce(Object, BinaryOperator)
1415 | */
1416 | @Override
1417 | public U reduce(U identity, BiFunction
1434 | * Like {@link #reduce(Object, BinaryOperator)}, {@code collect} operations
1435 | * can be parallelized without requiring additional synchronization.
1436 | *
1437 | * This is a terminal operation.
1438 | *
1439 | * There are many existing classes in the JDK whose signatures are
1440 | * well-suited for use with method references as arguments to {@code collect()}.
1441 | * For example, the following will accumulate strings into an {@code ArrayList}:
1442 | *
1447 | * The following will take a stream of strings and concatenates them into a
1448 | * single string:
1449 | *
1479 | * If the stream is parallel, and the {@code Collector} is
1480 | * {@link Collector.Characteristics#CONCURRENT concurrent}, and either the
1481 | * stream is unordered or the collector is
1482 | * {@link Collector.Characteristics#UNORDERED unordered},
1483 | * then a concurrent reduction will be performed (see {@link Collector} for
1484 | * details on concurrent reduction.)
1485 | *
1486 | * This is a terminal operation.
1487 | *
1488 | * When executed in parallel, multiple intermediate results may be
1489 | * instantiated, populated, and merged so as to maintain isolation of
1490 | * mutable data structures. Therefore, even when executed in parallel
1491 | * with non-thread-safe data structures (such as {@code ArrayList}), no
1492 | * additional synchronization is needed for a parallel reduction.
1493 | *
1494 | *
1495 | * The following will accumulate strings into an ArrayList:
1496 | *
1500 | * The following will classify {@code Person} objects by city:
1501 | *
1506 | * The following will classify {@code Person} objects by state and city,
1507 | * cascading two {@code Collector}s together:
1508 | *
1534 | * This is a stateful intermediate operation.
1535 | *
1536 | * @param
1549 | * This is a terminal operation.
1550 | *
1551 | * @param comparator a non-interfering, stateless {@code Comparator} to
1552 | * compare elements of this stream
1553 | * @return an {@code Optional} describing the minimum element of
1554 | * this stream, or an empty {@code Optional} if the
1555 | * stream is empty
1556 | *
1557 | * @throws NullPointerException if the minimum element is null
1558 | */
1559 | @Override
1560 | public Optional
1569 | * This is a terminal operation.
1570 | *
1571 | * @param comparator a non-interfering, stateless {@code Comparator} to
1572 | * compare keys of this stream
1573 | * @return an {@code Optional} describing the minimum element of
1574 | * this stream, or an empty {@code Optional} if the
1575 | * stream is empty
1576 | *
1577 | * @throws NullPointerException if the minimum element is null
1578 | */
1579 | public Optional
1588 | * This is a terminal operation.
1589 | *
1590 | * @param comparator a non-interfering, stateless {@code Comparator} to
1591 | * compare values of this stream
1592 | * @return an {@code Optional} describing the minimum element of
1593 | * this stream, or an empty {@code Optional} if the
1594 | * stream is empty
1595 | *
1596 | * @throws NullPointerException if the minimum element is null
1597 | */
1598 | public Optional
1606 | * This is a terminal operation.
1607 | *
1608 | * @param comparator a non-interfering, stateless {@code Comparator} to
1609 | * compare elements of this stream
1610 | * @return an {@code Optional} describing the maximum element of
1611 | * this stream, or an empty {@code Optional} if the
1612 | * stream is empty
1613 | *
1614 | * @throws NullPointerException if the maximum element is null
1615 | */
1616 | @Override
1617 | public Optional
1626 | * This is a terminal operation.
1627 | *
1628 | * @param comparator a non-interfering, stateless {@code Comparator} to
1629 | * compare keys of this stream
1630 | * @return an {@code Optional} describing the maximum element of
1631 | * this stream, or an empty {@code Optional} if the
1632 | * stream is empty
1633 | *
1634 | * @throws NullPointerException if the maximum element is null
1635 | */
1636 | public Optional
1645 | * This is a terminal operation.
1646 | *
1647 | * @param comparator a non-interfering, stateless {@code Comparator} to
1648 | * compare values of this stream
1649 | * @return an {@code Optional} describing the maximum element of
1650 | * this stream, or an empty {@code Optional} if the
1651 | * stream is empty
1652 | *
1653 | * @throws NullPointerException if the maximum element is null
1654 | */
1655 | public Optional
1666 | * This is a terminal operation.
1667 | *
1668 | * @return the count of elements in this stream
1669 | */
1670 | @Override
1671 | public long count() {
1672 | return inner.count();
1673 | }
1674 |
1675 | /**
1676 | * Returns whether any elements of this stream match the provided
1677 | * predicate. May not evaluate the predicate on all elements if not
1678 | * necessary for determining the result. If the stream is empty then
1679 | * {@code false} is returned and the predicate is not evaluated.
1680 | *
1681 | * This is a short-circuiting terminal operation.
1682 | *
1683 | *
1684 | * This method evaluates the existential quantification of the
1685 | * predicate over the elements of the stream (for some x P(x)).
1686 | *
1687 | * @param predicate a non-interfering, stateless predicate to apply to
1688 | * elements of this stream
1689 | * @return {@code true} if any elements of the stream match the
1690 | * provided predicate, otherwise {@code false}
1691 | */
1692 | @Override
1693 | public boolean anyMatch(Predicate> predicate) {
1694 | return inner.anyMatch(predicate);
1695 | }
1696 |
1697 | /**
1698 | * Returns whether any key-value pairs of this stream match the provided
1699 | * predicate. May not evaluate the predicate on all elements if not
1700 | * necessary for determining the result. If the stream is empty then
1701 | * {@code false} is returned and the predicate is not evaluated.
1702 | *
1703 | * This is a short-circuiting terminal operation.
1704 | *
1705 | *
1706 | * This method evaluates the existential quantification of the
1707 | * predicate over the elements of the stream (for some x P(x)).
1708 | *
1709 | * @param predicate a non-interfering, stateless predicate to apply to
1710 | * key-value pairs of this stream
1711 | * @return {@code true} if any key-value pairs of the stream match
1712 | * the provided predicate, otherwise {@code false}
1713 | */
1714 | public boolean anyMatch(BiPredicate predicate) {
1715 | return inner.anyMatch(e -> predicate.test(e.getKey(), e.getValue()));
1716 | }
1717 |
1718 | /**
1719 | * Returns whether all elements of this stream match the provided predicate.
1720 | * May not evaluate the predicate on all elements if not necessary for
1721 | * determining the result. If the stream is empty then {@code true} is
1722 | * returned and the predicate is not evaluated.
1723 | *
1724 | * This is a short-circuiting terminal operation.
1725 | *
1726 | *
1727 | * This method evaluates the universal quantification of the
1728 | * predicate over the elements of the stream (for all x P(x)). If the
1729 | * stream is empty, the quantification is said to be vacuously
1730 | * satisfied and is always {@code true} (regardless of P(x)).
1731 | *
1732 | * @param predicate a non-interfering, stateless predicate to apply to
1733 | * elements of this stream
1734 | * @return {@code true} if either all elements of the stream match
1735 | * the provided predicate or the stream is empty,
1736 | * otherwise {@code false}
1737 | */
1738 | @Override
1739 | public boolean allMatch(Predicate> predicate) {
1740 | return inner.allMatch(predicate);
1741 | }
1742 |
1743 | /**
1744 | * Returns whether all key-value pairs of this stream match the provided
1745 | * predicate. May not evaluate the predicate on all key-value pairs if not
1746 | * necessary for determining the result. If the stream is empty then
1747 | * {@code true} is returned and the predicate is not evaluated.
1748 | *
1749 | * This is a short-circuiting terminal operation.
1750 | *
1751 | *
1752 | * This method evaluates the universal quantification of the
1753 | * predicate over the elements of the stream (for all x P(x)). If the
1754 | * stream is empty, the quantification is said to be vacuously
1755 | * satisfied and is always {@code true} (regardless of P(x)).
1756 | *
1757 | * @param predicate a non-interfering, stateless predicate to apply to
1758 | * key-value pairs of this stream
1759 | * @return {@code true} if either all key-value pairs of the
1760 | * stream match the provided predicate or the stream is
1761 | * empty, otherwise {@code false}
1762 | */
1763 | public boolean allMatch(BiPredicate predicate) {
1764 | return inner.allMatch(e -> predicate.test(e.getKey(), e.getValue()));
1765 | }
1766 |
1767 | /**
1768 | * Returns whether no elements of this stream match the provided predicate.
1769 | * May not evaluate the predicate on all elements if not necessary for
1770 | * determining the result. If the stream is empty then {@code true} is
1771 | * returned and the predicate is not evaluated.
1772 | *
1773 | * This is a short-circuiting terminal operation.
1774 | *
1775 | *
1776 | * This method evaluates the universal quantification of the
1777 | * negated predicate over the elements of the stream (for all x ~P(x)). If
1778 | * the stream is empty, the quantification is said to be vacuously satisfied
1779 | * and is always {@code true}, regardless of P(x).
1780 | *
1781 | * @param predicate a non-interfering, stateless predicate to apply to
1782 | * elements of this stream
1783 | * @return {@code true} if either no elements of the stream match
1784 | * the provided predicate or the stream is empty,
1785 | * otherwise {@code false}
1786 | */
1787 | @Override
1788 | public boolean noneMatch(Predicate> predicate) {
1789 | return inner.noneMatch(predicate);
1790 | }
1791 |
1792 | /**
1793 | * Returns whether no key-value pairs of this stream match the provided
1794 | * predicate. May not evaluate the predicate on all key-value pairs if not
1795 | * necessary for determining the result. If the stream is empty then
1796 | * {@code true} is returned and the predicate is not evaluated.
1797 | *
1798 | * This is a short-circuiting terminal operation.
1799 | *
1800 | *
1801 | * This method evaluates the universal quantification of the
1802 | * negated predicate over the elements of the stream (for all x ~P(x)). If
1803 | * the stream is empty, the quantification is said to be vacuously satisfied
1804 | * and is always {@code true}, regardless of P(x).
1805 | *
1806 | * @param predicate a non-interfering, stateless predicate to apply to
1807 | * key-value pairs of this stream
1808 | * @return {@code true} if either no key-value pairs of the
1809 | * stream match the provided predicate or the stream is
1810 | * empty, otherwise {@code false}
1811 | */
1812 | public boolean noneMatch(BiPredicate predicate) {
1813 | return inner.noneMatch(e -> predicate.test(e.getKey(), e.getValue()));
1814 | }
1815 |
1816 | /**
1817 | * Returns an {@link Optional} describing the first element of this stream,
1818 | * or an empty {@code Optional} if the stream is empty. If the stream has
1819 | * no encounter order, then any element may be returned.
1820 | *
1821 | * This is a short-circuiting terminal operation.
1822 | *
1823 | * @return an {@code Optional} describing the first element of this stream,
1824 | * or an empty {@code Optional} if the stream is empty
1825 | *
1826 | * @throws NullPointerException if the element selected is null
1827 | */
1828 | @Override
1829 | public Optional
1837 | * This is a short-circuiting terminal operation.
1838 | *
1839 | * The behavior of this operation is explicitly nondeterministic; it is
1840 | * free to select any element in the stream. This is to allow for maximal
1841 | * performance in parallel operations; the cost is that multiple invocations
1842 | * on the same source may not return the same result. (If a stable result
1843 | * is desired, use {@link #findFirst()} instead.)
1844 | *
1845 | * @return an {@code Optional} describing some element of this stream, or an
1846 | * empty {@code Optional} if the stream is empty
1847 | *
1848 | * @throws NullPointerException if the element selected is null
1849 | * @see #findFirst()
1850 | */
1851 | @Override
1852 | public Optional
1859 | * This is a terminal operation.
1860 | *
1861 | * @return the element iterator for this stream
1862 | */
1863 | @Override
1864 | public Iterator
1871 | * This is a terminal operation.
1872 | *
1873 | * @return the element spliterator for this stream
1874 | */
1875 | @Override
1876 | public Spliterator
1897 | * This is an intermediate operation.
1898 | *
1899 | * @return a sequential stream
1900 | */
1901 | @Override
1902 | public MapStream
1912 | * This is an intermediate operation.
1913 | *
1914 | * @return a parallel stream
1915 | */
1916 | @Override
1917 | public MapStream
1928 | * This is an intermediate operation.
1929 | *
1930 | * @return an unordered stream
1931 | */
1932 | @Override
1933 | public MapStream
1950 | * This is an intermediate operation.
1951 | *
1952 | * @param closeHandler a task to execute when the stream is closed
1953 | * @return a stream with a handler that is run if the stream is
1954 | * closed
1955 | */
1956 | @Override
1957 | public MapStream
1976 | * If the mapped keys contains duplicates (according to
1977 | * {@link Object#equals(Object)}), an {@code IllegalStateException} is
1978 | * thrown when the collection operation is performed. If the mapped keys
1979 | * may have duplicates, use {@link #toMap(BinaryOperator)}
1980 | * instead.
1981 | *
1982 | *
1983 | * The returned {@code Map} is not concurrent. For parallel stream
1984 | * pipelines, the {@code combiner} function operates by merging the keys
1985 | * from one map into another, which can be an expensive operation. If it is
1986 | * not required that results are inserted into the {@code Map} in encounter
1987 | * order, using {@link #toConcurrentMap()}
1988 | * may offer better parallel performance.
1989 | *
1990 | * @return a {@code Map} whose keys and values are identical to the entries
1991 | * of this stream
1992 | *
1993 | * @see #toMap(BinaryOperator)
1994 | * @see #toConcurrentMap()
1995 | */
1996 | public Map
2006 | * If the mapped keys contains duplicates (according to
2007 | * {@link Object#equals(Object)}), the values are merged using the provided
2008 | * merging function.
2009 | *
2010 | *
2011 | * There are multiple ways to deal with collisions between multiple elements
2012 | * mapping to the same key. The other forms of {@code toMap} simply use
2013 | * a merge function that throws unconditionally, but you can easily write
2014 | * more flexible merge policies.
2015 | *
2016 | *
2017 | * The returned {@code Map} is not concurrent. For parallel stream
2018 | * pipelines, the {@code combiner} function operates by merging the keys
2019 | * from one map into another, which can be an expensive operation. If it is
2020 | * not required that results are merged into the {@code Map} in encounter
2021 | * order, using {@link #toConcurrentMap(BinaryOperator)}
2022 | * may offer better parallel performance.
2023 | *
2024 | * @param mergeFunction a merge function, used to resolve collisions
2025 | * between values associated with the same key, as
2026 | * supplied to {@link Map#merge(Object, Object, BiFunction)}
2027 | * @return a {@code Map} whose keys and values are identical
2028 | * to the entries of this stream with any collisions
2029 | * handled
2030 | *
2031 | * @see #toMap()
2032 | * @see #toConcurrentMap(BinaryOperator)
2033 | */
2034 | public Map
2046 | * If the mapped keys contains duplicates (according to
2047 | * {@link Object#equals(Object)}), an {@code IllegalStateException} is
2048 | * thrown when the collection operation is performed. If the mapped keys
2049 | * may have duplicates, use {@link #toConcurrentMap(BinaryOperator)} instead.
2050 | *
2051 | *
2052 | * It is common for either the key or the value to be the input elements.
2053 | * In this case, the utility method
2054 | * {@link java.util.function.Function#identity()} may be helpful.
2055 | *
2056 | * This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
2057 | * {@link Collector.Characteristics#UNORDERED unordered} Collector.
2058 | *
2059 | * @return a {@code ConcurrentMap} whose keys are taken from this stream
2060 | *
2061 | * @see #toMap()
2062 | * @see #toConcurrentMap(BinaryOperator)
2063 | */
2064 | public Map
2075 | * If the mapped keys contains duplicates (according to
2076 | * {@link Object#equals(Object)}), the value mapping function is applied to
2077 | * each equal element, and the results are merged using the provided merging
2078 | * function.
2079 | *
2080 | *
2081 | * There are multiple ways to deal with collisions between multiple elements
2082 | * mapping to the same key. The other forms of {@code toConcurrentMap} simply use
2083 | * a merge function that throws unconditionally, but you can easily write
2084 | * more flexible merge policies.
2085 | *
2086 | * @param mergeFunction a merge function, used to resolve collisions between
2087 | * values associated with the same key, as supplied
2088 | * to {@link Map#merge(Object, Object, BiFunction)}
2089 | * @return a {@code ConcurrentMap} whose keys are taken from this stream
2090 | *
2091 | * @see #toConcurrentMap()
2092 | * @see #toMap(BinaryOperator)
2093 | */
2094 | public Map{@code
482 | * orders.flatMap(order -> order.getLineItems().stream())...
483 | * }
484 | * {@code
488 | * Stream
491 | * The {@code mapper} function passed to {@code flatMap} splits a line,
492 | * using a simple regular expression, into an array of words, and then
493 | * creates a stream of words from that array.
494 | *
495 | * @param {@code
526 | * orders.flatMap(order -> order.getLineItems().stream())...
527 | * }
528 | * {@code
532 | * Stream
535 | * The {@code mapper} function passed to {@code flatMap} splits a line,
536 | * using a simple regular expression, into an array of words, and then
537 | * creates a stream of words from that array.
538 | *
539 | * @param {@code
1053 | * Stream.of("one", "two", "three", "four")
1054 | * .filter(e -> e.length() > 3)
1055 | * .peek(e -> System.out.println("Filtered value: " + e))
1056 | * .map(String::toUpperCase)
1057 | * .peek(e -> System.out.println("Mapped value: " + e))
1058 | * .collect(Collectors.toList());
1059 | * }
1060 | *
1061 | * @param action a non-interfering action to perform on the elements as
1062 | * they are consumed from the stream
1063 | * @return the new stream
1064 | */
1065 | @Override
1066 | public MapStream{@code
1086 | * Stream.of("one", "two", "three", "four")
1087 | * .filter(e -> e.length() > 3)
1088 | * .peek(e -> System.out.println("Filtered value: " + e))
1089 | * .map(String::toUpperCase)
1090 | * .peek(e -> System.out.println("Mapped value: " + e))
1091 | * .collect(Collectors.toList());
1092 | * }
1093 | *
1094 | * @param action a non-interfering action to perform on the key-value pairs
1095 | * as they are consumed from the stream
1096 | * @return the new stream
1097 | */
1098 | public MapStream{@code
1269 | * Person[] men = people.stream()
1270 | * .filter(p -> p.getGender() == MALE)
1271 | * .toArray(Person[]::new);
1272 | * }
1273 | *
1274 | * @param the element type of the resulting array
1275 | * @param generator a function which produces a new array of the desired
1276 | * type and the provided length
1277 | * @return an array containing the elements in this stream
1278 | * @throws ArrayStoreException if the runtime type of the array
1279 | * returned from the array generator is not a supertype of
1280 | * the runtime type of every element in this stream
1281 | */
1282 | @Override
1283 | public A[] toArray(IntFunction{@code
1292 | * T result = identity;
1293 | * for (T element : this stream)
1294 | * result = accumulator.apply(result, element)
1295 | * return result;
1296 | * }
1297 | *
1298 | * but is not constrained to execute sequentially.
1299 | * {@code
1311 | * Integer sum = integers.reduce(0, (a, b) -> a+b);
1312 | * }
1313 | *
1314 | * or:
1315 | *
1316 | * {@code
1317 | * Integer sum = integers.reduce(0, Integer::sum);
1318 | * }
1319 | * {@code
1340 | * boolean foundAny = false;
1341 | * T result = null;
1342 | * for (T element : this stream) {
1343 | * if (!foundAny) {
1344 | * foundAny = true;
1345 | * result = element;
1346 | * }
1347 | * else
1348 | * result = accumulator.apply(result, element);
1349 | * }
1350 | * return foundAny ? Optional.of(result) : Optional.empty();
1351 | * }
1352 | *
1353 | * but is not constrained to execute sequentially.
1354 | * {@code
1378 | * U result = identity;
1379 | * for (T element : this stream)
1380 | * result = accumulator.apply(result, element)
1381 | * return result;
1382 | * }
1383 | *
1384 | * but is not constrained to execute sequentially.
1385 | * {@code
1392 | * combiner.apply(u, accumulator.apply(identity, t)) == accumulator.apply(u, t)
1393 | * }
1394 | * {@code
1428 | * R result = supplier.get();
1429 | * for (T element : this stream)
1430 | * accumulator.accept(result, element);
1431 | * return result;
1432 | * }
1433 | * {@code
1443 | * List
1446 | * {@code
1450 | * String concat = stringStream.collect(StringBuilder::new, StringBuilder::append,
1451 | * StringBuilder::append)
1452 | * .toString();
1453 | * }
1454 | *
1455 | * @param {@code
1497 | * List
1499 | * {@code
1502 | * Map
1505 | * {@code
1509 | * Map
1513 | *
1514 | * @param {@code
1663 | * return mapToLong(e -> 1L).sum();
1664 | * }
1665 | *