From 7833e8fd0f22cff4d8e49c1ca90cb3a022e6e601 Mon Sep 17 00:00:00 2001 From: Dmitry Jemerov Date: Tue, 24 Mar 2015 12:52:27 +0100 Subject: [PATCH 1/3] minor updates to documentation on 'when' #KT-7078 Fixed --- docs/reference/control-flow.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/reference/control-flow.md b/docs/reference/control-flow.md index ee8dd9aa5fd..546ec5dfb83 100644 --- a/docs/reference/control-flow.md +++ b/docs/reference/control-flow.md @@ -62,10 +62,13 @@ when (x) { *when*{: .keyword } matches its argument against all branches consequently until some branch condition is satisfied. *when*{: .keyword } is an expression and results in the satisfied branch's right hand side. -If some of its branches return result in a value of type `Unit`, the whole expression has type `Unit`. -Note that the *else*{: .keyword } branch is mandatory, unless the compiler can prove that all possible cases are covered with branch conditions. +If some of the branches return a value of type `Unit`, the whole expression has type `Unit`. -If many cases should be handled in the same way, the branch conditions may be combined with a comma +The *else*{: .keyword } branch is evaluated if none of the other branch conditions are satisfied. +Note that if the return type of *when*{: .keyword } is not `Unit`, the *else*{: .keyword } branch is mandatory, +unless the compiler can prove that all possible cases are covered with branch conditions. + +If many cases should be handled in the same way, the branch conditions may be combined with a comma: ``` kotlin when (x) { @@ -104,7 +107,7 @@ val hasPrefix = when(x) { } ``` -*when*{: .keyword } can also be used as a replacement for an *if*{: .keyword }-*else*{: .keyword }-*if*{: .keyword } chain. +*when*{: .keyword } can also be used as a replacement for an *if*{: .keyword }-*else*{: .keyword } *if*{: .keyword } chain. If no argument is supplied, the branch conditions are simply boolean expressions, and a branch is executed when its condition is true: ``` kotlin @@ -115,6 +118,8 @@ when { } ``` +See the [grammar for *when*{: .keyword }](grammar.html#when). + ## For Loops From 8a06c613a7cd4063ab9ce053f6621b293e206dd2 Mon Sep 17 00:00:00 2001 From: Dmitry Jemerov Date: Tue, 24 Mar 2015 13:19:55 +0100 Subject: [PATCH 2/3] better wording for 'when' as statement vs. expression --- docs/reference/control-flow.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/reference/control-flow.md b/docs/reference/control-flow.md index 546ec5dfb83..efebad8396f 100644 --- a/docs/reference/control-flow.md +++ b/docs/reference/control-flow.md @@ -61,11 +61,12 @@ when (x) { ``` *when*{: .keyword } matches its argument against all branches consequently until some branch condition is satisfied. -*when*{: .keyword } is an expression and results in the satisfied branch's right hand side. -If some of the branches return a value of type `Unit`, the whole expression has type `Unit`. +*when*{: .keyword } can be used either as an expression or as a statement. If it is used as an expression, all branches +need to return a value of type other than `Unit`, and the value of the satisfied branch becomes the value of the +overall expression. If it is used as a statement, the values returned by individual branches are ignored. The *else*{: .keyword } branch is evaluated if none of the other branch conditions are satisfied. -Note that if the return type of *when*{: .keyword } is not `Unit`, the *else*{: .keyword } branch is mandatory, +If *when*{: .keyword } is used as an expression, the *else*{: .keyword } branch is mandatory, unless the compiler can prove that all possible cases are covered with branch conditions. If many cases should be handled in the same way, the branch conditions may be combined with a comma: From 25f1c7f92e87e40faf6b2756e9ca29f28b4cf2f8 Mon Sep 17 00:00:00 2001 From: Dmitry Jemerov Date: Tue, 24 Mar 2015 13:25:14 +0100 Subject: [PATCH 3/3] take 2 for better wording --- docs/reference/control-flow.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/reference/control-flow.md b/docs/reference/control-flow.md index efebad8396f..bbebce623b3 100644 --- a/docs/reference/control-flow.md +++ b/docs/reference/control-flow.md @@ -61,9 +61,10 @@ when (x) { ``` *when*{: .keyword } matches its argument against all branches consequently until some branch condition is satisfied. -*when*{: .keyword } can be used either as an expression or as a statement. If it is used as an expression, all branches -need to return a value of type other than `Unit`, and the value of the satisfied branch becomes the value of the -overall expression. If it is used as a statement, the values returned by individual branches are ignored. +*when*{: .keyword } can be used either as an expression or as a statement. If it is used as an expression, the value +of the satisfied branch becomes the value of the overall expression. If it is used as a statement, the values of +individual branches are ignored. (Just like with *if*{: .keyword }, each branch can be a block, and its value +is the value of the last expression in the block.) The *else*{: .keyword } branch is evaluated if none of the other branch conditions are satisfied. If *when*{: .keyword } is used as an expression, the *else*{: .keyword } branch is mandatory,