From 818da57e0d5063428e29420e0405221080b5af5b Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Tue, 5 Nov 2024 17:05:44 +0100 Subject: [PATCH] Ale review --- docs/topics/control-flow.md | 56 +++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 24 deletions(-) diff --git a/docs/topics/control-flow.md b/docs/topics/control-flow.md index b651d0e82f8..084e7c1f28a 100644 --- a/docs/topics/control-flow.md +++ b/docs/topics/control-flow.md @@ -27,10 +27,12 @@ fun main() { // You can also use `else if` in expressions: val maxLimit = 1 val maxOrLimit = if (maxLimit > a) maxLimit else if (a > b) a else b - - //sampleEnd + println("max is $max") + // max is 3 println("maxOrLimit is $maxOrLimit") + // maxOrLimit is 3 + //sampleEnd } ``` {kotlin-runnable="true" kotlin-min-compiler-version="1.3" id="if-else-if-kotlin"} @@ -52,7 +54,7 @@ assigning it to a variable, the `else` branch is mandatory. ## When expressions and statements -`when` is a conditional expression that executes code based on multiple possible values or conditions. It is +`when` is a conditional expression that runs code based on multiple possible values or conditions. It is similar to the `switch` statement in Java, C, and similar languages. For example: ```kotlin @@ -64,6 +66,7 @@ fun main() { 2 -> print("x == 2") else -> print("x is neither 1 nor 2") } + // x == 2 //sampleEnd } ``` @@ -72,7 +75,7 @@ fun main() { `when` matches its argument against all branches sequentially until some branch condition is satisfied. You can use `when` in a few different ways. Firstly, you can use `when` either as an **expression** or as a **statement**. -As an expression, `when` returns a value that you can use later in your code. As a statement, `when` completes an action +As an expression, `when` returns a value for later use in your code. As a statement, `when` completes an action without returning anything of further use: @@ -110,7 +113,9 @@ when (x) {
-Secondly, you can use `when` with or without a subject. +Secondly, you can use `when` with or without a subject. Whether you use a subject with `when` or not, your expression or +statement behaves the same. We recommend using `when`with a subject when possible, as it makes your code easier to read +and maintain by clearly showing what you're checking. @@ -135,15 +140,11 @@ when { ... }
-> Where possible, we recommend using `when` with a subject. Using `when` with a subject makes your code easier to read -> and maintain by clearly showing what is being checked. -> -{style="note"} - Depending on how you use `when`, there are different requirements for whether you need to cover all possible cases in your branches. -If you use `when` as a statement, you don't have to cover all possible cases: +If you use `when` as a statement, you don't have to cover all possible cases. In this example, some cases aren't covered, +so nothing happens. However, no error occurs: ```kotlin fun main() { @@ -154,6 +155,7 @@ fun main() { 1 -> print("x == 1") 2 -> print("x == 2") } + // x == 2 //sampleEnd } ``` @@ -162,8 +164,9 @@ fun main() { In a `when` statement, the values of individual branches are ignored. Just like with `if`, each branch can be a block, and its value is the value of the last expression in the block. -If you use `when` as an expression, you have to cover all possible cases. The value of the first matching branch becomes -the value of the overall expression. If you don't cover all cases, the compiler throws an error. +If you use `when` as an expression, you have to cover all possible cases. In other words, it must be _exhaustive_. +The value of the first matching branch becomes the value of the overall expression. If you don't cover all cases, +the compiler throws an error. If your `when` expression has a subject, you can use an `else` branch to make sure that all possible cases are covered, but it isn't mandatory. For example, if your subject is a `Boolean`, [`enum` class](enum-classes.md), [`sealed` class](sealed-classes.md), @@ -192,8 +195,8 @@ when { } ``` -`when` expressions and statements can be used in a number of different ways to simplify your code, handle multiple conditions, -and perform type checks. +`when` expressions and statements offer different ways to simplify your code, handle multiple conditions, and perform +type checks. You can define a common behavior for multiple cases by combining their conditions in a single line with a comma: @@ -224,7 +227,7 @@ when (x) { } ``` -Additionally, you can check that a value `is` or `!is` a particular type. Note that, +Additionally, you can check that a value is or isn't a particular type via the `is` or `!is` keywords. Note that, due to [smart casts](typecasts.md#smart-casts), you can access the member functions and properties of the type without any additional checks. @@ -236,7 +239,7 @@ fun hasPrefix(x: Any) = when(x) { ``` You can use `when` as a replacement for an `if`-`else` `if` chain. -If there's no subject, the branch conditions are simply boolean expressions, and a branch is executed when its condition is true: +If there's no subject, the branch conditions are simply boolean expressions, and a branch is run when its condition is true: ```kotlin when { @@ -289,11 +292,12 @@ To iterate over a range of numbers, use a [range expression](ranges.md): fun main() { //sampleStart for (i in 1..3) { - println(i) + print(i) } for (i in 6 downTo 0 step 2) { - println(i) + print(i) } + // 1236420 //sampleEnd } ``` @@ -308,8 +312,9 @@ fun main() { val array = arrayOf("a", "b", "c") //sampleStart for (i in array.indices) { - println(array[i]) + print(array[i]) } + // abc //sampleEnd } ``` @@ -324,6 +329,9 @@ fun main() { for ((index, value) in array.withIndex()) { println("the element at $index is $value") } + // the element at 0 is a + // the element at 1 is b + // the element at 2 is c //sampleEnd } ``` @@ -331,11 +339,11 @@ fun main() { ## While loops -`while` and `do-while` loops execute their body continuously while their condition is satisfied. +`while` and `do-while` loops process their body continuously while their condition is satisfied. The difference between them is the condition checking time: -* `while` checks the condition and, if it's satisfied, executes the body and then returns to the condition check. -* `do-while` executes the body and then checks the condition. If it's satisfied, the loop repeats. So, the body of `do-while` -executes at least once regardless of the condition. +* `while` checks the condition and, if it's satisfied, processes the body and then returns to the condition check. +* `do-while` processes the body and then checks the condition. If it's satisfied, the loop repeats. So, the body of `do-while` +runs at least once regardless of the condition. ```kotlin while (x > 0) {