1 /*
2 * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.util.stream;
26
27 import java.util.AbstractMap;
28 import java.util.AbstractSet;
29 import java.util.ArrayList;
30 import java.util.Arrays;
31 import java.util.Collection;
32 import java.util.Collections;
33 import java.util.Comparator;
34 import java.util.DoubleSummaryStatistics;
35 import java.util.EnumSet;
36 import java.util.HashMap;
37 import java.util.HashSet;
38 import java.util.IntSummaryStatistics;
39 import java.util.Iterator;
40 import java.util.List;
41 import java.util.LongSummaryStatistics;
42 import java.util.Map;
43 import java.util.Objects;
44 import java.util.Optional;
45 import java.util.Set;
46 import java.util.StringJoiner;
47 import java.util.concurrent.ConcurrentHashMap;
48 import java.util.concurrent.ConcurrentMap;
49 import java.util.function.BiConsumer;
50 import java.util.function.BiFunction;
51 import java.util.function.BinaryOperator;
52 import java.util.function.Consumer;
53 import java.util.function.Function;
54 import java.util.function.Predicate;
55 import java.util.function.Supplier;
56 import java.util.function.ToDoubleFunction;
57 import java.util.function.ToIntFunction;
58 import java.util.function.ToLongFunction;
59
60 /**
61 * Implementations of {@link Collector} that implement various useful reduction
62 * operations, such as accumulating elements into collections, summarizing
63 * elements according to various criteria, etc.
64 *
65 * <p>The following are examples of using the predefined collectors to perform
66 * common mutable reduction tasks:
67 *
68 * <pre>{@code
69 * // Accumulate names into a List
70 * List<String> list = people.stream().map(Person::getName).collect(Collectors.toList());
71 *
72 * // Accumulate names into a TreeSet
73 * Set<String> set = people.stream().map(Person::getName).collect(Collectors.toCollection(TreeSet::new));
74 *
75 * // Convert elements to strings and concatenate them, separated by commas
76 * String joined = things.stream()
77 * .map(Object::toString)
78 * .collect(Collectors.joining(", "));
79 *
80 * // Compute sum of salaries of employee
81 * int total = employees.stream()
82 * .collect(Collectors.summingInt(Employee::getSalary)));
83 *
84 * // Group employees by department
85 * Map<Department, List<Employee>> byDept
86 * = employees.stream()
87 * .collect(Collectors.groupingBy(Employee::getDepartment));
88 *
89 * // Compute sum of salaries by department
90 * Map<Department, Integer> totalByDept
91 * = employees.stream()
92 * .collect(Collectors.groupingBy(Employee::getDepartment,
93 * Collectors.summingInt(Employee::getSalary)));
94 *
95 * // Partition students into passing and failing
96 * Map<Boolean, List<Student>> passingFailing =
97 * students.stream()
98 * .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD));
99 *
100 * }</pre>
101 *
102 * @since 1.8
103 */
104 public final class Collectors {
105
106 static final Set<Collector.Characteristics> CH_CONCURRENT_ID
107 = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.CONCURRENT,
108 Collector.Characteristics.UNORDERED,
109 Collector.Characteristics.IDENTITY_FINISH));
110 static final Set<Collector.Characteristics> CH_CONCURRENT_NOID
111 = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.CONCURRENT,
112 Collector.Characteristics.UNORDERED));
113 static final Set<Collector.Characteristics> CH_ID
114 = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.IDENTITY_FINISH));
115 static final Set<Collector.Characteristics> CH_UNORDERED_ID
116 = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.UNORDERED,
117 Collector.Characteristics.IDENTITY_FINISH));
118 static final Set<Collector.Characteristics> CH_NOID = Collections.emptySet();
119
120 private Collectors() { }
121
122 /**
123 * Construct an {@code IllegalStateException} with appropriate message.
124 *
125 * @param k the duplicate key
126 * @param u 1st value to be accumulated/merged
127 * @param v 2nd value to be accumulated/merged
128 */
129 private static IllegalStateException duplicateKeyException(
130 Object k, Object u, Object v) {
131 return new IllegalStateException(String.format(
132 "Duplicate key %s (attempted merging values %s and %s)",
133 k, u, v));
134 }
135
136 /**
137 * {@code BinaryOperator<Map>} that merges the contents of its right
138 * argument into its left argument, throwing {@code IllegalStateException}
139 * if duplicate keys are encountered.
140 *
141 * @param <K> type of the map keys
142 * @param <V> type of the map values
143 * @param <M> type of the map
144 * @return a merge function for two maps
145 */
146 private static <K, V, M extends Map<K,V>>
147 BinaryOperator<M> uniqKeysMapMerger() {
148 return (m1, m2) -> {
149 for (Map.Entry<K,V> e : m2.entrySet()) {
150 K k = e.getKey();
151 V v = Objects.requireNonNull(e.getValue());
152 V u = m1.putIfAbsent(k, v);
153 if (u != null) throw duplicateKeyException(k, u, v);
154 }
155 return m1;
156 };
157 }
158
159 /**
160 * {@code BiConsumer<Map, T>} that accumulates (key, value) pairs
161 * extracted from elements into the map, throwing {@code IllegalStateException}
162 * if duplicate keys are encountered.
163 *
164 * @param keyMapper a function that maps an element into a key
165 * @param valueMapper a function that maps an element into a value
166 * @param <T> type of elements
167 * @param <K> type of map keys
168 * @param <V> type of map values
169 * @return an accumulating consumer
170 */
171 private static <T, K, V>
172 BiConsumer<Map<K, V>, T> uniqKeysMapAccumulator(Function<? super T, ? extends K> keyMapper,
173 Function<? super T, ? extends V> valueMapper) {
174 return (map, element) -> {
175 K k = keyMapper.apply(element);
176 V v = Objects.requireNonNull(valueMapper.apply(element));
177 V u = map.putIfAbsent(k, v);
178 if (u != null) throw duplicateKeyException(k, u, v);
179 };
180 }
181
182 @SuppressWarnings("unchecked")
183 private static <I, R> Function<I, R> castingIdentity() {
184 return i -> (R) i;
185 }
186
187 /**
188 * Simple implementation class for {@code Collector}.
189 *
190 * @param <T> the type of elements to be collected
191 * @param <R> the type of the result
192 */
193 static class CollectorImpl<T, A, R> implements Collector<T, A, R> {
194 private final Supplier<A> supplier;
195 private final BiConsumer<A, T> accumulator;
196 private final BinaryOperator<A> combiner;
197 private final Function<A, R> finisher;
198 private final Set<Characteristics> characteristics;
199
200 CollectorImpl(Supplier<A> supplier,
201 BiConsumer<A, T> accumulator,
202 BinaryOperator<A> combiner,
203 Function<A,R> finisher,
204 Set<Characteristics> characteristics) {
205 this.supplier = supplier;
206 this.accumulator = accumulator;
207 this.combiner = combiner;
208 this.finisher = finisher;
209 this.characteristics = characteristics;
210 }
211
212 CollectorImpl(Supplier<A> supplier,
213 BiConsumer<A, T> accumulator,
214 BinaryOperator<A> combiner,
215 Set<Characteristics> characteristics) {
216 this(supplier, accumulator, combiner, castingIdentity(), characteristics);
217 }
218
219 @Override
220 public BiConsumer<A, T> accumulator() {
221 return accumulator;
222 }
223
224 @Override
225 public Supplier<A> supplier() {
226 return supplier;
227 }
228
229 @Override
230 public BinaryOperator<A> combiner() {
231 return combiner;
232 }
233
234 @Override
235 public Function<A, R> finisher() {
236 return finisher;
237 }
238
239 @Override
240 public Set<Characteristics> characteristics() {
241 return characteristics;
242 }
243 }
244
245 /**
246 * Returns a {@code Collector} that accumulates the input elements into a
247 * new {@code Collection}, in encounter order. The {@code Collection} is
248 * created by the provided factory.
249 *
250 * @param <T> the type of the input elements
251 * @param <C> the type of the resulting {@code Collection}
252 * @param collectionFactory a {@code Supplier} which returns a new, empty
253 * {@code Collection} of the appropriate type
254 * @return a {@code Collector} which collects all the input elements into a
255 * {@code Collection}, in encounter order
256 */
257 public static <T, C extends Collection<T>>
258 Collector<T, ?, C> toCollection(Supplier<C> collectionFactory) {
259 return new CollectorImpl<>(collectionFactory, Collection<T>::add,
260 (r1, r2) -> { r1.addAll(r2); return r1; },
261 CH_ID);
262 }
263
264 /**
265 * Returns a {@code Collector} that accumulates the input elements into a
266 * new {@code List}. There are no guarantees on the type, mutability,
267 * serializability, or thread-safety of the {@code List} returned; if more
268 * control over the returned {@code List} is required, use {@link #toCollection(Supplier)}.
269 *
270 * @param <T> the type of the input elements
271 * @return a {@code Collector} which collects all the input elements into a
272 * {@code List}, in encounter order
273 */
274 public static <T>
275 Collector<T, ?, List<T>> toList() {
276 return new CollectorImpl<>((Supplier<List<T>>) ArrayList::new, List::add,
277 (left, right) -> { left.addAll(right); return left; },
278 CH_ID);
279 }
280
281 /**
282 * Returns a {@code Collector} that accumulates the input elements into a
283 * new {@code Set}. There are no guarantees on the type, mutability,
284 * serializability, or thread-safety of the {@code Set} returned; if more
285 * control over the returned {@code Set} is required, use
286 * {@link #toCollection(Supplier)}.
287 *
288 * <p>This is an {@link Collector.Characteristics#UNORDERED unordered}
289 * Collector.
290 *
291 * @param <T> the type of the input elements
292 * @return a {@code Collector} which collects all the input elements into a
293 * {@code Set}
294 */
295 public static <T>
296 Collector<T, ?, Set<T>> toSet() {
297 return new CollectorImpl<>((Supplier<Set<T>>) HashSet::new, Set::add,
298 (left, right) -> {
299 if (left.size() < right.size()) {
300 right.addAll(left); return right;
301 } else {
302 left.addAll(right); return left;
303 }
304 },
305 CH_UNORDERED_ID);
306 }
307
308 /**
309 * Returns a {@code Collector} that concatenates the input elements into a
310 * {@code String}, in encounter order.
311 *
312 * @return a {@code Collector} that concatenates the input elements into a
313 * {@code String}, in encounter order
314 */
315 public static Collector<CharSequence, ?, String> joining() {
316 return new CollectorImpl<CharSequence, StringBuilder, String>(
317 StringBuilder::new, StringBuilder::append,
318 (r1, r2) -> { r1.append(r2); return r1; },
319 StringBuilder::toString, CH_NOID);
320 }
321
322 /**
323 * Returns a {@code Collector} that concatenates the input elements,
324 * separated by the specified delimiter, in encounter order.
325 *
326 * @param delimiter the delimiter to be used between each element
327 * @return A {@code Collector} which concatenates CharSequence elements,
328 * separated by the specified delimiter, in encounter order
329 */
330 public static Collector<CharSequence, ?, String> joining(CharSequence delimiter) {
331 return joining(delimiter, "", "");
332 }
333
334 /**
335 * Returns a {@code Collector} that concatenates the input elements,
336 * separated by the specified delimiter, with the specified prefix and
337 * suffix, in encounter order.
338 *
339 * @param delimiter the delimiter to be used between each element
340 * @param prefix the sequence of characters to be used at the beginning
341 * of the joined result
342 * @param suffix the sequence of characters to be used at the end
343 * of the joined result
344 * @return A {@code Collector} which concatenates CharSequence elements,
345 * separated by the specified delimiter, in encounter order
346 */
347 public static Collector<CharSequence, ?, String> joining(CharSequence delimiter,
348 CharSequence prefix,
349 CharSequence suffix) {
350 return new CollectorImpl<>(
351 () -> new StringJoiner(delimiter, prefix, suffix),
352 StringJoiner::add, StringJoiner::merge,
353 StringJoiner::toString, CH_NOID);
354 }
355
356 /**
357 * {@code BinaryOperator<Map>} that merges the contents of its right
358 * argument into its left argument, using the provided merge function to
359 * handle duplicate keys.
360 *
361 * @param <K> type of the map keys
362 * @param <V> type of the map values
363 * @param <M> type of the map
364 * @param mergeFunction A merge function suitable for
365 * {@link Map#merge(Object, Object, BiFunction) Map.merge()}
366 * @return a merge function for two maps
367 */
368 private static <K, V, M extends Map<K,V>>
369 BinaryOperator<M> mapMerger(BinaryOperator<V> mergeFunction) {
370 return (m1, m2) -> {
371 for (Map.Entry<K,V> e : m2.entrySet())
372 m1.merge(e.getKey(), e.getValue(), mergeFunction);
373 return m1;
374 };
375 }
376
377 /**
378 * Adapts a {@code Collector} accepting elements of type {@code U} to one
379 * accepting elements of type {@code T} by applying a mapping function to
380 * each input element before accumulation.
381 *
382 * @apiNote
383 * The {@code mapping()} collectors are most useful when used in a
384 * multi-level reduction, such as downstream of a {@code groupingBy} or
385 * {@code partitioningBy}. For example, given a stream of
386 * {@code Person}, to accumulate the set of last names in each city:
387 * <pre>{@code
388 * Map<City, Set<String>> lastNamesByCity
389 * = people.stream().collect(groupingBy(Person::getCity,
390 * mapping(Person::getLastName, toSet())));
391 * }</pre>
392 *
393 * @param <T> the type of the input elements
394 * @param <U> type of elements accepted by downstream collector
395 * @param <A> intermediate accumulation type of the downstream collector
396 * @param <R> result type of collector
397 * @param mapper a function to be applied to the input elements
398 * @param downstream a collector which will accept mapped values
399 * @return a collector which applies the mapping function to the input
400 * elements and provides the mapped results to the downstream collector
401 */
402 public static <T, U, A, R>
403 Collector<T, ?, R> mapping(Function<? super T, ? extends U> mapper,
404 Collector<? super U, A, R> downstream) {
405 BiConsumer<A, ? super U> downstreamAccumulator = downstream.accumulator();
406 return new CollectorImpl<>(downstream.supplier(),
407 (r, t) -> downstreamAccumulator.accept(r, mapper.apply(t)),
408 downstream.combiner(), downstream.finisher(),
409 downstream.characteristics());
410 }
411
412 /**
413 * Adapts a {@code Collector} accepting elements of type {@code U} to one
414 * accepting elements of type {@code T} by applying a flat mapping function
415 * to each input element before accumulation. The flat mapping function
416 * maps an input element to a {@link Stream stream} covering zero or more
417 * output elements that are then accumulated downstream. Each mapped stream
418 * is {@link java.util.stream.BaseStream#close() closed} after its contents
419 * have been placed downstream. (If a mapped stream is {@code null}
420 * an empty stream is used, instead.)
421 *
422 * @apiNote
423 * The {@code flatMapping()} collectors are most useful when used in a
424 * multi-level reduction, such as downstream of a {@code groupingBy} or
425 * {@code partitioningBy}. For example, given a stream of
426 * {@code Order}, to accumulate the set of line items for each customer:
427 * <pre>{@code
428 * Map<String, Set<LineItem>> itemsByCustomerName
429 * = orders.stream().collect(groupingBy(Order::getCustomerName,
430 * flatMapping(order -> order.getLineItems().stream(), toSet())));
431 * }</pre>
432 *
433 * @param <T> the type of the input elements
434 * @param <U> type of elements accepted by downstream collector
435 * @param <A> intermediate accumulation type of the downstream collector
436 * @param <R> result type of collector
437 * @param mapper a function to be applied to the input elements, which
438 * returns a stream of results
439 * @param downstream a collector which will receive the elements of the
440 * stream returned by mapper
441 * @return a collector which applies the mapping function to the input
442 * elements and provides the flat mapped results to the downstream collector
443 * @since 9
444 */
445 public static <T, U, A, R>
446 Collector<T, ?, R> flatMapping(Function<? super T, ? extends Stream<? extends U>> mapper,
447 Collector<? super U, A, R> downstream) {
448 BiConsumer<A, ? super U> downstreamAccumulator = downstream.accumulator();
449 return new CollectorImpl<>(downstream.supplier(),
450 (r, t) -> {
451 try (Stream<? extends U> result = mapper.apply(t)) {
452 if (result != null)
453 result.sequential().forEach(u -> downstreamAccumulator.accept(r, u));
454 }
455 },
456 downstream.combiner(), downstream.finisher(),
457 downstream.characteristics());
458 }
459
460 /**
461 * Adapts a {@code Collector} to one accepting elements of the same type
462 * {@code T} by applying the predicate to each input element and only
463 * accumulating if the predicate returns {@code true}.
464 *
465 * @apiNote
466 * The {@code filtering()} collectors are most useful when used in a
467 * multi-level reduction, such as downstream of a {@code groupingBy} or
468 * {@code partitioningBy}. For example, given a stream of
469 * {@code Employee}, to accumulate the employees in each department that have a
470 * salary above a certain threshold:
471 * <pre>{@code
472 * Map<Department, Set<Employee>> wellPaidEmployeesByDepartment
473 * = employees.stream().collect(groupingBy(Employee::getDepartment,
474 * filtering(e -> e.getSalary() > 2000, toSet())));
475 * }</pre>
476 * A filtering collector differs from a stream's {@code filter()} operation.
477 * In this example, suppose there are no employees whose salary is above the
478 * threshold in some department. Using a filtering collector as shown above
479 * would result in a mapping from that department to an empty {@code Set}.
480 * If a stream {@code filter()} operation were done instead, there would be
481 * no mapping for that department at all.
482 *
483 * @param <T> the type of the input elements
484 * @param <A> intermediate accumulation type of the downstream collector
485 * @param <R> result type of collector
486 * @param predicate a predicate to be applied to the input elements
487 * @param downstream a collector which will accept values that match the
488 * predicate
489 * @return a collector which applies the predicate to the input elements
490 * and provides matching elements to the downstream collector
491 * @since 9
492 */
493 public static <T, A, R>
494 Collector<T, ?, R> filtering(Predicate<? super T> predicate,
495 Collector<? super T, A, R> downstream) {
496 BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
497 return new CollectorImpl<>(downstream.supplier(),
498 (r, t) -> {
499 if (predicate.test(t)) {
500 downstreamAccumulator.accept(r, t);
501 }
502 },
503 downstream.combiner(), downstream.finisher(),
504 downstream.characteristics());
505 }
506
507 /**
508 * Adapts a {@code Collector} to perform an additional finishing
509 * transformation. For example, one could adapt the {@link #toList()}
510 * collector to always produce an immutable list with:
511 * <pre>{@code
512 * List<String> people
513 * = people.stream().collect(collectingAndThen(toList(), Collections::unmodifiableList));
514 * }</pre>
515 *
516 * @param <T> the type of the input elements
517 * @param <A> intermediate accumulation type of the downstream collector
518 * @param <R> result type of the downstream collector
519 * @param <RR> result type of the resulting collector
520 * @param downstream a collector
521 * @param finisher a function to be applied to the final result of the downstream collector
522 * @return a collector which performs the action of the downstream collector,
523 * followed by an additional finishing step
524 */
525 public static<T,A,R,RR> Collector<T,A,RR> collectingAndThen(Collector<T,A,R> downstream,
526 Function<R,RR> finisher) {
527 Set<Collector.Characteristics> characteristics = downstream.characteristics();
528 if (characteristics.contains(Collector.Characteristics.IDENTITY_FINISH)) {
529 if (characteristics.size() == 1)
530 characteristics = Collectors.CH_NOID;
531 else {
532 characteristics = EnumSet.copyOf(characteristics);
533 characteristics.remove(Collector.Characteristics.IDENTITY_FINISH);
534 characteristics = Collections.unmodifiableSet(characteristics);
535 }
536 }
537 return new CollectorImpl<>(downstream.supplier(),
538 downstream.accumulator(),
539 downstream.combiner(),
540 downstream.finisher().andThen(finisher),
541 characteristics);
542 }
543
544 /**
545 * Returns a {@code Collector} accepting elements of type {@code T} that
546 * counts the number of input elements. If no elements are present, the
547 * result is 0.
548 *
549 * @implSpec
550 * This produces a result equivalent to:
551 * <pre>{@code
552 * reducing(0L, e -> 1L, Long::sum)
553 * }</pre>
554 *
555 * @param <T> the type of the input elements
556 * @return a {@code Collector} that counts the input elements
557 */
558 public static <T> Collector<T, ?, Long>
559 counting() {
560 return summingLong(e -> 1L);
561 }
562
563 /**
564 * Returns a {@code Collector} that produces the minimal element according
565 * to a given {@code Comparator}, described as an {@code Optional<T>}.
566 *
567 * @implSpec
568 * This produces a result equivalent to:
569 * <pre>{@code
570 * reducing(BinaryOperator.minBy(comparator))
571 * }</pre>
572 *
573 * @param <T> the type of the input elements
574 * @param comparator a {@code Comparator} for comparing elements
575 * @return a {@code Collector} that produces the minimal value
576 */
577 public static <T> Collector<T, ?, Optional<T>>
578 minBy(Comparator<? super T> comparator) {
579 return reducing(BinaryOperator.minBy(comparator));
580 }
581
582 /**
583 * Returns a {@code Collector} that produces the maximal element according
584 * to a given {@code Comparator}, described as an {@code Optional<T>}.
585 *
586 * @implSpec
587 * This produces a result equivalent to:
588 * <pre>{@code
589 * reducing(BinaryOperator.maxBy(comparator))
590 * }</pre>
591 *
592 * @param <T> the type of the input elements
593 * @param comparator a {@code Comparator} for comparing elements
594 * @return a {@code Collector} that produces the maximal value
595 */
596 public static <T> Collector<T, ?, Optional<T>>
597 maxBy(Comparator<? super T> comparator) {
598 return reducing(BinaryOperator.maxBy(comparator));
599 }
600
601 /**
602 * Returns a {@code Collector} that produces the sum of a integer-valued
603 * function applied to the input elements. If no elements are present,
604 * the result is 0.
605 *
606 * @param <T> the type of the input elements
607 * @param mapper a function extracting the property to be summed
608 * @return a {@code Collector} that produces the sum of a derived property
609 */
610 public static <T> Collector<T, ?, Integer>
611 summingInt(ToIntFunction<? super T> mapper) {
612 return new CollectorImpl<>(
613 () -> new int[1],
614 (a, t) -> { a[0] += mapper.applyAsInt(t); },
615 (a, b) -> { a[0] += b[0]; return a; },
616 a -> a[0], CH_NOID);
617 }
618
619 /**
620 * Returns a {@code Collector} that produces the sum of a long-valued
621 * function applied to the input elements. If no elements are present,
622 * the result is 0.
623 *
624 * @param <T> the type of the input elements
625 * @param mapper a function extracting the property to be summed
626 * @return a {@code Collector} that produces the sum of a derived property
627 */
628 public static <T> Collector<T, ?, Long>
629 summingLong(ToLongFunction<? super T> mapper) {
630 return new CollectorImpl<>(
631 () -> new long[1],
632 (a, t) -> { a[0] += mapper.applyAsLong(t); },
633 (a, b) -> { a[0] += b[0]; return a; },
634 a -> a[0], CH_NOID);
635 }
636
637 /**
638 * Returns a {@code Collector} that produces the sum of a double-valued
639 * function applied to the input elements. If no elements are present,
640 * the result is 0.
641 *
642 * <p>The sum returned can vary depending upon the order in which
643 * values are recorded, due to accumulated rounding error in
644 * addition of values of differing magnitudes. Values sorted by increasing
645 * absolute magnitude tend to yield more accurate results. If any recorded
646 * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
647 * sum will be {@code NaN}.
648 *
649 * @param <T> the type of the input elements
650 * @param mapper a function extracting the property to be summed
651 * @return a {@code Collector} that produces the sum of a derived property
652 */
653 public static <T> Collector<T, ?, Double>
654 summingDouble(ToDoubleFunction<? super T> mapper) {
655 /*
656 * In the arrays allocated for the collect operation, index 0
657 * holds the high-order bits of the running sum, index 1 holds
658 * the low-order bits of the sum computed via compensated
659 * summation, and index 2 holds the simple sum used to compute
660 * the proper result if the stream contains infinite values of
661 * the same sign.
662 */
663 return new CollectorImpl<>(
664 () -> new double[3],
665 (a, t) -> { double val = mapper.applyAsDouble(t);
666 sumWithCompensation(a, val);
667 a[2] += val;},
668 (a, b) -> { sumWithCompensation(a, b[0]);
669 a[2] += b[2];
670 return sumWithCompensation(a, b[1]); },
671 a -> computeFinalSum(a),
672 CH_NOID);
673 }
674
675 /**
676 * Incorporate a new double value using Kahan summation /
677 * compensation summation.
678 *
679 * High-order bits of the sum are in intermediateSum[0], low-order
680 * bits of the sum are in intermediateSum[1], any additional
681 * elements are application-specific.
682 *
683 * @param intermediateSum the high-order and low-order words of the intermediate sum
684 * @param value the name value to be included in the running sum
685 */
686 static double[] sumWithCompensation(double[] intermediateSum, double value) {
687 double tmp = value - intermediateSum[1];
688 double sum = intermediateSum[0];
689 double velvel = sum + tmp; // Little wolf of rounding error
690 intermediateSum[1] = (velvel - sum) - tmp;
691 intermediateSum[0] = velvel;
692 return intermediateSum;
693 }
694
695 /**
696 * If the compensated sum is spuriously NaN from accumulating one
697 * or more same-signed infinite values, return the
698 * correctly-signed infinity stored in the simple sum.
699 */
700 static double computeFinalSum(double[] summands) {
701 // Better error bounds to add both terms as the final sum
702 double tmp = summands[0] + summands[1];
703 double simpleSum = summands[summands.length - 1];
704 if (Double.isNaN(tmp) && Double.isInfinite(simpleSum))
705 return simpleSum;
706 else
707 return tmp;
708 }
709
710 /**
711 * Returns a {@code Collector} that produces the arithmetic mean of an integer-valued
712 * function applied to the input elements. If no elements are present,
713 * the result is 0.
714 *
715 * @param <T> the type of the input elements
716 * @param mapper a function extracting the property to be summed
717 * @return a {@code Collector} that produces the sum of a derived property
718 */
719 public static <T> Collector<T, ?, Double>
720 averagingInt(ToIntFunction<? super T> mapper) {
721 return new CollectorImpl<>(
722 () -> new long[2],
723 (a, t) -> { a[0] += mapper.applyAsInt(t); a[1]++; },
724 (a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
725 a -> (a[1] == 0) ? 0.0d : (double) a[0] / a[1], CH_NOID);
726 }
727
728 /**
729 * Returns a {@code Collector} that produces the arithmetic mean of a long-valued
730 * function applied to the input elements. If no elements are present,
731 * the result is 0.
732 *
733 * @param <T> the type of the input elements
734 * @param mapper a function extracting the property to be summed
735 * @return a {@code Collector} that produces the sum of a derived property
736 */
737 public static <T> Collector<T, ?, Double>
738 averagingLong(ToLongFunction<? super T> mapper) {
739 return new CollectorImpl<>(
740 () -> new long[2],
741 (a, t) -> { a[0] += mapper.applyAsLong(t); a[1]++; },
742 (a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
743 a -> (a[1] == 0) ? 0.0d : (double) a[0] / a[1], CH_NOID);
744 }
745
746 /**
747 * Returns a {@code Collector} that produces the arithmetic mean of a double-valued
748 * function applied to the input elements. If no elements are present,
749 * the result is 0.
750 *
751 * <p>The average returned can vary depending upon the order in which
752 * values are recorded, due to accumulated rounding error in
753 * addition of values of differing magnitudes. Values sorted by increasing
754 * absolute magnitude tend to yield more accurate results. If any recorded
755 * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
756 * average will be {@code NaN}.
757 *
758 * @implNote The {@code double} format can represent all
759 * consecutive integers in the range -2<sup>53</sup> to
760 * 2<sup>53</sup>. If the pipeline has more than 2<sup>53</sup>
761 * values, the divisor in the average computation will saturate at
762 * 2<sup>53</sup>, leading to additional numerical errors.
763 *
764 * @param <T> the type of the input elements
765 * @param mapper a function extracting the property to be summed
766 * @return a {@code Collector} that produces the sum of a derived property
767 */
768 public static <T> Collector<T, ?, Double>
769 averagingDouble(ToDoubleFunction<? super T> mapper) {
770 /*
771 * In the arrays allocated for the collect operation, index 0
772 * holds the high-order bits of the running sum, index 1 holds
773 * the low-order bits of the sum computed via compensated
774 * summation, and index 2 holds the number of values seen.
775 */
776 return new CollectorImpl<>(
777 () -> new double[4],
778 (a, t) -> { double val = mapper.applyAsDouble(t); sumWithCompensation(a, val); a[2]++; a[3]+= val;},
779 (a, b) -> { sumWithCompensation(a, b[0]); sumWithCompensation(a, b[1]); a[2] += b[2]; a[3] += b[3]; return a; },
780 a -> (a[2] == 0) ? 0.0d : (computeFinalSum(a) / a[2]),
781 CH_NOID);
782 }
783
784 /**
785 * Returns a {@code Collector} which performs a reduction of its
786 * input elements under a specified {@code BinaryOperator} using the
787 * provided identity.
788 *
789 * @apiNote
790 * The {@code reducing()} collectors are most useful when used in a
791 * multi-level reduction, downstream of {@code groupingBy} or
792 * {@code partitioningBy}. To perform a simple reduction on a stream,
793 * use {@link Stream#reduce(Object, BinaryOperator)}} instead.
794 *
795 * @param <T> element type for the input and output of the reduction
796 * @param identity the identity value for the reduction (also, the value
797 * that is returned when there are no input elements)
798 * @param op a {@code BinaryOperator<T>} used to reduce the input elements
799 * @return a {@code Collector} which implements the reduction operation
800 *
801 * @see #reducing(BinaryOperator)
802 * @see #reducing(Object, Function, BinaryOperator)
803 */
804 public static <T> Collector<T, ?, T>
805 reducing(T identity, BinaryOperator<T> op) {
806 return new CollectorImpl<>(
807 boxSupplier(identity),
808 (a, t) -> { a[0] = op.apply(a[0], t); },
809 (a, b) -> { a[0] = op.apply(a[0], b[0]); return a; },
810 a -> a[0],
811 CH_NOID);
812 }
813
814 @SuppressWarnings("unchecked")
815 private static <T> Supplier<T[]> boxSupplier(T identity) {
816 return () -> (T[]) new Object[] { identity };
817 }
818
819 /**
820 * Returns a {@code Collector} which performs a reduction of its
821 * input elements under a specified {@code BinaryOperator}. The result
822 * is described as an {@code Optional<T>}.
823 *
824 * @apiNote
825 * The {@code reducing()} collectors are most useful when used in a
826 * multi-level reduction, downstream of {@code groupingBy} or
827 * {@code partitioningBy}. To perform a simple reduction on a stream,
828 * use {@link Stream#reduce(BinaryOperator)} instead.
829 *
830 * <p>For example, given a stream of {@code Person}, to calculate tallest
831 * person in each city:
832 * <pre>{@code
833 * Comparator<Person> byHeight = Comparator.comparing(Person::getHeight);
834 * Map<City, Optional<Person>> tallestByCity
835 * = people.stream().collect(groupingBy(Person::getCity, reducing(BinaryOperator.maxBy(byHeight))));
836 * }</pre>
837 *
838 * @param <T> element type for the input and output of the reduction
839 * @param op a {@code BinaryOperator<T>} used to reduce the input elements
840 * @return a {@code Collector} which implements the reduction operation
841 *
842 * @see #reducing(Object, BinaryOperator)
843 * @see #reducing(Object, Function, BinaryOperator)
844 */
845 public static <T> Collector<T, ?, Optional<T>>
846 reducing(BinaryOperator<T> op) {
847 class OptionalBox implements Consumer<T> {
848 T value = null;
849 boolean present = false;
850
851 @Override
852 public void accept(T t) {
853 if (present) {
854 value = op.apply(value, t);
855 }
856 else {
857 value = t;
858 present = true;
859 }
860 }
861 }
862
863 return new CollectorImpl<T, OptionalBox, Optional<T>>(
864 OptionalBox::new, OptionalBox::accept,
865 (a, b) -> { if (b.present) a.accept(b.value); return a; },
866 a -> Optional.ofNullable(a.value), CH_NOID);
867 }
868
869 /**
870 * Returns a {@code Collector} which performs a reduction of its
871 * input elements under a specified mapping function and
872 * {@code BinaryOperator}. This is a generalization of
873 * {@link #reducing(Object, BinaryOperator)} which allows a transformation
874 * of the elements before reduction.
875 *
876 * @apiNote
877 * The {@code reducing()} collectors are most useful when used in a
878 * multi-level reduction, downstream of {@code groupingBy} or
879 * {@code partitioningBy}. To perform a simple map-reduce on a stream,
880 * use {@link Stream#map(Function)} and {@link Stream#reduce(Object, BinaryOperator)}
881 * instead.
882 *
883 * <p>For example, given a stream of {@code Person}, to calculate the longest
884 * last name of residents in each city:
885 * <pre>{@code
886 * Comparator<String> byLength = Comparator.comparing(String::length);
887 * Map<City, String> longestLastNameByCity
888 * = people.stream().collect(groupingBy(Person::getCity,
889 * reducing("", Person::getLastName, BinaryOperator.maxBy(byLength))));
890 * }</pre>
891 *
892 * @param <T> the type of the input elements
893 * @param <U> the type of the mapped values
894 * @param identity the identity value for the reduction (also, the value
895 * that is returned when there are no input elements)
896 * @param mapper a mapping function to apply to each input value
897 * @param op a {@code BinaryOperator<U>} used to reduce the mapped values
898 * @return a {@code Collector} implementing the map-reduce operation
899 *
900 * @see #reducing(Object, BinaryOperator)
901 * @see #reducing(BinaryOperator)
902 */
903 public static <T, U>
904 Collector<T, ?, U> reducing(U identity,
905 Function<? super T, ? extends U> mapper,
906 BinaryOperator<U> op) {
907 return new CollectorImpl<>(
908 boxSupplier(identity),
909 (a, t) -> { a[0] = op.apply(a[0], mapper.apply(t)); },
910 (a, b) -> { a[0] = op.apply(a[0], b[0]); return a; },
911 a -> a[0], CH_NOID);
912 }
913
914 /**
915 * Returns a {@code Collector} implementing a "group by" operation on
916 * input elements of type {@code T}, grouping elements according to a
917 * classification function, and returning the results in a {@code Map}.
918 *
919 * <p>The classification function maps elements to some key type {@code K}.
920 * The collector produces a {@code Map<K, List<T>>} whose keys are the
921 * values resulting from applying the classification function to the input
922 * elements, and whose corresponding values are {@code List}s containing the
923 * input elements which map to the associated key under the classification
924 * function.
925 *
926 * <p>There are no guarantees on the type, mutability, serializability, or
927 * thread-safety of the {@code Map} or {@code List} objects returned.
928 * @implSpec
929 * This produces a result similar to:
930 * <pre>{@code
931 * groupingBy(classifier, toList());
932 * }</pre>
933 *
934 * @implNote
935 * The returned {@code Collector} is not concurrent. For parallel stream
936 * pipelines, the {@code combiner} function operates by merging the keys
937 * from one map into another, which can be an expensive operation. If
938 * preservation of the order in which elements appear in the resulting {@code Map}
939 * collector is not required, using {@link #groupingByConcurrent(Function)}
940 * may offer better parallel performance.
941 *
942 * @param <T> the type of the input elements
943 * @param <K> the type of the keys
944 * @param classifier the classifier function mapping input elements to keys
945 * @return a {@code Collector} implementing the group-by operation
946 *
947 * @see #groupingBy(Function, Collector)
948 * @see #groupingBy(Function, Supplier, Collector)
949 * @see #groupingByConcurrent(Function)
950 */
951 public static <T, K> Collector<T, ?, Map<K, List<T>>>
952 groupingBy(Function<? super T, ? extends K> classifier) {
953 return groupingBy(classifier, toList());
954 }
955
956 /**
957 * Returns a {@code Collector} implementing a cascaded "group by" operation
958 * on input elements of type {@code T}, grouping elements according to a
959 * classification function, and then performing a reduction operation on
960 * the values associated with a given key using the specified downstream
961 * {@code Collector}.
962 *
963 * <p>The classification function maps elements to some key type {@code K}.
964 * The downstream collector operates on elements of type {@code T} and
965 * produces a result of type {@code D}. The resulting collector produces a
966 * {@code Map<K, D>}.
967 *
968 * <p>There are no guarantees on the type, mutability,
969 * serializability, or thread-safety of the {@code Map} returned.
970 *
971 * <p>For example, to compute the set of last names of people in each city:
972 * <pre>{@code
973 * Map<City, Set<String>> namesByCity
974 * = people.stream().collect(groupingBy(Person::getCity,
975 * mapping(Person::getLastName, toSet())));
976 * }</pre>
977 *
978 * @implNote
979 * The returned {@code Collector} is not concurrent. For parallel stream
980 * pipelines, the {@code combiner} function operates by merging the keys
981 * from one map into another, which can be an expensive operation. If
982 * preservation of the order in which elements are presented to the downstream
983 * collector is not required, using {@link #groupingByConcurrent(Function, Collector)}
984 * may offer better parallel performance.
985 *
986 * @param <T> the type of the input elements
987 * @param <K> the type of the keys
988 * @param <A> the intermediate accumulation type of the downstream collector
989 * @param <D> the result type of the downstream reduction
990 * @param classifier a classifier function mapping input elements to keys
991 * @param downstream a {@code Collector} implementing the downstream reduction
992 * @return a {@code Collector} implementing the cascaded group-by operation
993 * @see #groupingBy(Function)
994 *
995 * @see #groupingBy(Function, Supplier, Collector)
996 * @see #groupingByConcurrent(Function, Collector)
997 */
998 public static <T, K, A, D>
999 Collector<T, ?, Map<K, D>> groupingBy(Function<? super T, ? extends K> classifier,
1000 Collector<? super T, A, D> downstream) {
1001 return groupingBy(classifier, HashMap::new, downstream);
1002 }
1003
1004 /**
1005 * Returns a {@code Collector} implementing a cascaded "group by" operation
1006 * on input elements of type {@code T}, grouping elements according to a
1007 * classification function, and then performing a reduction operation on
1008 * the values associated with a given key using the specified downstream
1009 * {@code Collector}. The {@code Map} produced by the Collector is created
1010 * with the supplied factory function.
1011 *
1012 * <p>The classification function maps elements to some key type {@code K}.
1013 * The downstream collector operates on elements of type {@code T} and
1014 * produces a result of type {@code D}. The resulting collector produces a
1015 * {@code Map<K, D>}.
1016 *
1017 * <p>For example, to compute the set of last names of people in each city,
1018 * where the city names are sorted:
1019 * <pre>{@code
1020 * Map<City, Set<String>> namesByCity
1021 * = people.stream().collect(groupingBy(Person::getCity, TreeMap::new,
1022 * mapping(Person::getLastName, toSet())));
1023 * }</pre>
1024 *
1025 * @implNote
1026 * The returned {@code Collector} is not concurrent. For parallel stream
1027 * pipelines, the {@code combiner} function operates by merging the keys
1028 * from one map into another, which can be an expensive operation. If
1029 * preservation of the order in which elements are presented to the downstream
1030 * collector is not required, using {@link #groupingByConcurrent(Function, Supplier, Collector)}
1031 * may offer better parallel performance.
1032 *
1033 * @param <T> the type of the input elements
1034 * @param <K> the type of the keys
1035 * @param <A> the intermediate accumulation type of the downstream collector
1036 * @param <D> the result type of the downstream reduction
1037 * @param <M> the type of the resulting {@code Map}
1038 * @param classifier a classifier function mapping input elements to keys
1039 * @param downstream a {@code Collector} implementing the downstream reduction
1040 * @param mapFactory a function which, when called, produces a new empty
1041 * {@code Map} of the desired type
1042 * @return a {@code Collector} implementing the cascaded group-by operation
1043 *
1044 * @see #groupingBy(Function, Collector)
1045 * @see #groupingBy(Function)
1046 * @see #groupingByConcurrent(Function, Supplier, Collector)
1047 */
1048 public static <T, K, D, A, M extends Map<K, D>>
1049 Collector<T, ?, M> groupingBy(Function<? super T, ? extends K> classifier,
1050 Supplier<M> mapFactory,
1051 Collector<? super T, A, D> downstream) {
1052 Supplier<A> downstreamSupplier = downstream.supplier();
1053 BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
1054 BiConsumer<Map<K, A>, T> accumulator = (m, t) -> {
1055 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
1056 A container = m.computeIfAbsent(key, k -> downstreamSupplier.get());
1057 downstreamAccumulator.accept(container, t);
1058 };
1059 BinaryOperator<Map<K, A>> merger = Collectors.<K, A, Map<K, A>>mapMerger(downstream.combiner());
1060 @SuppressWarnings("unchecked")
1061 Supplier<Map<K, A>> mangledFactory = (Supplier<Map<K, A>>) mapFactory;
1062
1063 if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
1064 return new CollectorImpl<>(mangledFactory, accumulator, merger, CH_ID);
1065 }
1066 else {
1067 @SuppressWarnings("unchecked")
1068 Function<A, A> downstreamFinisher = (Function<A, A>) downstream.finisher();
1069 Function<Map<K, A>, M> finisher = intermediate -> {
1070 intermediate.replaceAll((k, v) -> downstreamFinisher.apply(v));
1071 @SuppressWarnings("unchecked")
1072 M castResult = (M) intermediate;
1073 return castResult;
1074 };
1075 return new CollectorImpl<>(mangledFactory, accumulator, merger, finisher, CH_NOID);
1076 }
1077 }
1078
1079 /**
1080 * Returns a concurrent {@code Collector} implementing a "group by"
1081 * operation on input elements of type {@code T}, grouping elements
1082 * according to a classification function.
1083 *
1084 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1085 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1086 *
1087 * <p>The classification function maps elements to some key type {@code K}.
1088 * The collector produces a {@code ConcurrentMap<K, List<T>>} whose keys are the
1089 * values resulting from applying the classification function to the input
1090 * elements, and whose corresponding values are {@code List}s containing the
1091 * input elements which map to the associated key under the classification
1092 * function.
1093 *
1094 * <p>There are no guarantees on the type, mutability, or serializability
1095 * of the {@code ConcurrentMap} or {@code List} objects returned, or of the
1096 * thread-safety of the {@code List} objects returned.
1097 * @implSpec
1098 * This produces a result similar to:
1099 * <pre>{@code
1100 * groupingByConcurrent(classifier, toList());
1101 * }</pre>
1102 *
1103 * @param <T> the type of the input elements
1104 * @param <K> the type of the keys
1105 * @param classifier a classifier function mapping input elements to keys
1106 * @return a concurrent, unordered {@code Collector} implementing the group-by operation
1107 *
1108 * @see #groupingBy(Function)
1109 * @see #groupingByConcurrent(Function, Collector)
1110 * @see #groupingByConcurrent(Function, Supplier, Collector)
1111 */
1112 public static <T, K>
1113 Collector<T, ?, ConcurrentMap<K, List<T>>>
1114 groupingByConcurrent(Function<? super T, ? extends K> classifier) {
1115 return groupingByConcurrent(classifier, ConcurrentHashMap::new, toList());
1116 }
1117
1118 /**
1119 * Returns a concurrent {@code Collector} implementing a cascaded "group by"
1120 * operation on input elements of type {@code T}, grouping elements
1121 * according to a classification function, and then performing a reduction
1122 * operation on the values associated with a given key using the specified
1123 * downstream {@code Collector}.
1124 *
1125 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1126 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1127 *
1128 * <p>The classification function maps elements to some key type {@code K}.
1129 * The downstream collector operates on elements of type {@code T} and
1130 * produces a result of type {@code D}. The resulting collector produces a
1131 * {@code Map<K, D>}.
1132 *
1133 * <p>There are no guarantees on the type, mutability, or serializability
1134 * of the {@code ConcurrentMap} returned.
1135 *
1136 * <p>For example, to compute the set of last names of people in each city,
1137 * where the city names are sorted:
1138 * <pre>{@code
1139 * ConcurrentMap<City, Set<String>> namesByCity
1140 * = people.stream().collect(groupingByConcurrent(Person::getCity,
1141 * mapping(Person::getLastName, toSet())));
1142 * }</pre>
1143 *
1144 * @param <T> the type of the input elements
1145 * @param <K> the type of the keys
1146 * @param <A> the intermediate accumulation type of the downstream collector
1147 * @param <D> the result type of the downstream reduction
1148 * @param classifier a classifier function mapping input elements to keys
1149 * @param downstream a {@code Collector} implementing the downstream reduction
1150 * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
1151 *
1152 * @see #groupingBy(Function, Collector)
1153 * @see #groupingByConcurrent(Function)
1154 * @see #groupingByConcurrent(Function, Supplier, Collector)
1155 */
1156 public static <T, K, A, D>
1157 Collector<T, ?, ConcurrentMap<K, D>> groupingByConcurrent(Function<? super T, ? extends K> classifier,
1158 Collector<? super T, A, D> downstream) {
1159 return groupingByConcurrent(classifier, ConcurrentHashMap::new, downstream);
1160 }
1161
1162 /**
1163 * Returns a concurrent {@code Collector} implementing a cascaded "group by"
1164 * operation on input elements of type {@code T}, grouping elements
1165 * according to a classification function, and then performing a reduction
1166 * operation on the values associated with a given key using the specified
1167 * downstream {@code Collector}. The {@code ConcurrentMap} produced by the
1168 * Collector is created with the supplied factory function.
1169 *
1170 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1171 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1172 *
1173 * <p>The classification function maps elements to some key type {@code K}.
1174 * The downstream collector operates on elements of type {@code T} and
1175 * produces a result of type {@code D}. The resulting collector produces a
1176 * {@code Map<K, D>}.
1177 *
1178 * <p>For example, to compute the set of last names of people in each city,
1179 * where the city names are sorted:
1180 * <pre>{@code
1181 * ConcurrentMap<City, Set<String>> namesByCity
1182 * = people.stream().collect(groupingBy(Person::getCity, ConcurrentSkipListMap::new,
1183 * mapping(Person::getLastName, toSet())));
1184 * }</pre>
1185 *
1186 *
1187 * @param <T> the type of the input elements
1188 * @param <K> the type of the keys
1189 * @param <A> the intermediate accumulation type of the downstream collector
1190 * @param <D> the result type of the downstream reduction
1191 * @param <M> the type of the resulting {@code ConcurrentMap}
1192 * @param classifier a classifier function mapping input elements to keys
1193 * @param downstream a {@code Collector} implementing the downstream reduction
1194 * @param mapFactory a function which, when called, produces a new empty
1195 * {@code ConcurrentMap} of the desired type
1196 * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
1197 *
1198 * @see #groupingByConcurrent(Function)
1199 * @see #groupingByConcurrent(Function, Collector)
1200 * @see #groupingBy(Function, Supplier, Collector)
1201 */
1202 public static <T, K, A, D, M extends ConcurrentMap<K, D>>
1203 Collector<T, ?, M> groupingByConcurrent(Function<? super T, ? extends K> classifier,
1204 Supplier<M> mapFactory,
1205 Collector<? super T, A, D> downstream) {
1206 Supplier<A> downstreamSupplier = downstream.supplier();
1207 BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
1208 BinaryOperator<ConcurrentMap<K, A>> merger = Collectors.<K, A, ConcurrentMap<K, A>>mapMerger(downstream.combiner());
1209 @SuppressWarnings("unchecked")
1210 Supplier<ConcurrentMap<K, A>> mangledFactory = (Supplier<ConcurrentMap<K, A>>) mapFactory;
1211 BiConsumer<ConcurrentMap<K, A>, T> accumulator;
1212 if (downstream.characteristics().contains(Collector.Characteristics.CONCURRENT)) {
1213 accumulator = (m, t) -> {
1214 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
1215 A resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
1216 downstreamAccumulator.accept(resultContainer, t);
1217 };
1218 }
1219 else {
1220 accumulator = (m, t) -> {
1221 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
1222 A resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
1223 synchronized (resultContainer) {
1224 downstreamAccumulator.accept(resultContainer, t);
1225 }
1226 };
1227 }
1228
1229 if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
1230 return new CollectorImpl<>(mangledFactory, accumulator, merger, CH_CONCURRENT_ID);
1231 }
1232 else {
1233 @SuppressWarnings("unchecked")
1234 Function<A, A> downstreamFinisher = (Function<A, A>) downstream.finisher();
1235 Function<ConcurrentMap<K, A>, M> finisher = intermediate -> {
1236 intermediate.replaceAll((k, v) -> downstreamFinisher.apply(v));
1237 @SuppressWarnings("unchecked")
1238 M castResult = (M) intermediate;
1239 return castResult;
1240 };
1241 return new CollectorImpl<>(mangledFactory, accumulator, merger, finisher, CH_CONCURRENT_NOID);
1242 }
1243 }
1244
1245 /**
1246 * Returns a {@code Collector} which partitions the input elements according
1247 * to a {@code Predicate}, and organizes them into a
1248 * {@code Map<Boolean, List<T>>}.
1249 *
1250 * There are no guarantees on the type, mutability,
1251 * serializability, or thread-safety of the {@code Map} or {@code List}
1252 * returned.
1253 *
1254 * @param <T> the type of the input elements
1255 * @param predicate a predicate used for classifying input elements
1256 * @return a {@code Collector} implementing the partitioning operation
1257 *
1258 * @see #partitioningBy(Predicate, Collector)
1259 */
1260 public static <T>
1261 Collector<T, ?, Map<Boolean, List<T>>> partitioningBy(Predicate<? super T> predicate) {
1262 return partitioningBy(predicate, toList());
1263 }
1264
1265 /**
1266 * Returns a {@code Collector} which partitions the input elements according
1267 * to a {@code Predicate}, reduces the values in each partition according to
1268 * another {@code Collector}, and organizes them into a
1269 * {@code Map<Boolean, D>} whose values are the result of the downstream
1270 * reduction.
1271 *
1272 * <p>There are no guarantees on the type, mutability,
1273 * serializability, or thread-safety of the {@code Map} returned.
1274 *
1275 * @param <T> the type of the input elements
1276 * @param <A> the intermediate accumulation type of the downstream collector
1277 * @param <D> the result type of the downstream reduction
1278 * @param predicate a predicate used for classifying input elements
1279 * @param downstream a {@code Collector} implementing the downstream
1280 * reduction
1281 * @return a {@code Collector} implementing the cascaded partitioning
1282 * operation
1283 *
1284 * @see #partitioningBy(Predicate)
1285 */
1286 public static <T, D, A>
1287 Collector<T, ?, Map<Boolean, D>> partitioningBy(Predicate<? super T> predicate,
1288 Collector<? super T, A, D> downstream) {
1289 BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
1290 BiConsumer<Partition<A>, T> accumulator = (result, t) ->
1291 downstreamAccumulator.accept(predicate.test(t) ? result.forTrue : result.forFalse, t);
1292 BinaryOperator<A> op = downstream.combiner();
1293 BinaryOperator<Partition<A>> merger = (left, right) ->
1294 new Partition<>(op.apply(left.forTrue, right.forTrue),
1295 op.apply(left.forFalse, right.forFalse));
1296 Supplier<Partition<A>> supplier = () ->
1297 new Partition<>(downstream.supplier().get(),
1298 downstream.supplier().get());
1299 if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
1300 return new CollectorImpl<>(supplier, accumulator, merger, CH_ID);
1301 }
1302 else {
1303 Function<Partition<A>, Map<Boolean, D>> finisher = par ->
1304 new Partition<>(downstream.finisher().apply(par.forTrue),
1305 downstream.finisher().apply(par.forFalse));
1306 return new CollectorImpl<>(supplier, accumulator, merger, finisher, CH_NOID);
1307 }
1308 }
1309
1310 /**
1311 * Returns a {@code Collector} that accumulates elements into a
1312 * {@code Map} whose keys and values are the result of applying the provided
1313 * mapping functions to the input elements.
1314 *
1315 * <p>If the mapped keys contains duplicates (according to
1316 * {@link Object#equals(Object)}), an {@code IllegalStateException} is
1317 * thrown when the collection operation is performed. If the mapped keys
1318 * may have duplicates, use {@link #toMap(Function, Function, BinaryOperator)}
1319 * instead.
1320 *
1321 * <p>There are no guarantees on the type, mutability, serializability,
1322 * or thread-safety of the {@code Map} returned.
1323 *
1324 * @apiNote
1325 * It is common for either the key or the value to be the input elements.
1326 * In this case, the utility method
1327 * {@link java.util.function.Function#identity()} may be helpful.
1328 * For example, the following produces a {@code Map} mapping
1329 * students to their grade point average:
1330 * <pre>{@code
1331 * Map<Student, Double> studentToGPA
1332 * students.stream().collect(toMap(Function.identity(),
1333 * student -> computeGPA(student)));
1334 * }</pre>
1335 * And the following produces a {@code Map} mapping a unique identifier to
1336 * students:
1337 * <pre>{@code
1338 * Map<String, Student> studentIdToStudent
1339 * students.stream().collect(toMap(Student::getId,
1340 * Function.identity());
1341 * }</pre>
1342 *
1343 * @implNote
1344 * The returned {@code Collector} is not concurrent. For parallel stream
1345 * pipelines, the {@code combiner} function operates by merging the keys
1346 * from one map into another, which can be an expensive operation. If it is
1347 * not required that results are inserted into the {@code Map} in encounter
1348 * order, using {@link #toConcurrentMap(Function, Function)}
1349 * may offer better parallel performance.
1350 *
1351 * @param <T> the type of the input elements
1352 * @param <K> the output type of the key mapping function
1353 * @param <U> the output type of the value mapping function
1354 * @param keyMapper a mapping function to produce keys
1355 * @param valueMapper a mapping function to produce values
1356 * @return a {@code Collector} which collects elements into a {@code Map}
1357 * whose keys and values are the result of applying mapping functions to
1358 * the input elements
1359 *
1360 * @see #toMap(Function, Function, BinaryOperator)
1361 * @see #toMap(Function, Function, BinaryOperator, Supplier)
1362 * @see #toConcurrentMap(Function, Function)
1363 */
1364 public static <T, K, U>
1365 Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
1366 Function<? super T, ? extends U> valueMapper) {
1367 return new CollectorImpl<>(HashMap::new,
1368 uniqKeysMapAccumulator(keyMapper, valueMapper),
1369 uniqKeysMapMerger(),
1370 CH_ID);
1371 }
1372
1373 /**
1374 * Returns a {@code Collector} that accumulates elements into a
1375 * {@code Map} whose keys and values are the result of applying the provided
1376 * mapping functions to the input elements.
1377 *
1378 * <p>If the mapped
1379 * keys contains duplicates (according to {@link Object#equals(Object)}),
1380 * the value mapping function is applied to each equal element, and the
1381 * results are merged using the provided merging function.
1382 *
1383 * <p>There are no guarantees on the type, mutability, serializability,
1384 * or thread-safety of the {@code Map} returned.
1385 *
1386 * @apiNote
1387 * There are multiple ways to deal with collisions between multiple elements
1388 * mapping to the same key. The other forms of {@code toMap} simply use
1389 * a merge function that throws unconditionally, but you can easily write
1390 * more flexible merge policies. For example, if you have a stream
1391 * of {@code Person}, and you want to produce a "phone book" mapping name to
1392 * address, but it is possible that two persons have the same name, you can
1393 * do as follows to gracefully deals with these collisions, and produce a
1394 * {@code Map} mapping names to a concatenated list of addresses:
1395 * <pre>{@code
1396 * Map<String, String> phoneBook
1397 * people.stream().collect(toMap(Person::getName,
1398 * Person::getAddress,
1399 * (s, a) -> s + ", " + a));
1400 * }</pre>
1401 *
1402 * @implNote
1403 * The returned {@code Collector} is not concurrent. For parallel stream
1404 * pipelines, the {@code combiner} function operates by merging the keys
1405 * from one map into another, which can be an expensive operation. If it is
1406 * not required that results are merged into the {@code Map} in encounter
1407 * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator)}
1408 * may offer better parallel performance.
1409 *
1410 * @param <T> the type of the input elements
1411 * @param <K> the output type of the key mapping function
1412 * @param <U> the output type of the value mapping function
1413 * @param keyMapper a mapping function to produce keys
1414 * @param valueMapper a mapping function to produce values
1415 * @param mergeFunction a merge function, used to resolve collisions between
1416 * values associated with the same key, as supplied
1417 * to {@link Map#merge(Object, Object, BiFunction)}
1418 * @return a {@code Collector} which collects elements into a {@code Map}
1419 * whose keys are the result of applying a key mapping function to the input
1420 * elements, and whose values are the result of applying a value mapping
1421 * function to all input elements equal to the key and combining them
1422 * using the merge function
1423 *
1424 * @see #toMap(Function, Function)
1425 * @see #toMap(Function, Function, BinaryOperator, Supplier)
1426 * @see #toConcurrentMap(Function, Function, BinaryOperator)
1427 */
1428 public static <T, K, U>
1429 Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
1430 Function<? super T, ? extends U> valueMapper,
1431 BinaryOperator<U> mergeFunction) {
1432 return toMap(keyMapper, valueMapper, mergeFunction, HashMap::new);
1433 }
1434
1435 /**
1436 * Returns a {@code Collector} that accumulates elements into a
1437 * {@code Map} whose keys and values are the result of applying the provided
1438 * mapping functions to the input elements.
1439 *
1440 * <p>If the mapped
1441 * keys contains duplicates (according to {@link Object#equals(Object)}),
1442 * the value mapping function is applied to each equal element, and the
1443 * results are merged using the provided merging function. The {@code Map}
1444 * is created by a provided supplier function.
1445 *
1446 * @implNote
1447 * The returned {@code Collector} is not concurrent. For parallel stream
1448 * pipelines, the {@code combiner} function operates by merging the keys
1449 * from one map into another, which can be an expensive operation. If it is
1450 * not required that results are merged into the {@code Map} in encounter
1451 * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator, Supplier)}
1452 * may offer better parallel performance.
1453 *
1454 * @param <T> the type of the input elements
1455 * @param <K> the output type of the key mapping function
1456 * @param <U> the output type of the value mapping function
1457 * @param <M> the type of the resulting {@code Map}
1458 * @param keyMapper a mapping function to produce keys
1459 * @param valueMapper a mapping function to produce values
1460 * @param mergeFunction a merge function, used to resolve collisions between
1461 * values associated with the same key, as supplied
1462 * to {@link Map#merge(Object, Object, BiFunction)}
1463 * @param mapSupplier a function which returns a new, empty {@code Map} into
1464 * which the results will be inserted
1465 * @return a {@code Collector} which collects elements into a {@code Map}
1466 * whose keys are the result of applying a key mapping function to the input
1467 * elements, and whose values are the result of applying a value mapping
1468 * function to all input elements equal to the key and combining them
1469 * using the merge function
1470 *
1471 * @see #toMap(Function, Function)
1472 * @see #toMap(Function, Function, BinaryOperator)
1473 * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1474 */
1475 public static <T, K, U, M extends Map<K, U>>
1476 Collector<T, ?, M> toMap(Function<? super T, ? extends K> keyMapper,
1477 Function<? super T, ? extends U> valueMapper,
1478 BinaryOperator<U> mergeFunction,
1479 Supplier<M> mapSupplier) {
1480 BiConsumer<M, T> accumulator
1481 = (map, element) -> map.merge(keyMapper.apply(element),
1482 valueMapper.apply(element), mergeFunction);
1483 return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_ID);
1484 }
1485
1486 /**
1487 * Returns a concurrent {@code Collector} that accumulates elements into a
1488 * {@code ConcurrentMap} whose keys and values are the result of applying
1489 * the provided mapping functions to the input elements.
1490 *
1491 * <p>If the mapped keys contains duplicates (according to
1492 * {@link Object#equals(Object)}), an {@code IllegalStateException} is
1493 * thrown when the collection operation is performed. If the mapped keys
1494 * may have duplicates, use
1495 * {@link #toConcurrentMap(Function, Function, BinaryOperator)} instead.
1496 *
1497 * <p>There are no guarantees on the type, mutability, or serializability
1498 * of the {@code ConcurrentMap} returned.
1499 *
1500 * @apiNote
1501 * It is common for either the key or the value to be the input elements.
1502 * In this case, the utility method
1503 * {@link java.util.function.Function#identity()} may be helpful.
1504 * For example, the following produces a {@code Map} mapping
1505 * students to their grade point average:
1506 * <pre>{@code
1507 * Map<Student, Double> studentToGPA
1508 * students.stream().collect(toMap(Function.identity(),
1509 * student -> computeGPA(student)));
1510 * }</pre>
1511 * And the following produces a {@code Map} mapping a unique identifier to
1512 * students:
1513 * <pre>{@code
1514 * Map<String, Student> studentIdToStudent
1515 * students.stream().collect(toConcurrentMap(Student::getId,
1516 * Function.identity());
1517 * }</pre>
1518 *
1519 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1520 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1521 *
1522 * @param <T> the type of the input elements
1523 * @param <K> the output type of the key mapping function
1524 * @param <U> the output type of the value mapping function
1525 * @param keyMapper the mapping function to produce keys
1526 * @param valueMapper the mapping function to produce values
1527 * @return a concurrent, unordered {@code Collector} which collects elements into a
1528 * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1529 * function to the input elements, and whose values are the result of
1530 * applying a value mapping function to the input elements
1531 *
1532 * @see #toMap(Function, Function)
1533 * @see #toConcurrentMap(Function, Function, BinaryOperator)
1534 * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1535 */
1536 public static <T, K, U>
1537 Collector<T, ?, ConcurrentMap<K,U>> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1538 Function<? super T, ? extends U> valueMapper) {
1539 return new CollectorImpl<>(ConcurrentHashMap::new,
1540 uniqKeysMapAccumulator(keyMapper, valueMapper),
1541 uniqKeysMapMerger(),
1542 CH_CONCURRENT_ID);
1543 }
1544
1545 /**
1546 * Returns a concurrent {@code Collector} that accumulates elements into a
1547 * {@code ConcurrentMap} whose keys and values are the result of applying
1548 * the provided mapping functions to the input elements.
1549 *
1550 * <p>If the mapped keys contains duplicates (according to {@link Object#equals(Object)}),
1551 * the value mapping function is applied to each equal element, and the
1552 * results are merged using the provided merging function.
1553 *
1554 * <p>There are no guarantees on the type, mutability, or serializability
1555 * of the {@code ConcurrentMap} returned.
1556 *
1557 * @apiNote
1558 * There are multiple ways to deal with collisions between multiple elements
1559 * mapping to the same key. The other forms of {@code toConcurrentMap} simply use
1560 * a merge function that throws unconditionally, but you can easily write
1561 * more flexible merge policies. For example, if you have a stream
1562 * of {@code Person}, and you want to produce a "phone book" mapping name to
1563 * address, but it is possible that two persons have the same name, you can
1564 * do as follows to gracefully deals with these collisions, and produce a
1565 * {@code Map} mapping names to a concatenated list of addresses:
1566 * <pre>{@code
1567 * Map<String, String> phoneBook
1568 * people.stream().collect(toConcurrentMap(Person::getName,
1569 * Person::getAddress,
1570 * (s, a) -> s + ", " + a));
1571 * }</pre>
1572 *
1573 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1574 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1575 *
1576 * @param <T> the type of the input elements
1577 * @param <K> the output type of the key mapping function
1578 * @param <U> the output type of the value mapping function
1579 * @param keyMapper a mapping function to produce keys
1580 * @param valueMapper a mapping function to produce values
1581 * @param mergeFunction a merge function, used to resolve collisions between
1582 * values associated with the same key, as supplied
1583 * to {@link Map#merge(Object, Object, BiFunction)}
1584 * @return a concurrent, unordered {@code Collector} which collects elements into a
1585 * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1586 * function to the input elements, and whose values are the result of
1587 * applying a value mapping function to all input elements equal to the key
1588 * and combining them using the merge function
1589 *
1590 * @see #toConcurrentMap(Function, Function)
1591 * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1592 * @see #toMap(Function, Function, BinaryOperator)
1593 */
1594 public static <T, K, U>
1595 Collector<T, ?, ConcurrentMap<K,U>>
1596 toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1597 Function<? super T, ? extends U> valueMapper,
1598 BinaryOperator<U> mergeFunction) {
1599 return toConcurrentMap(keyMapper, valueMapper, mergeFunction, ConcurrentHashMap::new);
1600 }
1601
1602 /**
1603 * Returns a concurrent {@code Collector} that accumulates elements into a
1604 * {@code ConcurrentMap} whose keys and values are the result of applying
1605 * the provided mapping functions to the input elements.
1606 *
1607 * <p>If the mapped keys contains duplicates (according to {@link Object#equals(Object)}),
1608 * the value mapping function is applied to each equal element, and the
1609 * results are merged using the provided merging function. The
1610 * {@code ConcurrentMap} is created by a provided supplier function.
1611 *
1612 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1613 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1614 *
1615 * @param <T> the type of the input elements
1616 * @param <K> the output type of the key mapping function
1617 * @param <U> the output type of the value mapping function
1618 * @param <M> the type of the resulting {@code ConcurrentMap}
1619 * @param keyMapper a mapping function to produce keys
1620 * @param valueMapper a mapping function to produce values
1621 * @param mergeFunction a merge function, used to resolve collisions between
1622 * values associated with the same key, as supplied
1623 * to {@link Map#merge(Object, Object, BiFunction)}
1624 * @param mapSupplier a function which returns a new, empty {@code Map} into
1625 * which the results will be inserted
1626 * @return a concurrent, unordered {@code Collector} which collects elements into a
1627 * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1628 * function to the input elements, and whose values are the result of
1629 * applying a value mapping function to all input elements equal to the key
1630 * and combining them using the merge function
1631 *
1632 * @see #toConcurrentMap(Function, Function)
1633 * @see #toConcurrentMap(Function, Function, BinaryOperator)
1634 * @see #toMap(Function, Function, BinaryOperator, Supplier)
1635 */
1636 public static <T, K, U, M extends ConcurrentMap<K, U>>
1637 Collector<T, ?, M> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1638 Function<? super T, ? extends U> valueMapper,
1639 BinaryOperator<U> mergeFunction,
1640 Supplier<M> mapSupplier) {
1641 BiConsumer<M, T> accumulator
1642 = (map, element) -> map.merge(keyMapper.apply(element),
1643 valueMapper.apply(element), mergeFunction);
1644 return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_CONCURRENT_ID);
1645 }
1646
1647 /**
1648 * Returns a {@code Collector} which applies an {@code int}-producing
1649 * mapping function to each input element, and returns summary statistics
1650 * for the resulting values.
1651 *
1652 * @param <T> the type of the input elements
1653 * @param mapper a mapping function to apply to each element
1654 * @return a {@code Collector} implementing the summary-statistics reduction
1655 *
1656 * @see #summarizingDouble(ToDoubleFunction)
1657 * @see #summarizingLong(ToLongFunction)
1658 */
1659 public static <T>
1660 Collector<T, ?, IntSummaryStatistics> summarizingInt(ToIntFunction<? super T> mapper) {
1661 return new CollectorImpl<T, IntSummaryStatistics, IntSummaryStatistics>(
1662 IntSummaryStatistics::new,
1663 (r, t) -> r.accept(mapper.applyAsInt(t)),
1664 (l, r) -> { l.combine(r); return l; }, CH_ID);
1665 }
1666
1667 /**
1668 * Returns a {@code Collector} which applies an {@code long}-producing
1669 * mapping function to each input element, and returns summary statistics
1670 * for the resulting values.
1671 *
1672 * @param <T> the type of the input elements
1673 * @param mapper the mapping function to apply to each element
1674 * @return a {@code Collector} implementing the summary-statistics reduction
1675 *
1676 * @see #summarizingDouble(ToDoubleFunction)
1677 * @see #summarizingInt(ToIntFunction)
1678 */
1679 public static <T>
1680 Collector<T, ?, LongSummaryStatistics> summarizingLong(ToLongFunction<? super T> mapper) {
1681 return new CollectorImpl<T, LongSummaryStatistics, LongSummaryStatistics>(
1682 LongSummaryStatistics::new,
1683 (r, t) -> r.accept(mapper.applyAsLong(t)),
1684 (l, r) -> { l.combine(r); return l; }, CH_ID);
1685 }
1686
1687 /**
1688 * Returns a {@code Collector} which applies an {@code double}-producing
1689 * mapping function to each input element, and returns summary statistics
1690 * for the resulting values.
1691 *
1692 * @param <T> the type of the input elements
1693 * @param mapper a mapping function to apply to each element
1694 * @return a {@code Collector} implementing the summary-statistics reduction
1695 *
1696 * @see #summarizingLong(ToLongFunction)
1697 * @see #summarizingInt(ToIntFunction)
1698 */
1699 public static <T>
1700 Collector<T, ?, DoubleSummaryStatistics> summarizingDouble(ToDoubleFunction<? super T> mapper) {
1701 return new CollectorImpl<T, DoubleSummaryStatistics, DoubleSummaryStatistics>(
1702 DoubleSummaryStatistics::new,
1703 (r, t) -> r.accept(mapper.applyAsDouble(t)),
1704 (l, r) -> { l.combine(r); return l; }, CH_ID);
1705 }
1706
1707 /**
1708 * Implementation class used by partitioningBy.
1709 */
1710 private static final class Partition<T>
1711 extends AbstractMap<Boolean, T>
1712 implements Map<Boolean, T> {
1713 final T forTrue;
1714 final T forFalse;
1715
1716 Partition(T forTrue, T forFalse) {
1717 this.forTrue = forTrue;
1718 this.forFalse = forFalse;
1719 }
1720
1721 @Override
1722 public Set<Map.Entry<Boolean, T>> entrySet() {
1723 return new AbstractSet<Map.Entry<Boolean, T>>() {
1724 @Override
1725 public Iterator<Map.Entry<Boolean, T>> iterator() {
1726 Map.Entry<Boolean, T> falseEntry = new SimpleImmutableEntry<>(false, forFalse);
1727 Map.Entry<Boolean, T> trueEntry = new SimpleImmutableEntry<>(true, forTrue);
1728 return Arrays.asList(falseEntry, trueEntry).iterator();
1729 }
1730
1731 @Override
1732 public int size() {
1733 return 2;
1734 }
1735 };
1736 }
1737 }
1738 }