Update Iterables.

Author: gk-brown

README.md

@@ -1141,6 +1141,8 @@ public static <T> Iterable<T> filter(Iterable<T> iterable, Predicate<? super T>
 public static <T, R> Iterable<R> mapAll(Iterable<T> iterable, Function<? super T, ? extends R> transform) { ... }
 public static <T> T firstOf(Iterable<T> iterable) { ... }
 public static boolean isEmpty(Iterable<?> iterable) { ... }
+
+public static <K, T> Function<Iterable<T>, Map<K, List<T>>> groupingBy(Function<? super T, ? extends K> classifier) { ... }
 ```
 
 These are provided as a less complex alternative to similar methods defined by the `java.util.stream.Stream` class:
@@ -1169,6 +1171,12 @@ var values = listOf();
 var result = isEmpty(values); // true
 ```
 
+```java
+var values = listOf("a", "b", "ab", "bc", "abc");
+
+var result = map(values, groupingBy(String::length)); // 1: a, b; 2: ab, bc; 3: abc
+```
+
 `Iterables` also provides the following method, which coerces a value to a given type:
 
 ```java

kilo-client/src/main/java/org/httprpc/kilo/util/Iterables.java

@@ -16,7 +16,11 @@
 
 import org.httprpc.kilo.beans.BeanAdapter;
 
+import java.util.ArrayList;
 import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.NoSuchElementException;
 import java.util.function.Function;
 import java.util.function.Predicate;
@@ -181,6 +185,37 @@ public static boolean isEmpty(Iterable<?> iterable) {
         return !iterable.iterator().hasNext();
     }
 
+    /**
+     * Returns a function that groups elements by a classification function.
+     *
+     * @param <K>
+     * The key type.
+     *
+     * @param <T>
+     * The element type.
+     *
+     * @param classifier
+     * The classification function.
+     *
+     * @return
+     * The grouping function.
+     */
+    public static <K, T> Function<Iterable<T>, Map<K, List<T>>> groupingBy(Function<? super T, ? extends K> classifier) {
+        if (classifier == null) {
+            throw new IllegalArgumentException();
+        }
+
+        return iterable -> {
+            var map = new LinkedHashMap<K, List<T>>();
+
+            for (var element : iterable) {
+                map.computeIfAbsent(classifier.apply(element), key -> new ArrayList<>()).add(element);
+            }
+
+            return map;
+        };
+    }
+
     /**
      * Returns a function that coerces a value to a given type.
      *

kilo-client/src/test/java/org/httprpc/kilo/util/IterablesTest.java

@@ -18,6 +18,7 @@
 
 import static org.httprpc.kilo.util.Collections.*;
 import static org.httprpc.kilo.util.Iterables.*;
+import static org.httprpc.kilo.util.Optionals.*;
 import static org.junit.jupiter.api.Assertions.*;
 
 public class IterablesTest {
@@ -64,6 +65,19 @@ public void testIsEmpty() {
         assertFalse(isEmpty(listOf(1, 2, 3)));
     }
 
+    @Test
+    public void testGroupingBy() {
+        var values = listOf("a", "b", "ab", "bc", "abc");
+
+        var result = map(values, groupingBy(String::length)); // 1: a, b; 2: ab, bc; 3: abc
+
+        assertEquals(mapOf(
+            entry(1, listOf("a", "b")),
+            entry(2, listOf("ab", "bc")),
+            entry(3, listOf("abc"))
+        ), result);
+    }
+
     @Test
     public void testToType() {
         var strings = listOf("1", "2", "3");