Merge pull request #514 from matthewjasper/drop-scopes

Document drop scopes

Author: matthewjasper

src/destructors.md

@@ -125,7 +125,7 @@ the remaining situations if that type is [`Sized`], then it may be possible to
 move the value. Only the following place expressions may be moved out of:
 
 * [Variables] which are not currently borrowed.
-* [Temporary values](#temporary-lifetimes).
+* [Temporary values](#temporaries).
 * [Fields][field] of a place expression which can be moved out of and
   doesn't implement [`Drop`].
 * The result of [dereferencing][deref] an expression with type [`Box<T>`] and
@@ -159,69 +159,12 @@ The following expressions can be mutable place expression contexts:
   then evaluates the value being indexed, but not the index, in mutable place
   expression context.
 
-### Temporary lifetimes
+### Temporaries
 
 When using a value expression in most place expression contexts, a temporary
 unnamed memory location is created initialized to that value and the expression
-evaluates to that location instead, except if promoted to `'static`. Promotion
-of a value expression to a `'static` slot occurs when the expression could be
-written in a constant, borrowed, and dereferencing that borrow where the
-expression was originally written, without changing the runtime behavior. That
-is, the promoted expression can be evaluated at compile-time and the resulting
-value does not contain [interior mutability] or [destructors] (these properties
-are determined based on the value where possible, e.g. `&None` always has the
-type `&'static Option<_>`, as it contains nothing disallowed). Otherwise, the
-lifetime of temporary values is typically
-
-- the innermost enclosing statement; the tail expression of a block is
-  considered part of the statement that encloses the block, or
-- the condition expression or the loop conditional expression if the
-  temporary is created in the condition expression of an `if` or in the loop
-  conditional expression of a `while` expression.
-
-When a temporary value expression is being created that is assigned into a
-[`let` declaration][let], however, the temporary is created with the lifetime of
-the enclosing block instead, as using the enclosing [`let` declaration][let]
-would be a guaranteed error (since a pointer to the temporary
-would be stored into a variable, but the temporary would be freed before the
-variable could be used). The compiler uses simple syntactic rules to decide
-which values are being assigned into a `let` binding, and therefore deserve a
-longer temporary lifetime.
-
-Here are some examples:
-
-- `let x = foo(&temp())`. The expression `temp()` is a value expression. As it
-  is being borrowed, a temporary is created which will be freed after
-  the innermost enclosing statement; in this case, the `let` declaration.
-- `let x = temp().foo()`. This is the same as the previous example,
-  except that the value of `temp()` is being borrowed via autoref on a
-  method-call. Here we are assuming that `foo()` is an `&self` method
-  defined in some trait, say `Foo`. In other words, the expression
-  `temp().foo()` is equivalent to `Foo::foo(&temp())`.
-- `let x = if foo(&temp()) {bar()} else {baz()};`. The expression `temp()` is
-  a value expression. As the temporary is created in the condition expression
-  of an `if`, it will be freed at the end of the condition expression;
-  in this example before the call to `bar` or `baz` is made.
-- `let x = if temp().must_run_bar {bar()} else {baz()};`.
-  Here we assume the type of `temp()` is a struct with a boolean field
-  `must_run_bar`. As the previous example, the temporary corresponding to
-  `temp()` will be freed at the end of the condition expression.
-- `while foo(&temp()) {bar();}`. The temporary containing the return value from
-  the call to `temp()` is created in the loop conditional expression. Hence it
-  will be freed at the end of the loop conditional expression; in this example
-  before the call to `bar` if the loop body is executed.
-- `let x = &temp()`. Here, the same temporary is being assigned into
-  `x`, rather than being passed as a parameter, and hence the
-  temporary's lifetime is considered to be the enclosing block.
-- `let x = SomeStruct { foo: &temp() }`. As in the previous case, the
-  temporary is assigned into a struct which is then assigned into a
-  binding, and hence it is given the lifetime of the enclosing block.
-- `let x = [ &temp() ]`. As in the previous case, the
-  temporary is assigned into an array which is then assigned into a
-  binding, and hence it is given the lifetime of the enclosing block.
-- `let ref x = temp()`. In this case, the temporary is created using a ref
-  binding, but the result is the same: the lifetime is extended to the enclosing
-  block.
+evaluates to that location instead, except if [promoted] to a `static`. The
+[drop scope] of the temporary is usually the end of the enclosing statement.
 
 ### Implicit Borrows
 
@@ -304,24 +247,25 @@ They are never allowed before:
 [deref]:                expressions/operator-expr.md#the-dereference-operator
 
 [destructors]:          destructors.md
-[interior mutability]:  interior-mutability.md
-[`Box<T>`]:             ../std/boxed/struct.Box.md
+[drop scope]:           destructors.md#drop-scopes
+
+[`Box<T>`]:             ../std/boxed/struct.Box.html
 [`Copy`]:               special-types-and-traits.md#copy
 [`Drop`]:               special-types-and-traits.md#drop
 [`Sized`]:              special-types-and-traits.md#sized
 [implicit borrow]:      #implicit-borrows
 [implicitly mutably borrowed]: #implicit-borrows
-[let]:                  statements.md#let-statements
+[interior mutability]:  interior-mutability.md
 [let statement]:        statements.md#let-statements
 [Mutable `static` items]: items/static-items.md#mutable-statics
 [scrutinee]:            glossary.md#scrutinee
+[promoted]:             destructors.md#constant-promotion
 [slice]:                types/slice.md
 [statement]:            statements.md
 [static variables]:     items/static-items.md
-[Temporary values]:     #temporary-lifetimes
+[Temporary values]:     #temporaries
 [Variables]:            variables.md
 
-
 [_ArithmeticOrLogicalExpression_]: expressions/operator-expr.md#arithmetic-and-logical-binary-operators
 [_ArrayExpression_]:              expressions/array-expr.md
 [_AsyncBlockExpression_]:         expressions/block-expr.md#async-blocks

src/expressions.md

@@ -295,6 +295,6 @@ expression `()`.
 [_Pattern_]: ../patterns.md
 [`match` expression]: match-expr.md
 [scrutinee]: ../glossary.md#scrutinee
-[temporary values]: ../expressions.md#temporary-lifetimes
+[temporary values]: ../expressions.md#temporaries
 [_LazyBooleanOperatorExpression_]: operator-expr.md#lazy-boolean-operators
 [`if let` expressions]: if-expr.md#if-let-expressions

src/expressions/loop-expr.md

@@ -455,7 +455,7 @@ assert_eq!(x, 14);
 
 [place expression]: ../expressions.md#place-expressions-and-value-expressions
 [value expression]: ../expressions.md#place-expressions-and-value-expressions
-[temporary value]: ../expressions.md#temporary-lifetimes
+[temporary value]: ../expressions.md#temporaries
 [float-int]: https://github.com/rust-lang/rust/issues/10184
 [float-float]: https://github.com/rust-lang/rust/issues/15536
 [`unit` type]: ../types/tuple.md

src/expressions/operator-expr.md

@@ -139,9 +139,9 @@ attention to making those sections the best that they can be.
 [_Expression_]: expressions.md
 [cargo book]: ../cargo/index.html
 [cargo reference]: ../cargo/reference/index.html
-[expressions chapter]: expressions.md
-[lifetime of temporaries]: expressions.md#temporary-lifetimes
-[linkage]: linkage.md
+[expressions chapter]: expressions.html
+[lifetime of temporaries]: expressions.html#temporaries
+[linkage]: linkage.html
 [rustc book]: ../rustc/index.html
 [Notation]: notation.md
 [Discord]: https://discord.gg/rust-lang

src/introduction.md

@@ -56,4 +56,4 @@ and raw pointers.
 [_TypeNoBounds_]: ../types.md#type-expressions
 [`unsafe` operation]: ../unsafety.md
 [dynamically sized types]: ../dynamically-sized-types.md
-[temporary value]: ../expressions.md#temporary-lifetimes
+[temporary value]: ../expressions.md#temporaries

src/types/pointer.md

@@ -1,7 +1,7 @@
 # Variables
 
 A _variable_ is a component of a stack frame, either a named function parameter,
-an anonymous [temporary](expressions.md#temporary-lifetimes), or a named local
+an anonymous [temporary](expressions.md#temporaries), or a named local
 variable.
 
 A _local variable_ (or *stack-local* allocation) holds a value directly,