Patterns chapter #419

ehuss · 2018-09-16T23:10:56Z

This is a repost of #284, rebased, updated, most review comments addressed, and some additional information added.

This adds a small description of binding modes which covers #280, but I'm not confident it is detailed enough to consider it complete. There are a lot of details not covered in depth (like const references).

src/SUMMARY.md

ehuss · 2018-09-16T23:15:41Z

src/patterns.md

+> _IdentifierPattern_ :\
+> &nbsp;&nbsp; &nbsp;&nbsp; `ref`<sup>?</sup> `mut`<sup>?</sup> [IDENTIFIER] (`@` [_Pattern_] ) <sup>?</sup>
+
+_Identifier patterns_ bind the value they match to a **previously undeclared** variable.


The phrase "previously undeclared" here is confusing to me. I'm not certain if the original intent is to emphasize that the identifier must be unique within a pattern (i.e. (x, x) is an invalid pattern), or if it is trying to express something else. The identifier can shadow bindings of the same name from outside the pattern, so that's why I'm confused by the "previously undeclared" part. What do you think of changing it to something like this?

Identifier patterns bind the value they match to a variable. The identifier must be unique within the pattern. The variable will shadow any variables of the same name in scope.

SGTM. I would also add that the scope of the variable is dependent upon the context of where the pattern is used.

Havvy · 2018-09-17T07:20:09Z

src/expressions/match-expr.md

-`match` expression has a *head expression*, which is the value to compare to
-the patterns. The type of the patterns must equal the type of the head
-expression.
+occurs depends on the pattern. See [Patterns] for more details. A `match`


I don't know if we want to explicitly nudge people to the chapter like that, or just make "pattern" in the previous sentence.

Havvy · 2018-09-17T07:21:02Z

src/expressions/match-expr.md

-expression.
+occurs depends on the pattern. See [Patterns] for more details. A `match`
+expression has a *head expression*, which is the value to compare to the
+patterns. The type of the patterns must equal the type of the head expression.


This last sentence is okay, but I feel it would read better as "The head expression and the patterns must have the same type."

Havvy · 2018-09-17T07:24:02Z

src/expressions/match-expr.md

@@ -65,62 +62,9 @@ match x {
 Patterns that bind variables default to binding to a copy or move of the
 matched value (depending on the matched value's type). This can be changed to
 bind to a reference by using the `ref` keyword, or to a mutable reference using
-`ref mut`.
+`ref mut`. See [Identifier Patterns].


Make the keywords links to that section instead of adding a "See also" line. I would also change "using" to "prepending", but that doesn't have to be done in this PR, although it would be nice.

This entire section seems duped from the Identifier Patterns" section?

Yea, the paragraph is mostly a dupe, so I rewrote it to say something relevant.

Havvy · 2018-09-17T07:26:01Z

src/patterns.md

+> &nbsp;&nbsp; | [_SlicePattern_]\
+> &nbsp;&nbsp; | [_PathPattern_]
+
+Patterns in Rust are used to match values against structures and to,


"in Rust" is redundant unless contrasting with another language, which this is not doing.

Havvy · 2018-09-17T07:26:53Z

src/patterns.md

+
+Patterns in Rust are used to match values against structures and to,
+optionally, bind variables to values inside these structures. They are also
+used in variable declarations and function/closure parameters, though in these


General style right now is to not use x/y. Could rewrite as "parameters for functions and closures".

The clause after the comma could be its own sentence, or maybe even removed. If not removed, "though in these cases most of the time" -> "though in most of these cases,".

Havvy · 2018-09-17T07:30:48Z

src/patterns.md

+* [`if let` expressions](expressions/if-expr.html)
+* [`while let` expressions](expressions/loop-expr.html#predicate-pattern-loops)
+* [`for` expressions](expressions/loop-expr.html#iterator-loops)
+* Inside other patterns


This is a weird way of saying that patterns are recursive. I wouldn't really call a subpattern a pattern on its own right personally.

Havvy · 2018-09-17T07:31:18Z

src/patterns.md

+
+## Destructuring
+
+Patterns can be used to *destructure* structs, enums, and tuples. Destructuring


Not required, but would be nice to make "structs", "enums", and "tuples" be links.

Havvy · 2018-09-17T07:31:50Z

src/patterns.md

+## Destructuring
+
+Patterns can be used to *destructure* structs, enums, and tuples. Destructuring
+breaks a value up into its component pieces. The syntax used is almost the same as


"breaks up a value"?

Havvy · 2018-09-17T07:32:30Z

src/patterns.md

+
+Patterns can be used to *destructure* structs, enums, and tuples. Destructuring
+breaks a value up into its component pieces. The syntax used is almost the same as
+when creating such values. When destructing a data structure with named (but


"destructing" -> "destructuring"

Havvy · 2018-09-17T07:34:30Z

src/patterns.md

+breaks a value up into its component pieces. The syntax used is almost the same as
+when creating such values. When destructing a data structure with named (but
+not numbered) fields, it is allowed to write `fieldname` as a shorthand for
+`fieldname: fieldname`. In a pattern whose head expression has a `struct`,


I feel the sentence about _ and .. should precede the one about field (de)structuring shorthand. Also "stands" -> "stands in"

Havvy · 2018-09-17T07:37:31Z

src/patterns.md

+
+## Refutability
+
+A pattern is said to be *Refutable* when it **has the possibility of not being matched**


"Refutable" -> "refutable" (casing). I'm iffy about bolding the definition part. especially since the irrefutable definition part isn't bolded. If you want to propose changing our style to actually bold them like that, file an issue.

Havvy · 2018-09-17T07:39:53Z

src/patterns.md

+not literals in Rust, literal patterns also accept an optional minus sign before the
+literal.
+
+Floating-point literals are currently accepted, but due to the complexity of comparing


We generally don't talk about the future of Rust, but this seems a worthwhile exception. But it should be placed in a warning box (you can find the syntax for it in introduction.md)

Havvy · 2018-09-17T07:42:39Z

src/patterns.md

+[FLOAT_LITERAL]: tokens.html#floating-point-literals
+
+_Literal patterns_ match exactly the value they represent. Since negative numbers are
+not literals in Rust, literal patterns also accept an optional minus sign before the


Link "literals" please.

Remove "in Rust".

State that they match the same value as what is created by the literal.

State that the minus sign acts like the negation operator expression.

Havvy · 2018-09-17T07:54:19Z

src/patterns.md

+```
+
+match any value and bind it to that identifier. This is the most commonly
+used pattern in variable declarations and function/closure parameters.


Same "x/y" as earlier.

Havvy · 2018-09-17T07:56:33Z

src/patterns.md

+binds to `e` the value 2 (not the entire range: the range here is a range subpattern).
+
+By default, identifier patterns bind a variable to a copy of or move from the
+matched value (depending whether the matched value implements the [Copy trait]).


The parenthesis are superfluous. The words inside are crucial to the meaning of the sentence.

"depending" -> "depending on".

the [Copy trait] -> [`Copy`]

Havvy · 2018-09-17T08:00:56Z

src/tokens.md

@@ -611,3 +611,8 @@ them are referred to as "token trees" in [macros].  The three types of brackets
 [extern]: items/external-blocks.html
 [struct expressions]: expressions/struct-expr.html
 [tuple index]: expressions/tuple-expr.html#tuple-indexing-expressions
+[Wildcard patterns]: patterns.html#wildcard-pattern


Can you alphabetize these? You don't need to alphabetize all of the ones that are already here, but at least from extern downwards (since the three already at the end are alphabetized by coincidence). Uppercase sorts before all lowercase.

Havvy · 2018-09-17T08:04:16Z

Overall this looks good. I'm not done nitpicking it, and you don't have to listen to my nitpicks (especially the ones with "?"s attached. Just respond to the nitpick saying so if you don't.

src/patterns.md

Havvy · 2018-09-20T22:07:57Z

src/patterns.md

+}
+```
+
+binds to `e` the value 2 (not the entire range: the range here is a range subpattern).


This should be on the same line as the "For example".

Havvy · 2018-09-20T22:08:42Z

src/patterns.md

+match any value and bind it to that identifier. This is the most commonly
+used pattern in variable declarations and parameters for functions and closures.
+
+To bind non-trivial patterns to a variable, the use of the syntax `variable @


The passive voice here is an inversion on what is normally written. I also don't like the word "non-trivial", but don't have a better word to replace it personally.

Havvy · 2018-09-20T22:10:14Z

src/patterns.md

+if let Person{name: &person_name, age: 18..=150} = value { }
+```
+
+is not valid. What we must do is:


"What we must do is:" -> "To make it valid, we can write the following."

Havvy · 2018-09-20T22:13:59Z

src/patterns.md

+
+A struct pattern is refutable when one of its subpatterns is refutable.
+
+## TupleStruct patterns


Do we want "TupleStruct" to be one word or two?

I generally don't like smashing words together.

Havvy · 2018-09-20T22:14:54Z

src/patterns.md

+## Tuple patterns
+
+> **<sup>Syntax</sup>**\
+> _TuplePattern_ :<a name="tuple-pattern-syntax"></a>\


"name" attribute is deprecated for "id" in HTML, IIRC.

Havvy · 2018-09-20T22:18:13Z

Alright, I've finished looking over all of the changes.

ehuss · 2018-09-21T16:04:38Z

I rewrote all the situations where a sentence was split across the example code. In the very first example, I'm not sure if it is clearer if the code sample should appear before or after the text talking about it. It's fairly small, so it should fit on one screen on most devices, so it probably doesn't matter too much?

Havvy · 2018-09-21T18:09:49Z

Just need to rebase against master (conflict with tokens.md) and this should be good to merge.

- Added the chapter about patterns, with some explanations and the grammar. - Had to move some documentation about patterns from the `match` section. - Removed the bit about the new syntax of inclusive pattern ranges (a..=b), since it is not stable nor in the process of being stabilized.

ehuss · 2018-09-21T18:30:10Z

Rebased!

Havvy · 2018-09-21T18:37:34Z

And merged! Many thanks for taking this over and getting it finished! (Imagine twenty part hat emojis here)

ehuss commented Sep 16, 2018

View reviewed changes

Havvy reviewed Sep 17, 2018

View reviewed changes

Havvy reviewed Sep 20, 2018

View reviewed changes

src/patterns.md Outdated Show resolved Hide resolved

Havvy reviewed Sep 20, 2018

View reviewed changes

Havvy mentioned this pull request Sep 20, 2018

WIP: Patterns chapter #284

Closed

Havvy approved these changes Sep 21, 2018

View reviewed changes

brauliobz and others added 9 commits September 21, 2018 11:27

Added links and fixed compiler erros

efdf008

..= patterns ARE being stabilized.

939015a

Address review comments.

fc172c1

Minor updates and fixes.

61b7fa3

Add more details to patterns.

6216f45

Address patterns review comments.

52a335e

More review comments.

4ea8e34

More review comments.

dd1e2e6

Fix tuple index for struct field pattern.

7edf953

ehuss force-pushed the patterns_basic branch from 87a63a5 to 7edf953 Compare September 21, 2018 18:29

Havvy approved these changes Sep 21, 2018

View reviewed changes

Havvy merged commit 5e296d2 into rust-lang:master Sep 21, 2018


		## Destructuring

		Patterns can be used to destructure structs, enums, and tuples. Destructuring


		## Refutability

		A pattern is said to be Refutable when it has the possibility of not being matched


		A struct pattern is refutable when one of its subpatterns is refutable.

		## TupleStruct patterns

Patterns chapter #419

Patterns chapter #419

Uh oh!

Conversation

ehuss commented Sep 16, 2018

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Havvy commented Sep 17, 2018

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Havvy commented Sep 20, 2018

Uh oh!

ehuss commented Sep 21, 2018

Uh oh!

Havvy commented Sep 21, 2018

Uh oh!

ehuss commented Sep 21, 2018

Uh oh!

Havvy commented Sep 21, 2018

Uh oh!

Uh oh!