Class GuavaCollectors

java.lang.Object
com.google.guava.labs.collect.GuavaCollectors
@CheckReturnValue public final class GuavaCollectors extends Object
Guava-specific Collectors and BiCollectors.
Since:
4.7

  • Method Details

    • toImmutableMap

      public static <K,V> BiCollector<K, V, ImmutableMap<K,V>> toImmutableMap()
      Returns a BiCollector that collects the key-value pairs into an ImmutableMap.

      Normally calling biStream.toMap() is more convenient, but for example when you've got a BiStream<K, LinkedList<V>>, and need to collect it into ImmutableMap<K, List<V>>, you'll need to call collect(toImmutableMap()) instead of toMap().

    • toImmutableMap

      public static <K,V> BiCollector<K, V, ImmutableMap<K,V>> toImmutableMap(BinaryOperator<V> valueMerger)
      Returns a BiCollector that collects the key-value pairs into an ImmutableMap using valueMerger to merge values of duplicate keys.

    • countingBy

      public static <T,B> Collector<T, ?, ImmutableMultiset<B>> countingBy(Function<? super T, ? extends B> bucketer)
      Returns a collector that counts the number of occurrences for each unique bucket as determined by the bucketer function. The result counts are stored in an ImmutableMultiset, hence implying that bucketer cannot return null.

      stream.collect(countingBy(User::id)) is equivalent to stream.map(User::id).collect(toImmutableMultiset()), but reads more intuitive when you are trying to count occurrences (as opposed to building Multiset as the end goal).

      Alternatively, one can use groupingBy(bucketer, Collectors.counting()) to collect the equivalent counts in an ImmutableMap<B, Long>. Which of the two types to use depends on whether you need to handle very large counts (potentially exceeding Integer.MAX_VALUE), or whether the Multiset API is more useful (particularly, Multiset.count(java.lang.Object)). The memory footprint of ImmutableMultiset<B> is also more compact than ImmutableMap<B, Long>.

      Since:
      5.6

    • indexingBy

      public static <K,V> Collector<V, ?, ImmutableMap<K,V>> indexingBy(Function<? super V, ? extends K> indexingFunction)
      Returns a Collector that collects to an ImmutableMap with the input elements uniquely indexed by the return value of indexingFunction.

    • toImmutableMap

      public static <K,V1,V> BiCollector<K, V1, ImmutableMap<K,V>> toImmutableMap(Collector<V1,?,V> valueCollector)
      Returns a BiCollector that collects the key-value pairs into an ImmutableMap using valueCollector to collect values of identical keys into a final value of type V.

      For example, the following calculates total population per state from city demographic data: 

      
 ImmutableMap<StateId, Integer> statePopulations = BiStream.from(cities, City::getState, c -> c)
     .collect(toImmutableMap(summingInt(City::getPopulation)));

      Entries are collected in encounter order.

    • toImmutableSortedMap

      public static <K,V> BiCollector<K, V, ImmutableSortedMap<K,V>> toImmutableSortedMap(Comparator<? super K> comparator, BinaryOperator<V> valueMerger)
      Returns a BiCollector that collects the key-value pairs into an ImmutableSortedMap according to comparator, using valueMerger to merge values of duplicate keys.

    • toImmutableSortedMap

      public static <K,V> BiCollector<K, V, ImmutableSortedMap<K,V>> toImmutableSortedMap(Comparator<? super K> comparator)
      Returns a BiCollector that collects the key-value pairs into an ImmutableSortedMap according to comparator.

    • toMultimap

      public static <K, V, M extends Multimap<K,V>> BiCollector<K,V,M> toMultimap(Supplier<M> multimapSupplier)
      Returns a BiCollector that collects the key-value pairs into a Multimap created with multimapSupplier.

    • toImmutableListMultimap

      public static <K,V> BiCollector<K, V, ImmutableListMultimap<K,V>> toImmutableListMultimap()
      Returns a BiCollector that collects the key-value pairs into an ImmutableListMultimap. Equivalent to ImmutableListMultimap::toImmutableListMultimap.

    • flatteningToImmutableListMultimap

      public static <K,T,V> BiCollector<K, T, ImmutableListMultimap<K,V>> flatteningToImmutableListMultimap(Function<? super T, ? extends Stream<? extends V>> flattener)
      Returns a BiCollector that first flattens each value of the input pair with flattener, and then collects the flattened pairs into an ImmutableListMultimap.

      For example, you can collect groupingBy() results into a multimap using: 

      
 Map<PhoneNumber, Contact> phoneBook = ...;
 ImmutableListMultimap<AreaCode, Contact> contactsByAreaCode = BiStream.from(phoneBook)
     .collect(BiCollectors.groupingBy(PhoneNumber::areaCode, mergingContacts()))
     .collect(BiCollectors.flatteningToImmutableListMultimap(Collection::stream));

    • toImmutableSetMultimap

      public static <K,V> BiCollector<K, V, ImmutableSetMultimap<K,V>> toImmutableSetMultimap()
      Returns a BiCollector that collects the key-value pairs into an ImmutableSetMultimap. Equivalent to ImmutableSetMultimap::toImmutableSetMultimap.

    • flatteningToImmutableSetMultimap

      public static <K,T,V> BiCollector<K, T, ImmutableSetMultimap<K,V>> flatteningToImmutableSetMultimap(Function<? super T, ? extends Stream<? extends V>> flattener)
      Returns a BiCollector that first flattens each value of the input pair with flattener, and then collects the flattened pairs into an ImmutableSetMultimap.

      For example, you can collect groupingBy() results into a multimap using: 

      
 Map<PhoneNumber, Contact> phoneBook = ...;
 ImmutableSetMultimap<AreaCode, Contact> contactsByAreaCode = BiStream.from(phoneBook)
     .collect(BiCollectors.groupingBy(PhoneNumber::areaCode, mergingContacts()))
     .collect(BiCollectors.flatteningToImmutableSetMultimap(Collection::stream));

    • toImmutableMultiset

      public static <K,V> BiCollector<K, V, ImmutableMultiset<K>> toImmutableMultiset(ToIntFunction<? super V> countFunction)
      Returns a BiCollector that collects the key-value pairs into an ImmutableMultiset whose elements are the keys, with counts equal to the result of applying countFunction to the values.

      For duplicate keys (according to Object.equals(java.lang.Object)), the first occurrence in encounter order appears in the resulting multiset, with count equal to the sum of the outputs of countFunction.applyAsInt(value) for each value mapped to that key.

      biStream.collect(toImmutableMultiset(countFunction)) is logically equivalent to biStream.collect(toImmutableMap(summingInt(countFunction))), except that it collects to ImmutableMultiset<K> while the latter collects to ImmutableMap<K, Integer>.

    • toImmutableBiMap

      public static <K,V> BiCollector<K, V, ImmutableBiMap<K,V>> toImmutableBiMap()
      Returns a BiCollector that collects the key-value pairs into an ImmutableBiMap. Equivalent to ImmutableBimap::toImmutableBiMap.

    • toImmutableTable

      public static <R,C,V> BiCollector<R, BiStream<? extends C, ? extends V>, ImmutableTable<R,C,V>> toImmutableTable()
      Returns a BiCollector that collects the key-value pairs into an ImmutableTable<R,C,V>, where each input key (of type R) is mapped to a row in the table, and each input value is a BiStream<C, V> whose keys (of type C) are mapped to columns in the table, and whose values (of type V) are mapped to the cell values.

      Typically useful in combination with a nested BiStream.groupingBy(java.util.function.Function<? super V, ? extends K>, java.util.function.BinaryOperator<V>). For example: 

      
 import static com.google.common.labs.collect.BiStream.groupingBy;

 List<Contact> contacts = ...;
 ImmutableTable<LastName, FirstName, Long> nameCounts = contacts.stream()
     .collect(groupingBy(Contact::lastName, groupingBy(Contact::firstName, counting())))
     .collect(toImmutableTable());

      Similarly, cascading group-by can be performed on a Map or Multimap through groupingBy(), and then reduced in the same way using toImmutableTable(): 

      
 import static com.google.common.labs.collect.BiCollectors.groupingBy;

 Multimap<Address, PhoneNumber> phoneBook = ...;
 ImmutableTable<State, City, ImmutableSet<PhoneNumber>> phoneNumbersByLocation =
     BiStream.from(phoneBook)
         .collect(groupingBy(Address::state, groupingBy(Address::city, toImmutableSet())))
         .collect(toImmutableTable());

      Cells are collected in encounter order.

      The returned BiCollector is not optimized for parallel reduction.

    • toImmutableMap

      public static <T,K,V> Collector<T, ?, ImmutableMap<K,V>> toImmutableMap(Function<? super T, ? extends Both<? extends K, ? extends V>> mapper)
      Returns a collector that first maps each input into a key-value pair, and then collects them into a ImmutableMap.
      Since:
      5.1

    • toImmutableListMultimap

      public static <T,K,V> Collector<T, ?, ImmutableListMultimap<K,V>> toImmutableListMultimap(Function<? super T, ? extends Both<? extends K, ? extends V>> mapper)
      Returns a collector that first maps each input into a key-value pair, and then collects them into a ImmutableListMultimap.
      Since:
      5.1

    • toImmutableSetMultimap

      public static <T,K,V> Collector<T, ?, ImmutableSetMultimap<K,V>> toImmutableSetMultimap(Function<? super T, ? extends Both<? extends K, ? extends V>> mapper)
      Returns a collector that first maps each input into a key-value pair, and then collects them into a ImmutableSetMultimap.
      Since:
      5.1

    • toImmutableBiMap

      public static <T,K,V> Collector<T, ?, ImmutableBiMap<K,V>> toImmutableBiMap(Function<? super T, ? extends Both<? extends K, ? extends V>> mapper)
      Returns a collector that first maps each input into a key-value pair, and then collects them into a ImmutableBiMap.
      Since:
      5.1

    • toImmutableMapIgnoringDuplicateEntries

      public static <T,K,V> Collector<T, ?, ImmutableMap<K,V>> toImmutableMapIgnoringDuplicateEntries(Function<? super T, ? extends Both<? extends K, ? extends V>> mapper)
      Returns a collector that first maps each input into a key-value pair, and then collects them into a ImmutableListMultimap.

      Inconsistent (unequal) values mapped to the same key (according to Object.equals(Object)) will throw IllegalArgumentException, Duplicate (equal) values mapped to the same key will be ignored. Entries will appear in the encounter order of the first occurrence of the key.

      Since:
      6.6

    • toImmutableTable

      public static <T,R,C,V> Collector<T, ?, ImmutableTable<R,C,V>> toImmutableTable(Function<? super T, ? extends R> rowFunction, Function<? super T, ? extends C> columnFunction, Collector<T,?,V> cellCollector)
      Returns a collector that maps each value into a row-key and column-key for a table, and then collects all values mapped to the same cell using cellCollector. For example: 
      
 ImmutableTable<State, County, ImmutableSet<City>> citiesByStateAndCounty =
     cities.stream().collect(
         toImmutableTable(City::state, City::county, toImmutableSet());

      To transform values before they are collected, use Collectors.mapping(java.util.function.Function<? super T, ? extends U>, java.util.stream.Collector<? super U, A, R>). For more complex operations on row- or column-keys, look at BiStream.groupingBy(java.util.function.Function<? super V, ? extends K>, java.util.function.BinaryOperator<V>). For collectors that throw or merge when values map to the same cell, see ImmutableTable.toImmutableTable(java.util.function.Function<? super T, ? extends R>, java.util.function.Function<? super T, ? extends C>, java.util.function.Function<? super T, ? extends V>).

      Since:
      6.6

    • toImmutableMapIgnoringDuplicateEntries

      public static <T,K,V> Collector<T, ?, ImmutableMap<K,V>> toImmutableMapIgnoringDuplicateEntries(Function<? super T, ? extends K> toKey, Function<? super T, ? extends V> toValue)
      Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.

      Inconsistent (unequal) values mapped to the same key (according to Object.equals(Object)) will throw IllegalArgumentException, Duplicate (equal) values mapped to the same key will be ignored. Entries will appear in the encounter order of the first occurrence of the key.

      Since:
      6.6

    • partitioningBy

      public static <T> Collector<T, ?, Both<ImmutableList<T>, ImmutableList<T>>> partitioningBy(Predicate<? super T> predicate)
      Returns a collector that partitions the incoming elements into two groups: elements that match predicate, and those that don't.

      For example: 

      
 candidates
     .collect(partitioningBy(Candidate::isEligible))
     .andThen((eligible, ineligible) -> ...);

      Null elements are not allowed. To support nulls, use MoreCollectors.partitioningBy(java.util.function.Predicate<? super E>, java.util.stream.Collector<E, ?, ? extends R>) with a null-supporting downstream collector, such as MoreCollectors.partitioningBy(predicate, toList()).

      Since:
      6.0

    • toListOf

      public static <F,T> Collector<F, ?, ImmutableList<T>> toListOf(Function<? super F, ? extends T> mapper)
      Returns a collector that collects the results of applying the mapper function on the input elements into an ImmutableList.

      Equivalent to but more convenient than Collectors.mapping(mapper, toImmutableList()).

      Since:
      7.0

    • toSetOf

      public static <F,T> Collector<F, ?, ImmutableSet<T>> toSetOf(Function<? super F, ? extends T> mapper)
      Returns a collector that collects the results of applying the mapper function on the input elements into an ImmutableSet.

      Equivalent to but more convenient than Collectors.mapping(mapper, toImmutableSet()).

      Since:
      7.0

    • toImmutableRangeMap

      public static <K extends Comparable<K>, V> BiCollector<Range<K>, V, ImmutableRangeMap<K,V>> toImmutableRangeMap()
      Returns a BiCollector that takes input (disjoint) ranges and the corresponding values and builds an ImmutableRangeMap.
      Since:
      8.1

    • toImmutableRangeMap

      public static <K extends Comparable<K>, V> BiCollector<Range<K>, V, ImmutableRangeMap<K,V>> toImmutableRangeMap(BinaryOperator<V> merger)
      Returns a BiCollector that merges values mapped to overlapping ranges using the merger function and builds an ImmutableRangeMap with disjoint ranges and the corresponding merged values.

      For example: 

      
 Map<Range<Integer>, String> rangeMap = ...; // [1..3] -> "foo", [2..4] -> "bar"

 // [1..2) -> "foo", [2..3] -> "foobar", (3..4] -> "bar"
 ImmutableRangeMap<Integer, String> result =
     BiStream.from(rangeMap).collect(toImmutableRangeMap(String::concat));

      To avoid quadratic range merging, it's generally safer to arrange the input ranges longer range first.

      Since:
      8.1

    • toRangeMap

      public static <K extends Comparable<K>, V, M extends RangeMap<K,V>> BiCollector<Range<K>,V,M> toRangeMap(Supplier<? extends M> factory, BinaryOperator<V> merger)
      Returns a BiCollector that merges values mapped to overlapping ranges using the merger function and builds a mutable RangeMap of type M that's created by factory, and populated with disjoint ranges and the corresponding merged values.

      For example: 

      
 Map<Range<Integer>, String> rangeMap = ...; // [1..3] -> "foo", [2..4] -> "bar"

 // [1..2) -> "foo", [2..3] -> "foobar", (3..4] -> "bar"
 TreeRangeMap<Integer, String> result =
     BiStream.from(rangeMap).collect(toRangeMap(TreeRangeMap::create, String::concat));

      To avoid quadratic range merging, it's generally safer to arrange the input ranges longer range first.

      Since:
      8.1

    • toDisjointRanges

      public static <K extends Comparable<K>, V> BiCollector<Range<K>, V, BiStream<Range<K>,Chain<V>>> toDisjointRanges()
      Returns a BiCollector that merges values mapped to overlapping ranges into a Chain, which is an immutable List that may have been deeply concatenated. The result is a BiStream with disjoint ranges and the corresponding merged list (Chain) of values.

      For example: 

      
 Map<Range<Integer>, String> rangeMap = ...; // [1..3] -> "foo", [2..4] -> "bar"

 // [1..2) -> ["foo"], [2..3] -> ["foo", "bar"], (3..4] -> ["bar"]
 ImmutableMap<Range<Integer>, List<String>> result =
     BiStream.from(rangeMap)
         .collect(toDisjointRanges())
         .collect(toImmutableMap());

      To avoid quadratic range merging, it's generally safer to arrange the input ranges longer range first.

      Since:
      8.1

    • toDisjointRanges

      public static <K extends Comparable<K>, V> BiCollector<Range<K>, V, BiStream<Range<K>,V>> toDisjointRanges(BinaryOperator<V> merger)
      Returns a BiCollector that merges values mapped to overlapping ranges using the merger function and builds a BiStream with disjoint ranges and the corresponding merged values.

      For example: 

      
 Map<Range<Integer>, String> rangeMap = ...; // [1..3] -> "foo", [2..4] -> "bar"

 // [1..2) -> "foo", [2..3] -> "foobar", (3..4] -> "bar"
 Map<Range<Integer>, String> result =
     BiStream.from(rangeMap)
         .collect(toDisjointRanges(String::concat))
         .toMap();

      To avoid quadratic range merging, it's generally safer to arrange the input ranges longer range first.

      Since:
      8.1

    • toDisjointRanges

      public static <K extends Comparable<K>, V, R> BiCollector<Range<K>, V, BiStream<Range<K>,R>> toDisjointRanges(Collector<V,?,R> valueCollector)
      Returns a BiCollector that collects values mapped to overlapping ranges using valueCollector, and builds a BiStream with disjoint ranges and the corresponding collector results.

      For example: 

      
 Map<Range<Integer>, String> rangeMap = ...; // [1..3] -> foo, [2..4] -> bar

 // [1..2) -> [foo], [2..3] -> [foo, bar], (3..4] -> [bar]
 Map<Range<Integer>, ImmutableSet<String>> result =
     BiStream.from(rangeMap)
         .collect(toDisjointRanges(toImmutableSet()))
         .toMap();

      Performance note: when a range is repetitively detected to overlap with another range, and the mapped values are re-mapped to each split sub-range, the re-mapping takes O(1) time even when there have been N mapped values. The final mapped values for each disjoint range will be eventually collected using the valueCollector, once per disjoint range. In other words, if valueCollector is O(n), toDisjointRanges() is an O(nlogn) operation, while the worst-case runtime of a naive implementation that recombines the mapped values on each re-mapping will be O(n^2).

      Also, to avoid quadratic range merging, it's generally safer to arrange the input ranges longer range first.

      Since:
      8.1