2.4 Reworked chapter

Froussios · Froussios · commit e3aea7edfbfd · 2015-06-10T17:20:53.000+02:00
diff --git a/Part 2 - Sequence Basics/4. Aggregation.md b/Part 2 - Sequence Basics/4. Aggregation.md
@@ -1,8 +1,8 @@
 # Aggregation
 
-We've seen how to cut away parts of a sequence that we don't want, how to get single values, how to inspect the contents of sequence and how to deal with that information. Those things can be seen as reasoning about the containing sequence. Now we will see how we can use the raw data in the sequence to produce meaningful values.
+We've seen how to cut away parts of a sequence that we don't want, how to get single values and how to inspect the contents of sequence. Those things can be seen as reasoning about the containing sequence. Now we will see how we can use the data in the sequence to derive new meaningful values.
 
-The methods we will see here resemble what is called catamorphism. In our case, it would mean that the methods that all the values in the sequence and compose them into one. However, they do not strictly meet the definition, as they don't return a single value. Rather, they return an observable that promises to emit a single value.
+The methods we will see here resemble what is called catamorphism. In our case, it would mean that the methods consume the values in the sequence and compose them into one. However, they do not strictly meet the definition, as they don't return a single value. Rather, they return an observable that promises to emit a single value.
 
 If you've been reading through all of the examples, you should have noticed some repetition. To do away with that and to focus on what matters, we will now introduce a custom `Subscriber`, which we will use in our examples.
 
@@ -31,7 +31,7 @@ This is a very basic implementation that prints every event to the console, alon
 
 ### count
 
-Our first method is `count`. It serves the same purpose as `length` and `size`, found in Java collections. This method will return an observable that waits until the sequence completes and emits the number of values in the source.
+Our first method is `count`. It serves the same purpose as `length` and `size`, found in most Java containers. This method will return an observable that waits until the sequence completes and emits the number of values encountered.
 
 ![](https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/count.png)
 
@@ -72,15 +72,15 @@ Instead of getting a `java.util.NoSuchElementException`, you can use `firstOrDef
 
 ### last
 
-`last` and `lastOrDefault` work in the same way, only the item returned is the last item before the sequence completed. When using the overload with a predicate, the item returned is the last item that matched the predicate.
+`last` and `lastOrDefault` work in the same way as `first`, except that the item returned is the last item before the sequence completed. When using the overload with a predicate, the item returned is the last item that matched the predicate.
 
 ### single
 
 `single` emits the only value in the sequence, or the only value that met predicate when one is given. It differs from `first` and `last` in that it does not ignore multiple matches. If multiple matches are found, it will emit an error. It can be used to assert that a sequence must only contain one such value.
 
 ![](https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/single.p.png)
 
-Remember that single must check the entire sequence to ensure your assertion.
+Remember that `single` must check the entire sequence to ensure your assertion.
 
 ```java
 Observable<Long> values = Observable.interval(100, TimeUnit.MILLISECONDS);
@@ -107,14 +107,14 @@ The methods we saw on this chapter so far don't seem that different from the one
 
 ### reduce
 
-You may have heard of `reduce` from MapReduce. Otherwise, you might have met it under the names "aggregate", "accumulate" or "fold". The general idea is that you produce a single value out of many by combining them two at a time. It its most basic overload, all you need is a function that combines two values into one.
+You may have heard of `reduce` from MapReduce. Alternatively, you might have met it under the names "aggregate", "accumulate" or "fold". The general idea is that you produce a single value out of many by combining them two at a time. It its most basic overload, all you need is a function that combines two values into one.
 
 ```java
 public final Observable<T> reduce(Func2<T,T,T> accumulator)
 ```
 ![](https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/reduce.png)
 
-This is best explained with an example. Here we will calculate the sum of a sequence of integers: 0+1+2+3+4=10 and separately the minimum value;
+This is best explained with an example. Here we will calculate the sum of a sequence of integers: `0+1+2+3+4+...`. We will also calculate the minimum value for a different example;
 
 ```java
 Observable<Integer> values = Observable.range(0,5);
@@ -135,13 +135,13 @@ Min: 0
 Min: Completed
 ```
 
-`reduce` in Rx is not identical to "reduce" in parallel systems. In the context of parallel systems, it implies that the pairs of values can be choosen arbitrarily so that multiple machines can work independently. In Rx, the `accumulator` function is applied in sequence from left to right (as seen on the marble diagram). Each time, the accumulator function combines the result of the previous accumulations with the next value. This is more obvious in the other overload:
+`reduce` in Rx is not identical to "reduce" in parallel systems. In the context of parallel systems, it implies that the pairs of values can be choosen arbitrarily so that multiple machines can work independently. In Rx, the `accumulator` function is applied in sequence from left to right (as seen on the marble diagram). Each time, the accumulator function combines the result of the previous step with the next value. This is more obvious in another overload:
 
 ```java
 public final <R> Observable<R> reduce(R initialValue, Func2<R,? super T,R> accumulator)
 ```
 
-The accumulator returns a different type than the one in the observable. The first argument of the accumulator is the previous partial result of the accumulation process and the second in the next value. To begin the process, an initial value is supplied. We will demonstrate this process by reimplementing `count`
+The accumulator returns a different type than the one in the observable. The first parameter for the accumulator is the previous partial result of the accumulation process and the second is the next value. To begin the process, an initial value is supplied. We will demonstrate the usefulness of this by reimplementing `count`
 
 ```java
 Observable<String> values = Observable.just("Rx", "is", "easy");
@@ -157,6 +157,8 @@ Count: 3
 Count: Completed
 ```
 
+We start with an accumulator of `0`, as we have counted 0 items. Every time a new item arrives, we return a new accumulator that is increased by one. The last value corresponds to the number of elements in the source sequence.
+
 `reduce` can be used to implement the functionality of most of the operators that emit a single value. It can not implement behaviour where a value is emitted before the source completes. So, you can implement `last` using `reduce`, but an implementation of `all` would not behave exactly like the original.
 
 ### scan
@@ -242,7 +244,7 @@ Output
 [10, 11, 12, 13, 14]
 ```
 
-The code above has a problem with a formality: `reduce` is meant to be a functional fold and folds are not supposed to work on mutable accumulators. If we were to do this the "right" way, we would have to create a new instance of `ArrayList<Integer>` for every new item, like this:
+The code above has a problem with formality: `reduce` is meant to be a functional fold and such folds are not supposed to work on mutable accumulators. If we were to do this the "right" way, we would have to create a new instance of `ArrayList<Integer>` for every new item, like this:
 
 ```java
 // Formally correct but very inefficient
@@ -269,7 +271,7 @@ values
 	.subscribe(v -> System.out.println(v));
 ```
 
-Usually, you won't have to collect values manually. Rxjava offers a variety of operators for collecting your sequence into a container. Those aggregators return an observable that will emit the corresponding collection when it is ready.
+Usually, you won't have to collect values manually. Rxjava offers a variety of operators for collecting your sequence into a container. Those aggregators return an observable that will emit the corresponding collection when it is ready, just like what we did here. We will see such aggregators next.
 
 #### toList
 
@@ -327,7 +329,7 @@ public final <K,V> Observable<java.util.Map<K,V>> toMap(
 
 `keySelector` is a function that produces a key from a value. `valueSelector` produces from the emitted value the actual value that will be stored in the map. `mapFactory` creates the collection that will hold the items.
 
-Lets start with an example of the simple overload. We want to map people to their age. We start with a data structure
+Lets start with an example of the simplest overload. We want to map people to their age. First, we need a data structure to work on:
 
 ```java
 class Person {
@@ -377,7 +379,7 @@ toMap: {Saul=35, Nick=40, Will=25}
 toMap: Completed
 ```
 
-If we want to be explicit about the container that will be used or initialise it, we can supply our own:
+If we want to be explicit about the container that will be used or initialise it, we can supply our own container:
 
 ```java
 values
@@ -388,9 +390,11 @@ values
 	.subscribe(new PrintSubscriber("toMap"));
 ```
 
+The container is provided as a factory function because a new container needs to be created for every new subscription.
+
 #### toMultimap
 
-When mapping, it is very common that many values share the same key. We call it "grouping" and the datastructure for this is a multimap, a map from keys to collections
+When mapping, it is very common that many values share the same key. The datastructure that maps one key to multiple values is called a multimap and it is a map from keys to collections. This process can also be called "grouping".
 
 ```java
 public final <K> Observable<java.util.Map<K,java.util.Collection<T>>> toMultimap(
@@ -430,7 +434,7 @@ toMap: {35=[Will, Saul], 40=[Nick]}
 toMap: Completed
 ```
 
-The first three overloads are familiar from `toMap`. The fourth allows us to provide not only the `Map` but also the `Collection` that the values will be stored in. The collection can be customised according to the corresponding key:
+The first three overloads are familiar from `toMap`. The fourth allows us to provide not only the `Map` but also the `Collection` that the values will be stored in. The key is provided as a parameter, in case we want to customise the corresponding collection based on the key. In this example we'll just ignore it.
 
 ```java
 Observable<Person> values = Observable.just(
@@ -450,7 +454,7 @@ values
 
 #### Note
 
-The operators just presented have actually very limited use. It is tempting for a beginner to collect the data in a collection and process them in the traditional way. That should be avoided not just for didactic purposes, but because this way defeats the advantages of using Rx in the first place.
+The operators just presented have actually limited use. It is tempting for a beginner to collect the data in a collection and process them in the traditional way. That should be avoided not just for didactic purposes, but because this practice defeats the advantages of using Rx in the first place.
 
 
 ### groupBy
@@ -463,9 +467,9 @@ public final <K> Observable<GroupedObservable<K,T>> groupBy(Func1<? super T,? ex
 
 ![](https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.png)
 
-The return value is an observable of observables. Every time a new key is met, a new inner `GroupedObservable` will be emitted. That type is nothing more than a standard observable with a `getKey()` accessor, for getting the group's key. As values come from the source observable, they will be emitted by the observable with the corresponding key.
+The return value is an observable of `GroupedObservable`. Every time a new key is met, a new inner `GroupedObservable` will be emitted. That type is nothing more than a standard observable with a `getKey()` accessor, for getting the group's key. As values come from the source observable, they will be emitted by the observable with the corresponding key.
 
-The nested obseravbles may complicate the signature, but they allow the groups to start emitting their items before the source observable has completed.
+The nested observables may complicate the signature, but they offer the advantage of allowing the groups to start emitting their items before the source observable has completed.
 
 In the next example, we will take a set of words and, for each starting letter, we will print the last word that occured.
 
@@ -511,7 +515,7 @@ t: third
 f: fifth
 ```
 
-We will formally introduce `map` and `flatMap` in the next chapter.
+`map` and `flatMap` are unknown for now. We will introduce them properly in the next chapter.
 
 # Nested observables
 
@@ -547,7 +551,7 @@ Output
 2
 ```
 
-Nesting observables to consume them doesn't make much sense. Towards the end of the pipeline, you'd rather flatten and simply your observables. Nesting is useful when you need to make a non-nested observable be of the same type as a nested observable that you have from elsewhere. Once they are of the same type, you can for example combine them, as we will see in the chapter about [combining sequences](/Part 3 - Taming the sequence/4. Combining sequences.md).
+Nesting observables to consume them doesn't make much sense. Towards the end of the pipeline, you'd rather flatten and simply your observables, rather than nest them. Nesting is useful when you need to make a non-nested observable be of the same type as a nested observable that you have from elsewhere. Once they are of the same type, you can combine them, as we will see in the chapter about [combining sequences](/Part 3 - Taming the sequence/4. Combining sequences.md).
 
 
 
