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