Document let_chains again
#1740
+172
−144
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,34 +1,40 @@ | ||
| r[expr.if] | ||
| # `if` expressions | ||
|
|
||
| r[expr.if.syntax] | ||
| ```grammar,expressions | ||
| IfExpression -> | ||
| `if` IfConditions BlockExpression | ||
| (`else` ( BlockExpression | IfExpression ) )? | ||
|
|
||
| IfConditions -> IfCondition ( `&&` IfCondition )* | ||
|
|
||
| IfCondition -> | ||
| Expression _except [StructExprStruct]_ | ||
| | `let` Pattern `=` Scrutinee _except [LazyBooleanExpression]_ | ||
| ``` | ||
| <!-- TODO: The exception above isn't accurate, see https://github.com/rust-lang/reference/issues/569 --> | ||
|
|
||
| r[expr.if.intro] | ||
| The syntax of an `if` expression is a sequence of one or more condition operands separated by `&&`, | ||
| followed by a consequent block, any number of `else if` conditions and blocks, and an optional trailing `else` block. | ||
|
|
||
| r[expr.if.condition] | ||
| Condition operands must be either an [_Expression_] with a [boolean type] or a conditional `let` match. | ||
|
|
||
| r[expr.if.condition-true] | ||
| If all of the condition operands evaluate to `true` and all of the `let` patterns successfully match their [scrutinee]s, | ||
| the consequent block is executed and any subsequent `else if` or `else` block is skipped. | ||
|
|
||
| r[expr.if.else-if] | ||
| If any condition operand evaluates to `false` or any `let` pattern does not match its scrutinee, | ||
| the consequent block is skipped and any subsequent `else if` condition is evaluated. | ||
|
|
||
| r[expr.if.else] | ||
| If all `if` and `else if` conditions evaluate to `false` then any `else` block is executed. | ||
|
|
||
| r[expr.if.result] | ||
| An `if` expression evaluates to the same value as the executed block, or `()` if no block is evaluated. | ||
|
|
||
| r[expr.if.type] | ||
| An `if` expression must have the same type in all situations. | ||
|
|
@@ -43,6 +49,7 @@ if x == 4 { | |
| println!("x is something else"); | ||
| } | ||
|
|
||
| // `if` can be used as an expression. | ||
| let y = if 12 * 15 > 150 { | ||
| "Bigger" | ||
| } else { | ||
|
|
@@ -52,39 +59,25 @@ assert_eq!(y, "Bigger"); | |
| ``` | ||
|
|
||
| r[expr.if.let] | ||
| ## `if let` patterns | ||
|
|
||
| r[expr.if.let.intro] | ||
| `let` patterns in an `if` condition allow binding new variables into scope when the pattern matches successfully. | ||
|
|
||
| The following examples illustrate bindings using `let` patterns: | ||
|
|
||
| ```rust | ||
| let dish = ("Ham", "Eggs"); | ||
|
|
||
| // This body will be skipped because the pattern is refuted. | ||
| if let ("Bacon", b) = dish { | ||
| println!("Bacon is served with {}", b); | ||
| } else { | ||
| // This block is evaluated instead. | ||
| println!("No bacon will be served"); | ||
| } | ||
|
|
||
| // This body will execute. | ||
| if let ("Ham", b) = dish { | ||
| println!("Ham is served with {}", b); | ||
| } | ||
|
|
@@ -94,47 +87,9 @@ if let _ = 5 { | |
| } | ||
| ``` | ||
|
|
||
| r[expr.if.let.or-pattern] | ||
| Multiple patterns may be specified with the `|` operator. | ||
| This has the same semantics as with `|` in [`match` expressions]: | ||
|
|
||
| ```rust | ||
| enum E { | ||
|
|
@@ -148,27 +103,71 @@ if let E::X(n) | E::Y(n) = v { | |
| } | ||
| ``` | ||
|
|
||
| r[expr.if.chains] | ||
| ## Chains of conditions | ||
|
|
||
| r[expr.if.chains.intro] | ||
| Multiple condition operands can be separated with `&&`. | ||
|
|
||
| r[expr.if.chains.order] | ||
| Similar to a `&&` [_LazyBooleanOperatorExpression_], each operand is evaluated from left-to-right until an operand evaluates as `false` or a `let` match fails, | ||
| in which case the subsequent operands are not evaluated. | ||
|
|
||
| r[expr.if.chains.bindings] | ||
| The bindings of each pattern are put into scope to be available for the next condition operand and the consequent block. | ||
|
|
||
| The following is an example of chaining multiple expressions, mixing `let` bindings and boolean expressions, and with expressions able to reference pattern bindings from previous expressions: | ||
|
|
||
| ```rust | ||
| fn single() { | ||
| let outer_opt = Some(Some(1i32)); | ||
|
|
||
| if let Some(inner_opt) = outer_opt | ||
| && let Some(number) = inner_opt | ||
| && number == 1 | ||
| { | ||
| println!("Peek a boo"); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The above is equivalent to the following without using chains of conditions: | ||
|
|
||
| ```rust | ||
| fn nested() { | ||
| let outer_opt = Some(Some(1i32)); | ||
|
|
||
| if let Some(inner_opt) = outer_opt { | ||
| if let Some(number) = inner_opt { | ||
| if number == 1 { | ||
| println!("Peek a boo"); | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| r[expr.if.chains.or] | ||
| If any condition operand is a `let` pattern, then none of the condition operands can be a `||` [lazy boolean operator expression][_LazyBooleanOperatorExpression_] due to ambiguity and precedence with the `let` scrutinee. | ||
| If a `||` expression is needed, then parentheses can be used. For example: | ||
|
|
||
| ```rust | ||
| # let foo = Some(123); | ||
| # let condition1 = true; | ||
| # let condition2 = false; | ||
| // Parentheses are required here. | ||
| if let Some(x) = foo && (condition1 || condition2) { /*...*/ } | ||
| ``` | ||
|
|
||
| r[expr.if.edition2024] | ||
| > [!EDITION-2024] | ||
| > Before the 2024 edition, let chains are not supported and only a single _IfCondition_ is allowed in an `if` expression. | ||
|
Comment on lines
+163
to
+164
There was a problem hiding this comment. IIUC, this will need to be duplicated in loop-expr.md for There was a problem hiding this comment. when I wrote rust-lang/rust#140204 (comment) I thought so too, but there is this paragraph in the
I'd say that this one implies that while let chains are under the same edition specific restriction. |
||
|
|
||
| [_BlockExpression_]: block-expr.md | ||
| [_Expression_]: ../expressions.md | ||
| [_LazyBooleanOperatorExpression_]: operator-expr.md#lazy-boolean-operators | ||
| [_Pattern_]: ../patterns.md | ||
| [_Scrutinee_]: match-expr.md | ||
| [`match` expressions]: match-expr.md | ||
| [boolean type]: ../types/boolean.md | ||
| [scrutinee]: ../glossary.md#scrutinee | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This can't be right, e.g. (considering only parsing):
That is, the exception isn't just
LazyBooleanExpression; it's any boolean expression with a lower precedence than&&.We're also asking, I think, for something kind of magic to happen here. When we have,
we're hoping for
Expressionto betrue == false. But when we have,we're hoping for
Expressionto try to betrue || false && let () = (), notice that's impossible, and fail (i.e., rather than allowingExpressionto betrue || false, which would be wrong). But this isn't really encoded anywhere.Ideas?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You are right that the exception isn't just that, and maybe it's misleading to list only
LazyBooleanExpressionbecause people might think that's an exhaustive list of exceptions.From what I can see, the reference doesn't require the grammar to be "precedence fitting", i.e. only allow what's possible to express in text form following precedence rules. Instead, it puts the precedence into a table and assumes the grammar is parsed according to the precedence. I would say that table also applies here, as it's part of the larger "expression" family of things.
Because people might think it's exhaustive, we could maybe remove the exception altogether and replace it with a note instead?
||has weaker precedence, so there isn't a top level && chain any more. On the other hand,==has stronger precedence.The example with
||is parsed to sth like:The example with
==is parsed like:So in the
||example, the BinOp with&&is actually not top level, its arms can't beIfConditions. So its arms don't have a "permit to let". While in the==example, it has such a permission.So I think this property is emergent from the grammar and the fact that it is parsed according to precedence.