Merge pull request #2075 from dianne/deref-box-special-case

Add special cases and links relating to dereferencing boxes

Author: traviscross

src/expressions.md

@@ -369,6 +369,7 @@ They are never allowed before:
 * [Range] expressions.
 * Binary operator expressions ([ArithmeticOrLogicalExpression], [ComparisonExpression], [LazyBooleanExpression], [TypeCastExpression], [AssignmentExpression], [CompoundAssignmentExpression]).
 
+[`Box<T>`]:             special-types-and-traits.md#boxt
 [`Copy`]:               special-types-and-traits.md#copy
 [`Drop`]:               special-types-and-traits.md#drop
 [`if let`]:             expressions/if-expr.md#if-let-patterns

src/expressions/operator-expr.md

@@ -164,10 +164,13 @@ r[expr.deref.intro]
 The `*` (dereference) operator is also a unary prefix operator.
 
 r[expr.deref.result]
-When applied to a [pointer](../types/pointer.md) it denotes the pointed-to location.
+When applied to a [pointer](../types/pointer.md) or [`Box`], it denotes the pointed-to location.
 
 r[expr.deref.mut]
-If the expression is of type `&mut T` or `*mut T`, and is either a local variable, a (nested) field of a local variable or is a mutable [place expression], then the resulting memory location can be assigned to.
+If the expression is of type `&mut T`, `*mut T`, or `Box<T>`, and is either a local variable, a (nested) field of a local variable or is a mutable [place expression], then the resulting memory location can be assigned to.
+
+r[expr.deref.box]
+When applied to a [`Box`], the resultant place may be [moved from].
 
 r[expr.deref.safety]
 Dereferencing a raw pointer requires `unsafe`.
@@ -176,11 +179,14 @@ r[expr.deref.traits]
 On non-pointer types `*x` is equivalent to `*std::ops::Deref::deref(&x)` in an [immutable place expression context](../expressions.md#mutability) and `*std::ops::DerefMut::deref_mut(&mut x)` in a mutable place expression context.
 
 ```rust
+# struct NoCopy;
 let x = &7;
 assert_eq!(*x, 7);
 let y = &mut 9;
 *y = 11;
 assert_eq!(*y, 11);
+let z = Box::new(NoCopy);
+let _: NoCopy = *z;
 ```
 
 r[expr.try]
@@ -1208,6 +1214,7 @@ As with normal assignment expressions, compound assignment expressions always pr
 > [!WARNING]
 > Avoid writing code that depends on the evaluation order of operands in compound assignments as it can be unusual and surprising.
 
+[`Box`]: ../special-types-and-traits.md#boxt
 [`Try`]: core::ops::Try
 [autoref]: expr.method.candidate-receivers-refs
 [copies or moves]: ../expressions.md#moved-and-copied-types
@@ -1222,6 +1229,7 @@ As with normal assignment expressions, compound assignment expressions always pr
 [logical not]: ../types/boolean.md#logical-not
 [logical or]: ../types/boolean.md#logical-or
 [logical xor]: ../types/boolean.md#logical-xor
+[moved from]: expr.move.movable-place
 [mutable]: ../expressions.md#mutability
 [place expression]: ../expressions.md#place-expressions-and-value-expressions
 [assignee expression]: ../expressions.md#place-expressions-and-value-expressions

src/special-types-and-traits.md

@@ -14,8 +14,8 @@ r[lang-types.box.intro]
 defined types.
 
 r[lang-types.box.deref]
-* The [dereference operator] for `Box<T>` produces a place which can be moved
-  from. This means that the `*` operator and the destructor of `Box<T>` are
+* The [dereference operator] for `Box<T>` produces a place which can be [moved
+  from]. This means that the `*` operator and the destructor of `Box<T>` are
   built-in to the language.
 
 r[lang-types.box.receiver]
@@ -239,6 +239,7 @@ These implicit `Sized` bounds may be relaxed by using the special `?Sized` bound
 [main function]: crates-and-source-files.md#main-functions
 [Methods]: items/associated-items.md#associated-functions-and-methods
 [method resolution]: expressions/method-call-expr.md
+[moved from]: expr.move.movable-place
 [operators]: expressions/operator-expr.md
 [orphan rules]: items/implementations.md#trait-implementation-coherence
 [`static` items]: items/static-items.md