1 /*
2 * Copyright (c) 2012, 2013, 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.Collection;
31 import java.util.Collections;
32 import java.util.Comparator;
33 import java.util.DoubleSummaryStatistics;
34 import java.util.EnumSet;
35 import java.util.HashMap;
36 import java.util.HashSet;
37 import java.util.IntSummaryStatistics;
38 import java.util.Iterator;
39 import java.util.List;
40 import java.util.LongSummaryStatistics;
41 import java.util.Map;
42 import java.util.NoSuchElementException;
43 import java.util.Objects;
44 import java.util.Set;
45 import java.util.StringJoiner;
46 import java.util.concurrent.ConcurrentHashMap;
47 import java.util.concurrent.ConcurrentMap;
48 import java.util.function.BiFunction;
49 import java.util.function.BinaryOperator;
50 import java.util.function.Function;
51 import java.util.function.Predicate;
52 import java.util.function.Supplier;
53 import java.util.function.ToDoubleFunction;
54 import java.util.function.ToIntFunction;
55 import java.util.function.ToLongFunction;
56
57 /**
58 * Implementations of {@link Collector} that implement various useful reduction
59 * operations, such as accumulating elements into collections, summarizing
60 * elements according to various criteria, etc.
61 *
62 * <p>The following are examples of using the predefined {@code Collector}
63 * implementations in {@link Collectors} with the {@code Stream} API to perform
64 * mutable reduction tasks:
65 *
66 * <pre>{@code
67 * // Accumulate elements into a List
68 * List<Person> list = people.collect(Collectors.toList());
69 *
70 * // Accumulate elements into a TreeSet
71 * List<Person> list = people.collect(Collectors.toCollection(TreeSet::new));
72 *
73 * // Convert elements to strings and concatenate them, separated by commas
74 * String joined = stream.map(Object::toString)
75 * .collect(Collectors.toStringJoiner(", "))
76 * .toString();
77 *
78 * // Find highest-paid employee
79 * Employee highestPaid = employees.stream()
80 * .collect(Collectors.maxBy(Comparator.comparing(Employee::getSalary)));
81 *
82 * // Group employees by department
83 * Map<Department, List<Employee>> byDept
84 * = employees.stream()
85 * .collect(Collectors.groupingBy(Employee::getDepartment));
86 *
87 * // Find highest-paid employee by department
88 * Map<Department, Employee> highestPaidByDept
89 * = employees.stream()
90 * .collect(Collectors.groupingBy(Employee::getDepartment,
91 * Collectors.maxBy(Comparator.comparing(Employee::getSalary))));
92 *
93 * // Partition students into passing and failing
94 * Map<Boolean, List<Student>> passingFailing =
95 * students.stream()
96 * .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD);
97 *
98 * }</pre>
99 *
100 * TODO explanation of parallel collection
101 *
102 * @since 1.8
103 */
104 public final class Collectors {
105
106 private static final Set<Collector.Characteristics> CH_CONCURRENT
107 = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.CONCURRENT,
108 Collector.Characteristics.STRICTLY_MUTATIVE,
109 Collector.Characteristics.UNORDERED));
110 private static final Set<Collector.Characteristics> CH_STRICT
111 = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.STRICTLY_MUTATIVE));
112 private static final Set<Collector.Characteristics> CH_STRICT_UNORDERED
113 = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.STRICTLY_MUTATIVE,
114 Collector.Characteristics.UNORDERED));
115
116 private Collectors() { }
117
118 /**
119 * Returns a merge function, suitable for use in
120 * {@link Map#merge(Object, Object, BiFunction) Map.merge()} or
121 * {@link #toMap(Function, Function, BinaryOperator) toMap()}, which always
122 * throws {@code IllegalStateException}. This can be used to enforce the
123 * assumption that the elements being collected are distinct.
124 *
125 * @param <T> the type of input arguments to the merge function
126 * @return a merge function which always throw {@code IllegalStateException}
127 *
128 * @see #firstWinsMerger()
129 * @see #lastWinsMerger()
130 */
131 public static <T> BinaryOperator<T> throwingMerger() {
132 return (u,v) -> { throw new IllegalStateException(String.format("Duplicate key %s", u)); };
133 }
134
135 /**
136 * Returns a merge function, suitable for use in
137 * {@link Map#merge(Object, Object, BiFunction) Map.merge()} or
138 * {@link #toMap(Function, Function, BinaryOperator) toMap()},
139 * which implements a "first wins" policy.
140 *
141 * @param <T> the type of input arguments to the merge function
142 * @return a merge function which always returns its first argument
143 * @see #lastWinsMerger()
144 * @see #throwingMerger()
145 */
146 public static <T> BinaryOperator<T> firstWinsMerger() {
147 return (u,v) -> u;
148 }
149
150 /**
151 * Returns a merge function, suitable for use in
152 * {@link Map#merge(Object, Object, BiFunction) Map.merge()} or
153 * {@link #toMap(Function, Function, BinaryOperator) toMap()},
154 * which implements a "last wins" policy.
155 *
156 * @param <T> the type of input arguments to the merge function
157 * @return a merge function which always returns its second argument
158 * @see #firstWinsMerger()
159 * @see #throwingMerger()
160 */
161 public static <T> BinaryOperator<T> lastWinsMerger() {
162 return (u,v) -> v;
163 }
164
165 /**
166 * Simple implementation class for {@code Collector}.
167 *
168 * @param <T> the type of elements to be collected
169 * @param <R> the type of the result
170 */
171 private static final class CollectorImpl<T, R> implements Collector<T,R> {
172 private final Supplier<R> resultSupplier;
173 private final BiFunction<R, T, R> accumulator;
174 private final BinaryOperator<R> combiner;
175 private final Set<Characteristics> characteristics;
176
177 CollectorImpl(Supplier<R> resultSupplier,
178 BiFunction<R, T, R> accumulator,
179 BinaryOperator<R> combiner,
180 Set<Characteristics> characteristics) {
181 this.resultSupplier = resultSupplier;
182 this.accumulator = accumulator;
183 this.combiner = combiner;
184 this.characteristics = characteristics;
185 }
186
187 CollectorImpl(Supplier<R> resultSupplier,
188 BiFunction<R, T, R> accumulator,
189 BinaryOperator<R> combiner) {
190 this(resultSupplier, accumulator, combiner, Collections.emptySet());
191 }
192
193 @Override
194 public BiFunction<R, T, R> accumulator() {
195 return accumulator;
196 }
197
198 @Override
199 public Supplier<R> resultSupplier() {
200 return resultSupplier;
201 }
202
203 @Override
204 public BinaryOperator<R> combiner() {
205 return combiner;
206 }
207
208 @Override
209 public Set<Characteristics> characteristics() {
210 return characteristics;
211 }
212 }
213
214 /**
215 * Returns a {@code Collector} that accumulates the input elements into a
216 * new {@code Collection}, in encounter order. The {@code Collection} is
217 * created by the provided factory.
218 *
219 * @param <T> the type of the input elements
220 * @param <C> the type of the resulting {@code Collection}
221 * @param collectionFactory a {@code Supplier} which returns a new, empty
222 * {@code Collection} of the appropriate type
223 * @return a {@code Collector} which collects all the input elements into a
224 * {@code Collection}, in encounter order
225 */
226 public static <T, C extends Collection<T>>
227 Collector<T, C> toCollection(Supplier<C> collectionFactory) {
228 return new CollectorImpl<>(collectionFactory,
229 (r, t) -> { r.add(t); return r; },
230 (r1, r2) -> { r1.addAll(r2); return r1; },
231 CH_STRICT);
232 }
233
234 /**
235 * Returns a {@code Collector} that accumulates the input elements into a
236 * new {@code List}. There are no guarantees on the type, mutability,
237 * serializability, or thread-safety of the {@code List} returned.
238 *
239 * @param <T> the type of the input elements
240 * @return a {@code Collector} which collects all the input elements into a
241 * {@code List}, in encounter order
242 */
243 public static <T>
244 Collector<T, List<T>> toList() {
245 BiFunction<List<T>, T, List<T>> accumulator = (list, t) -> {
246 switch (list.size()) {
247 case 0:
248 return Collections.singletonList(t);
249 case 1:
250 List<T> newList = new ArrayList<>();
251 newList.add(list.get(0));
252 newList.add(t);
253 return newList;
254 default:
255 list.add(t);
256 return list;
257 }
258 };
259 BinaryOperator<List<T>> combiner = (left, right) -> {
260 switch (left.size()) {
261 case 0:
262 return right;
263 case 1:
264 List<T> newList = new ArrayList<>(left.size() + right.size());
265 newList.addAll(left);
266 newList.addAll(right);
267 return newList;
268 default:
269 left.addAll(right);
270 return left;
271 }
272 };
273 return new CollectorImpl<>(Collections::emptyList, accumulator, combiner);
274 }
275
276 /**
277 * Returns a {@code Collector} that accumulates the input elements into a
278 * new {@code Set}. There are no guarantees on the type, mutability,
279 * serializability, or thread-safety of the {@code Set} returned.
280 *
281 * <p>This is an {@link Collector.Characteristics#UNORDERED unordered}
282 * Collector.
283 *
284 * @param <T> the type of the input elements
285 * @return a {@code Collector} which collects all the input elements into a
286 * {@code Set}
287 */
288 public static <T>
289 Collector<T, Set<T>> toSet() {
290 return new CollectorImpl<>((Supplier<Set<T>>) HashSet::new,
291 (r, t) -> { r.add(t); return r; },
292 (r1, r2) -> { r1.addAll(r2); return r1; },
293 CH_STRICT_UNORDERED);
294 }
295
296 /**
297 * Returns a {@code Collector} that concatenates the input elements into a
298 * new {@link StringBuilder}.
299 *
300 * @return a {@code Collector} which collects String elements into a
301 * {@code StringBuilder}, in encounter order
302 */
303 public static Collector<String, StringBuilder> toStringBuilder() {
304 return new CollectorImpl<>(StringBuilder::new,
305 (r, t) -> { r.append(t); return r; },
306 (r1, r2) -> { r1.append(r2); return r1; },
307 CH_STRICT);
308 }
309
310 /**
311 * Returns a {@code Collector} that concatenates the input elements into a
312 * new {@link StringJoiner}, using the specified delimiter.
313 *
314 * @param delimiter the delimiter to be used between each element
315 * @return A {@code Collector} which collects String elements into a
316 * {@code StringJoiner}, in encounter order
317 */
318 public static Collector<CharSequence, StringJoiner> toStringJoiner(CharSequence delimiter) {
319 BinaryOperator<StringJoiner> merger = (sj, other) -> {
320 if (other.length() > 0)
321 sj.add(other.toString());
322 return sj;
323 };
324 return new CollectorImpl<>(() -> new StringJoiner(delimiter),
325 (r, t) -> { r.add(t); return r; },
326 merger, CH_STRICT);
327 }
328
329 /**
330 * {@code BinaryOperator<Map>} that merges the contents of its right
331 * argument into its left argument, using the provided merge function to
332 * handle duplicate keys.
333 *
334 * @param <K> type of the map keys
335 * @param <V> type of the map values
336 * @param <M> type of the map
337 * @param mergeFunction A merge function suitable for
338 * {@link Map#merge(Object, Object, BiFunction) Map.merge()}
339 * @return a merge function for two maps
340 */
341 private static <K, V, M extends Map<K,V>>
342 BinaryOperator<M> mapMerger(BinaryOperator<V> mergeFunction) {
343 return (m1, m2) -> {
344 for (Map.Entry<K,V> e : m2.entrySet())
345 m1.merge(e.getKey(), e.getValue(), mergeFunction);
346 return m1;
347 };
348 }
349
350 /**
351 * Adapts a {@code Collector<U,R>} to a {@code Collector<T,R>} by applying
352 * a mapping function to each input element before accumulation.
353 *
354 * @apiNote
355 * The {@code mapping()} collectors are most useful when used in a
356 * multi-level reduction, downstream of {@code groupingBy} or
357 * {@code partitioningBy}. For example, given a stream of
358 * {@code Person}, to accumulate the set of last names in each city:
359 * <pre>{@code
360 * Map<City, Set<String>> lastNamesByCity
361 * = people.stream().collect(groupingBy(Person::getCity,
362 * mapping(Person::getLastName, toSet())));
363 * }</pre>
364 *
365 * @param <T> the type of the input elements
366 * @param <U> type of elements accepted by downstream collector
367 * @param <R> result type of collector
368 * @param mapper a function to be applied to the input elements
369 * @param downstream a collector which will accept mapped values
370 * @return a collector which applies the mapping function to the input
371 * elements and provides the mapped results to the downstream collector
372 */
373 public static <T, U, R> Collector<T, R>
374 mapping(Function<? super T, ? extends U> mapper, Collector<? super U, R> downstream) {
375 BiFunction<R, ? super U, R> downstreamAccumulator = downstream.accumulator();
376 return new CollectorImpl<>(downstream.resultSupplier(),
377 (r, t) -> downstreamAccumulator.apply(r, mapper.apply(t)),
378 downstream.combiner(), downstream.characteristics());
379 }
380
381 /**
382 * Returns a {@code Collector<T, Long>} that counts the number of input
383 * elements.
384 *
385 * @implSpec
386 * This produces a result equivalent to:
387 * <pre>{@code
388 * reducing(0L, e -> 1L, Long::sum)
389 * }</pre>
390 *
391 * @param <T> the type of the input elements
392 * @return a {@code Collector} that counts the input elements
393 */
394 public static <T> Collector<T, Long>
395 counting() {
396 return reducing(0L, e -> 1L, Long::sum);
397 }
398
399 /**
400 * Returns a {@code Collector<T, T>} that produces the minimal element
401 * according to a given {@code Comparator}.
402 *
403 * @implSpec
404 * This produces a result equivalent to:
405 * <pre>{@code
406 * reducing(BinaryOperator.minBy(comparator))
407 * }</pre>
408 *
409 * @param <T> the type of the input elements
410 * @param comparator a {@code Comparator} for comparing elements
411 * @return a {@code Collector} that produces the minimal value
412 */
413 public static <T> Collector<T, T>
414 minBy(Comparator<? super T> comparator) {
415 return reducing(BinaryOperator.minBy(comparator));
416 }
417
418 /**
419 * Returns a {@code Collector<T, T>} that produces the maximal element
420 * according to a given {@code Comparator}.
421 *
422 * @implSpec
423 * This produces a result equivalent to:
424 * <pre>{@code
425 * reducing(BinaryOperator.maxBy(comparator))
426 * }</pre>
427 *
428 * @param <T> the type of the input elements
429 * @param comparator a {@code Comparator} for comparing elements
430 * @return a {@code Collector} that produces the maximal value
431 */
432 public static <T> Collector<T, T>
433 maxBy(Comparator<? super T> comparator) {
434 return reducing(BinaryOperator.maxBy(comparator));
435 }
436
437 /**
438 * Returns a {@code Collector<T, Long>} that produces the sum of a
439 * long-valued function applied to the input element.
440 *
441 * @implSpec
442 * This produces a result equivalent to:
443 * <pre>{@code
444 * reducing(0L, mapper, Long::sum)
445 * }</pre>
446 *
447 * @param <T> the type of the input elements
448 * @param mapper a function extracting the property to be summed
449 * @return a {@code Collector} that produces the sum of a derived property
450 */
451 public static <T> Collector<T, Long>
452 sumBy(Function<? super T, Long> mapper) {
453 return reducing(0L, mapper, Long::sum);
454 }
455
456 /**
457 * Returns a {@code Collector<T,T>} which performs a reduction of its
458 * input elements under a specified {@code BinaryOperator}.
459 *
460 * @apiNote
461 * The {@code reducing()} collectors are most useful when used in a
462 * multi-level reduction, downstream of {@code groupingBy} or
463 * {@code partitioningBy}. To perform a simple reduction on a stream,
464 * use {@link Stream#reduce(BinaryOperator)} instead.
465 *
466 * @param <T> element type for the input and output of the reduction
467 * @param identity the identity value for the reduction (also, the value
468 * that is returned when there are no input elements)
469 * @param op a {@code BinaryOperator<T>} used to reduce the input elements
470 * @return a {@code Collector} which implements the reduction operation
471 *
472 * @see #reducing(BinaryOperator)
473 * @see #reducing(Object, Function, BinaryOperator)
474 */
475 public static <T> Collector<T, T>
476 reducing(T identity, BinaryOperator<T> op) {
477 return new CollectorImpl<>(() -> identity, (r, t) -> (r == null ? t : op.apply(r, t)), op);
478 }
479
480 /**
481 * Returns a {@code Collector<T,T>} which performs a reduction of its
482 * input elements under a specified {@code BinaryOperator}.
483 *
484 * @apiNote
485 * The {@code reducing()} collectors are most useful when used in a
486 * multi-level reduction, downstream of {@code groupingBy} or
487 * {@code partitioningBy}. To perform a simple reduction on a stream,
488 * use {@link Stream#reduce(BinaryOperator)} instead.
489 *
490 * <p>For example, given a stream of {@code Person}, to calculate tallest
491 * person in each city:
492 * <pre>{@code
493 * Comparator<Person> byHeight = Comparator.comparing(Person::getHeight);
494 * BinaryOperator<Person> tallerOf = BinaryOperator.greaterOf(byHeight);
495 * Map<City, Person> tallestByCity
496 * = people.stream().collect(groupingBy(Person::getCity, reducing(tallerOf)));
497 * }</pre>
498 *
499 * @implSpec
500 * The default implementation is equivalent to:
501 * <pre>{@code
502 * reducing(null, op);
503 * }</pre>
504 *
505 * @param <T> element type for the input and output of the reduction
506 * @param op a {@code BinaryOperator<T>} used to reduce the input elements
507 * @return a {@code Collector} which implements the reduction operation
508 *
509 * @see #reducing(Object, BinaryOperator)
510 * @see #reducing(Object, Function, BinaryOperator)
511 */
512 public static <T> Collector<T, T>
513 reducing(BinaryOperator<T> op) {
514 return reducing(null, op);
515 }
516
517 /**
518 * Returns a {@code Collector<T,U>} which performs a reduction of its
519 * input elements under a specified mapping function and
520 * {@code BinaryOperator}. This is a generalization of
521 * {@link #reducing(Object, BinaryOperator)} which allows a transformation
522 * of the elements before reduction.
523 *
524 * @apiNote
525 * The {@code reducing()} collectors are most useful when used in a
526 * multi-level reduction, downstream of {@code groupingBy} or
527 * {@code partitioningBy}. To perform a simple reduction on a stream,
528 * use {@link Stream#reduce(BinaryOperator)} instead.
529 *
530 * <p>For example, given a stream of {@code Person}, to calculate the longest
531 * last name of residents in each city:
532 * <pre>{@code
533 * Comparator<String> byLength = Comparator.comparing(String::length);
534 * BinaryOperator<String> longerOf = BinaryOperator.greaterOf(byLength);
535 * Map<City, String> longestLastNameByCity
536 * = people.stream().collect(groupingBy(Person::getCity,
537 * reducing(Person::getLastName, longerOf)));
538 * }</pre>
539 *
540 * @param <T> the type of the input elements
541 * @param <U> the type of the mapped values
542 * @param identity the identity value for the reduction (also, the value
543 * that is returned when there are no input elements)
544 * @param mapper a mapping function to apply to each input value
545 * @param op a {@code BinaryOperator<U>} used to reduce the mapped values
546 * @return a {@code Collector} implementing the map-reduce operation
547 *
548 * @see #reducing(Object, BinaryOperator)
549 * @see #reducing(BinaryOperator)
550 */
551 public static <T, U>
552 Collector<T, U> reducing(U identity,
553 Function<? super T, ? extends U> mapper,
554 BinaryOperator<U> op) {
555 return new CollectorImpl<>(() -> identity,
556 (r, t) -> (r == null ? mapper.apply(t) : op.apply(r, mapper.apply(t))),
557 op);
558 }
559
560 /**
561 * Returns a {@code Collector} implementing a "group by" operation on
562 * input elements of type {@code T}, grouping elements according to a
563 * classification function.
564 *
565 * <p>The classification function maps elements to some key type {@code K}.
566 * The collector produces a {@code Map<K, List<T>>} whose keys are the
567 * values resulting from applying the classification function to the input
568 * elements, and whose corresponding values are {@code List}s containing the
569 * input elements which map to the associated key under the classification
570 * function.
571 *
572 * <p>There are no guarantees on the type, mutability, serializability, or
573 * thread-safety of the {@code Map} or {@code List} objects returned.
574 * @implSpec
575 * This produces a result similar to:
576 * <pre>{@code
577 * groupingBy(classifier, toList());
578 * }</pre>
579 *
580 * @param <T> the type of the input elements
581 * @param <K> the type of the keys
582 * @param classifier the classifier function mapping input elements to keys
583 * @return a {@code Collector} implementing the group-by operation
584 *
585 * @see #groupingBy(Function, Collector)
586 * @see #groupingBy(Function, Supplier, Collector)
587 * @see #groupingByConcurrent(Function)
588 */
589 public static <T, K>
590 Collector<T, Map<K, List<T>>> groupingBy(Function<? super T, ? extends K> classifier) {
591 return groupingBy(classifier, HashMap::new, toList());
592 }
593
594 /**
595 * Returns a {@code Collector} implementing a cascaded "group by" operation
596 * on input elements of type {@code T}, grouping elements according to a
597 * classification function, and then performing a reduction operation on
598 * the values associated with a given key using the specified downstream
599 * {@code Collector}.
600 *
601 * <p>The classification function maps elements to some key type {@code K}.
602 * The downstream collector operates on elements of type {@code T} and
603 * produces a result of type {@code D}. The resulting collector produces a
604 * {@code Map<K, D>}.
605 *
606 * <p>There are no guarantees on the type, mutability,
607 * serializability, or thread-safety of the {@code Map} returned.
608 *
609 * <p>For example, to compute the set of last names of people in each city:
610 * <pre>{@code
611 * Map<City, Set<String>> namesByCity
612 * = people.stream().collect(groupingBy(Person::getCity,
613 * mapping(Person::getLastName, toSet())));
614 * }</pre>
615 *
616 * @param <T> the type of the input elements
617 * @param <K> the type of the keys
618 * @param <D> the result type of the downstream reduction
619 * @param classifier a classifier function mapping input elements to keys
620 * @param downstream a {@code Collector} implementing the downstream reduction
621 * @return a {@code Collector} implementing the cascaded group-by operation
622 * @see #groupingBy(Function)
623 *
624 * @see #groupingBy(Function, Supplier, Collector)
625 * @see #groupingByConcurrent(Function, Collector)
626 */
627 public static <T, K, D>
628 Collector<T, Map<K, D>> groupingBy(Function<? super T, ? extends K> classifier,
629 Collector<? super T, D> downstream) {
630 return groupingBy(classifier, HashMap::new, downstream);
631 }
632
633 /**
634 * Returns a {@code Collector} implementing a cascaded "group by" operation
635 * on input elements of type {@code T}, grouping elements according to a
636 * classification function, and then performing a reduction operation on
637 * the values associated with a given key using the specified downstream
638 * {@code Collector}. The {@code Map} produced by the Collector is created
639 * with the supplied factory function.
640 *
641 * <p>The classification function maps elements to some key type {@code K}.
642 * The downstream collector operates on elements of type {@code T} and
643 * produces a result of type {@code D}. The resulting collector produces a
644 * {@code Map<K, D>}.
645 *
646 * <p>For example, to compute the set of last names of people in each city,
647 * where the city names are sorted:
648 * <pre>{@code
649 * Map<City, Set<String>> namesByCity
650 * = people.stream().collect(groupingBy(Person::getCity, TreeMap::new,
651 * mapping(Person::getLastName, toSet())));
652 * }</pre>
653 *
654 * @param <T> the type of the input elements
655 * @param <K> the type of the keys
656 * @param <D> the result type of the downstream reduction
657 * @param <M> the type of the resulting {@code Map}
658 * @param classifier a classifier function mapping input elements to keys
659 * @param downstream a {@code Collector} implementing the downstream reduction
660 * @param mapFactory a function which, when called, produces a new empty
661 * {@code Map} of the desired type
662 * @return a {@code Collector} implementing the cascaded group-by operation
663 *
664 * @see #groupingBy(Function, Collector)
665 * @see #groupingBy(Function)
666 * @see #groupingByConcurrent(Function, Supplier, Collector)
667 */
668 public static <T, K, D, M extends Map<K, D>>
669 Collector<T, M> groupingBy(Function<? super T, ? extends K> classifier,
670 Supplier<M> mapFactory,
671 Collector<? super T, D> downstream) {
672 Supplier<D> downstreamSupplier = downstream.resultSupplier();
673 BiFunction<D, ? super T, D> downstreamAccumulator = downstream.accumulator();
674 BiFunction<M, T, M> accumulator = (m, t) -> {
675 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
676 D oldContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
677 D newContainer = downstreamAccumulator.apply(oldContainer, t);
678 if (newContainer != oldContainer)
679 m.put(key, newContainer);
680 return m;
681 };
682 return new CollectorImpl<>(mapFactory, accumulator, mapMerger(downstream.combiner()), CH_STRICT);
683 }
684
685 /**
686 * Returns a {@code Collector} implementing a concurrent "group by"
687 * operation on input elements of type {@code T}, grouping elements
688 * according to a classification function.
689 *
690 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
691 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
692 *
693 * <p>The classification function maps elements to some key type {@code K}.
694 * The collector produces a {@code ConcurrentMap<K, List<T>>} whose keys are the
695 * values resulting from applying the classification function to the input
696 * elements, and whose corresponding values are {@code List}s containing the
697 * input elements which map to the associated key under the classification
698 * function.
699 *
700 * <p>There are no guarantees on the type, mutability, or serializability
701 * of the {@code Map} or {@code List} objects returned, or of the
702 * thread-safety of the {@code List} objects returned.
703 * @implSpec
704 * This produces a result similar to:
705 * <pre>{@code
706 * groupingByConcurrent(classifier, toList());
707 * }</pre>
708 *
709 * @param <T> the type of the input elements
710 * @param <K> the type of the keys
711 * @param classifier a classifier function mapping input elements to keys
712 * @return a {@code Collector} implementing the group-by operation
713 *
714 * @see #groupingBy(Function)
715 * @see #groupingByConcurrent(Function, Collector)
716 * @see #groupingByConcurrent(Function, Supplier, Collector)
717 */
718 public static <T, K>
719 Collector<T, ConcurrentMap<K, List<T>>> groupingByConcurrent(Function<? super T, ? extends K> classifier) {
720 return groupingByConcurrent(classifier, ConcurrentHashMap::new, toList());
721 }
722
723 /**
724 * Returns a {@code Collector} implementing a concurrent cascaded "group by"
725 * operation on input elements of type {@code T}, grouping elements
726 * according to a classification function, and then performing a reduction
727 * operation on the values associated with a given key using the specified
728 * downstream {@code Collector}.
729 *
730 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
731 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
732 *
733 * <p>The classification function maps elements to some key type {@code K}.
734 * The downstream collector operates on elements of type {@code T} and
735 * produces a result of type {@code D}. The resulting collector produces a
736 * {@code Map<K, D>}.
737 *
738 * <p>For example, to compute the set of last names of people in each city,
739 * where the city names are sorted:
740 * <pre>{@code
741 * ConcurrentMap<City, Set<String>> namesByCity
742 * = people.stream().collect(groupingByConcurrent(Person::getCity, TreeMap::new,
743 * mapping(Person::getLastName, toSet())));
744 * }</pre>
745 *
746 * @param <T> the type of the input elements
747 * @param <K> the type of the keys
748 * @param <D> the result type of the downstream reduction
749 * @param classifier a classifier function mapping input elements to keys
750 * @param downstream a {@code Collector} implementing the downstream reduction
751 * @return a {@code Collector} implementing the cascaded group-by operation
752 *
753 * @see #groupingBy(Function, Collector)
754 * @see #groupingByConcurrent(Function)
755 * @see #groupingByConcurrent(Function, Supplier, Collector)
756 */
757 public static <T, K, D>
758 Collector<T, ConcurrentMap<K, D>> groupingByConcurrent(Function<? super T, ? extends K> classifier,
759 Collector<? super T, D> downstream) {
760 return groupingByConcurrent(classifier, ConcurrentHashMap::new, downstream);
761 }
762
763 /**
764 * Returns a concurrent {@code Collector} implementing a cascaded "group by"
765 * operation on input elements of type {@code T}, grouping elements
766 * according to a classification function, and then performing a reduction
767 * operation on the values associated with a given key using the specified
768 * downstream {@code Collector}. The {@code ConcurrentMap} produced by the
769 * Collector is created with the supplied factory function.
770 *
771 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
772 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
773 *
774 * <p>The classification function maps elements to some key type {@code K}.
775 * The downstream collector operates on elements of type {@code T} and
776 * produces a result of type {@code D}. The resulting collector produces a
777 * {@code Map<K, D>}.
778 *
779 * <p>For example, to compute the set of last names of people in each city,
780 * where the city names are sorted:
781 * <pre>{@code
782 * ConcurrentMap<City, Set<String>> namesByCity
783 * = people.stream().collect(groupingBy(Person::getCity, ConcurrentSkipListMap::new,
784 * mapping(Person::getLastName, toSet())));
785 * }</pre>
786 *
787 *
788 * @param <T> the type of the input elements
789 * @param <K> the type of the keys
790 * @param <D> the result type of the downstream reduction
791 * @param <M> the type of the resulting {@code ConcurrentMap}
792 * @param classifier a classifier function mapping input elements to keys
793 * @param downstream a {@code Collector} implementing the downstream reduction
794 * @param mapFactory a function which, when called, produces a new empty
795 * {@code ConcurrentMap} of the desired type
796 * @return a {@code Collector} implementing the cascaded group-by operation
797 *
798 * @see #groupingByConcurrent(Function)
799 * @see #groupingByConcurrent(Function, Collector)
800 * @see #groupingBy(Function, Supplier, Collector)
801 */
802 public static <T, K, D, M extends ConcurrentMap<K, D>>
803 Collector<T, M> groupingByConcurrent(Function<? super T, ? extends K> classifier,
804 Supplier<M> mapFactory,
805 Collector<? super T, D> downstream) {
806 Supplier<D> downstreamSupplier = downstream.resultSupplier();
807 BiFunction<D, ? super T, D> downstreamAccumulator = downstream.accumulator();
808 BinaryOperator<M> combiner = mapMerger(downstream.combiner());
809 if (downstream.characteristics().contains(Collector.Characteristics.CONCURRENT)) {
810 BiFunction<M, T, M> accumulator = (m, t) -> {
811 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
812 downstreamAccumulator.apply(m.computeIfAbsent(key, k -> downstreamSupplier.get()), t);
813 return m;
814 };
815 return new CollectorImpl<>(mapFactory, accumulator, combiner, CH_CONCURRENT);
816 } else if (downstream.characteristics().contains(Collector.Characteristics.STRICTLY_MUTATIVE)) {
817 BiFunction<M, T, M> accumulator = (m, t) -> {
818 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
819 D resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
820 synchronized (resultContainer) {
821 downstreamAccumulator.apply(resultContainer, t);
822 }
823 return m;
824 };
825 return new CollectorImpl<>(mapFactory, accumulator, combiner, CH_CONCURRENT);
826 } else {
827 BiFunction<M, T, M> accumulator = (m, t) -> {
828 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
829 do {
830 D oldResult = m.computeIfAbsent(key, k -> downstreamSupplier.get());
831 if (oldResult == null) {
832 if (m.putIfAbsent(key, downstreamAccumulator.apply(null, t)) == null)
833 return m;
834 } else {
835 synchronized (oldResult) {
836 if (m.get(key) != oldResult)
837 continue;
838 D newResult = downstreamAccumulator.apply(oldResult, t);
839 if (oldResult != newResult)
840 m.put(key, newResult);
841 return m;
842 }
843 }
844 } while (true);
845 };
846 return new CollectorImpl<>(mapFactory, accumulator, combiner, CH_CONCURRENT);
847 }
848 }
849
850 /**
851 * Returns a {@code Collector} which partitions the input elements according
852 * to a {@code Predicate}, and organizes them into a
853 * {@code Map<Boolean, List<T>>}.
854 *
855 * There are no guarantees on the type, mutability,
856 * serializability, or thread-safety of the {@code Map} returned.
857 *
858 * @param <T> the type of the input elements
859 * @param predicate a predicate used for classifying input elements
860 * @return a {@code Collector} implementing the partitioning operation
861 *
862 * @see #partitioningBy(Predicate, Collector)
863 */
864 public static <T>
865 Collector<T, Map<Boolean, List<T>>> partitioningBy(Predicate<? super T> predicate) {
866 return partitioningBy(predicate, toList());
867 }
868
869 /**
870 * Returns a {@code Collector} which partitions the input elements according
871 * to a {@code Predicate}, reduces the values in each partition according to
872 * another {@code Collector}, and organizes them into a
873 * {@code Map<Boolean, D>} whose values are the result of the downstream
874 * reduction.
875 *
876 * <p>There are no guarantees on the type, mutability,
877 * serializability, or thread-safety of the {@code Map} returned.
878 *
879 * @param <T> the type of the input elements
880 * @param <D> the result type of the downstream reduction
881 * @param predicate a predicate used for classifying input elements
882 * @param downstream a {@code Collector} implementing the downstream
883 * reduction
884 * @return a {@code Collector} implementing the cascaded partitioning
885 * operation
886 *
887 * @see #partitioningBy(Predicate)
888 */
889 public static <T, D>
890 Collector<T, Map<Boolean, D>> partitioningBy(Predicate<? super T> predicate,
891 Collector<? super T, D> downstream) {
892 BiFunction<D, ? super T, D> downstreamAccumulator = downstream.accumulator();
893 BiFunction<Map<Boolean, D>, T, Map<Boolean, D>> accumulator = (result, t) -> {
894 Partition<D> asPartition = ((Partition<D>) result);
895 if (predicate.test(t)) {
896 D newResult = downstreamAccumulator.apply(asPartition.forTrue, t);
897 if (newResult != asPartition.forTrue)
898 asPartition.forTrue = newResult;
899 } else {
900 D newResult = downstreamAccumulator.apply(asPartition.forFalse, t);
901 if (newResult != asPartition.forFalse)
902 asPartition.forFalse = newResult;
903 }
904 return result;
905 };
906 return new CollectorImpl<>(() -> new Partition<>(downstream.resultSupplier().get(),
907 downstream.resultSupplier().get()),
908 accumulator, partitionMerger(downstream.combiner()), CH_STRICT);
909 }
910
911 /**
912 * Merge function for two partitions, given a merge function for the
913 * elements.
914 */
915 private static <D> BinaryOperator<Map<Boolean, D>> partitionMerger(BinaryOperator<D> op) {
916 return (m1, m2) -> {
917 Partition<D> left = (Partition<D>) m1;
918 Partition<D> right = (Partition<D>) m2;
919 if (left.forFalse == null)
920 left.forFalse = right.forFalse;
921 else if (right.forFalse != null)
922 left.forFalse = op.apply(left.forFalse, right.forFalse);
923 if (left.forTrue == null)
924 left.forTrue = right.forTrue;
925 else if (right.forTrue != null)
926 left.forTrue = op.apply(left.forTrue, right.forTrue);
927 return left;
928 };
929 }
930
931 /**
932 * Accumulate elements into a {@code Map} whose keys and values are the
933 * result of applying mapping functions to the input elements.
934 * If the mapped keys contains duplicates (according to
935 * {@link Object#equals(Object)}), an {@code IllegalStateException} is
936 * thrown when the collection operation is performed. If the mapped keys
937 * may have duplicates, use {@link #toMap(Function, Function, BinaryOperator)}
938 * instead.
939 *
940 * @apiNote
941 * It is common for either the key or the value to be the input elements.
942 * In this case, the utility method
943 * {@link java.util.function.Function#identity()} may be helpful.
944 * For example, the following produces a {@code Map} mapping
945 * students to their grade point average:
946 * <pre>{@code
947 * Map<Student, Double> studentToGPA
948 * students.stream().collect(toMap(Functions.identity(),
949 * student -> computeGPA(student)));
950 * }</pre>
951 * And the following produces a {@code Map} mapping a unique identifier to
952 * students:
953 * <pre>{@code
954 * Map<String, Student> studentIdToStudent
955 * students.stream().collect(toMap(Student::getId,
956 * Functions.identity());
957 * }</pre>
958 *
959 * @param <T> the type of the input elements
960 * @param <K> the output type of the key mapping function
961 * @param <U> the output type of the value mapping function
962 * @param keyMapper a mapping function to produce keys
963 * @param valueMapper a mapping function to produce values
964 * @return a {@code Collector} which collects elements into a {@code Map}
965 * whose keys and values are the result of applying mapping functions to
966 * the input elements
967 *
968 * @see #toMap(Function, Function, BinaryOperator)
969 * @see #toMap(Function, Function, BinaryOperator, Supplier)
970 * @see #toConcurrentMap(Function, Function)
971 */
972 public static <T, K, U>
973 Collector<T, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
974 Function<? super T, ? extends U> valueMapper) {
975 return toMap(keyMapper, valueMapper, throwingMerger(), HashMap::new);
976 }
977
978 /**
979 * Accumulate elements into a {@code Map} whose keys and values are the
980 * result of applying mapping functions to the input elements. If the mapped
981 * keys contains duplicates (according to {@link Object#equals(Object)}),
982 * the value mapping function is applied to each equal element, and the
983 * results are merged using the provided merging function.
984 *
985 * @apiNote
986 * There are multiple ways to deal with collisions between multiple elements
987 * mapping to the same key. There are some predefined merging functions,
988 * such as {@link #throwingMerger()}, {@link #firstWinsMerger()}, and
989 * {@link #lastWinsMerger()}, that implement common policies, or you can
990 * implement custom policies easily. For example, if you have a stream
991 * of {@code Person}, and you want to produce a "phone book" mapping name to
992 * address, but it is possible that two persons have the same name, you can
993 * do as follows to gracefully deals with these collisions, and produce a
994 * {@code Map} mapping names to a concatenated list of addresses:
995 * <pre>{@code
996 * Map<String, String> phoneBook
997 * people.stream().collect(toMap(Person::getName,
998 * Person::getAddress,
999 * (s, a) -> s + ", " + a));
1000 * }</pre>
1001 *
1002 * @param <T> the type of the input elements
1003 * @param <K> the output type of the key mapping function
1004 * @param <U> the output type of the value mapping function
1005 * @param keyMapper a mapping function to produce keys
1006 * @param valueMapper a mapping function to produce values
1007 * @param mergeFunction a merge function, used to resolve collisions between
1008 * values associated with the same key, as supplied
1009 * to {@link Map#merge(Object, Object, BiFunction)}
1010 * @return a {@code Collector} which collects elements into a {@code Map}
1011 * whose keys are the result of applying a key mapping function to the input
1012 * elements, and whose values are the result of applying a value mapping
1013 * function to all input elements equal to the key and combining them
1014 * using the merge function
1015 *
1016 * @see #toMap(Function, Function)
1017 * @see #toMap(Function, Function, BinaryOperator, Supplier)
1018 * @see #toConcurrentMap(Function, Function, BinaryOperator)
1019 */
1020 public static <T, K, U>
1021 Collector<T, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
1022 Function<? super T, ? extends U> valueMapper,
1023 BinaryOperator<U> mergeFunction) {
1024 return toMap(keyMapper, valueMapper, mergeFunction, HashMap::new);
1025 }
1026
1027 /**
1028 * Accumulate elements into a {@code Map} whose keys and values are the
1029 * result of applying mapping functions to the input elements. If the mapped
1030 * keys contains duplicates (according to {@link Object#equals(Object)}),
1031 * the value mapping function is applied to each equal element, and the
1032 * results are merged using the provided merging function. The {@code Map}
1033 * is created by a provided supplier function.
1034 *
1035 * @param <T> the type of the input elements
1036 * @param <K> the output type of the key mapping function
1037 * @param <U> the output type of the value mapping function
1038 * @param <M> the type of the resulting {@code Map}
1039 * @param keyMapper a mapping function to produce keys
1040 * @param valueMapper a mapping function to produce values
1041 * @param mergeFunction a merge function, used to resolve collisions between
1042 * values associated with the same key, as supplied
1043 * to {@link Map#merge(Object, Object, BiFunction)}
1044 * @param mapSupplier a function which returns a new, empty {@code Map} into
1045 * which the results will be inserted
1046 * @return a {@code Collector} which collects elements into a {@code Map}
1047 * whose keys are the result of applying a key mapping function to the input
1048 * elements, and whose values are the result of applying a value mapping
1049 * function to all input elements equal to the key and combining them
1050 * using the merge function
1051 *
1052 * @see #toMap(Function, Function)
1053 * @see #toMap(Function, Function, BinaryOperator)
1054 * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1055 */
1056 public static <T, K, U, M extends Map<K, U>>
1057 Collector<T, M> toMap(Function<? super T, ? extends K> keyMapper,
1058 Function<? super T, ? extends U> valueMapper,
1059 BinaryOperator<U> mergeFunction,
1060 Supplier<M> mapSupplier) {
1061 BiFunction<M, T, M> accumulator
1062 = (map, element) -> {
1063 map.merge(keyMapper.apply(element), valueMapper.apply(element), mergeFunction);
1064 return map;
1065 };
1066 return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_STRICT);
1067 }
1068
1069 /**
1070 * Accumulate elements into a {@code ConcurrentMap} whose keys and values
1071 * are the result of applying mapping functions to the input elements.
1072 * If the mapped keys contains duplicates (according to
1073 * {@link Object#equals(Object)}), an {@code IllegalStateException} is
1074 * thrown when the collection operation is performed. If the mapped keys
1075 * may have duplicates, use
1076 * {@link #toConcurrentMap(Function, Function, BinaryOperator)} instead.
1077 *
1078 * @apiNote
1079 * It is common for either the key or the value to be the input elements.
1080 * In this case, the utility method
1081 * {@link java.util.function.Function#identity()} may be helpful.
1082 * For example, the following produces a {@code Map} mapping
1083 * students to their grade point average:
1084 * <pre>{@code
1085 * Map<Student, Double> studentToGPA
1086 * students.stream().collect(toMap(Functions.identity(),
1087 * student -> computeGPA(student)));
1088 * }</pre>
1089 * And the following produces a {@code Map} mapping a unique identifier to
1090 * students:
1091 * <pre>{@code
1092 * Map<String, Student> studentIdToStudent
1093 * students.stream().collect(toConcurrentMap(Student::getId,
1094 * Functions.identity());
1095 * }</pre>
1096 *
1097 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1098 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1099 *
1100 * @param <T> the type of the input elements
1101 * @param <K> the output type of the key mapping function
1102 * @param <U> the output type of the value mapping function
1103 * @param keyMapper the mapping function to produce keys
1104 * @param valueMapper the mapping function to produce values
1105 * @return a concurrent {@code Collector} which collects elements into a
1106 * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1107 * function to the input elements, and whose values are the result of
1108 * applying a value mapping function to the input elements
1109 *
1110 * @see #toMap(Function, Function)
1111 * @see #toConcurrentMap(Function, Function, BinaryOperator)
1112 * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1113 */
1114 public static <T, K, U>
1115 Collector<T, ConcurrentMap<K,U>> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1116 Function<? super T, ? extends U> valueMapper) {
1117 return toConcurrentMap(keyMapper, valueMapper, throwingMerger(), ConcurrentHashMap::new);
1118 }
1119
1120 /**
1121 * Accumulate elements into a {@code ConcurrentMap} whose keys and values
1122 * are the result of applying mapping functions to the input elements. If
1123 * the mapped keys contains duplicates (according to {@link Object#equals(Object)}),
1124 * the value mapping function is applied to each equal element, and the
1125 * results are merged using the provided merging function.
1126 *
1127 * @apiNote
1128 * There are multiple ways to deal with collisions between multiple elements
1129 * mapping to the same key. There are some predefined merging functions,
1130 * such as {@link #throwingMerger()}, {@link #firstWinsMerger()}, and
1131 * {@link #lastWinsMerger()}, that implement common policies, or you can
1132 * implement custom policies easily. For example, if you have a stream
1133 * of {@code Person}, and you want to produce a "phone book" mapping name to
1134 * address, but it is possible that two persons have the same name, you can
1135 * do as follows to gracefully deals with these collisions, and produce a
1136 * {@code Map} mapping names to a concatenated list of addresses:
1137 * <pre>{@code
1138 * Map<String, String> phoneBook
1139 * people.stream().collect(toConcurrentMap(Person::getName,
1140 * Person::getAddress,
1141 * (s, a) -> s + ", " + a));
1142 * }</pre>
1143 *
1144 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1145 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1146 *
1147 * @param <T> the type of the input elements
1148 * @param <K> the output type of the key mapping function
1149 * @param <U> the output type of the value mapping function
1150 * @param keyMapper a mapping function to produce keys
1151 * @param valueMapper a mapping function to produce values
1152 * @param mergeFunction a merge function, used to resolve collisions between
1153 * values associated with the same key, as supplied
1154 * to {@link Map#merge(Object, Object, BiFunction)}
1155 * @return a concurrent {@code Collector} which collects elements into a
1156 * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1157 * function to the input elements, and whose values are the result of
1158 * applying a value mapping function to all input elements equal to the key
1159 * and combining them using the merge function
1160 *
1161 * @see #toConcurrentMap(Function, Function)
1162 * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1163 * @see #toMap(Function, Function, BinaryOperator)
1164 */
1165 public static <T, K, U>
1166 Collector<T, ConcurrentMap<K,U>> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1167 Function<? super T, ? extends U> valueMapper,
1168 BinaryOperator<U> mergeFunction) {
1169 return toConcurrentMap(keyMapper, valueMapper, mergeFunction, ConcurrentHashMap::new);
1170 }
1171
1172 /**
1173 * Accumulate elements into a {@code ConcurrentMap} whose keys and values
1174 * are the result of applying mapping functions to the input elements. If
1175 * the mapped keys contains duplicates (according to {@link Object#equals(Object)}),
1176 * the value mapping function is applied to each equal element, and the
1177 * results are merged using the provided merging function. The
1178 * {@code ConcurrentMap} is created by a provided supplier function.
1179 *
1180 * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1181 * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1182 *
1183 * @param <T> the type of the input elements
1184 * @param <K> the output type of the key mapping function
1185 * @param <U> the output type of the value mapping function
1186 * @param <M> the type of the resulting {@code ConcurrentMap}
1187 * @param keyMapper a mapping function to produce keys
1188 * @param valueMapper a mapping function to produce values
1189 * @param mergeFunction a merge function, used to resolve collisions between
1190 * values associated with the same key, as supplied
1191 * to {@link Map#merge(Object, Object, BiFunction)}
1192 * @param mapSupplier a function which returns a new, empty {@code Map} into
1193 * which the results will be inserted
1194 * @return a concurrent {@code Collector} which collects elements into a
1195 * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1196 * function to the input elements, and whose values are the result of
1197 * applying a value mapping function to all input elements equal to the key
1198 * and combining them using the merge function
1199 *
1200 * @see #toConcurrentMap(Function, Function)
1201 * @see #toConcurrentMap(Function, Function, BinaryOperator)
1202 * @see #toMap(Function, Function, BinaryOperator, Supplier)
1203 */
1204 public static <T, K, U, M extends ConcurrentMap<K, U>>
1205 Collector<T, M> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1206 Function<? super T, ? extends U> valueMapper,
1207 BinaryOperator<U> mergeFunction,
1208 Supplier<M> mapSupplier) {
1209 BiFunction<M, T, M> accumulator = (map, element) -> {
1210 map.merge(keyMapper.apply(element), valueMapper.apply(element), mergeFunction);
1211 return map;
1212 };
1213 return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_CONCURRENT);
1214 }
1215
1216 /**
1217 * Returns a {@code Collector} which applies an {@code int}-producing
1218 * mapping function to each input element, and returns summary statistics
1219 * for the resulting values.
1220 *
1221 * @param <T> the type of the input elements
1222 * @param mapper a mapping function to apply to each element
1223 * @return a {@code Collector} implementing the summary-statistics reduction
1224 *
1225 * @see #toDoubleSummaryStatistics(ToDoubleFunction)
1226 * @see #toLongSummaryStatistics(ToLongFunction)
1227 */
1228 public static <T>
1229 Collector<T, IntSummaryStatistics> toIntSummaryStatistics(ToIntFunction<? super T> mapper) {
1230 return new CollectorImpl<>(IntSummaryStatistics::new,
1231 (r, t) -> { r.accept(mapper.applyAsInt(t)); return r; },
1232 (l, r) -> { l.combine(r); return l; }, CH_STRICT);
1233 }
1234
1235 /**
1236 * Returns a {@code Collector} which applies an {@code long}-producing
1237 * mapping function to each input element, and returns summary statistics
1238 * for the resulting values.
1239 *
1240 * @param <T> the type of the input elements
1241 * @param mapper the mapping function to apply to each element
1242 * @return a {@code Collector} implementing the summary-statistics reduction
1243 *
1244 * @see #toDoubleSummaryStatistics(ToDoubleFunction)
1245 * @see #toIntSummaryStatistics(ToIntFunction)
1246 */
1247 public static <T>
1248 Collector<T, LongSummaryStatistics> toLongSummaryStatistics(ToLongFunction<? super T> mapper) {
1249 return new CollectorImpl<>(LongSummaryStatistics::new,
1250 (r, t) -> { r.accept(mapper.applyAsLong(t)); return r; },
1251 (l, r) -> { l.combine(r); return l; }, CH_STRICT);
1252 }
1253
1254 /**
1255 * Returns a {@code Collector} which applies an {@code double}-producing
1256 * mapping function to each input element, and returns summary statistics
1257 * for the resulting values.
1258 *
1259 * @param <T> the type of the input elements
1260 * @param mapper a mapping function to apply to each element
1261 * @return a {@code Collector} implementing the summary-statistics reduction
1262 *
1263 * @see #toLongSummaryStatistics(ToLongFunction)
1264 * @see #toIntSummaryStatistics(ToIntFunction)
1265 */
1266 public static <T>
1267 Collector<T, DoubleSummaryStatistics> toDoubleSummaryStatistics(ToDoubleFunction<? super T> mapper) {
1268 return new CollectorImpl<>(DoubleSummaryStatistics::new,
1269 (r, t) -> { r.accept(mapper.applyAsDouble(t)); return r; },
1270 (l, r) -> { l.combine(r); return l; }, CH_STRICT);
1271 }
1272
1273 /**
1274 * Implementation class used by partitioningBy.
1275 */
1276 private static final class Partition<T>
1277 extends AbstractMap<Boolean, T>
1278 implements Map<Boolean, T> {
1279 T forTrue;
1280 T forFalse;
1281
1282 Partition(T forTrue, T forFalse) {
1283 this.forTrue = forTrue;
1284 this.forFalse = forFalse;
1285 }
1286
1287 @Override
1288 public Set<Map.Entry<Boolean, T>> entrySet() {
1289 return new AbstractSet<Map.Entry<Boolean, T>>() {
1290 @Override
1291 public Iterator<Map.Entry<Boolean, T>> iterator() {
1292
1293 return new Iterator<Map.Entry<Boolean, T>>() {
1294 int state = 0;
1295
1296 @Override
1297 public boolean hasNext() {
1298 return state < 2;
1299 }
1300
1301 @Override
1302 public Map.Entry<Boolean, T> next() {
1303 if (state >= 2)
1304 throw new NoSuchElementException();
1305 return (state++ == 0)
1306 ? new SimpleImmutableEntry<>(false, forFalse)
1307 : new SimpleImmutableEntry<>(true, forTrue);
1308 }
1309 };
1310 }
1311
1312 @Override
1313 public int size() {
1314 return 2;
1315 }
1316 };
1317 }
1318 }
1319 }