docs: revised Stdlib (Kotlin#54)

Author: p7nov

examples/05_stdlib/01_letFunction.md

@@ -1,40 +1,65 @@
 # let
 
-**let** is a useful function defined in Kotlin Standard Library. It can be used for scoping and null-checks. 
+`let` function  allows you to call a specified functional block on an object. This function is useful for scoping and null-checks. 
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
-var i = 0
-fun funWithSideEffect(): String = ".".repeat(i++)
-
-fun getNullableString0(): String? = null
-fun getNullableString1(): String? = null
-
 fun main() {
-//sampleStart
-    val r = funWithSideEffect().let {
-        it.isEmpty() || it.contains("Kotlin")                      // 1
-    }
-    println("r = $r")
 
+    fun checkStringContent(ns: String?) {
+            println("for \"$ns\":")
+    
+            ns.let {                                                  // 1
+                println("\tcontent: " + it)                           // 2
+            }
+        }
+        
+        checkStringContent(null)
+        checkStringContent("")
+        checkStringContent("some string with Kotlin")
+    
     fun checkNullableString(ns: String?) {
         println("for \"$ns\":")
 
-        ns?.let {                                                  // 2
-            println("\tis empty? " + it.isEmpty())
+        ns?.let {                                                   // 3
+            println("\tis empty? " + it.isEmpty())                  
             println("\tcontains Kotlin? " + it.contains("Kotlin"))
         }
     }
     checkNullableString(null)
     checkNullableString("")
     checkNullableString("some string with Kotlin")
-//sampleEnd
 }
+
 ```
 
 </div>
 
+1. Defines a code block to execute on `ns`.
+2. Inside the curly braces `ns` is accessible by the name `it`.
+3. Uses a null-safe call, so `let` and its code block are executed only on non-null values.   
+
+`let` can also be called on a result of another function execution:
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+fun getStringOfLength(l: Int) = ".".repeat(l)
+
+fun main() {    
+    fun checkString(l: Int) {
+    	val empty = getStringOfLength(l).let {
+            println("\"$it\" is empty: ${it.isEmpty()} ")    // 1
+
+    	}
+    }
+    
+    checkString(0)
+    checkString(1)
+}
+
+```
+
+</div>
 
-1. Result of `funWithSideEffect` is now accessible by reference `it`.
-2. Use safe call, so `let` and its code block will be executed only with non-null value.   
+1. Here `it` is the result of the `getStringOfLength(l)` call. 

examples/05_stdlib/02_withFunction.md

@@ -1,7 +1,6 @@
 # with
 
-*with* is a function defined in the standard library that can be used to access members of an object in a more concise way, avoiding having to
-prefix each member with the instance name. 
+*with* function lets you access members of an object in a short and concise way. Inside the `with` block you can refer to object members without specifying its name as a prefix. 
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 

examples/05_stdlib/03_filter.md

@@ -1,7 +1,6 @@
 # filter
 
-*filter* is a function defined in the standard library that can be used to filter collection. It takes a predicate as an lambda-parameters. 
-
+*filter* function enables you to filter collections. It takes a filter predicate as a lambda-parameter. The predicate is applied to each element. Elements that make the predicate `true` are returned in the result collection.
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
@@ -23,6 +22,6 @@ fun main() {
 
 </div>
 
-1. Define collection of numbers.
-2. Filter negative numbers.
-3. Or using even shorter way to filter positive numbers. 
+1. Defines collection of numbers.
+2. Gets positive numbers.
+3. Uses the shorter `it` notation to get negative numbers. 

examples/05_stdlib/04_map.md

@@ -1,6 +1,6 @@
 # map
 
-*map* is an extension function defined in the standard library that can be used to transform collection into another collection. It takes a transformer as an lambda-parameters.
+*map* extension function enables you to apply a transformation to all elements in a collection. It takes a transformer function as a lambda-parameter.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -23,6 +23,6 @@ fun main() {
 
 </div>
 
-1. Define collection of numbers.
-2. Double numbers.
-3. Or using even shorter way to triple numbers. 
+1. Defines a  collection of numbers.
+2. Doubles numbers.
+3. Uses the shorter `it` notation to triple the numbers. 

examples/05_stdlib/05_existential.md

@@ -1,10 +1,10 @@
 # any, all, none
 
-This extension functions answer the question about existence element(s) in collection based on given predicate.
+These functions check the existence of collection elements that match a given predicate.
 
 ### Function `any`
 
-Function `any` returns `true` if collection contains at least one element matching the given predicate.
+Function `any` returns `true` if the collection contains **at least one** element that matches the given predicate.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -27,14 +27,14 @@ fun main() {
 
 </div>
 
-1. Define collection of numbers.
-2. Whether there is an element less than `0`.
-3. Whether there is an element greater than `6`. 
+1. Defines a collection of numbers.
+2. Checks if there are negative elements.
+3. Checks if there are elements greater than `6`. 
 
 
 ### Function `all`
 
-Function `all` returns `true` iff all elements in collection matching the given predicate.
+Function `all` returns `true` if **all** elements in collection match the given predicate.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -57,14 +57,14 @@ fun main() {
 
 </div>
 
-1. Define collection of numbers.
-2. Whether all elements are even.
-3. Whether all elements less than `6`.
+1. Defines a collection of numbers.
+2. Checks whether all elements are even.
+3. Checks whether all elements are less than `6`.
 
 
 ### Function `none`
 
-Function `none` return `true` iff there is no element in collection matching the given predicate.
+Function `none` returns `true` if there are **no** elements that match the given predicate in the collection.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -87,7 +87,7 @@ fun main() {
 
 </div>
 
-1. Define collection of numbers.
-2. Whether there is no odd element which means all elements are even.
-3. If there is no element grater than 6.
+1. Defines a collection of numbers.
+2. Checks if there are no odd elements (all elements are even).
+3. Checks if there are no elements greater than 6.
 

examples/05_stdlib/06_find.md

@@ -1,6 +1,7 @@
-# find
+# find, findLast
+
+`find` and `findLast` functions return the first or the last collection element that matches the given predicate. If there are no such elements, functions return `null`.
 
-Returns the first or last element matching the given predicate, or `null` if no such element was found.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -24,7 +25,7 @@ fun main() {
 
 </div>
 
-1. Define collection of different words.
-2. Looking for the first word starting with "some".
-3. Looking for the last word starting with "some".
-4. Looking for the first word containing "nothing".
+1. Defines a collection of words.
+2. Looks for the first word starting with "some".
+3. Looks for the last word starting with "some".
+4. Looks for the first word containing "nothing".

examples/05_stdlib/07_firstlast.md

@@ -2,11 +2,9 @@
 
 ### `first`, `last`
 
-Those functions return either the first or last element of the collection or the first/last matching the given predicate.
+These functions return the first and the last element of the collection correspondingly. You can also use them with a predicate; in this case, they return the first or the last element that matches the given predicate.
 
-In case of empty collection or if nothing matching the predicate those function throw an `NoSuchElementException`.
-
-Lets make some Kotlin!
+If a collection is empty or doesn't contain elements matching the predicate, the functions throw `NoSuchElementException`.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -30,17 +28,15 @@ fun main() {
 
 </div>
 
-1. Define collection of numbers.
-2. Pick first element.
-3. Pick last element.
-4. Pick first even element.
-5. Pick last odd element.
-
+1. Defines a collection of numbers.
+2. Picks the first element.
+3. Picks the last element.
+4. Picks the first even element.
+5. Picks the last odd element.
 
 ### `firstOrNull`, `lastOrNull`
 
-Behaviour is almost the same instead if nothing was found the null is returned.
-
+These functions work almost the same way with one difference: they return `null` if there are no matching elements.
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
 ```kotlin
@@ -67,11 +63,11 @@ fun main() {
 
 </div>
 
-1. Define collection of different words.
-2. Define an empty collection.
-3. Pick the first element from empty collection. It supposed to be `null`
-4. Pick the last element from empty collection. It supposed to be `null` as well.
-5. Pick the first word starting with 'f'
-6. Pick the first word starting with 'z'
-7. Pick the last word ending with 'f'
-8. Pick the last word ending with 'z'
+1. Defines a collection of words.
+2. Defines an empty collection.
+3. Picks the first element from empty collection. It supposed to be `null`.
+4. Picks the last element from empty collection. It supposed to be `null` as well.
+5. Picks the first word starting with 'f'.
+6. Picks the first word starting with 'z'.
+7. Picks the last word ending with 'f'.
+8. Picks the last word ending with 'z'.

examples/05_stdlib/08_count.md

@@ -1,6 +1,6 @@
 # count
 
-The extension function `count` returns either the total number of elements in collection or the number of elements matching the given predicate.
+`count` functions returns either the total number of elements in a collection or the number of elements matching the given predicate.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -21,6 +21,6 @@ fun main() {
 
 </div>
 
-1. Define collection of numbers.
-2. Count total number of elements.
-3. Count number of even elements.
+1. Defines a collection of numbers.
+2. Counts the total number of elements.
+3. Counts the number of even elements.

examples/05_stdlib/09_partition.md

@@ -1,6 +1,8 @@
 # partition
 
-This function splits the original collection into pair of lists, where first list contains elements for which predicate yielded `true`, while second list contains elements for which predicate yielded `false`.
+`partition` function splits the original collection into pair of lists using a given predicate:
+ * Elements for which the predicate is `true`.
+ * Elements for which the predicate is `false`.
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 
@@ -10,16 +12,21 @@ fun main() {
 //sampleStart
     val numbers = listOf(1, -2, 3, -4, 5, -6)                // 1
 
-    val (postives, negatives) = numbers.partition { it > 0 } // 2
+    val evenOdd = numbers.partition { it % 2 == 0 }           // 2
+    val (positives, negatives) = numbers.partition { it > 0 } // 3
 //sampleEnd
 
     println("Numbers: $numbers")
-    println("Positive numbers: $postives")
+    println("Odd numbers: ${evenOdd.first}")
+    println("Odd numbers: ${evenOdd.second}")
+    println("Positive numbers: $positives")
     println("Negative numbers: $negatives")
 }
+
 ```
 
 </div>
 
-1. Define collection of numbers.
-2. Use `partition` to split `numbers` into two lists with positive and negative numbers. Also apply destructuring to get members of returning `Pair`
+1. Defines a collection of numbers.
+2. Splits `numbers` into a `Pair` of lists with even and odd numbers.
+3. Splits `numbers` into two lists with positive and negative numbers. Pair destructuring is applied here to get the `Pair` members.

examples/05_stdlib/10_associateBy.md

@@ -1,9 +1,11 @@
 # associateBy, groupBy
 
-Both functions return a `Map` containing the elements from the given collection indexed by the key returned from `keySelector` function applied to each element.
-If `valueSelector` is also passed it is applied to each element as well.
+Functions `associateBy` and `groupBy` build maps from the elements of a collection indexed by the specified key. The key is defined in the `keySelector` parameter.
+You can also specify an optional `valueSelector` to define what will be stored in the `value` of the map element.
 
-The difference between `associateBy` and `groupBy` is the behaviour for values with the same key. `associateBy` takes only last element when `groupBy` takes all elements into collection. 
+The difference between `associateBy` and `groupBy` is how they process objects with the same key:
+* `associateBy` uses the last suitable element as the value.
+* `groupBy` builds a list of all suitable elements and puts it in the value. 
 
 The returned map preserves the entry iteration order of the original collection.
 
@@ -37,8 +39,8 @@ fun main() {
 
 </div>
 
-1. Define data class descirbes a Person.
-2. Define collection of known people.
-3. Build a map from person's phone number to person information.
-4. Build another map from phone number to city where owner lives.
-5. Build the third map which contains cities and people living there.
+1. Defines a data class that descirbes a person.
+2. Defines a collection of people.
+3. Builds a map from phone numbers to their owners' information. `it.phone` is the `keySelector` here. The `valueSelector` is not provided, so the values of the map are `Person` objects themselves.
+4. Builds a map from phone numbers to the cities where owners live. `Person::city` is the `valueSelector` here, so the values of the map contain only cities. 
+5. Builds a map that contains cities and people living there. The values of the map are lists of person names.