chore: update introduction

Author: AlexanderPrendota

examples/01_introduction/02_Functions.md

@@ -0,0 +1,143 @@
+# Functions
+
+### Default parameter values and named arguments
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+fun printMessage(message: String): Unit {                           // 1
+    println(message)
+}
+
+fun printMessageWithPrefix(message: String, prefix : String = "") { // 2
+    println("[$prefix] $message")
+}
+
+fun sum(x: Int, y: Int): Int {                                      // 3
+    return x + y
+}
+
+fun multiply(x: Int, y: Int) = x * y                                // 4
+
+fun main() {
+    printMessage("Hello")                                           // 5                    
+    printMessageWithPrefix("Hello", "Log")                          // 6
+    printMessageWithPrefix("Hello")                                 // 7
+    printMessageWithPrefix(prefix = "Log", message = "Hello")       // 8
+    sum(1, 2)
+}
+```
+
+</div>
+
+1. Create a function that takes a parameter of type string and returns Unit (i.e. no return value).
+2. Create a function that takes a second optional parameter with default value empty String. Also return Unit, which can be omitted.
+3. Create a function that returns an integer.
+4. Create a single-expression function that returns an integer (inferred).
+5. Call a function passing as argument `Hello`.
+6. Call a function with two parameters, passing a value for the second optional parameter.
+7. Call a function with two parameters, ignoring the second one. 
+8. Call a function using named parameters and changing order of arguments.
+
+### Infix functions
+
+Member functions and extensions with a single parameter can be turned into infix functions.
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+fun main() {
+
+  infix fun Int.times(str: String) = str.repeat(this)        // 1
+  println(2 times "Bye ")                                    // 2
+
+  val pair = "Ferrari" to "Katrina"                          // 3
+  println(pair)
+
+  infix fun String.onto(other: String) = Pair(this, other)   // 4
+  val myPair = "McLaren" onto "Lucas"
+  println(myPair)
+
+  val sophia = Person("Sophia")
+  val claudia = Person("Claudia")
+  sophia likes claudia                                       // 5
+}
+
+class Person(val name: String) {
+  val likedPeople = mutableListOf<Person>()
+  infix fun likes(other: Person) { likedPeople.add(other) }  // 6
+}
+```
+
+</div>
+
+1. Defines an infix extension function on `Int`
+2. Call infix function `1`
+3. The infix function `to` from the standard library lets you easily create `Pair`s
+4. Here's your own implementation of `to` creatively called `onto`
+5. Extensions also work on members functions (methods).
+6. The containing class becomes the first parameter.
+
+Note that the example uses _local functions_ (functions nested into another function).
+
+### Operator functions
+
+Certain functions can be "upgraded" to operators, allowing to use them with the corresponding operator symbol.
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+fun main() {
+//sampleStart
+
+  operator fun Int.times(str: String) = str.repeat(this)       // 1
+  println(2 * "Bye ")                                          // 2
+
+  operator fun String.get(range: IntRange) = substring(range)  // 3
+  val str = "Always forgive your enemies; nothing annoys them so much."
+  println(str[0..14])                                          // 4
+//sampleEnd
+}
+```
+
+</div>
+
+1. This takes the infix function from above one step further using the `operator` modifier.
+2. The operator symbol for `times()` is `*` so that you can call the function using `2 * "Bye"`
+3. An operator function allowing easy range access on strings
+4. The `get()` operator enables bracket-access syntax
+
+### Functions with `vararg` parameters
+
+Varargs allow passing any number of arguments by comma-separating them.
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+fun main() {
+//sampleStart
+  fun printAll(vararg messages: String) {                            // 1
+    for (m in messages) println(m)
+  }
+  printAll("Hello", "Hallo", "Salut", "Hola", "你好")                 // 2
+
+  fun printAllWithPrefix(vararg messages: String, prefix: String) {  // 3
+    for (m in messages) println(prefix + m)
+  }
+  printAllWithPrefix("Hello", "Hallo", "Salut", "Hola", "你好",
+    prefix = "Greeting: ")                                           // 4
+
+  fun log(vararg entries: String) {
+    printAll(*entries)                                               // 5
+  }
+//sampleEnd
+}
+```
+
+</div>
+
+1. The `vararg` modifier turns a parameter into a vararg.
+2. This allows calling `printAll` with any number of string arguments.
+3. Thanks to named parameters, you can even add another parameter of the same type after the vararg. This wouldn't be allowed in Java because there's no way to pass a value.
+4. Using named parameters, you can set a value to `prefix` despite the vararg.
+5. At runtime, a vararg is simply an array. To pass it along into a vararg parameter, you can use the special spread operator `*foo` to pass in `*entries` (a vararg of `String`) instead of `entries` (an `Array<String>`).

examples/01_introduction/03_Equality Checks.md

@@ -0,0 +1,68 @@
+# Variables
+
+Kotlin has powerful type inference. While you can explicitly declare the type of a variable, you'll usually let the
+compiler do the work by inferring it. While Kotlin does not enforce immutability, it is recommended.
+In essence use *val* over *var*.
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+fun main() {
+//sampleStart
+    var a: String = "initial"  // 1
+    println(a)
+    val b: Int = 1             // 2
+    val c = 3                  // 3
+//sampleEnd
+}
+```
+
+</div>
+
+1. Declare a mutable variable and initialise it
+2. Declare an immutable variable and initialise it
+3. Declare an immutable variable and initialise it. The compiler infers the type.
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+fun main() {
+//sampleStart
+    var e: Int  // 1
+    println(e)  // 2
+//sampleEnd
+}
+```
+
+</div>
+
+1. Declare a variable, but don't initialise it.
+2. Produces compiler error: Variable 'e' must be initialized
+
+Variable initialization can be postponed, but it must be initialized before the first read.
+ 
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+fun someCondition() = true 
+
+fun main() {
+//sampleStart
+    val d: Int  // 1
+    
+    if (someCondition()) {
+        d = 1   // 2
+    } else {
+        d = 2   // 2
+    }
+    
+    println(d) // 3
+//sampleEnd
+}
+```
+
+</div>
+
+1. Declare a variable, but don't initialise it.
+2. Initialize variable with different values depending on some condition.
+3. The first use of the variable.

examples/01_introduction/03_Variables.md

@@ -0,0 +1,33 @@
+# Classes
+
+The class declaration consists of the class name, the class header (specifying its type parameters, 
+the primary constructor etc.) and the class body, surrounded by curly braces. 
+Both the header and the body are optional; if the class has no body, curly braces can be omitted.
+    
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+class Customer                                  // 1
+
+class Contact(val id: Int, var email: String)   // 2
+
+fun main() {
+
+    val customer = Customer()                   // 3
+    
+    val contact = Contact(1, "[email protected]")  // 4
+
+    println(contact.id)                         // 5
+    contact.email = "[email protected]"            // 6
+}
+```
+
+</div>  
+
+
+1. Declare a class named `Customer` with parameterless constructor
+2. Declare a class with an immutable property `id`, a mutable property `email` and constructor with two parameters `id` and `name`
+3. Create an instance of the class `Customer`
+4. Create an instance of the class `Contact` using the constructor with two arguments
+5. Access the property `id`
+6. Write to the property `email`

examples/01_introduction/02_Null Safety.md renamed to examples/01_introduction/04_Null Safety.md

@@ -0,0 +1,91 @@
+# Generics
+
+Generics are one genericity mechanism that's become standard in modern languages. Generic classes and functions increase code reusability by encapsulating common logic that is independent of a particular generic type, like the logic inside a `List<T>` is independent of what `T` is.
+
+### Generic classes
+
+The first way to use generics in Kotlin is creating generic classes.
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+//sampleStart
+class MutableStack<E>(vararg items: E) {              // 1
+
+  private val elements = items.toMutableList()
+
+  fun push(element: E) = elements.add(element)        // 2
+
+  fun peek(): E = elements.last()                     // 3
+
+  fun pop(): E = elements.removeAt(elements.size - 1)
+
+  fun isEmpty() = elements.isEmpty()
+
+  fun size() = elements.size
+
+  override fun toString() = "MutableStack(${elements.joinToString()})"
+}
+//sampleEnd
+
+fun main() {
+  val stack = MutableStack(0.62, 3.14, 2.7)
+  stack.push(9.87)
+  println(stack)
+
+  println("peek(): ${stack.peek()}")
+  println(stack)
+
+  for (i in 1..stack.size()) {
+    println("pop(): ${stack.pop()}")
+    println(stack)
+  }
+}
+
+```
+
+</div>
+
+1. Defines a generic class `MutableStack<E>` where `E` is called the _generic type parameter_. At use-site, it is assigned to a concrete type such as `Int` by declaring a `MutableStack<Int>`.
+2. Inside the generic class, `E` can be used as a parameter like any other type.
+3. You can also use `E` as a return type.
+
+Note that the implementation makes heavy use of Kotlin's shorthand syntax for functions that can be defined in a single expression.
+
+
+### Generic functions
+
+You can also generify functions if their logic is independent of the concrete type. For instance, you can create a utility function to create mutable stacks more easily:
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+class MutableStack<E>(vararg items: E) {              // 1
+
+  private val elements = items.toMutableList()
+
+  fun push(element: E) = elements.add(element)        // 2
+
+  fun peek(): E = elements.last()                     // 3
+
+  fun pop(): E = elements.removeAt(elements.size - 1)
+
+  fun isEmpty() = elements.isEmpty()
+
+  fun size() = elements.size
+
+  override fun toString() = "MutableStack(${elements.joinToString()})"
+}
+
+//sampleStart
+fun <E> mutableStackOf(vararg elements: E) = MutableStack(*elements)
+
+fun main() {
+  val stack = mutableStackOf(0.62, 3.14, 2.7)
+}
+//sampleEnd
+```
+
+</div>
+
+Note how to compiler can infer the generic type from the parameters of `mutableStackOf` so that you don't have to write `mutableStackOf<Int>(...)`.