Que argumentos e parâmetros o método groupingBy da classe Collectors em Java espera?

O método groupingBy da classe Collectors em Java é utilizado para agrupar elementos de um stream por uma chave, que é determinada por uma função de classificação.

As principais variantes de argumentos são:

1. groupingBy(Function<? super T, ? extends K> classifier)

   • Aceita uma função que retorna uma chave de agrupamento para cada elemento.
   • Retorna um Collector<T, ?, Map<K, List<T>>>, onde os valores são listas de elementos agrupados por chave.

2. groupingBy(Function<? super T, ? extends K> classifier, Collector<? super T, A, D> downstream)

   • Além da função de classificação, aceita outro coletor que é aplicado aos elementos de cada grupo.
   • Permite, por exemplo, contar imediatamente o quantidade de elementos em cada grupo, coletá-los em um conjunto, etc.

3. groupingBy(Function<? super T, ? extends K> classifier, Supplier<M> mapFactory, Collector<? super T, A, D> downstream)

   • Permite especificar uma implementação concreta do mapa (por exemplo, TreeMap em vez de HashMap).

Exemplo de uso:

List<String> names = Arrays.asList("Anna", "Bob", "Alice", "Brian", "Amanda");

Map<Character, List<String>> grouped = names.stream()
    .collect(Collectors.groupingBy(name -> name.charAt(0)));

// `grouped` conterá as chaves 'A' e 'B' com as listas de nomes correspondentes

E um exemplo com um coletor downstream:

Map<Character, Long> countByFirstLetter = names.stream()
    .collect(Collectors.groupingBy(name -> name.charAt(0), Collectors.counting()));

// conta a quantidade de nomes para cada letra