[WIP] Expressions rewrite #13

matthewjasper · 2017-03-15T19:28:54Z

So this is a WIP attempt to improve the expressions section. It documents more features, fixes inaccuracies and hopefully makes things clearer. All feedback is welcome.

Changes

General
- Always wrap at 80 characters
- Make more things links
Structs
- State that struct expressions can't be used in control flow expressions
Methods
- Add examples for methods
- Explained auto-deref
  - ~~UFCS (or whatever it's called now) isn't in the reference!!!~~ It has a PR now.
Fields
- Show the syntax for calling a struct field
Calls
- Move before operators
- Explain the function call syntax
- Mention Fn traits
Lambdas
- Move lambda section
- Lambdas have unique types
- move is part of the lambda expression according to libsyntax, so I'm going with that
- Explain that move can extend the lifetime of the closure
- Use closure, except when followed by 'expression'
- Closure traits depend on how captures are used, not on how they are captured
Arrays
- Explain what arrays expressions do
- statics aren't constant expressions
- Explain Copy requirement
Index
- Specify how overloading is done
- Indices must be of type usize
Unary operators
- Explained std::ops::Neg
- Hopefully made it clearer how Deref works
- Explained std::ops::Not
- Say that &mut can't be applied to everything
Binary operators
- Merge with unary operators
- Built in operators don't use traits
- Show all of the operators in examples
- Put all of this into a table, to avoid having to repeat so many words.
Compound assignments
- Explain overloading of these operators
Precedence
- Add unary operators
- Show the correct associativity
Grouped expressions
- Better example
Loops and control flow.
- Use 'then' instead of and for sequenced operations in while loops
- State that all loops return () (Except loop but that's in another PR)
- Add some more examples
- Don't use 'identical' for things that aren't (would also need to look at if let semantically equivalence to if is wrong w.r.t. scope #47 in this respect)
- Make the definition of if let and while let clearer

Update:

Further Changes
- Mention array to slice coercions happening in method calls.
- Use 'mutable lvalue (context)' to describe some things. (I have no idea if this is how it should be described, but this was the easiest way to describe the behaviour that I tested).
- Explain when lvalues can be moved out of. (or, how not to do a move semantics tutorial)
- Explain that most things are actually in libcore, in only one place.
- Explicitly say that blocks are rvalues.
- Say exactly what operations are overflow.
- Say some things about implicit borrows.
- Add examples to show what is meant by method 'receiver'.
- Explain when fields can be viewed as separate entities for borrows and moves.
- Note that methods don't use lifetimes, mutability or safety to help with resolution.
- Say that paths to static mut require unsafe in this chapter.
- Enums variants can also be used in 'struct expressions'
- Mention tuple indexing.
- Mention that generic traits and methods are considered to be one trait for method resolution
- Show some paths with :: in path expressions section.
- Document const expr (including RFC 71)
- Document casts, sort of.
- RFC 736 - Privacy respecting Functional Record Update (FRU)
- RFC 968 - Closure return type syntax
- RFC 1229 - Compile time asserts
- RFC 1535 - Stable overflow checks

I'll probably split this up into pieces that can more easily be reviewed and avoid blocking everything on the lang team explaining how lvalues actually work.

* Add examples for methods * Show the syntax for calling a struct field * Explain the function call syntax * Mention `Fn` traits * Move lambda section * Lambdas have unique types * `move` is part of the lambda expression according to libsyntax * Explain that `move` can extend the lifetime of the closure * Use closure, except when followed by 'expression' * Closure traits depend on how captures are used, not on how they are captured

* Parameters are patterns, not idents. * Make it clear that inference can be done on just some of the parameters

* Explain what arrays expressions do. * `static`s aren't constant expressions. * Explain `Copy` requirement.

* Specify how overloading is done. * Indices must be of type `usize`.

* Explained `std::ops::Neg`. * Hopefully made it clearer how `Deref` works * Explained `std::ops::Not`. * Say that `&mut` can't be applied to everything.

* Built in operators don't use traits. * Explain that the type of right shift depends on the type.

* Explain overloading

* Add unary operators * Show the correct associativity

* Use 'then' instead of and. * State that all loops return `()`. * Add some more examples. * Don't use 'identical' for things that aren't. * Make the definition of `if let` and `while let` clearer. * State that struct expressions can't be used in control flow expressions.

Add operator examples Mention `if let` and `while let` as more places where struct literals can't be used.

matthewjasper

Some questions I had while writing this. (Outdated comments are still sometimes relevant)

matthewjasper · 2017-03-15T19:29:36Z

src/expressions.md

-is typically the innermost enclosing statement; the tail expression of
-a block is considered part of the statement that encloses the block.
+When an rvalue is used in an lvalue context, a temporary un-named lvalue is
+created and used instead. The lifetime of temporary values is typically the


This isn't true for the LHS of =.

matthewjasper · 2017-03-15T19:31:08Z

src/expressions.md

+1. Trait methods with receiver of type `&A`.
+1. Trait methods with receiver of type `&mut A`.
+1. If it's possible, Rust will then repeat steps 1-5 with
+  `<A as std::ops::Deref>::Target`, and insert a dereference operator.


Is this clear and correct? Is it what is intended?

Some other explanations to look at
typeck - suggests there is also 'unsizing' happening.
stack overflow

This might not be perfect, but it's also not incorrect; we may want to elaborate later, but I don't think it needs to block this PR

matthewjasper · 2017-03-15T19:31:33Z

src/expressions.md

+## Lambda expressions
+
+A _lambda expression_ (sometimes called an "anonymous function expression")
+defines a closure and denotes it as a value, in a single expression. A lambda


Am I using 'lambda expression' and 'closure' correctly? Is there even a (single) correct choice?

I personally would always refer to these as "closures" everywhere. Rust only has "closures" and "functions", it does not have anonymous functions nor named closures. "lambda" adds another term for no real gain, IMO.

matthewjasper · 2017-03-15T19:32:50Z

src/expressions.md

+Operators are defined for built in types by the Rust language. Operators will
+panic when they overflow when compiled in debug mode. Many of the following
+operators can be overloaded using traits in `std::ops` or `std::cmp`. Note that
+the traits in `std::cmp` are used more generally to show how a type may be


Here, and other places, should I link to std documentation?
Should I mention that these are also in core?

matthewjasper · 2017-03-15T19:34:03Z

src/expressions.md

+    assigned to. Dereferencing a raw pointer requires `unsafe`. On non-pointer
+    types `*x` is equivalent to `*std::ops::Deref::deref(&x)` or
+    `*std::ops::Deref::deref_mut(&mut x)` depending on whether the rquired
+    lvalue has to be mutable.


Should deref coercions be explained here, or in the Deref chapter, or elsewhere?

matthewjasper · 2017-03-15T19:35:32Z

src/expressions.md

-    and written in postfix notation.
+  : Propagating errors if applied to `Err(_)` and unwrapping if applied to
+    `Ok(_)`. Only works on the `Result<T, E>` type, and written in postfix
+    notation.


Suggestions on how to improve this are welcome.

matthewjasper · 2017-03-15T19:36:09Z

src/expressions.md

+| `<<`   | Left Shift              |             |                | `std::ops::Shl`    |
+| `>>`   | Right Shift*            |             |                | `std::ops::Shr`    |
+
+\* Arithmetic right shift on signed integers, Logical right shift on unsigned integers.


Tables for operators, 👍/👎?

matthewjasper · 2017-03-15T19:37:04Z

src/expressions.md

+    the borrow expires. If the `&` or `&mut` operators are applied to an
+    rvalue, a temporary value is created; the lifetime of this temporary value
+    is defined by [syntactic rules](#temporary-lifetimes). `&mut` may only be
+    applied to `lvalues` that can be mutated. These operators cannot be


I want to write 'mutable lvalue' so much, but is that the proper way to say what I mean?

Possibly relevant part of typeck.

matthewjasper · 2017-03-15T19:38:14Z

src/expressions.md

+```rust
+let x = false || true; // true
+let y = false && panic!(); // false, doesn't evaluate `panic!()`
+```

 ### Type cast expressions


Should I copy the (old) book explanation for all of the as casts here, or somewhere else?

here seems good

matthewjasper · 2017-03-15T19:38:56Z

src/expressions.md

+    "Smaller"
+};
+assert_eq!(y, "Bigger");
+```

 ## `match` expressions


Can patterns be moved to their own section?

seems good to me

matthewjasper · 2017-03-23T16:24:26Z

cc #9 (RFC 558, maybe 560 also), #10, #20, #23.

* Mutable lvalues * Implicit borrows * Overflow

matthewjasper · 2017-05-14T22:31:08Z

src/expressions.md

-a block is considered part of the statement that encloses the block.
+When an lvalue is evaluated in an _rvalue context_, it denotes the value held
+_in_ that memory location. If value is of a type that implements `Copy`, then
+the value will be copied. In other situations if the type of the value is


There are a few places I'm using 'other' to mean 'all other' or 'otherwise'. Any suggestions for an alternative wording would also be appreciated.

Is there a reason why you don't like 'other' here? Seems fine to me.

My concern is that could be interpreted as 'some other'.

steveklabnik · 2017-05-16T18:27:02Z

Hey @matthewjasper

Sorry this has taken me so long to look at, big PRs are tough. I will try to do so this week.

matthewjasper · 2017-05-16T18:53:47Z

I understand that, feel free to only review some of this or ask me for things to make this easier to review.

steveklabnik

whew! thank you so much for all of this, and sorry it took me so long.

I'm broadly in favor of merging this, but there's some formatting nits, and the lambda thing.

steveklabnik · 2017-05-26T15:18:56Z

src/expressions.md

-a block is considered part of the statement that encloses the block.
+When an lvalue is evaluated in an _rvalue context_, it denotes the value held
+_in_ that memory location. If value is of a type that implements `Copy`, then
+the value will be copied. In other situations if the type of the value is


Is there a reason why you don't like 'other' here? Seems fine to me.

steveklabnik · 2017-05-26T15:19:16Z

src/expressions.md

+the value will be copied. In other situations if the type of the value is
+[`Sized`](the-sized-trait.html) it may be possible to move the value. Only the
+following lvalues may be moved out of:
+* [Variables](#variables.html) which are not currently borrowed.


can you add a newline above this? I like to let it breathe a bit 😄

steveklabnik · 2017-05-26T15:20:35Z

src/expressions.md

+```
+
+Implicit borrows may be taken in the following expressions:
+* Left operand in [method-call expressions](#method-call-expressions).


steveklabnik · 2017-05-26T15:21:54Z

src/expressions.md

+
+When resolving method calls on an expression of type `A`, Rust will use the
+following order:
+1. Inherent methods, with receiver of type `A`, `&A`, `&mut A`.


steveklabnik · 2017-05-26T15:22:26Z

src/expressions.md

+
+Note: that in steps 1-4 the receiver is used, not the type of `Self`, which may
+not be the same as `A`. For example
+```rust


steveklabnik · 2017-05-26T15:31:00Z

src/expressions.md

+* `e` is a function pointer type and `U` is an integer; *fptr-addr-cast*
+    * Same concerns as with pointer to address casts
+
+TODO: Explain the semantics of these.


Doing so doesn't block this PR, IMHO; the reference is still incomplete.

steveklabnik · 2017-05-26T15:31:40Z

src/expressions.md

+present, then labelled `break` and `continue` expressions nested within this
+loop may exit out of this loop or return control to its head. See [break
+expressions](#break-expressions) and [continue
+expressions](#continue-expressions). Any `loop` expression has value `()`.


this is not true anymore now that that is being stabilized

steveklabnik · 2017-05-26T15:31:57Z

src/expressions.md

 conditional expression evaluates to `false`, the `while` expression completes.

-An example:
+ An example:


why this space?

steveklabnik · 2017-05-26T15:32:09Z

src/expressions.md

+    "Smaller"
+};
+assert_eq!(y, "Bigger");
+```

 ## `match` expressions


seems good to me

steveklabnik · 2017-05-26T15:32:32Z

src/expressions.md

+pattern, an `=` and an expression. If the value of the expression on the right
+hand side of the `=` matches the pattern, the loop body block executes then
+control returns to the pattern matching statement. Otherwise, the while
+expression completes. Like `while` loops, `while let` loops evaluate to `()`.


same issue here wrt new features

steveklabnik · 2017-06-01T14:55:12Z

Thanks so much! I'm happy to land this even with the WIP bits.

steveklabnik · 2017-06-01T18:27:28Z

Looks like this ended up breaking some links

[00:46:48] reference/variables.html:73: broken link fragment `#lvalues-rvalues-and-temporaries` pointing to `reference/expressions.html`
[00:46:48] reference/tokens.html:291: broken link fragment `#unary-operator-expressions` pointing to `reference/expressions.html`
[00:46:48] reference/tokens.html:343: broken link fragment `#unary-operator-expressions` pointing to `reference/expressions.html`
[00:46:48] reference/tokens.html:343: broken link fragment `#binary-operator-expressions` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:115: broken link fragment `#the-drop-trait` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:182: broken link fragment `#array-and-slice-types` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:213: broken link - reference/let-statements
[00:46:48] reference/expressions.html:222: broken link fragment `#paths` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:247: broken link fragment `#dereference-operator` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:273: broken link fragment `#lvalues-rvalues-and-temporaries` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:274: broken link fragment `#unsafe-block` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:478: broken link fragment `#lvalues-rvalues-and-temporaries` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:486: broken link fragment `#the-drop-trait` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:675: broken link fragment `#lvalues-rvalues-and-temporaries` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:766: broken link fragment `#lvalues-rvalues-and-temporaries` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:933: broken link - reference/type.html
[00:46:48] reference/expressions.html:992: broken link fragment `#lvalues-rvalues-and-temporaries` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:994: broken link fragment `#lvalues-rvalues-and-temporaries` pointing to `reference/expressions.html`
[00:46:48] reference/expressions.html:1226: broken link fragment `#lvalues-rvalues-and-temporaries` pointing to `reference/expressions.html`
[00:46:48] reference/types.html:305: broken link fragment `#lambda-expressions` pointing to `reference/expressions.html`
[00:46:48] reference/string-table-productions.html:72: broken link fragment `#unary-operator-expressions` pointing to `reference/expressions.html`
[00:46:48] reference/string-table-productions.html:73: broken link fragment `#binary-operator-expressions` pointing to `reference/expressions.html`

I don't know why CI didn't catch this...

matthewjasper · 2017-06-01T18:34:11Z

Should I submit a new PR to fix them?

steveklabnik · 2017-06-01T18:36:59Z

@matthewjasper that'd be great if you have the chance; I just pushed a commit fixing some of them If you have the chance to take the rest, that'd be great! I'd like to get this done today since tomorrow is the cutoff for beta; rust-lang/rust#42353 is the actual PR.

matthewjasper added 22 commits March 13, 2017 12:59

Alway wrap text in expressions.md at 80 characters

7e33fb9

Make 'identifier's into links.

c993ff9

Some more corrections to lambda expressions

e924901

* Parameters are patterns, not idents. * Make it clear that inference can be done on just some of the parameters

Expand and correct the array expressions section.

f8b3af3

* Explain what arrays expressions do. * `static`s aren't constant expressions. * Explain `Copy` requirement.

Explain method call resolution

c2e6797

Improve index expressions

7105048

* Specify how overloading is done. * Indices must be of type `usize`.

Improve unary operators

29af6c4

* Explained `std::ops::Neg`. * Hopefully made it clearer how `Deref` works * Explained `std::ops::Not`. * Say that `&mut` can't be applied to everything.

More wrapping changes

4853a00

Merge operators

837b41f

Improve binary operators

bcbba66

* Built in operators don't use traits. * Explain that the type of right shift depends on the type.

Remove an unnecessary new blank line in an example

5e4a958

Improve Compound assignments

e091c57

* Explain overloading

Improve operator precedence.

a6048c3

* Add unary operators * Show the correct associativity

Remove some unnecessary blank lines

764da0e

Improve the example for grouped expressions

a57aeea

Simlify and clarify method call resolution

056ffa6

Use 'then' instead of 'and' for ordered events.

f2ded24

Move field expressions next to Methods

d72c188

Make operator tables

ed91f13

Add operator examples Mention `if let` and `while let` as more places where struct literals can't be used.

Add another example, fix a typo.

0e119ee

matthewjasper commented Mar 15, 2017

View reviewed changes

matthewjasper and others added 2 commits March 17, 2017 12:22

Fix while let example.

6403330

More rvalue and lvalue stuff

ffecb50

Matthew Jasper added 4 commits March 24, 2017 00:19

Get most of the potential content in place

36789c0

* Mutable lvalues * Implicit borrows * Overflow

More examples for method receivers.

227ac3f

Add some links, fix typos

3dda6f8

Fields can be borrowed/moved separately

ca6fb9b

matthewjasper added 2 commits April 9, 2017 16:42

Fix spelling, document rfcs 736, 968, 1229, 1535.

e654bf5

FIx a mistake in what casts are allowed

8418895

chriskrycho mentioned this pull request May 13, 2017

Document all features #9

Closed

48 tasks

Clean up some notes

e030480

matthewjasper commented May 14, 2017

View reviewed changes

steveklabnik suggested changes May 26, 2017

View reviewed changes

matthewjasper added 7 commits May 26, 2017 18:28

Merge with more recent updates

3c46293

Fix links to loops secction

156a7f8

Remove most remaining lambda references

5ea3d30

Clean up some of the casts section

baf6f8e

Fix whitespace issues

7cc613d

Fix some things in the operator section

02ee9a6

Fix tests

b75f52a

matthewjasper force-pushed the expressions-rewrite branch 2 times, most recently from 2e8f7a4 to d6ee031 Compare May 26, 2017 21:48

Make some small improvements to phrasing and examples

4f39ffb

matthewjasper force-pushed the expressions-rewrite branch from d6ee031 to 4f39ffb Compare May 26, 2017 22:04

steveklabnik approved these changes Jun 1, 2017

View reviewed changes

steveklabnik merged commit 986aea4 into rust-lang:master Jun 1, 2017

This was referenced Jun 1, 2017

Fix expr links #65

Merged

Document bool cast semantics #20

Closed

Document pointer cast semantics #66

Open

matthewjasper mentioned this pull request Aug 5, 2017

document constant expressions #18

Closed

matthewjasper deleted the expressions-rewrite branch October 18, 2018 21:00

[WIP] Expressions rewrite #13

[WIP] Expressions rewrite #13

Conversation

matthewjasper commented Mar 15, 2017 • edited Loading

Changes

matthewjasper left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matthewjasper Mar 23, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matthewjasper commented Mar 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik commented May 16, 2017

matthewjasper commented May 16, 2017

steveklabnik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik commented Jun 1, 2017

steveklabnik commented Jun 1, 2017

matthewjasper commented Jun 1, 2017

steveklabnik commented Jun 1, 2017

matthewjasper commented Mar 15, 2017 •

edited

Loading

matthewjasper left a comment •

edited

Loading

matthewjasper Mar 23, 2017 •

edited

Loading