Make lists returned from groupBy calls unmodifiable (#95)

+ Reimplement integrator to be slightly easier to follow
+ FWIW I also reimplemented this entirely with the `GroupChangingGatherer` but it felt clumsy so here we are

Author: tginsberg

src/main/java/com/ginsberg/gatherers4j/Gatherers4j.java

@@ -472,17 +472,17 @@ public static <INPUT> GroupChangingGatherer<INPUT> groupNonIncreasing(final Comp
         return GroupChangingGatherer.usingComparator(ChangingOperation.NonIncreasing, comparator);
     }
 
-    /// Turn a `Stream<INPUT>` into a `Stream<List<INPUT>>` where consecutive
-    /// equal elements, where equality is measured by `Object.equals(Object)`.
+    /// Turn a `Stream<INPUT>` into a `Stream<List<INPUT>>` where consecutive equal elements are in the same `List`
+    /// and equality is measured by `Object.equals(Object)`. The lists emitted to the output stream are unmodifiable.
     ///
     /// @param <INPUT> Type of elements in the input stream
     /// @return A non-null `GroupingByGatherer`
     public static <INPUT extends @Nullable Object> GroupingByGatherer<INPUT> grouping() {
         return new GroupingByGatherer<>();
     }
 
-    /// Turn a `Stream<INPUT>` into a `Stream<List<INPUT>>` where consecutive
-    /// equal elements, where equality is measured by the given `mappingFunction`, are in the same `List`.
+    /// Turn a `Stream<INPUT>` into a `Stream<List<INPUT>>` where consecutive equal elements are in the same `List`
+    /// and equality is measured by the given `mappingFunction`. The lists emitted to the output stream are unmodifiable.
     ///
     /// @param mappingFunction A non-null function, the results of which are used to measure equality of consecutive elements.
     /// @param <INPUT>         Type of elements in the input stream

src/main/java/com/ginsberg/gatherers4j/GroupingByGatherer.java

@@ -19,6 +19,7 @@
 import org.jspecify.annotations.Nullable;
 
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
 import java.util.function.BiConsumer;
 import java.util.function.Function;
@@ -38,7 +39,7 @@ public class GroupingByGatherer<INPUT extends @Nullable Object> implements
         mappingFunction = null;
     }
 
-    GroupingByGatherer(Function<@Nullable INPUT, @Nullable Object> mappingFunction) {
+    GroupingByGatherer(final Function<@Nullable INPUT, @Nullable Object> mappingFunction) {
         mustNotBeNull(mappingFunction, "Mapping function must not be null");
         this.mappingFunction = mappingFunction;
     }
@@ -51,34 +52,28 @@ public Supplier<State<INPUT>> initializer() {
     @Override
     public Integrator<State<INPUT>, INPUT, List<INPUT>> integrator() {
         return Integrator.ofGreedy((state, element, downstream) -> {
-            final Object thisMatch = mappingFunction == null ? element: mappingFunction.apply(element);
-            if (state.working == null) {
+            final Object thisMappedElement = mappingFunction == null ? element: mappingFunction.apply(element);
+            if (!state.working.isEmpty() && !safeEquals(state.previousMappedElement, thisMappedElement)) {
+                downstream.push(Collections.unmodifiableList(state.working));
                 state.working = new ArrayList<>();
-                state.working.add(element);
-                state.pastMatch = thisMatch;
-            } else if (!safeEquals(state.pastMatch, thisMatch)) {
-                downstream.push(state.working);
-                state.working = new ArrayList<>();
-                state.working.add(element);
-                state.pastMatch = thisMatch;
-            } else {
-                state.working.add(element);
             }
+            state.previousMappedElement = thisMappedElement;
+            state.working.add(element);
             return !downstream.isRejecting();
         });
     }
 
     @Override
     public BiConsumer<State<INPUT>, Downstream<? super List<INPUT>>> finisher() {
         return (state, downstream) -> {
-            if (state.working != null) {
-                downstream.push(state.working);
+            if (!state.working.isEmpty()) {
+                downstream.push(Collections.unmodifiableList(state.working));
             }
         };
     }
 
     public static class State<INPUT> {
-        @Nullable Object pastMatch = null;
-        @Nullable List<INPUT> working = null;
+        @Nullable Object previousMappedElement = null;
+        List<INPUT> working = new ArrayList<>();
     }
 }

src/test/java/com/ginsberg/gatherers4j/GroupingByGathererTest.java

@@ -74,6 +74,7 @@ void groupingByIdentity() {
         );
     }
 
+    @SuppressWarnings("DataFlowIssue")
     @Test
     void mappingFunctionMustNotBeNull() {
         assertThatThrownBy(() -> new GroupingByGatherer<>(null)).isInstanceOf(IllegalArgumentException.class);
@@ -96,6 +97,23 @@ void nullsMatch() {
                 );
     }
 
+    @Test
+    void returnedListUnmodifiable() {
+        // Arrange
+        final Stream<String> input = Stream.of("A", "A", "B", "B", "C", "C", "C");
+
+        // Act
+        final List<List<String>> output = input.gather(Gatherers4j.grouping()).toList();
+
+        // Assert
+        assertThat(output).hasSize(3);
+        output.forEach(it ->
+                assertThatThrownBy(() ->
+                        it.add("D")
+                ).isInstanceOf(UnsupportedOperationException.class)
+        );
+    }
+
     @Test
     void singleElementStream() {
         // Arrange