feat: add scope functions (Kotlin#70)

* docs: added scope functions, renamed chapter stdlib

* docs: added scope functions, renamed chapter stdlib

* docs: text corrections after proofread

Author: p7nov

examples/06_scope_functions/00_description.md

@@ -0,0 +1,2 @@
+# Scope Functions
+

examples/06_scope_functions/01_let.md

@@ -0,0 +1,42 @@
+# let
+
+The Kotlin standard library function `let` can be used for scoping and null-checks. When called on an object, `let` executes the given block of code and returns the result of its last expression.
+The object is accessible inside the block by the reference `it`. 
+
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+fun customPrint(s: String) {
+    print(s.toUpperCase())
+}
+
+fun main() {
+//sampleStart
+    val empty = "testKotlin".let {         // 1
+        customPrint(it)                    // 2
+        it.isEmpty()                       // 3
+    }
+    println(" is empty: $empty")
+
+
+    fun printNonNull(str: String?) {
+        println("Printing \"$str\":")
+
+        str?.let {                         // 4
+            print("\t")
+            customPrint(it)
+            println()
+        }
+    }
+    printNonNull(null)
+    printNonNull("my string") 
+//sampleEnd
+}
+```
+
+</div>
+
+1. Calls the given block on the result on the string "_test_".
+2. Calls the function on "_test_" by the `it` reference.
+3. `let` returns the value of this expression.
+4. Uses safe call, so `let` and its code block will be executed only on non-null values.   

examples/06_scope_functions/02_run.md

@@ -0,0 +1,32 @@
+# run
+
+Like [`let`](01_let.md), `run` is another scoping function from the standard library. Basically, it does the same: executes a code block and returns its result. 
+The difference is that inside `run` the object is accessed by `this`. This is useful when you want to call the object's methods rather than pass it as an argument.<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+
+fun main() {
+//sampleStart
+    fun getNullableLength(ns: String?) {
+        println("for \"$ns\":")
+        ns?.run {                                                  // 1
+            println("\tis empty? " + isEmpty())                    // 2
+            println("\tlength = $length")                           
+            length                                                 // 3
+        }
+    }
+    getNullableLength(null)
+    getNullableLength("")
+    getNullableLength("some string with Kotlin")
+//sampleEnd
+}
+```
+
+</div>
+
+
+1. Calls the given block on a nullable variable.
+2. Inside `run`, the object's members are accessed without its name.
+3. `run` returns the `length` of the given `String` if it's not `null`.     

examples/06_stdlib/02_withFunction.md renamed to examples/06_scope_functions/03_with.md

@@ -1,6 +1,8 @@
+
+
 # with
 
-*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. 
+`with` is a non-extension function that can access members of its argument concisely: you can omit the instance name when referring to its members. 
 
 <div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
 

examples/06_scope_functions/04_apply.md

@@ -0,0 +1,32 @@
+# apply
+
+`apply` executes a block of code on an object and returns the object itself. Inside the block, the object is referenced by `this`.
+This function is handy for initializing objects.  
+
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+data class Person(var name: String, var age: Int, var about: String) {
+    constructor() : this("", 0, "")
+}
+
+fun main() {
+//sampleStart
+    val jake = Person()                                     // 1
+    val stringDescription = jake.apply {                    // 2
+        name = "Jake"                                       // 3
+        age = 30
+        about = "Android developer"
+    }.toString()                                            // 4
+//sampleEnd
+    println(stringDescription)
+}
+```
+
+</div>
+
+
+1. Creates a `Person()` instance with default property values.
+2. Applies the code block (next 3 lines) to the instance.   
+3. Inside `apply`, it's equivalent to `jake.name = "Jake"`.
+4. The return value is the instance itself, so you can chain other operations.

examples/06_scope_functions/05_also.md

@@ -0,0 +1,32 @@
+# also
+
+`also` works like [`apply`](04_apply.md): it executes a given block and returns the object called.
+Inside the block, the object is referenced by `it`, so it's easier to pass it as an argument.
+This function is handy for embedding additional actions, such as logging in call chains. 
+
+<div class="language-kotlin" theme="idea" data-min-compiler-version="1.3">
+
+```kotlin
+data class Person(var name: String, var age: Int, var about: String) {
+             constructor() : this("", 0, "")
+}
+         
+fun writeCreationLog(p: Person) {
+    println("A new person ${p.name} was created.")              
+}
+         
+fun main() {
+//sampleStart
+    val jake = Person("Jake", 30, "Android developer")   // 1
+        .also {                                          // 2 
+            writeCreationLog(it)                         // 3
+    }
+//sampleEnd
+}
+```
+
+</div>
+
+1. Creates a `Person()` object with the given property values.
+2. Applies the given code block to the object. The return value is the object itself. 
+3. Calls the logging function passing the object as an argument.