Merge branch 'master' into one-line-expressions

Author: ehuss

book.toml

@@ -10,6 +10,8 @@ edit-url-template = "https://github.com/rust-lang/reference/edit/master/{path}"
 
 [output.html.redirect]
 "/expressions/enum-variant-expr.html" = "struct-expr.html"
+"/unsafe-blocks.html" = "unsafe-keyword.html"
+"/unsafe-functions.html" = "unsafe-keyword.html"
 
 [rust]
 edition = "2021"

src/SUMMARY.md

@@ -118,8 +118,7 @@
 - [Inline assembly](inline-assembly.md)
 
 - [Unsafety](unsafety.md)
-    - [Unsafe functions](unsafe-functions.md)
-    - [Unsafe blocks](unsafe-blocks.md)
+    - [The `unsafe` keyword](unsafe-keyword.md)
     - [Behavior considered undefined](behavior-considered-undefined.md)
     - [Behavior not considered unsafe](behavior-not-considered-unsafe.md)
 

src/attributes/codegen.md

@@ -347,7 +347,7 @@ trait object whose methods are attributed.
 [target architecture]: ../conditional-compilation.md#target_arch
 [trait]: ../items/traits.md
 [undefined behavior]: ../behavior-considered-undefined.md
-[unsafe function]: ../unsafe-functions.md
+[unsafe function]: ../unsafe-keyword.md
 [rust-abi]: ../items/external-blocks.md#abi
 [`core::intrinsics::caller_location`]: ../../core/intrinsics/fn.caller_location.html
 [`core::panic::Location::caller`]: ../../core/panic/struct.Location.html#method.caller

src/conditional-compilation.md

@@ -191,6 +191,25 @@ Example values:
 * `"pc"`
 * `"unknown"`
 
+### `target_has_atomic`
+
+Key-value option set for each bit width that the target supports
+atomic loads, stores, and compare-and-swap operations.
+
+When this cfg is present, all of the stable [`core::sync::atomic`] APIs are available for
+the relevant atomic width.
+
+[`core::sync::atomic`]: ../core/sync/atomic/index.html
+
+Possible values:
+
+* `"8"`
+* `"16"`
+* `"32"`
+* `"64"`
+* `"128"`
+* `"ptr"`
+
 ### `test`
 
 Enabled when compiling the test harness. Done with `rustc` by using the

src/expressions/block-expr.md

@@ -140,6 +140,10 @@ unsafe {
 let a = unsafe { an_unsafe_fn() };
 ```
 
+## Labelled block expressions
+
+Labelled block expressions are documented in the [Loops and other breakable expressions] section.
+
 ## Attributes on block expressions
 
 [Inner attributes] are allowed directly after the opening brace of a block expression in the following situations:
@@ -189,3 +193,4 @@ fn is_unix_platform() -> bool {
 [tuple expressions]: tuple-expr.md
 [unsafe operations]: ../unsafety.md
 [value expressions]: ../expressions.md#place-expressions-and-value-expressions
+[Loops and other breakable expressions]: loop-expr.md#labelled-block-expressions

src/expressions/loop-expr.md

@@ -1,4 +1,4 @@
-# Loops
+# Loops and other breakable expressions
 
 > **<sup>Syntax</sup>**\
 > _LoopExpression_ :\
@@ -7,23 +7,27 @@
 > &nbsp;&nbsp; &nbsp;&nbsp; | [_PredicateLoopExpression_]\
 > &nbsp;&nbsp; &nbsp;&nbsp; | [_PredicatePatternLoopExpression_]\
 > &nbsp;&nbsp; &nbsp;&nbsp; | [_IteratorLoopExpression_]\
+> &nbsp;&nbsp; &nbsp;&nbsp; | [_LabelBlockExpression_]\
 > &nbsp;&nbsp; )
 
 [_LoopLabel_]: #loop-labels
 [_InfiniteLoopExpression_]: #infinite-loops
 [_PredicateLoopExpression_]: #predicate-loops
 [_PredicatePatternLoopExpression_]: #predicate-pattern-loops
 [_IteratorLoopExpression_]: #iterator-loops
+[_LabelBlockExpression_]: #labelled-block-expressions
 
-Rust supports four loop expressions:
+Rust supports five loop expressions:
 
 *   A [`loop` expression](#infinite-loops) denotes an infinite loop.
 *   A [`while` expression](#predicate-loops) loops until a predicate is false.
 *   A [`while let` expression](#predicate-pattern-loops) tests a pattern.
 *   A [`for` expression](#iterator-loops) extracts values from an iterator, looping until the iterator is empty.
+*   A [labelled block expression](#labelled-block-expressions) runs a loop exactly once, but allows exiting the loop early with `break`.
 
-All four types of loop support [`break` expressions](#break-expressions), [`continue` expressions](#continue-expressions), and [labels](#loop-labels).
-Only `loop` supports [evaluation to non-trivial values](#break-and-loop-values).
+All five types of loop support [`break` expressions](#break-expressions), and [labels](#loop-labels).
+All except labelled block expressions support [`continue` expressions](#continue-expressions).
+Only `loop` and labelled block expressions support [evaluation to non-trivial values](#break-and-loop-values).
 
 ## Infinite loops
 
@@ -193,6 +197,18 @@ A loop expression may optionally have a _label_. The label is written as a lifet
 If a label is present, then labeled `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).
 
+Labels follow the hygiene and shadowing rules of local variables. For example, this code will print "outer loop":
+
+```rust
+'a: loop {
+    'a: loop {
+        break 'a;
+    }
+    print!("outer loop");
+    break 'a;
+}
+```
+
 ## `break` expressions
 
 > **<sup>Syntax</sup>**\
@@ -226,6 +242,16 @@ Example:
 
 A `break` expression is only permitted in the body of a loop, and has one of the forms `break`, `break 'label` or ([see below](#break-and-loop-values)) `break EXPR` or `break 'label EXPR`.
 
+## Labelled block expressions
+
+> **<sup>Syntax</sup>**\
+> _LabelBlockExpression_ :\
+> &nbsp;&nbsp; [_BlockExpression_]
+
+Labelled block expressions are exactly like block expressions, except that they allow using `break` expressions within the block.
+Unlike other loops, `break` expressions within a label expression *must* have a label (i.e. the label is not optional).
+Unlike other loops, labelled block expressions *must* begin with a label.
+
 ## `continue` expressions
 
 > **<sup>Syntax</sup>**\

src/items/functions.md

@@ -59,8 +59,8 @@ fn answer_to_life_the_universe_and_everything() -> i32 {
 
 ## Function parameters
 
-As with `let` bindings, function parameters are irrefutable [patterns], so any
-pattern that is valid in a let binding is also valid as a parameter:
+Function parameters are irrefutable [patterns], so any pattern that is valid in
+an else-less `let` binding is also valid as a parameter:
 
 ```rust
 fn first((value, _): (i32, i32)) -> i32 { value }

src/statements.md

@@ -46,13 +46,35 @@ fn outer() {
 > **<sup>Syntax</sup>**\
 > _LetStatement_ :\
 > &nbsp;&nbsp; [_OuterAttribute_]<sup>\*</sup> `let` [_PatternNoTopAlt_]
->     ( `:` [_Type_] )<sup>?</sup> (`=` [_Expression_] )<sup>?</sup> `;`
-
-A *`let` statement* introduces a new set of [variables], given by an irrefutable [pattern].
-The pattern is followed optionally by a type annotation and then optionally by an initializer expression.
+>     ( `:` [_Type_] )<sup>?</sup> (`=` [_Expression_] [†](#let-else-restriction)
+>     ( `else` [_BlockExpression_]) <sup>?</sup> ) <sup>?</sup> `;`
+>
+> <span id="let-else-restriction">† When an `else` block is specified, the
+> _Expression_ must not be a [_LazyBooleanExpression_], or end with a `}`.</span>
+
+A *`let` statement* introduces a new set of [variables], given by a [pattern].
+The pattern is followed optionally by a type annotation and then either ends,
+or is followed by an initializer expression plus an optional `else` block.
 When no type annotation is given, the compiler will infer the type, or signal an error if insufficient type information is available for definite inference.
 Any variables introduced by a variable declaration are visible from the point of declaration until the end of the enclosing block scope, except when they are shadowed by another variable declaration.
 
+If an `else` block is not present, the pattern must be irrefutable.
+If an `else` block is present, the pattern may be refutable.
+If the pattern does not match (this requires it to be refutable), the `else`
+block is executed.
+The `else` block must always diverge (evaluate to the [never type]).
+
+```rust
+let (mut v, w) = (vec![1, 2, 3], 42); // The bindings may be mut or const
+let Some(t) = v.pop() else { // Refutable patterns require an else block
+    panic!(); // The else block must diverge
+};
+let [u, v] = [v[0], v[1]] else { // This pattern is irrefutable, so the compiler
+                                 // will lint as the else block is redundant.
+    panic!();
+};
+```
+
 ## Expression statements
 
 > **<sup>Syntax</sup>**\
@@ -106,16 +128,19 @@ The attributes that have meaning on a statement are [`cfg`], and [the lint check
 [function]: items/functions.md
 [item]: items.md
 [module]: items/modules.md
+[never type]: types/never.md
 [canonical path]: paths.md#canonical-paths
 [implementations]: items/implementations.md
 [variables]: variables.md
 [outer attributes]: attributes.md
 [`cfg`]: conditional-compilation.md
 [the lint check attributes]: attributes/diagnostics.md#lint-check-attributes
 [pattern]: patterns.md
+[_BlockExpression_]: expressions/block-expr.md
 [_ExpressionStatement_]: #expression-statements
 [_Expression_]: expressions.md
 [_Item_]: items.md
+[_LazyBooleanExpression_]: expressions/operator-expr.md#lazy-boolean-operators
 [_LetStatement_]: #let-statements
 [_MacroInvocationSemi_]: macros.md#macro-invocation
 [_OuterAttribute_]: attributes.md

src/types/function-pointer.md

@@ -62,5 +62,5 @@ restrictions as [regular function parameters].
 [closures]: closure.md
 [extern function]: ../items/functions.md#extern-function-qualifier
 [function items]: function-item.md
-[unsafe function]: ../unsafe-functions.md
+[unsafe function]: ../unsafe-keyword.md
 [regular function parameters]: ../items/functions.md#attributes-on-function-parameters

src/unsafe-blocks.md

@@ -0,0 +1,58 @@
+# The `unsafe` keyword
+
+The `unsafe` keyword can occur in several different contexts:
+unsafe functions (`unsafe fn`), unsafe blocks (`unsafe {}`), unsafe traits (`unsafe trait`), and unsafe trait implementations (`unsafe impl`).
+It plays several different roles, depending on where it is used and whether the `unsafe_op_in_unsafe_fn` lint is enabled:
+- it is used to mark code that *defines* extra safety conditions (`unsafe fn`, `unsafe trait`)
+- it is used to mark code that needs to *satisfy* extra safety conditions (`unsafe {}`, `unsafe impl`, `unsafe fn` without [`unsafe_op_in_unsafe_fn`])
+
+The following discusses each of these cases.
+See the [keyword documentation][keyword] for some illustrative examples.
+
+## Unsafe functions (`unsafe fn`)
+
+Unsafe functions are functions that are not safe in all contexts and/or for all possible inputs.
+We say they have *extra safety conditions*, which are requirements that must be upheld by all callers and that the compiler does not check.
+For example, [`get_unchecked`] has the extra safety condition that the index must be in-bounds.
+The unsafe function should come with documentation explaining what those extra safety conditions are.
+
+Such a function must be prefixed with the keyword `unsafe` and can only be called from inside an `unsafe` block, or inside `unsafe fn` without the [`unsafe_op_in_unsafe_fn`] lint.
+
+## Unsafe blocks (`unsafe {}`)
+
+A block of code can be prefixed with the `unsafe` keyword, to permit calling `unsafe` functions or dereferencing raw pointers.
+By default, the body of an unsafe function is also considered to be an unsafe block;
+this can be changed by enabling the [`unsafe_op_in_unsafe_fn`] lint.
+
+By putting operations into an unsafe block, the programmer states that they have taken care of satisfying the extra safety conditions of all operations inside that block.
+
+Unsafe blocks are the logical dual to unsafe functions:
+where unsafe functions define a proof obligation that callers must uphold, unsafe blocks state that all relevant proof obligations have been discharged.
+There are many ways to discharge proof obligations;
+for example, there could be run-time checks or data structure invariants that guarantee that certain properties are definitely true, or the unsafe block could be inside an `unsafe fn` and use its own proof obligations to discharge the proof obligations of its callees.
+
+Unsafe blocks are used to wrap foreign libraries, make direct use of hardware or implement features not directly present in the language.
+For example, Rust provides the language features necessary to implement memory-safe concurrency in the language but the implementation of threads and message passing in the standard library uses unsafe blocks.
+
+Rust's type system is a conservative approximation of the dynamic safety requirements, so in some cases there is a performance cost to using safe code.
+For example, a doubly-linked list is not a tree structure and can only be represented with reference-counted pointers in safe code.
+By using `unsafe` blocks to represent the reverse links as raw pointers, it can be implemented without reference counting.
+(See ["Learn Rust With Entirely Too Many Linked Lists"](https://rust-unofficial.github.io/too-many-lists/) for a more in-depth exploration of this particular example.)
+
+## Unsafe traits (`unsafe trait`)
+
+An unsafe trait is a trait that comes with extra safety conditions that must be upheld by *implementations* of the trait.
+The unsafe trait should come with documentation explaining what those extra safety conditions are.
+
+Such a trait must be prefixed with the keyword `unsafe` and can only be implemented by `unsafe impl` blocks.
+
+## Unsafe trait implementations (`unsafe impl`)
+
+When implementing an unsafe trait, the implementation needs to be prefixed with the `unsafe` keyword.
+By writing `unsafe impl`, the programmer states that they have taken care of satisfying the extra safety conditions required by the trait.
+
+Unsafe trait implementations are the logical dual to unsafe traits: where unsafe traits define a proof obligation that implementations must uphold, unsafe implementations state that all relevant proof obligations have been discharged.
+
+[keyword]: ../std/keyword.unsafe.html
+[`get_unchecked`]: ../std/primitive.slice.html#method.get_unchecked
+[`unsafe_op_in_unsafe_fn`]: ../rustc/lints/listing/allowed-by-default.html#unsafe-op-in-unsafe-fn