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