Package com.google.mu.util.stream

Class GuavaCollectors

java.lang.Object
com.google.mu.util.stream.GuavaCollectors
@RequiresGuava public final class GuavaCollectors extends Object
Guava-specific Collectors and BiCollectors.
Since:
4.7

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T, B> Collector<T,?,com.google.common.collect.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.
    static <K, T, V> BiCollector<K,T,com.google.common.collect.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.
    static <K, T, V> BiCollector<K,T,com.google.common.collect.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.
    static <K, V> Collector<V,?,com.google.common.collect.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.
    static <T> Collector<T,?,Both<com.google.common.collect.ImmutableList<T>,com.google.common.collect.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.
    static <K, V> BiCollector<K,V,com.google.common.collect.ImmutableBiMap<K,V>>
    toImmutableBiMap()
    Returns a BiCollector that collects the key-value pairs into an ImmutableBiMap.
    static <T, K, V> Collector<T,?,com.google.common.collect.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.
    static <K, V> BiCollector<K,V,com.google.common.collect.ImmutableListMultimap<K,V>>
    toImmutableListMultimap()
    Returns a BiCollector that collects the key-value pairs into an ImmutableListMultimap.
    static <T, K, V> Collector<T,?,com.google.common.collect.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.
    static <K, V> BiCollector<K,V,com.google.common.collect.ImmutableMap<K,V>>
    toImmutableMap()
    Returns a BiCollector that collects the key-value pairs into an ImmutableMap.
    static <K, V> BiCollector<K,V,com.google.common.collect.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.
    static <T, K, V> Collector<T,?,com.google.common.collect.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.
    static <K, V1, V> BiCollector<K,V1,com.google.common.collect.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.
    static <T, K, V> Collector<T,?,com.google.common.collect.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.
    static <T, K, V> Collector<T,?,com.google.common.collect.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.
    static <K, V> BiCollector<K,V,com.google.common.collect.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.
    static <K, V> BiCollector<K,V,com.google.common.collect.ImmutableSetMultimap<K,V>>
    toImmutableSetMultimap()
    Returns a BiCollector that collects the key-value pairs into an ImmutableSetMultimap.
    static <T, K, V> Collector<T,?,com.google.common.collect.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.
    static <K, V> BiCollector<K,V,com.google.common.collect.ImmutableSortedMap<K,V>>
    toImmutableSortedMap(Comparator<? super K> comparator)
    Returns a BiCollector that collects the key-value pairs into an ImmutableSortedMap according to comparator.
    static <K, V> BiCollector<K,V,com.google.common.collect.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.
    static <R, C, V> BiCollector<R,BiStream<? extends C,? extends V>,com.google.common.collect.ImmutableTable<R,C,V>>
    toImmutableTable()
    Returns a BiCollector that collects the key-value pairs into an com.google.common.collect.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.
    static <T, R, C, V>
    Collector<T,?,com.google.common.collect.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.
    static <F, T> Collector<F,?,com.google.common.collect.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.
    static <K, V, M extends com.google.common.collect.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.
    static <F, T> Collector<F,?,com.google.common.collect.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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • toImmutableMap

      public static <K, V> BiCollector<K,V,com.google.common.collect.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,com.google.common.collect.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,?,com.google.common.collect.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,?,com.google.common.collect.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,com.google.common.collect.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,com.google.common.collect.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,com.google.common.collect.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 com.google.common.collect.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,com.google.common.collect.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,com.google.common.collect.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,com.google.common.collect.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,com.google.common.collect.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,com.google.common.collect.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,com.google.common.collect.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>,com.google.common.collect.ImmutableTable<R,C,V>> toImmutableTable()
      Returns a BiCollector that collects the key-value pairs into an com.google.common.collect.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,?,com.google.common.collect.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,?,com.google.common.collect.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,?,com.google.common.collect.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,?,com.google.common.collect.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,?,com.google.common.collect.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,?,com.google.common.collect.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,?,com.google.common.collect.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<com.google.common.collect.ImmutableList<T>,com.google.common.collect.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, ?, R>) with a null-supporting downstream collector, such as MoreCollectors.partitioningBy(predicate, toList()).

      Since:
      6.0

    • toListOf

      public static <F, T> Collector<F,?,com.google.common.collect.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,?,com.google.common.collect.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