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

Author: Kyle Strand

src/behavior-considered-undefined.md

@@ -78,13 +78,18 @@ reading uninitialized memory is permitted are inside `union`s and in "padding"
 [dangling]: #dangling-pointers
 
 A reference/pointer is "dangling" if it is null or not all of the bytes it
-points to are part of the same allocation (so in particular they all have to be
+points to are part of the same live allocation (so in particular they all have to be
 part of *some* allocation). The span of bytes it points to is determined by the
-pointer value and the size of the pointee type (using `size_of_val`). As a
-consequence, if the span is empty, "dangling" is the same as "non-null". Note
-that slices and strings point to their entire range, so it is important that the length
-metadata is never too large. In particular, allocations and therefore slices and strings
-cannot be bigger than `isize::MAX` bytes.
+pointer value and the size of the pointee type (using `size_of_val`).
+
+If the size is 0, then the pointer must either point inside of a live allocation
+(including pointing just after the last byte of the allocation), or it must be
+directly constructed from a non-zero integer literal.
+
+Note that dynamically sized types (such as slices and strings) point to their
+entire range, so it is important that the length metadata is never too large. In
+particular, the dynamic size of a Rust value (as determined by `size_of_val`)
+must never exceed `isize::MAX`.
 
 [`bool`]: types/boolean.md
 [`const`]: items/constant-items.md

src/expressions.md

@@ -157,7 +157,7 @@ A *value expression* is an expression that represents an actual value.
 The following contexts are *place expression* contexts:
 
 * The left operand of a [compound assignment] expression.
-* The operand of a unary [borrow] or [dereference][deref] operator.
+* The operand of a unary [borrow], [address-of][addr-of] or [dereference][deref] operator.
 * The operand of a field expression.
 * The indexed operand of an array indexing expression.
 * The operand of any [implicit borrow].
@@ -308,6 +308,7 @@ They are never allowed before:
 
 [assign]:               expressions/operator-expr.md#assignment-expressions
 [borrow]:               expressions/operator-expr.md#borrow-operators
+[addr-of]:              expressions/operator-expr.md#raw-address-of-operators
 [comparison]:           expressions/operator-expr.md#comparison-operators
 [compound assignment]:  expressions/operator-expr.md#compound-assignment-expressions
 [deref]:                expressions/operator-expr.md#the-dereference-operator

src/expressions/operator-expr.md

@@ -79,6 +79,50 @@ let a = && && mut 10;
 let a = & & & & mut 10;
 ```
 
+### Raw address-of operators
+
+Related to the borrow operators are the *raw address-of operators*, which do not have first-class syntax, but are exposed via the macros [`ptr::addr_of!(expr)`][addr_of] and [`ptr::addr_of_mut!(expr)`][addr_of_mut].
+The expression `expr` is evaluated in place expression context.
+`ptr::addr_of!(expr)` then creates a const raw pointer of type `*const T` to the given place, and `ptr::addr_of_mut!(expr)` creates a mutable raw pointer of type `*mut T`.
+
+The raw address-of operators must be used instead of a borrow operator whenever the place expression could evaluate to a place that is not properly aligned or does not store a valid value as determined by its type, or whenever creating a reference would introduce incorrect aliasing assumptions.
+In those situations, using a borrow operator would cause [undefined behavior] by creating an invalid reference, but a raw pointer may still be constructed using an address-of operator.
+
+The following is an example of creating a raw pointer to an unaligned place through a `packed` struct:
+
+```rust
+use std::ptr;
+
+#[repr(packed)]
+struct Packed {
+    f1: u8,
+    f2: u16,
+}
+
+let packed = Packed { f1: 1, f2: 2 };
+// `&packed.f2` would create an unaligned reference, and thus be Undefined Behavior!
+let raw_f2 = ptr::addr_of!(packed.f2);
+assert_eq!(unsafe { raw_f2.read_unaligned() }, 2);
+```
+
+The following is an example of creating a raw pointer to a place that does not contain a valid value:
+
+```rust
+use std::{ptr, mem::MaybeUninit};
+
+struct Demo {
+    field: bool,
+}
+
+let mut uninit = MaybeUninit::<Demo>::uninit();
+// `&uninit.as_mut().field` would create a reference to an uninitialized `bool`,
+// and thus be Undefined Behavior!
+let f1_ptr = unsafe { ptr::addr_of_mut!((*uninit.as_mut_ptr()).field) };
+unsafe { f1_ptr.write(true); }
+let init = unsafe { uninit.assume_init() };
+```
+
+
 ## The dereference operator
 
 > **<sup>Syntax</sup>**\
@@ -605,6 +649,9 @@ See [this test] for an example of using this dependency.
 [float-float]: https://github.com/rust-lang/rust/issues/15536
 [Function pointer]: ../types/function-pointer.md
 [Function item]: ../types/function-item.md
+[undefined behavior]: ../behavior-considered-undefined.md
+[addr_of]: ../../std/ptr/macro.addr_of.html
+[addr_of_mut]: ../../std/ptr/macro.addr_of_mut.html
 
 [_BorrowExpression_]: #borrow-operators
 [_DereferenceExpression_]: #the-dereference-operator

src/items/external-blocks.md

@@ -162,6 +162,29 @@ this to satisfy the linking requirements of extern blocks elsewhere in your
 code (including upstream crates) instead of adding the attribute to each extern
 block.
 
+#### Linking modifiers: `bundle`
+
+This modifier is only compatible with the `static` linking kind.
+Using any other kind will result in a compiler error.
+
+When building a rlib or staticlib `+bundle` means that all object files from the native static
+library will be added to the rlib or staticlib archive, and then used from it during linking of
+the final binary.
+
+When building a rlib `-bundle` means that the native static library is registered as a dependency
+of that rlib "by name", and object files from it are included only during linking of the final
+binary, the file search by that name is also performed during final linking. \
+When building a staticlib `-bundle` means that the native static library is simply not included
+into the archive and some higher level build system will need to add it later during linking of
+the final binary.
+
+This modifier has no effect when building other targets like executables or dynamic libraries.
+
+The default for this modifier is `+bundle`.
+
+More implementation details about this modifier can be found in
+[`bundle` documentation for rustc].
+
 #### Linking modifiers: `whole-archive`
 
 This modifier is only compatible with the `static` linking kind.
@@ -170,7 +193,10 @@ Using any other kind will result in a compiler error.
 `+whole-archive` means that the static library is linked as a whole archive
 without throwing any object files away.
 
-More implementation details about this modifier can be found in [documentation for rustc].
+The default for this modifier is `-whole-archive`.
+
+More implementation details about this modifier can be found in
+[`whole-archive` documentation for rustc].
 
 ### The `link_name` attribute
 
@@ -205,4 +231,5 @@ restrictions as [regular function parameters].
 [_Visibility_]: ../visibility-and-privacy.md
 [attributes]: ../attributes.md
 [regular function parameters]: functions.md#attributes-on-function-parameters
-[documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-whole-archive
+[`bundle` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-bundle
+[`whole-archive` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-whole-archive

src/items/unions.md

@@ -20,6 +20,16 @@ The key property of unions is that all fields of a union share common storage.
 As a result, writes to one field of a union can overwrite its other fields, and
 size of a union is determined by the size of its largest field.
 
+Union field types are restricted to the following subset of types:
+- `Copy` types
+- References (`&T` and `&mut T` for arbitrary `T`)
+- `ManuallyDrop<T>` (for arbitrary `T`)
+- Tuples and arrays containing only allowed union field types
+
+This restriction ensures, in particular, that union fields never need to be
+dropped. Like for structs and enums, it is possible to `impl Drop` for a union
+to manually define what happens when it gets dropped.
+
 ## Initialization of a union
 
 A value of a union type can be created using the same syntax that is used for
@@ -67,32 +77,13 @@ unsafe {
 }
 ```
 
-Writes to [`Copy`] or [`ManuallyDrop`][ManuallyDrop] union fields do not
-require reads for running destructors, so these writes don't have to be placed
-in `unsafe` blocks
-
-```rust
-# use std::mem::ManuallyDrop;
-union MyUnion { f1: u32, f2: ManuallyDrop<String> }
-let mut u = MyUnion { f1: 1 };
-
-// These do not require `unsafe`.
-u.f1 = 2;
-u.f2 = ManuallyDrop::new(String::from("example"));
-```
-
 Commonly, code using unions will provide safe wrappers around unsafe union
 field accesses.
 
-## Unions and `Drop`
-
-When a union is dropped, it cannot know which of its fields needs to be dropped.
-For this reason, all union fields must either be of a [`Copy`] type or of the
-shape [`ManuallyDrop<_>`][ManuallyDrop].  This ensures that a union does not
-need to drop anything when it goes out of scope.
-
-Like for structs and enums, it is possible to `impl Drop` for a union to
-manually define what happens when it gets dropped.
+In contrast, writes to union fields are safe, since they just overwrite
+arbitrary data, but cannot cause undefined behavior. (Note that union field
+types can never have drop glue, so a union field write will never implicitly
+drop anything.)
 
 ## Pattern matching on unions
 

src/macros-by-example.md

@@ -193,6 +193,53 @@ compiler knows how to expand them properly:
     not have the same number. This requirement applies to every layer of nested
     repetitions.
 
+## Dollar-dollar ($$)
+
+`$$` expands to a single `$`.
+
+Since metavariable expressions always apply during the expansion of a macro, they cannot be used in recursive macro definitions and this is where `$$` expressions comes into play, i.e., `$$` can be used to resolve ambiguities in nested macros.
+
+The following example illustrates a macro that fails to compile due to the ambiguity of the repetition in a nested macro:
+
+```rust,compile_fail
+macro_rules! foo_error {
+    () => {
+        macro_rules! bar_error {
+            ( $( $any:tt )* ) => { $( $any )* };
+            // ^^^^^^^^^^^ error: attempted to repeat an expression containing no syntax variables matched as repeating at this depth
+        }
+    };
+}
+
+foo_error!();
+```
+
+The following resolves the problem by escaping the `$` in the repetition with `$$`:
+
+```rust
+macro_rules! foo_ok {
+    () => {
+        macro_rules! bar_ok {
+            ( $$( $any:tt )* ) => { $$( $any )* };
+        }
+    };
+}
+
+foo_ok!();
+```
+
+One consequence of such expansion is that deeper nested levels make dollar-dollar declarations grown linearly, starting at `$$`, then `$$$$`, then `$$$$$` and so on. This is also necessary to be fully featured so that it is possible to specify names of metavariables using other metavariables at each nesting level.
+
+```ignore
+$foo          => bar      => bar    // Evaluate foo at level 1
+$$foo         => $foo     => bar    // Evaluate foo at level 2
+$$$foo        => $bar     => baz    // Evaluate foo at level 1, and use that as a name at level 2
+$$$$foo       => $$foo    => $foo   // Evaluate foo at level 3
+$$$$$foo      => $$bar    => $bar   // Evaluate foo at level 1, and use that as a name at level 3
+$$$$$$foo     => $$$foo   => $bar   // Evaluate foo at level 2, and use that as a name at level 3
+$$$$$$$foo    => $$$bar   => $baz   // Evaluate foo at level 1, use that at level 2, and then use *that* at level 3
+```
+
 ## Scoping, Exporting, and Importing
 
 For historical reasons, the scoping of macros by example does not work entirely

src/paths.md

@@ -81,6 +81,9 @@ arguments, then const arguments, then equality constraints.
 Const arguments must be surrounded by braces unless they are a
 [literal] or a single segment path.
 
+The synthetic type parameters corresponding to `impl Trait` types are implicit,
+and these cannot be explicitly specified.
+
 ## Qualified paths
 
 > **<sup>Syntax</sup>**\

src/runtime.md

@@ -63,6 +63,13 @@ the [subsystem] when linking on a Windows target. It uses the
 `console` or `windows`. This attribute is ignored on non-Windows targets, and
 for non-`bin` [crate types].
 
+The "console" subsystem is the default. If a console process is run from an
+existing console then it will be attached to that console, otherwise a new
+console window will be created.
+
+The "windows" subsystem is commonly used by GUI applications that do not want to
+display a console window on startup. It will run detached from any existing console.
+
 ```rust
 #![windows_subsystem = "windows"]
 ```

src/subtyping.md

@@ -61,25 +61,51 @@ Variance of types is automatically determined as follows
 | `[T]` and `[T; n]`            |                   | covariant         |
 | `fn() -> T`                   |                   | covariant         |
 | `fn(T) -> ()`                 |                   | contravariant     |
-| `fn(T) -> T`                  |                   | invariant         |
 | `std::cell::UnsafeCell<T>`    |                   | invariant         |
 | `std::marker::PhantomData<T>` |                   | covariant         |
 | `dyn Trait<T> + 'a`           | covariant         | invariant         |
 
-The variance of other `struct`, `enum`, `union`, and tuple types is decided by
+The variance of other `struct`, `enum`, and `union` types is decided by
 looking at the variance of the types of their fields. If the parameter is used
 in positions with different variances then the parameter is invariant. For
-example the following struct is covariant in `'a` and `T` and invariant in `'b`
+example the following struct is covariant in `'a` and `T` and invariant in `'b`, `'c`,
 and `U`.
 
 ```rust
 use std::cell::UnsafeCell;
-struct Variance<'a, 'b, T, U: 'a> {
+struct Variance<'a, 'b, 'c, T, U: 'a> {
     x: &'a U,               // This makes `Variance` covariant in 'a, and would
                             // make it covariant in U, but U is used later
     y: *const T,            // Covariant in T
     z: UnsafeCell<&'b f64>, // Invariant in 'b
     w: *mut U,              // Invariant in U, makes the whole struct invariant
+
+    f: fn(&'c ()) -> &'c () // Both co- and contravariant, makes 'c invariant
+                            // in the struct.
+}
+```
+
+When used outside of an `struct`, `enum`, or `union`, the variance for parameters is checked at each location separately.
+
+```rust
+# use std::cell::UnsafeCell;
+fn generic_tuple<'short, 'long: 'short>(
+    // 'long is used inside of a tuple in both a co- and invariant position.
+    x: (&'long u32, UnsafeCell<&'long u32>),
+) {
+    // As the variance at these positions is computed separately,
+    // we can freely shrink 'long in the covariant position.
+    let _: (&'short u32, UnsafeCell<&'long u32>) = x;
+}
+
+fn takes_fn_ptr<'short, 'middle: 'short>(
+    // 'middle is used in both a co- and contravariant position.
+    f: fn(&'middle ()) -> &'middle (),
+) {
+    // As the variance at these positions is computed separately,
+    // we can freely shrink 'middle in the covariant position
+    // and extend it in the contravariant position.
+    let _: fn(&'static ()) -> &'short () = f;
 }
 ```
 

src/tokens.md

@@ -148,18 +148,28 @@ which must be _escaped_ by a preceding `U+005C` character (`\`).
 Line-breaks are allowed in string literals. A line-break is either a newline
 (`U+000A`) or a pair of carriage return and newline (`U+000D`, `U+000A`). Both
 byte sequences are normally translated to `U+000A`, but as a special exception,
-when an unescaped `U+005C` character (`\`) occurs immediately before the
-line-break, then the `U+005C` character, the line-break, and all whitespace at the
-beginning of the next line are ignored. Thus `a` and `b` are equal:
+when an unescaped `U+005C` character (`\`) occurs immediately before a line
+break, then the line break character(s), and all immediately following
+` ` (`U+0020`), `\t` (`U+0009`), `\n` (`U+000A`) and `\r` (`U+0000D`) characters
+are ignored. Thus `a`, `b` and `c` are equal:
 
 ```rust
 let a = "foobar";
 let b = "foo\
          bar";
+let c = "foo\
 
-assert_eq!(a,b);
+     bar";
+
+assert_eq!(a, b);
+assert_eq!(b, c);
 ```
 
+> Note: Rust skipping additional newlines (like in example `c`) is potentially confusing and
+> unexpected. This behavior may be adjusted in the future. Until a decision is made, it is
+> recommended to avoid relying on this, i.e. skipping multiple newlines with line continuations.
+> See [this issue](https://github.com/rust-lang/reference/pull/1042) for more information.
+
 #### Character escapes
 
 Some additional _escapes_ are available in either character or non-raw string