re-arrange stream intro

Author: forax

chapter25-stream.jsh

@@ -4,8 +4,8 @@
 
 // # Stream
 // A stream is an API that defines a query on a source of values.
-// It's an abstraction of loops over the values using a declarative API
-// (what result you want and not how to compute it).
+// It's an abstraction of loops over values using a declarative API,
+// an API that describe the result you want and not how to compute it.
 
 // By example, to count the number of persons with a name starting by 'E',
 // one can write
@@ -24,6 +24,14 @@ var count = names.stream().filter(name -> name.startsWith("E")).count();
 System.out.println(count);
 
 
+// ### Why using streams instead of loops
+// The main reason is that it makes the code more readable,
+// obviously once you are used to read stream query,
+// - by allowing to easily compose operations
+// - by removing the declaration of intermediary local variables/states
+//   (the variable `count` in the example above).
+
+
 // ## Sources
 // There are several ways to create a stream depending on the source
 // (The following examples are using `count()` to compute the number of values,

guide/chapter25-stream.md

@@ -1,7 +1,7 @@
 # Stream
 A stream is an API that defines a query on a source of values.
-It's an abstraction of loops over the values using a declarative API
-(what result you want and not how to compute it).
+It's an abstraction of loops over values using a declarative API,
+an API that describe the result you want and not how to compute it.
 
 By example, to count the number of persons with a name starting by 'E',
 one can write
@@ -24,6 +24,14 @@ System.out.println(count);
 ```
 
 
+### Why using streams instead of loops
+The main reason is that it makes the code more readable,
+obviously once you are used to read stream query,
+- by allowing to easily compose operations
+- by removing the declaration of intermediary local variables/states
+  (the variable `count` in the example above).
+
+
 ## Sources
 There are several ways to create a stream depending on the source
 (The following examples are using `count()` to compute the number of values,

jupyter/chapter25-stream.ipynb

@@ -2,7 +2,7 @@
   "cells": [{
   "cell_type": "markdown",
   "metadata": {},
-  "source": ["# Stream\n", "A stream is an API that defines a query on a source of values.\n", "It's an abstraction of loops over the values using a declarative API\n", "(what result you want and not how to compute it).\n"]
+  "source": ["# Stream\n", "A stream is an API that defines a query on a source of values.\n", "It's an abstraction of loops over values using a declarative API,\n", "an API that describe the result you want and not how to compute it.\n"]
 }
 ,
 {
@@ -33,6 +33,12 @@
   "source": ["var names = List.of(\"Evan\", \"Helen\", \"Ebo\");\n", "var count = names.stream().filter(name -> name.startsWith(\"E\")).count();\n", "System.out.println(count);\n"]
 }
 ,
+{
+  "cell_type": "markdown",
+  "metadata": {},
+  "source": ["### Why using streams instead of loops\n", "The main reason is that it makes the code more readable,\n", "obviously once you are used to read stream query,\n", "- by allowing to easily compose operations\n", "- by removing the declaration of intermediary local variables/states\n", "  (the variable `count` in the example above).\n"]
+}
+,
 {
   "cell_type": "markdown",
   "metadata": {},