dt - documentation for Mutable<T>

Co-Authored-By: brianberzins <[email protected]>

Author: isidore

approvaltests-util-tests/src/test/java/org/lambda/utils/MutableTest.exampleOfMutable.approved.txt

@@ -0,0 +1,3 @@
+adding event as Brian
+rsvping as Mr. Brian
+booking hotel as Steve

approvaltests-util-tests/src/test/java/org/lambda/utils/MutableTest.java

@@ -0,0 +1,56 @@
+package org.lambda.utils;
+
+import org.approvaltests.Approvals;
+import org.junit.jupiter.api.Test;
+import org.lambda.functions.Function0;
+
+public class MutableTest {
+
+    @Test
+    public void exampleOfSingleElementArray() {
+        // snippet: single_element_array
+        final int[] i = {1};
+        Function0<Integer> counter = () -> i[0]++;
+        // end-snippet
+    }
+
+    @Test
+    public void exampleOfMutable() {
+        // snippet: mutable_example
+        Mutable<String> i = new Mutable<>("Brian");
+        Scheduler scheduler = new Scheduler(() -> i.get());
+        scheduler.addEvent();
+        i.update(n -> "Mr. " + n);
+        scheduler.rsvp();
+        i.set("Steve");
+        scheduler.bookHotel();
+        // end-snippet
+        Approvals.verify(scheduler);
+    }
+
+
+    private class Scheduler {
+        private Function0<String> namer;
+        private String log = "";
+        public Scheduler(Function0<String> namer) {
+            this.namer = namer;
+        }
+
+        public void rsvp() {
+            log += "rsvping as " + namer.call() + "\n";
+        }
+
+        public void addEvent() {
+            log += "adding event as " + namer.call() + "\n";
+        }
+
+        public void bookHotel() {
+            log += "booking hotel as " + namer.call() + "\n";
+        }
+
+        @Override
+        public String toString() {
+            return log;
+        }
+    }
+}

approvaltests-util/docs/README.md

@@ -20,6 +20,10 @@ A set of convenience functions to make life easier.
 * Working with [Checked Exceptions](reference/RuntimeExceptions.md#top): tools to hide them.
 * [SimpleLogger](reference/SimpleLogger.md#top) 
 
+## Lambdas
+
+* [Mutable](how_to/UseMutablesInLambdas.md)
+
 ---
 
 [Back to User Guide](README.md#top)

approvaltests-util/docs/how_to/UseMutablesInLambdas.md

@@ -0,0 +1,51 @@
+<a id="top"></a>
+
+# Use to use mutable variables with lamdbas
+
+<!-- toc -->
+## Contents
+
+  * [Why use logs?](#why-use-logs)
+  * [Capturing logs in test](#capturing-logs-in-test)
+  * [See also](#see-also)<!-- endToc -->
+
+
+## The problem
+
+If you are using a value that changes in a lambda, Java will not compile.
+
+For example: 
+```java
+int i = 1;
+Function0<Integer> counter = () -> i++;
+```
+Will give a compilation error:
+
+```
+Variable used in lambda expression should be final or effectively final
+```
+
+Despite Java wanting the expressions to be final, the truth is that the objects themselves can have mutable state. This means that the workaround is to put the mutable state inside an effectively final object.
+
+`Mutable<T>` is a solution to this problem.
+
+## Single Element array solution
+
+The most common solution to this is to use a single element array. While this works, we find it to be ugly.
+
+For example:
+
+snippet: single_element_array
+
+## Mutable<T> solution
+
+Mutable allows for easy getting/setting/updating.
+
+For example:
+
+snippet: mutable_example
+
+Will produce the following:
+
+snippet: MutableTest.exampleOfMutable.approved.txt
+