Nitpicks on 2.13’s collections guide

Author: julienrf

_overviews/collections-2.13/arrays.md

@@ -47,7 +47,7 @@ The difference between the two implicit conversions on arrays is shown in the ne
     scala> ops.reverse
     res3: Array[Int] = Array(3, 2, 1)
 
-You see that calling reverse on `seq`, which is an `ArraySeq`, will give again a `ArraySeq`. That's logical, because wrapped arrays are `Seqs`, and calling reverse on any `Seq` will give again a `Seq`. On the other hand, calling reverse on the ops value of class `ArrayOps` will give an `Array`, not a `Seq`.
+You see that calling reverse on `seq`, which is an `ArraySeq`, will give again a `ArraySeq`. That's logical, because arrayseqs are `Seqs`, and calling reverse on any `Seq` will give again a `Seq`. On the other hand, calling reverse on the ops value of class `ArrayOps` will give an `Array`, not a `Seq`.
 
 The `ArrayOps` example above was quite artificial, intended only to show the difference to `ArraySeq`. Normally, you'd never define a value of class `ArrayOps`. You'd just call a `Seq` method on an array:
 

_overviews/collections-2.13/seqs.md

@@ -22,7 +22,7 @@ The operations on sequences, summarized in the table below, fall into the follow
 * **Update operations** `updated`, `patch`, which return a new sequence obtained by replacing some elements of the original sequence.
 * **Sorting operations** `sorted`, `sortWith`, `sortBy`, which sort sequence elements according to various criteria.
 * **Reversal operations** `reverse`, `reverseIterator`, which yield or process sequence elements in reverse order.
-* **Comparisons** `startsWith`, `endsWith`, `contains`, `containsSlice`, `corresponds`, which relate two sequences or search an element in a sequence.
+* **Comparisons** `startsWith`, `endsWith`, `contains`, `containsSlice`, `corresponds`, `search`, which relate two sequences or search an element in a sequence.
 * **Multiset** operations `intersect`, `diff`, `distinct`, `distinctBy`, which perform set-like operations on the elements of two sequences or remove duplicates.
 
 If a sequence is mutable, it offers in addition a side-effecting `update` method, which lets sequence elements be updated. As always in Scala, syntax like `seq(idx) = elem` is just a shorthand for `seq.update(idx, elem)`, so `update` gives convenient assignment syntax for free. Note the difference between `update` and `updated`. `update` changes a sequence element in place, and is only available for mutable sequences. `updated` is available for all sequences and always returns a new sequence instead of modifying the original.
@@ -61,19 +61,19 @@ If a sequence is mutable, it offers in addition a side-effecting `update` method
 |  **Reversals:** 	    |						     |
 |  `xs.reverse`	            |A sequence with the elements of `xs` in reverse order.|
 |  `xs.reverseIterator`	    |An iterator yielding all the elements of `xs` in reverse order.|
-|  `xs reverseMap f`	    |A sequence obtained by mapping `f` over the elements of `xs` in reverse order.|
 |  **Comparisons:** 	    |						     |
 |  `xs sameElements ys`	    |A test whether `xs` and `ys` contain the same elements in the same order|
 |  `xs startsWith ys`	    |Tests whether `xs` starts with sequence `ys` (several variants exist).|
 |  `xs endsWith ys`	    |Tests whether `xs` ends with sequence `ys` (several variants exist).|
 |  `xs contains x`	    |Tests whether `xs` has an element equal to `x`.|
+|  `xs search x`        |Tests whether a sorted sequence `xs` has an element equal to `x`, possibly in a more efficient way than `xs contains x`.|
 |  `xs containsSlice ys`    |Tests whether `xs` has a contiguous subsequence equal to `ys`.|
 |  `(xs corresponds ys)(p)` |Tests whether corresponding elements of `xs` and `ys` satisfy the binary predicate `p`.|
 |  **Multiset Operations:** |						     |
 |  `xs intersect ys`	    |The multi-set intersection of sequences `xs` and `ys` that preserves the order of elements in `xs`.|
 |  `xs diff ys`	    	    |The multi-set difference of sequences `xs` and `ys` that preserves the order of elements in `xs`.|
 |  `xs.distinct`	    |A subsequence of `xs` that contains no duplicated element.|
-|  `xs distinctBy f`	    |A subsequence of `xs` that contains no duplicated element after applying the transforming function `f`. For instance, `List("foo", "bar", "quux").distinctBy(_.length) == List("foo", "quux")`|
+|  `xs distinctBy f`	    |A subsequence of `xs` that contains no duplicated element after applying the transforming function `f`. For instance, `List("foo", "bar", "quux").distinctBy(_.length) == List("foo", "bar")`|
 
 Trait [Seq](http://www.scala-lang.org/api/current/scala/collection/Seq.html) has two subtraits [LinearSeq](http://www.scala-lang.org/api/current/scala/collection/LinearSeq.html), and [IndexedSeq](http://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html). These do not add any new operations to the immutable branch, but each offers different performance characteristics: A linear sequence has efficient `head` and `tail` operations, whereas an indexed sequence has efficient `apply`, `length`, and (if mutable) `update` operations. Frequently used linear sequences are `scala.collection.immutable.List` and `scala.collection.immutable.LazyList`. Frequently used indexed sequences are `scala.Array` and `scala.collection.mutable.ArrayBuffer`. The `Vector` class provides an interesting compromise between indexed and linear access. It has both effectively constant time indexing overhead and constant time linear access overhead. Because of this, vectors are a good foundation for mixed access patterns where both indexed and linear accesses are used. You'll learn more on vectors [later](concrete-immutable-collection-classes.html).
 
@@ -106,8 +106,9 @@ Two often used implementations of buffers are `ListBuffer` and `ArrayBuffer`.  A
 |  `buf appendAll xs`<br>or`buf ++= xs`         |Appends all elements in `xs` to buffer.|
 |  `buf prepend x`<br>or `x +=: buf`            |Prepends element `x` to buffer.|
 |  `buf prependAll xs`<br>or `xs ++=: buf`      |Prepends all elements in `xs` to buffer.|
-|  `buf insert (i, x)`     |Inserts element `x` at index `i` in buffer.|
-|  `buf insertAll (i, xs)` |Inserts all elements in `xs` at index `i` in buffer.|
+|  `buf.insert(i, x)`      |Inserts element `x` at index `i` in buffer.|
+|  `buf.insertAll(i, xs)`  |Inserts all elements in `xs` at index `i` in buffer.|
+|  `buf.padToInPlace(n, x)`                     |Appends element `x` to buffer until it has `n` elements in total.|
 |  **Removals:**           |                                                                  |
 |  `buf subtractOne x`<br>or `buf -= x`         |Removes element `x` from buffer.|
 |  `buf subtractAll xs`<br>or `buf --= xs`      |Removes elements in `xs` from buffer.|
@@ -116,15 +117,7 @@ Two often used implementations of buffers are `ListBuffer` and `ArrayBuffer`.  A
 |  `buf trimStart n`       |Removes first `n` elements from buffer.|
 |  `buf trimEnd n`         |Removes last `n` elements from buffer.|
 |  `buf.clear()`           |Removes all elements from buffer.|
-|  **Cloning:**            |                                                                  |
-|  `buf.clone`             |A new buffer with the same elements as `buf`.|
-|  **Transformations:**       | |
+|  **Replacement:**        | |
 |  `buf.patchInPlace(i, xs, n)`   |Replaces (at most) `n` elements of buffer by elements in `xs`, starting from index `i` in buffer.|
-|  `buf dropInPlace n`            |Like `buf trimStart n`, but returns `buf` itself as result.|
-|  `buf dropRightInPlace n`       |Like `buf trimEnd n`, but returns `buf` itself as result.|
-|  `buf takeInPlace n`            |Keeps the `n` first elements of the buffer.|
-|  `buf takeRightInPlace n`       |Keeps the `n` last elements of the buffer.|
-|  `buf.sliceInPlace(from, until)`|Like `buf.takeInPlace(until).dropInPlace(from)`.|
-|  `buf dropWhileInPlace p`       |Removes the first elements that satisfy the predicate `p`.|
-|  `buf takeWhileInPlace p`       |Keeps the first elements that satisfy the predicate `p`.|
-|  `buf.padToInPlace(n, x)`       |Appends element `x` to buffer until it has `n` elements in total.|
+|  **Cloning:**            |                                                                  |
+|  `buf.clone()`           |A new buffer with the same elements as `buf`.|

_overviews/collections-2.13/sets.md

@@ -28,7 +28,7 @@ For example:
 
 
 * **Additions** `incl` and `concat` (or `+` and `++`, respectively), which add one or more elements to a set, yielding a new set.
-* **Removals** `excl` and `removeAll` (or `-` and `--`, respectively), which remove one or more elements from a set, yielding a new set.
+* **Removals** `excl` and `removedAll` (or `-` and `--`, respectively), which remove one or more elements from a set, yielding a new set.
 * **Set operations** for union, intersection, and set difference. Each of these operations exists in two forms: alphabetic and symbolic. The alphabetic versions are `intersect`, `union`, and `diff`, whereas the symbolic versions are `&`, `|`, and `&~`. In fact, the `++` that `Set` inherits from `Iterable` can be seen as yet another alias of `union` or `|`, except that `++` takes an `IterableOnce` argument whereas `union` and `|` take sets.
 
 ### Operations in Class Set ###
@@ -58,7 +58,7 @@ Immutable sets offer methods to add or remove elements by returning new `Set`s,
 |  `xs incl x`<br>or `xs + x`                 |The set containing all elements of `xs` as well as `x`.|
 |  **Removals:**               |						     |
 |  `xs excl x`<br>or `xs - x`  	            |The set containing all elements of `xs` except `x`.|
-|  `xs removeAll ys`<br>or `xs -- ys`  	            |The set containing all elements of `xs` except the elements of `ys`.|
+|  `xs removedAll ys`<br>or `xs -- ys`  	            |The set containing all elements of `xs` except the elements of `ys`.|
 
 Mutable sets offer in addition methods to add, remove, or update elements, which are summarized in below.
 

_overviews/collections-2.13/strings.md

@@ -22,7 +22,7 @@ Like arrays, strings are not directly sequences, but they can be converted to th
     res7: String = HELLO
     scala> str drop 3
     res8: String = lo
-    scala> str slice (1, 4)
+    scala> str.slice(1, 4)
     res9: String = ell
     scala> val s: Seq[Char] = str
     s: Seq[Char] = hello

_overviews/collections-2.13/trait-iterable.md

@@ -24,14 +24,14 @@ Collection classes that implement `Iterable` just need to define this method; al
 * **Map** operations `map`, `flatMap`, and `collect`, which produce a new collection by applying some function to collection elements.
 * **Conversions** `toArray`, `toList`, `toIterable`, `toSeq`, `toIndexedSeq`, `toStream`, `toSet`, `toMap`, which turn an `Iterable` collection into something more specific. All these conversions return their receiver argument unchanged if the run-time type of the collection already matches the demanded collection type. For instance, applying `toList` to a list will yield the list itself.
 * **Copying operations**  `copyToArray`. As its name implies, this copies collection elements to an array.
-* **Size info** operations `isEmpty`, `nonEmpty`, `size`, `knownSize`, `sizeCompare`. The number of elements of a collections can require a traversal in some cases (e.g. `List`). In other cases the collection can have an infinite number of elements (e.g. `LazyList.from(1)`).
+* **Size info** operations `isEmpty`, `nonEmpty`, `size`, `knownSize`, `sizeIs`. The number of elements of a collections can require a traversal in some cases (e.g. `List`). In other cases the collection can have an infinite number of elements (e.g. `LazyList.from(1)`).
 * **Element retrieval** operations `head`, `last`, `headOption`, `lastOption`, and `find`. These select the first or last element of a collection, or else the first element matching a condition. Note, however, that not all collections have a well-defined meaning of what "first" and "last" means. For instance, a hash set might store elements according to their hash keys, which might change from run to run. In that case, the "first" element of a hash set could also be different for every run of a program. A collection is _ordered_ if it always yields its elements in the same order. Most collections are ordered, but some (_e.g._ hash sets) are not-- dropping the ordering gives a little bit of extra efficiency. Ordering is often essential to give reproducible tests and to help in debugging. That's why Scala collections give ordered alternatives for all collection types. For instance, the ordered alternative for `HashSet` is `LinkedHashSet`.
 * **Sub-collection retrieval operations** `tail`, `init`, `slice`, `take`, `drop`, `takeWhile`, `dropWhile`, `filter`, `filterNot`, `withFilter`. These all return some sub-collection identified by an index range or some predicate.
-* **Subdivision operations** `splitAt`, `span`, `partition`, `groupBy`, which split the elements of this collection into several sub-collections.
+* **Subdivision operations** `splitAt`, `span`, `partition`, `partitionMap`, `groupBy`, `groupMap`, `groupMapReduce`, which split the elements of this collection into several sub-collections.
 * **Element tests** `exists`, `forall`, `count` which test collection elements with a given predicate.
 * **Folds** `foldLeft`, `foldRight`, `reduceLeft`, `reduceRight` which apply a binary operation to successive elements.
 * **Specific folds** `sum`, `product`, `min`, `max`, which work on collections of specific types (numeric or comparable).
-* **String** operations `mkString`, `addString`, `stringPrefix`, which give alternative ways of converting a collection to a string.
+* **String** operations `mkString`, `addString`, `className`, which give alternative ways of converting a collection to a string.
 * **View** operation: A view is a collection that's evaluated lazily. You'll learn more about views in [later](views.html).
 
 Two more methods exist in `Iterable` that return iterators: `grouped` and `sliding`. These iterators, however, do not return single elements but whole subsequences of elements of the original collection. The maximal size of these subsequences is given as an argument to these methods. The `grouped` method returns its elements in "chunked" increments, where `sliding` yields a sliding "window" over the elements. The difference between the two should become clear by looking at the following REPL interaction:
@@ -58,7 +58,7 @@ Two more methods exist in `Iterable` that return iterators: `grouped` and `slidi
 | WHAT IT IS  	  	    | WHAT IT DOES				     |
 | ------       	       	    | ------					     |
 |  **Abstract Method:**     |						     |
-|  `xs.iterator`	    |An `iterator` that yields every element in `xs`, in the same order as `foreach` traverses elements.|
+|  `xs.iterator`	    |An `iterator` that yields every element in `xs`.|
 |  **Other Iterators:**     |						     |
 |  `xs foreach f`	    |Executes function `f` for every element of `xs`.|
 |  `xs grouped size`   	    |An iterator that yields fixed-sized "chunks" of this collection.|
@@ -112,8 +112,8 @@ Two more methods exist in `Iterable` that return iterators: `grouped` and `slidi
 |  `xs span p`	    	    |Split `xs` according to a predicate, giving the pair of collections `(xs takeWhile p, xs.dropWhile p)`.|
 |  `xs partition p`	    |Split `xs` into a pair of collections; one with elements that satisfy the predicate `p`, the other with elements that do not, giving the pair of collections `(xs filter p, xs.filterNot p)`|
 |  `xs groupBy f`	    |Partition `xs` into a map of collections according to a discriminator function `f`.|
-|  `xs.groupMap(f, g)`|Partition `xs` into a map of collections according to a discriminator function `f`, and applying the transformation function `g` to each element in a group.|
-|  `xs.groupMapReduce(f, g, h)`|Partition `xs` according to a discriminator function `f`, and then combine the results of applying the function `g` to each element in a partition using the `h` function.|
+|  `xs.groupMap(f)(g)`|Partition `xs` into a map of collections according to a discriminator function `f`, and applies the transformation function `g` to each element in a group.|
+|  `xs.groupMapReduce(f)(g)(h)`|Partition `xs` according to a discriminator function `f`, and then combine the results of applying the function `g` to each element in a group using the `h` function.|
 |  **Element Conditions:**  |						     |
 |  `xs forall p`	    |A boolean indicating whether the predicate `p` holds for all elements of `xs`.|
 |  `xs exists p`	    |A boolean indicating whether the predicate `p` holds for some element in `xs`.|