From 557b1be23f1be95923b0f0d9fb035e9f6deab23f Mon Sep 17 00:00:00 2001 From: alfredo-toledano Date: Sat, 24 Aug 2024 21:26:32 +0200 Subject: [PATCH] doc(docs.topics.basicSyntax): add notes --- docs/topics/basic-syntax/basic-syntax.md | 292 +---------------------- 1 file changed, 8 insertions(+), 284 deletions(-) diff --git a/docs/topics/basic-syntax/basic-syntax.md b/docs/topics/basic-syntax/basic-syntax.md index 8be24997674..f5cdf629c9c 100644 --- a/docs/topics/basic-syntax/basic-syntax.md +++ b/docs/topics/basic-syntax/basic-syntax.md @@ -85,311 +85,35 @@ ## Conditional expressions -* TODO: -```kotlin -//sampleStart -fun maxOf(a: Int, b: Int): Int { - if (a > b) { - return a - } else { - return b - } -} -//sampleEnd - -fun main() { - println("max of 0 and 42 is ${maxOf(0, 42)}") -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-conditional-expressions"} - -In Kotlin, `if` can also be used as an expression: - -```kotlin -//sampleStart -fun maxOf(a: Int, b: Int) = if (a > b) a else b -//sampleEnd - -fun main() { - println("max of 0 and 42 is ${maxOf(0, 42)}") -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-if-expression"} - -See [`if`-expressions](docs/topics/control-flow.md#if-expression). +* Check [Kotlin Tour Control Flow](docs/tour/kotlin-tour-control-flow/kotlin-tour-control-flow.md) ## for loop -```kotlin -fun main() { -//sampleStart - val items = listOf("apple", "banana", "kiwifruit") - for (item in items) { - println(item) - } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-for-loop"} - -or: - -```kotlin -fun main() { -//sampleStart - val items = listOf("apple", "banana", "kiwifruit") - for (index in items.indices) { - println("item at $index is ${items[index]}") - } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-for-loop-indices"} - -See [for loop](docs/topics/control-flow.md#for-loops). +* Check [Kotlin Tour Control Flow](docs/tour/kotlin-tour-control-flow/kotlin-tour-control-flow.md) & [for loop](docs/topics/control-flow.md#for-loops) ## while loop -```kotlin -fun main() { -//sampleStart - val items = listOf("apple", "banana", "kiwifruit") - var index = 0 - while (index < items.size) { - println("item at $index is ${items[index]}") - index++ - } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-while-loop"} - -See [while loop](docs/topics/control-flow.md#while-loops). +* Check [Kotlin Tour Control Flow](docs/tour/kotlin-tour-control-flow/kotlin-tour-control-flow.md) & [while loop](docs/topics/control-flow.md#while-loops) ## when expression -```kotlin -//sampleStart -fun describe(obj: Any): String = - when (obj) { - 1 -> "One" - "Hello" -> "Greeting" - is Long -> "Long" - !is String -> "Not a string" - else -> "Unknown" - } -//sampleEnd - -fun main() { - println(describe(1)) - println(describe("Hello")) - println(describe(1000L)) - println(describe(2)) - println(describe("other")) -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-when-expression"} - -See [when expression](docs/topics/control-flow.md#when-expression). +* Check [Kotlin Tour Control Flow](docs/tour/kotlin-tour-control-flow/kotlin-tour-control-flow.md) & [when expression](docs/topics/control-flow.md#when-expression) ## Ranges -Check if a number is within a range using `in` operator: - -```kotlin -fun main() { -//sampleStart - val x = 10 - val y = 9 - if (x in 1..y+1) { - println("fits in range") - } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-range-in"} - -Check if a number is out of range: - -```kotlin -fun main() { -//sampleStart - val list = listOf("a", "b", "c") - - if (-1 !in 0..list.lastIndex) { - println("-1 is out of range") - } - if (list.size !in list.indices) { - println("list size is out of valid list indices range, too") - } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-out-of-range"} - -Iterate over a range: - -```kotlin -fun main() { -//sampleStart - for (x in 1..5) { - print(x) - } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-iterate-range"} - -Or over a progression: - -```kotlin -fun main() { -//sampleStart - for (x in 1..10 step 2) { - print(x) - } - println() - for (x in 9 downTo 0 step 3) { - print(x) - } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-iterate-progression"} - -See [Ranges and progressions](docs/topics/ranges.md). +* Check [Kotlin Tour Control Flow](docs/tour/kotlin-tour-control-flow/kotlin-tour-control-flow.md) & [Ranges and progressions](docs/topics/ranges.md) ## Collections -Iterate over a collection: - -```kotlin -fun main() { - val items = listOf("apple", "banana", "kiwifruit") -//sampleStart - for (item in items) { - println(item) - } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-iterate-collection"} - -Check if a collection contains an object using `in` operator: - -```kotlin -fun main() { - val items = setOf("apple", "banana", "kiwifruit") -//sampleStart - when { - "orange" in items -> println("juicy") - "apple" in items -> println("apple is fine too") - } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-collection-in"} - -Use [lambda expressions](lambdas.md) to filter and map collections: - -```kotlin -fun main() { -//sampleStart - val fruits = listOf("banana", "avocado", "apple", "kiwifruit") - fruits - .filter { it.startsWith("a") } - .sortedBy { it } - .map { it.uppercase() } - .forEach { println(it) } -//sampleEnd -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-collection-filter-map"} - -See [Collections overview](docs/topics/collections-overview.md). +* Check [Kotlin Tour Collections](docs/tour/kotlin-tour-collections/kotlin-tour-collections.md) & [Collections overview](docs/topics/collections-overview.md) ## Nullable values and null checks -A reference must be explicitly marked as nullable when `null` value is possible. Nullable type names have `?` at the end. - -Return `null` if `str` does not hold an integer: - -```kotlin -fun parseInt(str: String): Int? { - // ... -} -``` - -Use a function returning nullable value: - -```kotlin -fun parseInt(str: String): Int? { - return str.toIntOrNull() -} - -//sampleStart -fun printProduct(arg1: String, arg2: String) { - val x = parseInt(arg1) - val y = parseInt(arg2) - - // Using `x * y` yields error because they may hold nulls. - if (x != null && y != null) { - // x and y are automatically cast to non-nullable after null check - println(x * y) - } - else { - println("'$arg1' or '$arg2' is not a number") - } -} -//sampleEnd - -fun main() { - printProduct("6", "7") - printProduct("a", "7") - printProduct("a", "b") -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-function-nullable-value"} - -or: - -```kotlin -fun parseInt(str: String): Int? { - return str.toIntOrNull() -} - -fun printProduct(arg1: String, arg2: String) { - val x = parseInt(arg1) - val y = parseInt(arg2) - -//sampleStart - // ... - if (x == null) { - println("Wrong number format in arg1: '$arg1'") - return - } - if (y == null) { - println("Wrong number format in arg2: '$arg2'") - return - } - - // x and y are automatically cast to non-nullable after null check - println(x * y) -//sampleEnd -} - -fun main() { - printProduct("6", "7") - printProduct("a", "7") - printProduct("99", "b") -} -``` -{kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="kotlin-basic-syntax-function-null-check"} - -See [Null-safety](docs/topics/null-safety.md). +* Check [Kotlin Tour Collections](docs/tour/kotlin-tour-null-safety/kotlin-tour-null-safety.md) & [Null-safety](docs/topics/null-safety.md) ## Type checks and automatic casts +* TODO: The `is` operator checks if an expression is an instance of a type. If an immutable local variable or property is checked for a specific type, there's no need to cast it explicitly: