Merge branch 'master' of https://github.com/rust-lang/reference into c-unwind-documentation

Author: Kyle Strand

src/behavior-considered-undefined.md

@@ -25,7 +25,7 @@ code.
 * Data races.
 * Evaluating a [dereference expression] (`*expr`) on a raw pointer that is
   [dangling] or unaligned, even in [place expression context]
-  (e.g. `addr_of!(&*expr)`).
+  (e.g. `addr_of!(*expr)`).
 * Breaking the [pointer aliasing rules]. `Box<T>`, `&mut T` and `&T` follow
   LLVM’s scoped [noalias] model, except if the `&T` contains an
   [`UnsafeCell<U>`]. References and boxes must not be [dangling] while they are

src/const_eval.md

@@ -113,7 +113,7 @@ Conversely, the following are possible in a const function, but not in a const c
 [Const parameters]:     items/generics.md
 [dereference operator]: expressions/operator-expr.md#the-dereference-operator
 [destructors]:          destructors.md
-[enum discriminants]:   items/enumerations.md#custom-discriminant-values-for-fieldless-enumerations
+[enum discriminants]:   items/enumerations.md#discriminants
 [expression statements]: statements.md#expression-statements
 [expressions]:          expressions.md
 [field]:                expressions/field-expr.md

src/destructors.md

@@ -162,7 +162,7 @@ smallest scope that contains the expression and is one of the following:
 * The `else` block of an `if` expression.
 * The condition expression of an `if` or `while` expression, or a `match`
   guard.
-* The expression for a match arm.
+* The body expression for a match arm.
 * The second operand of a [lazy boolean expression].
 
 > **Notes**:
@@ -272,8 +272,9 @@ let x = &mut 0;
 println!("{}", x);
 ```
 
-If a borrow, dereference, field, or tuple indexing expression has an extended
-temporary scope then so does its operand. If an indexing expression has an
+If a [borrow][borrow expression], [dereference][dereference expression],
+[field][field expression], or [tuple indexing expression] has an extended
+temporary scope then so does its operand. If an [indexing expression] has an
 extended temporary scope then the indexed expression also has an extended
 temporary scope.
 
@@ -386,8 +387,12 @@ variable or field from being dropped automatically.
 [block expression]: expressions/block-expr.md
 [borrow expression]: expressions/operator-expr.md#borrow-operators
 [cast expression]: expressions/operator-expr.md#type-cast-expressions
+[dereference expression]: expressions/operator-expr.md#the-dereference-operator
+[field expression]: expressions/field-expr.md
+[indexing expression]: expressions/array-expr.md#array-and-slice-indexing-expressions
 [struct expression]: expressions/struct-expr.md
 [tuple expression]: expressions/tuple-expr.md#tuple-expressions
+[tuple indexing expression]: expressions/tuple-expr.md#tuple-indexing-expressions
 
 [`for`]: expressions/loop-expr.md#iterator-loops
 [`if let`]: expressions/if-expr.md#if-let-expressions

src/expressions/field-expr.md

@@ -37,7 +37,7 @@ foo().x;
 ## Automatic dereferencing
 
 If the type of the container operand implements [`Deref`] or [`DerefMut`][`Deref`] depending on whether the operand is [mutable], it is *automatically dereferenced* as many times as necessary to make the field access possible.
-This processes is also called *autoderef* for short.
+This process is also called *autoderef* for short.
 
 ## Borrowing
 

src/expressions/if-expr.md

@@ -129,7 +129,7 @@ The expression cannot be a [lazy boolean operator expression][_LazyBooleanOperat
 Use of a lazy boolean operator is ambiguous with a planned feature change of the language (the implementation of if-let chains - see [eRFC 2947][_eRFCIfLetChain_]).
 When lazy boolean operator expression is desired, this can be achieved by using parenthesis as below:
 
-<!-- ignore: psuedo code -->
+<!-- ignore: pseudo code -->
 ```rust,ignore
 // Before...
 if let PAT = EXPR && EXPR { .. }

src/expressions/operator-expr.md

@@ -368,7 +368,7 @@ reference types and `mut` or `const` in pointer types.
 | Type of `e`           | `U`                   | Cast performed by `e as U`       |
 |-----------------------|-----------------------|----------------------------------|
 | Integer or Float type | Integer or Float type | Numeric cast                     |
-| C-like enum           | Integer type          | Enum cast                        |
+| Enumeration           | Integer type          | Enum cast                        |
 | `bool` or `char`      | Integer type          | Primitive to integer cast        |
 | `u8`                  | `char`                | `u8` to `char` cast              |
 | `*T`                  | `*V` where `V: Sized` \* | Pointer to pointer cast       |
@@ -430,6 +430,10 @@ halfway between two floating point numbers.
 #### Enum cast
 
 Casts an enum to its discriminant, then uses a numeric cast if needed.
+Casting is limited to the following kinds of enumerations:
+
+* [Unit-only enums]
+* [Field-less enums] without [explicit discriminants], or where only unit-variants have explicit discriminants
 
 #### Primitive to integer cast
 
@@ -596,7 +600,7 @@ It will then set the value of the assigned operand's place to the value of perfo
 
 > **Note**: This is different than other expressions in that the right operand is evaluated before the left one.
 
-Otherwise, this expression is syntactic sugar for calling the function of the overloading compound assigment trait of the operator (see the table earlier in this chapter).
+Otherwise, this expression is syntactic sugar for calling the function of the overloading compound assignment trait of the operator (see the table earlier in this chapter).
 A mutable borrow of the assigned operand is automatically taken.
 
 For example, the following expression statements in `example` are equivalent:
@@ -632,6 +636,8 @@ See [this test] for an example of using this dependency.
 
 [copies or moves]: ../expressions.md#moved-and-copied-types
 [dropping]: ../destructors.md
+[explicit discriminants]: ../items/enumerations.md#explicit-discriminants
+[field-less enums]: ../items/enumerations.md#field-less-enum
 [grouped expression]: grouped-expr.md
 [literal expression]: literal-expr.md#integer-literal-expressions
 [logical and]: ../types/boolean.md#logical-and
@@ -643,6 +649,7 @@ See [this test] for an example of using this dependency.
 [assignee expression]: ../expressions.md#place-expressions-and-value-expressions
 [undefined behavior]: ../behavior-considered-undefined.md
 [unit]: ../types/tuple.md
+[Unit-only enums]: ../items/enumerations.md#unit-only-enum
 [value expression]: ../expressions.md#place-expressions-and-value-expressions
 [temporary value]: ../expressions.md#temporaries
 [this test]: https://github.com/rust-lang/rust/blob/1.58.0/src/test/ui/expr/compound-assignment/eval-order.rs

src/items/enumerations.md

@@ -13,8 +13,8 @@
 >
 > _EnumItem_ :\
 > &nbsp;&nbsp; _OuterAttribute_<sup>\*</sup> [_Visibility_]<sup>?</sup>\
-> &nbsp;&nbsp; [IDENTIFIER]&nbsp;( _EnumItemTuple_ | _EnumItemStruct_
->                                | _EnumItemDiscriminant_ )<sup>?</sup>
+> &nbsp;&nbsp; [IDENTIFIER]&nbsp;( _EnumItemTuple_ | _EnumItemStruct_ )<sup>?</sup>
+>                                _EnumItemDiscriminant_<sup>?</sup>
 >
 > _EnumItemTuple_ :\
 > &nbsp;&nbsp; `(` [_TupleFields_]<sup>?</sup> `)`
@@ -56,22 +56,71 @@ a = Animal::Cat { name: "Spotty".to_string(), weight: 2.7 };
 ```
 
 In this example, `Cat` is a _struct-like enum variant_, whereas `Dog` is simply
-called an enum variant. Each enum instance has a _discriminant_ which is an
-integer associated to it that is used to determine which variant it holds. An
-opaque reference to this discriminant can be obtained with the
-[`mem::discriminant`] function.
+called an enum variant.
 
-## Custom Discriminant Values for Fieldless Enumerations
+An enum where no constructors contain fields are called a
+*<span id="field-less-enum">field-less enum</span>*. For example, this is a fieldless enum:
 
-If there is no data attached to *any* of the variants of an enumeration,
-then the discriminant can be directly chosen and accessed.
+```rust
+enum Fieldless {
+    Tuple(),
+    Struct{},
+    Unit,
+}
+```
+
+If a field-less enum only contains unit variants, the enum is called an
+*<span id="unit-only-enum">unit-only enum</span>*. For example:
+
+```rust
+enum Enum {
+    Foo = 3,
+    Bar = 2,
+    Baz = 1,
+}
+```
+
+<span id="custom-discriminant-values-for-fieldless-enumerations"></span>
+## Discriminants
+
+Each enum instance has a _discriminant_: an integer logically associated to it
+that is used to determine which variant it holds.
+
+Under the [default representation], the discriminant is interpreted as
+an `isize` value. However, the compiler is allowed to use a smaller type (or
+another means of distinguishing variants) in its actual memory layout.
+
+### Assigning discriminant values
+
+#### Explicit discriminants
 
-These enumerations can be cast to integer types with the `as` operator by a
-[numeric cast]. The enumeration can optionally specify which integer each
-discriminant gets by following the variant name with `=` followed by a [constant
-expression]. If the first variant in the declaration is unspecified, then it is
-set to zero. For every other unspecified discriminant, it is set to one higher
-than the previous variant in the declaration.
+In two circumstances, the discriminant of a variant may be explicitly set by
+following the variant name with `=` and a [constant expression]:
+
+
+1. if the enumeration is "[unit-only]".
+
+
+2. if a [primitive representation] is used. For example:
+
+   ```rust
+   #[repr(u8)]
+   enum Enum {
+       Unit = 3,
+       Tuple(u16),
+       Struct {
+           a: u8,
+           b: u16,
+       } = 1,
+   }
+   ```
+
+#### Implicit discriminants
+
+If a discriminant for a variant is not specified, then it is set to one higher
+than the discriminant of the previous variant in the declaration. If the
+discriminant of the first variant in the declaration is unspecified, then
+it is set to zero.
 
 ```rust
 enum Foo {
@@ -84,10 +133,7 @@ let baz_discriminant = Foo::Baz as u32;
 assert_eq!(baz_discriminant, 123);
 ```
 
-Under the [default representation], the specified discriminant is interpreted as
-an `isize` value although the compiler is allowed to use a smaller type in the
-actual memory layout. The size and thus acceptable values can be changed by
-using a [primitive representation] or the [`C` representation].
+#### Restrictions
 
 It is an error when two variants share the same discriminant.
 
@@ -122,7 +168,89 @@ enum OverflowingDiscriminantError2 {
 }
 ```
 
-## Zero-variant Enums
+### Accessing discriminant
+
+#### Via `mem::discriminant`
+
+[`mem::discriminant`] returns an opaque reference to the discriminant of
+an enum value which can be compared. This cannot be used to get the value
+of the discriminant.
+
+#### Casting
+
+If an enumeration is [unit-only] (with no tuple and struct variants), then its
+discriminant can be directly accessed with a [numeric cast]; e.g.:
+
+```rust
+enum Enum {
+    Foo,
+    Bar,
+    Baz,
+}
+
+assert_eq!(0, Enum::Foo as isize);
+assert_eq!(1, Enum::Bar as isize);
+assert_eq!(2, Enum::Baz as isize);
+```
+
+[Field-less enums] can be casted if they do not have explicit discriminants, or where only unit variants are explicit.
+
+```rust
+enum Fieldless {
+    Tuple(),
+    Struct{},
+    Unit,
+}
+
+assert_eq!(0, Fieldless::Tuple() as isize);
+assert_eq!(1, Fieldless::Struct{} as isize);
+assert_eq!(2, Fieldless::Unit as isize);
+
+#[repr(u8)]
+enum FieldlessWithDiscrimants {
+    First = 10,
+    Tuple(),
+    Second = 20,
+    Struct{},
+    Unit,
+}
+
+assert_eq!(10, FieldlessWithDiscrimants::First as u8);
+assert_eq!(11, FieldlessWithDiscrimants::Tuple() as u8);
+assert_eq!(20, FieldlessWithDiscrimants::Second as u8);
+assert_eq!(21, FieldlessWithDiscrimants::Struct{} as u8);
+assert_eq!(22, FieldlessWithDiscrimants::Unit as u8);
+```
+
+#### Pointer casting
+
+If the enumeration specifies a [primitive representation], then the
+discriminant may be reliably accessed via unsafe pointer casting:
+
+```rust
+#[repr(u8)]
+enum Enum {
+    Unit,
+    Tuple(bool),
+    Struct{a: bool},
+}
+
+impl Enum {
+    fn discriminant(&self) -> u8 {
+        unsafe { *(self as *const Self as *const u8) }
+    }
+}
+
+let unit_like = Enum::Unit;
+let tuple_like = Enum::Tuple(true);
+let struct_like = Enum::Struct{a: false};
+
+assert_eq!(0, unit_like.discriminant());
+assert_eq!(1, tuple_like.discriminant());
+assert_eq!(2, struct_like.discriminant());
+```
+
+## Zero-variant enums
 
 Enums with zero variants are known as *zero-variant enums*. As they have
 no valid values, they cannot be instantiated.
@@ -181,8 +309,10 @@ enum E {
 [enumerated type]: ../types/enum.md
 [`mem::discriminant`]: ../../std/mem/fn.discriminant.html
 [never type]: ../types/never.md
+[unit-only]: #unit-only-enum
 [numeric cast]: ../expressions/operator-expr.md#semantics
 [constant expression]: ../const_eval.md#constant-expressions
 [default representation]: ../type-layout.md#the-default-representation
 [primitive representation]: ../type-layout.md#primitive-representations
 [`C` representation]: ../type-layout.md#the-c-representation
+[Field-less enums]: #field-less-enum

src/linkage.md

@@ -73,7 +73,7 @@ be ignored in favor of only building the artifacts specified by command line.
   being built for a different target.
 
 Note that these outputs are stackable in the sense that if multiple are
-specified, then the compiler will produce each form of output at once without
+specified, then the compiler will produce each form of output without
 having to recompile. However, this only applies for outputs specified by the
 same method. If only `crate_type` attributes are specified, then they will all
 be built, but if one or more `--crate-type` command line flags are specified,

src/patterns.md

@@ -429,7 +429,7 @@ The bounds can be literals or paths that point to constant values.
 
 A half open range with only an upper bound is written as `..=` followed by its upper bound.
 These range patterns will match on any value less than or equal to the upper bound.
-For example, `..=10` will match 10, 1, 0, and for signed interger types, all negative values.
+For example, `..=10` will match 10, 1, 0, and for signed integer types, all negative values.
 
 Half-open range patterns cannot be used as the top-level pattern for subpatterns in [slice patterns](#slice-patterns).
 

src/trait-bounds.md

@@ -27,7 +27,7 @@ provided on any type in a [where clause]. There are also shorter forms for
 certain common cases:
 
 * Bounds written after declaring a [generic parameter][generic]:
-  `fn f<A: Copy>() {}` is the same as `fn f<A> where A: Copy () {}`.
+  `fn f<A: Copy>() {}` is the same as `fn f<A>() where A: Copy {}`.
 * In trait declarations as [supertraits]: `trait Circle : Shape {}` is
   equivalent to `trait Circle where Self : Shape {}`.
 * In trait declarations as bounds on [associated types]: