more streams

Author: bowbahdoe

src/SUMMARY.md

@@ -945,13 +945,13 @@ TODO: Wait for hermetic java
 
 # Data Types X
 
-- [Streams 🚧](./streams.md)
-  - [Purpose](./streams/purpose.md)
+- [Streams](./streams.md)
   - [stream](./streams/stream.md)
   - [map](./streams/map.md)
   - [filter](./streams/filter.md)
+  - [Terminal Operations](./streams/terminal_operations.md)
   - [Collectors](./streams/collectors.md)
-  - [toList](./streams/toList.md)
+  - [Purpose](./streams/purpose.md)
   - [Challenges](./streams/challenges.md)
 <!-- - [Regular Expressions 🚧]()
 - [Strings III 🚧]()

src/streams/collectors.md

@@ -1 +1,80 @@
 # Collectors
+
+The most common kind of terminal operation you will perform on a stream
+is "collecting" elements into a new collection.
+
+For this you use the `.collect` method along with an implemention of the
+`Collector` interface.
+
+```java
+~void main() {
+List<String> roles = List.of("seer", "clown", "nightmare");
+
+Function<String, Integer> countVowels = s -> {
+    int vowels = 0;
+    for (int i = 0; i < s.length(); i++) {
+        char c = s.charAt(i);
+        if (c == 'a' || c == 'e' || c == 'i' || c == 'o' || c == 'u') {
+            vowels++;
+        }
+    }
+    return vowels;
+};
+
+List<Integer> vowelCounts = roles.stream()
+    .map(countVowels)
+    .collect(Collectors.toList());
+
+IO.println(vowelCounts);
+~}
+```
+
+There are implementations available as static methods on the `Collectors` class for
+collecting into `List`s, `Set`s, and even `Map`s.
+
+Because collecting into specifically a `List` is so common, there is
+also a `.toList()` method directly on `Stream` that serves as a shortcut
+for `.collect(Collectors.toUnmodifiableList())`.
+
+```java
+~void main() {
+List<String> roles = List.of("seer", "clown", "nightmare");
+
+Function<String, Integer> countVowels = s -> {
+    int vowels = 0;
+    for (int i = 0; i < s.length(); i++) {
+        char c = s.charAt(i);
+        if (c == 'a' || c == 'e' || c == 'i' || c == 'o' || c == 'u') {
+            vowels++;
+        }
+    }
+    return vowels;
+};
+
+// There is also Collectors.toUnmodifiableList
+List<Integer> vowelCountsList = roles.stream()
+    .map(countVowels)
+    .collect(Collectors.toList());
+    
+IO.println(vowelCountsList);
+
+vowelCountsList = roles.stream()
+    .map(countVowels)
+    .toList();
+IO.println(vowelCountsList);
+
+// ...and Collectors.toUnmodifiableSet()
+Set<Integer> vowelCountsSet = roles.stream()
+    .map(countVowels)
+    .collect(Collectors.toSet());
+IO.println(vowelCountsSet);
+
+// ...and Collectors.toUnmodifiableMap
+Map<String, Integer> vowelCountsMap = roles.stream()
+    .collect(Collectors.toMap(
+        s -> s,
+        s -> countVowels.apply(s)
+    ));
+IO.println(vowelCountsMap);
+~}
+```

src/streams/filter.md

@@ -1,8 +1,20 @@
 # filter
 
-To drop elements from a `Stream` you can use `.filter`.
+With a stream of elements you can also drop the
+elements of the stream as they flow by[^metaphor] with `.filter`.
 
 `.filter` will test each element with a predicate. If the
 predicate returns `true` the element will be retained.
 If it returns `false` the element will be dropped.
 
+
+```java,no_run
+var numbers = List.of("1", "2", "3");
+
+Stream<Integer> numberStream = numbers.stream()
+    .map(Integer::parseInt) // 1, 2, 3
+    .filter(x -> x % 2 == 1); // 1, 3
+```
+
+[^metaphor]: In the real life stream metaphor, this is akin to rocks stuck along the way and not
+continuing to go with the flow of water.

src/streams/map.md

@@ -6,7 +6,7 @@ elements of the stream as they flow by[^metaphor] with `.map`.
 `.map` applies a `Function` to the elements of the stream
 one by one and returns you a new `Stream` containing the new elements.
 
-```java
+```java,no_run
 var numbers = List.of("1", "2", "3");
 
 Stream<Integer> numberStream = numbers.stream()

src/streams/purpose.md

@@ -2,4 +2,42 @@
 
 The purpose of streams is to "de-couple"
 the source of data, the transformations to apply on that
-data, and the final shape you want that data in.
+data, and the final shape you want that data in.
+
+This serves one somewhat holistic goal and one practical one.
+
+The holistic goal is that you are "declaring what you want done"
+as opposed to "expressing how you want something done."
+This is often referred to as "declarative" vs "imperative" programming.
+
+Compare these two bits of code. They both add one to every number in a list.
+
+```java,no_run
+List<Double> doubles = List.of(1.5, 2.5, 3.9);
+
+List<Double> newDoubles = new ArrayList<>();
+for (double d : doubles) {
+    newDoubles.add(d + 1);
+}
+```
+
+```java
+List<Double> doubles = List.of(1.5, 2.5, 3.9);
+
+List<Double> newDoubles = doubles.stream()
+    .map(d -> d + 1)
+    .toList();
+```
+
+You can argue that the second code snippet more transparently "reflects the intent"
+than the first one. The mechanics of looping and adding to a new list are
+hidden and the only things on screen are `doubles.stream()` (using this collection as a source),
+`.map(d -> d + 1)` (apply this transformation), and `.toList()` (put the results in a list.)
+
+This has its upsides and downsides. Part of the trouble is that there isn't a good rule of
+thumb as to when you should use a regular loop or use a stream - it often comes down to
+personal taste and other "soft" factors.
+
+The mechanical reason for streams is that, because the operations to perform are separated somewhat
+from how to perform them, there are opportunities for Java to be "smart" about how it does them.
+The usual example given for this is "parallel streams," which we can get into eventually.

src/streams/terminal_operations.md

@@ -0,0 +1,42 @@
+# Terminal Operations
+
+We call `.map`, `.filter`, and methods like them "intermediate operations."
+This is because they run "in the middle" of the entire process.
+
+For consuming a stream you use "terminal operations." Terminal operations
+"consume" the stream and produce some result.
+
+The simplest terminal operation is `.forEach`. It consumes the entire stream and does
+something for each element in the flow.
+
+```java,no_run
+~void main() {
+List<String> cities = List.of(
+    "St. Louis", "Dallas", "London", "Tokyo"
+);
+
+cities.stream()
+    .filter(city -> !city.startsWith("S"))
+    .forEach(IO::println); // Dallas, London, Tokyo
+~}
+```
+
+Once a terminal operation has been performed the stream is no longer
+usable.
+
+```java
+~void main() {
+List<String> cities = List.of(
+    "St. Louis", "Dallas", "London", "Tokyo"
+);
+
+Stream<String> citiesStream = cities.stream()
+    .filter(city -> !city.startsWith("S"));
+
+// Dallas, London, Tokyo
+citiesStream.forEach(IO::println);
+
+// java.lang.IllegalStateException: stream has already been operated upon or closed
+citiesStream.forEach(IO::println);
+~}
+```