chore(examples): add Declarations examples

Author: AlexanderPrendota

examples/03_declarations/00_description.md

@@ -0,0 +1 @@
+# Declarations

examples/03_declarations/01_Variables.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/03_declarations/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/03_declarations/03_Classes.md

@@ -0,0 +1,34 @@
+# 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/03_declarations/04_Inheritance.md

@@ -0,0 +1,89 @@
+# Inheritance
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+open class Dog {                // 1
+    open fun sayHello() {       // 2
+        println("wow wow!")
+    }
+}
+
+class Yorkshire : Dog() {       // 3
+    override fun sayHello() {   // 4
+        println("wif wif!")
+    }
+}
+
+fun main() {
+    val dog: Dog = Yorkshire()
+    dog.sayHello()
+}
+```
+
+</div>
+
+1. Kotlin classes are _final_ by default. If you want to allow overriding a
+    class, it must be marked with the `open` modifier.
+2. Kotlin methods are also _final_ by default. As with the classes, the `open`
+    modifier allows overriding them.
+3. A class is overriding by following the subclass name with
+    `: SuperclassName()`. The empty parentheses `()` indicate an invocation to
+    the default constructor of the superclass.
+4. Overriding methods or attributes requires the `override` modifier.
+
+### Inheriting without default constructor
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+//sampleStart
+open class Tiger(val origin: String) {
+    fun sayHello() {
+        println("A tiger from $origin says: grrhhh!")
+    }
+}
+
+class SiberianTiger : Tiger("Siberia")                  // 1
+
+fun main() {
+    val tiger: Tiger = SiberianTiger()
+    tiger.sayHello()
+}
+//sampleEnd
+```
+
+</div>
+
+1. When the superclass does not provide a default constructor, arguments must be
+    provided when invoking the superclass constructor from the subclass.
+
+
+### Bypass constructor arguments
+
+<div class="language-kotlin" theme="idea">
+
+```kotlin
+//sampleStart
+open class Lion(val name: String, val origin: String) {
+    fun sayHello() {
+        println("$name, the lion from $origin says: graoh!")
+    }
+}
+
+class Asiatic(name: String) : Lion(name = name, origin = "India") // 1
+
+fun main() {
+    val lion: Lion = Asiatic("Rufo")
+    lion.sayHello()
+}
+//sampleEnd
+```
+
+</div>
+
+
+1. Observe that `name` is neither a `var` nor `val` because it is a
+    constructor argument for `Asiatic`, whose value is passed to the `name`
+    attribute of `Lion` (it does not override it).
+