From 415cafe9bbd6d6a624581dadd3b32a57900653d6 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 14 Jan 2025 10:43:33 -0800 Subject: [PATCH] Adjust position of rules attached to headers Adjusts the position of rules with headers to match the style from https://github.com/rust-lang/reference/pull/1710 --- src/keywords.md | 12 ++--- src/lifetime-elision.md | 9 ++-- src/macros.md | 6 +-- src/memory-allocation-and-lifetime.md | 3 +- src/names.md | 9 ++-- src/paths.md | 39 ++++++----------- src/patterns.md | 63 +++++++++------------------ src/runtime.md | 15 +++---- src/special-types-and-traits.md | 51 ++++++++-------------- 9 files changed, 69 insertions(+), 138 deletions(-) diff --git a/src/keywords.md b/src/keywords.md index e8c6cd908..cf2c5f8ac 100644 --- a/src/keywords.md +++ b/src/keywords.md @@ -1,6 +1,5 @@ -# Keywords - r[lex.keywords] +# Keywords Rust divides keywords into three categories: @@ -8,9 +7,8 @@ Rust divides keywords into three categories: * [reserved](#reserved-keywords) * [weak](#weak-keywords) -## Strict keywords - r[lex.keywords.strict] +## Strict keywords r[lex.keywords.strict.intro] These keywords can only be used in their correct contexts. They cannot @@ -71,9 +69,8 @@ The following keywords were added beginning in the 2018 edition. > KW_AWAIT : `await`\ > KW_DYN : `dyn` -## Reserved keywords - r[lex.keywords.reserved] +## Reserved keywords r[lex.keywords.reserved.intro] These keywords aren't used yet, but they are reserved for future use. They have @@ -107,9 +104,8 @@ The following keywords are reserved beginning in the 2024 edition. > **Lexer 2024+**\ > KW_GEN : `gen` -## Weak keywords - r[lex.keywords.weak] +## Weak keywords r[lex.keywords.weak.intro] These keywords have special meaning only in certain contexts. For example, it diff --git a/src/lifetime-elision.md b/src/lifetime-elision.md index d80118b33..ade704aec 100644 --- a/src/lifetime-elision.md +++ b/src/lifetime-elision.md @@ -1,13 +1,11 @@ -# Lifetime elision - r[lifetime-elision] +# Lifetime elision Rust has rules that allow lifetimes to be elided in various places where the compiler can infer a sensible default choice. -## Lifetime elision in functions - r[lifetime-elision.function] +## Lifetime elision in functions r[lifetime-elision.function.intro] In order to make common patterns more ergonomic, lifetime arguments can be @@ -91,9 +89,8 @@ fn frob(s: &str, t: &str) -> &str; // ILLEGAL # } ``` -## Default trait object lifetimes - r[lifetime-elision.trait-object] +## Default trait object lifetimes r[lifetime-elision.trait-object.intro] The assumed lifetime of references held by a [trait object] is called its diff --git a/src/macros.md b/src/macros.md index c8c76fb74..62e6ace20 100644 --- a/src/macros.md +++ b/src/macros.md @@ -1,6 +1,5 @@ -# Macros - r[macro] +# Macros r[macro.intro] The functionality and syntax of Rust can be extended with custom definitions @@ -13,9 +12,8 @@ There are two ways to define new macros: * [Procedural Macros] define function-like macros, custom derives, and custom attributes using functions that operate on input tokens. -## Macro Invocation - r[macro.invocation] +## Macro Invocation r[macro.invocation.syntax] > **Syntax**\ diff --git a/src/memory-allocation-and-lifetime.md b/src/memory-allocation-and-lifetime.md index 267afbf52..2c4f7643f 100644 --- a/src/memory-allocation-and-lifetime.md +++ b/src/memory-allocation-and-lifetime.md @@ -1,6 +1,5 @@ -# Memory allocation and lifetime - r[alloc] +# Memory allocation and lifetime r[alloc.static] The _items_ of a program are those functions, modules, and types that have their diff --git a/src/names.md b/src/names.md index 300a0f9e3..92d2cd82c 100644 --- a/src/names.md +++ b/src/names.md @@ -1,6 +1,5 @@ -# Names - r[names] +# Names r[names.intro] An *entity* is a language construct that can be referred to in some way within @@ -36,9 +35,8 @@ and labels to entity declarations. r[names.visibility] Access to certain names may be restricted based on their [*visibility*]. -## Explicitly declared entities - r[names.explicit] +## Explicitly declared entities r[names.explicit.list] Entities that explicitly introduce a name in the source code are: @@ -87,9 +85,8 @@ r[names.explicit.macro-invocation] Additionally, [macro invocations] and [attributes] can introduce names by expanding to one of the above items. -## Implicitly declared entities - r[names.implicit] +## Implicitly declared entities r[names.implicit.list] The following entities are implicitly defined by the language, or are diff --git a/src/paths.md b/src/paths.md index a11929df3..262590344 100644 --- a/src/paths.md +++ b/src/paths.md @@ -1,6 +1,5 @@ -# Paths - r[paths] +# Paths r[paths.intro] A *path* is a sequence of one or more path segments separated by `::` tokens. @@ -16,9 +15,8 @@ x::y::z; ## Types of paths -### Simple Paths - r[paths.simple] +### Simple Paths r[paths.simple.syntax] > **Syntax**\ @@ -40,9 +38,8 @@ mod m { } ``` -### Paths in expressions - r[paths.expr] +### Paths in expressions r[paths.expr.syntax] > **Syntax**\ @@ -99,9 +96,8 @@ r[paths.expr.impl-trait-params] The synthetic type parameters corresponding to `impl Trait` types are implicit, and these cannot be explicitly specified. -## Qualified paths - r[paths.qualified] +## Qualified paths r[paths.qualified.syntax] > **Syntax**\ @@ -137,9 +133,8 @@ S::f(); // Calls the inherent impl. ::f(); // Calls the T2 trait function. ``` -### Paths in types - r[paths.type] +### Paths in types r[paths.type.syntax] > **Syntax**\ @@ -179,16 +174,14 @@ fn i<'a>() -> impl Iterator> { type G = std::boxed::Box isize>; ``` -## Path qualifiers - r[paths.qualifiers] +## Path qualifiers Paths can be denoted with various leading qualifiers to change the meaning of how it is resolved. -### `::` - r[paths.qualifiers.global-root] +### `::` r[paths.qualifiers.global-root.intro] Paths starting with `::` are considered to be *global paths* where the segments of the path @@ -227,9 +220,8 @@ mod b { # fn main() {} ``` -### `self` - r[paths.qualifiers.mod-self] +### `self` r[paths.qualifiers.mod-self.intro] `self` resolves the path relative to the current module. @@ -254,9 +246,8 @@ impl S { # fn main() {} ``` -### `Self` - r[paths.qualifiers.type-self] +### `Self` r[paths.qualifiers.type-self.intro] `Self`, with a capital "S", is used to refer to the current type being implemented or defined. It may be used in the following situations: @@ -319,9 +310,8 @@ struct NonEmptyList { } ``` -### `super` - r[paths.qualifiers.super] +### `super` r[paths.qualifiers.super.intro] `super` in a path resolves to the parent module. @@ -361,9 +351,8 @@ mod a { # fn main() {} ``` -### `crate` - r[paths.qualifiers.crate] +### `crate` r[paths.qualifiers.crate.intro] `crate` resolves the path relative to the current crate. @@ -381,9 +370,8 @@ mod a { # fn main() {} ``` -### `$crate` - r[paths.qualifiers.macro-crate] +### `$crate` r[paths.qualifiers.macro-crate.allowed-positions] `$crate` is only used within [macro transcribers], and can only be used as the first @@ -406,9 +394,8 @@ macro_rules! inc { # fn main() { } ``` -## Canonical paths - r[paths.canonical] +## Canonical paths r[paths.canonical.intro] Items defined in a module or implementation have a *canonical path* that diff --git a/src/patterns.md b/src/patterns.md index 977f6afc4..40f023b0f 100644 --- a/src/patterns.md +++ b/src/patterns.md @@ -1,6 +1,5 @@ -# Patterns - r[patterns] +# Patterns r[patterns.syntax] > **Syntax**\ @@ -85,9 +84,8 @@ r[patterns.while-let] r[patterns.for] * [`for` expressions](expressions/loop-expr.md#iterator-loops) -## Destructuring - r[patterns.destructure] +## Destructuring r[patterns.destructure.intro] Patterns can be used to *destructure* [structs], [enums], and [tuples]. @@ -119,9 +117,8 @@ match message { }; ``` -## Refutability - r[patterns.refutable] +## Refutability A pattern is said to be *refutable* when it has the possibility of not being matched by the value it is being matched against. *Irrefutable* patterns, on the other hand, always match the value they are being matched against. @@ -137,9 +134,8 @@ if let (a, 3) = (1, 2) { // "(a, 3)" is refutable, and will not match } ``` -## Literal patterns - r[patterns.literal] +## Literal patterns r[patterns.literal.syntax] > **Syntax**\ @@ -190,9 +186,8 @@ for i in -2..5 { } ``` -## Identifier patterns - r[patterns.ident] +## Identifier patterns r[patterns.ident.syntax] > **Syntax**\ @@ -290,9 +285,8 @@ It is an error if `ref` or `ref mut` is specified and the identifier shadows a c r[patterns.ident.refutable] Identifier patterns are irrefutable if the `@` subpattern is irrefutable or the subpattern is not specified. -### Binding modes - r[patterns.ident.binding] +### Binding modes r[patterns.ident.binding.intro] To service better ergonomics, patterns operate in different *binding modes* in order to make it easier to bind references to values. @@ -372,9 +366,8 @@ Example: let Person { name, ref age } = person; ``` -## Wildcard pattern - r[patterns.wildcard] +## Wildcard pattern r[patterns.wildcard.syntax] > **Syntax**\ @@ -422,9 +415,8 @@ if let Some(_) = x {} r[patterns.wildcard.refutable] The wildcard pattern is always irrefutable. -## Rest patterns - r[patterns.rest] +## Rest patterns > **Syntax**\ > _RestPattern_ :\ @@ -480,9 +472,8 @@ match tuple { } ``` -## Range patterns - r[patterns.range] +## Range patterns r[patterns.range.syntax] > **Syntax**\ @@ -665,9 +656,8 @@ The range of values for a `char` type are precisely those ranges containing all r[patterns.range.edition2021] > **Edition differences**: Before the 2021 edition, range patterns with both a lower and upper bound may also be written using `...` in place of `..=`, with the same meaning. -## Reference patterns - r[patterns.ref] +## Reference patterns r[patterns.ref.syntax] > **Syntax**\ @@ -697,9 +687,8 @@ Adding the `mut` keyword dereferences a mutable reference. The mutability must m r[patterns.ref.refutable] Reference patterns are always irrefutable. -## Struct patterns - r[patterns.struct] +## Struct patterns r[patterns.struct.syntax] > **Syntax**\ @@ -817,9 +806,8 @@ let Struct{a: x, b: y, c: z} = struct_value; // destructure all fields r[patterns.struct.refutable] A struct pattern is refutable if the _PathInExpression_ resolves to a constructor of an enum with more than one variant, or one of its subpatterns is refutable. -## Tuple struct patterns - r[patterns.tuple-struct] +## Tuple struct patterns r[patterns.tuple-struct.syntax] > **Syntax**\ @@ -836,9 +824,8 @@ They are also used to [destructure](#destructuring) a tuple struct or enum value r[patterns.tuple-struct.refutable] A tuple struct pattern is refutable if the _PathInExpression_ resolves to a constructor of an enum with more than one variant, or one of its subpatterns is refutable. -## Tuple patterns - r[patterns.tuple] +## Tuple patterns r[patterns.tuple.syntax] > **Syntax**\ @@ -870,9 +857,8 @@ assert_eq!(a, 10); assert_eq!(b, "ten"); ``` -## Grouped patterns - r[patterns.paren] +## Grouped patterns r[patterns.paren.syntax] > **Syntax**\ @@ -891,9 +877,8 @@ match int_reference { } ``` -## Slice patterns - r[patterns.slice] +## Slice patterns r[patterns.slice.syntax] > **Syntax**\ @@ -934,9 +919,8 @@ r[patterns.slice.restriction] Within a slice, a range pattern without both lower and upper bound must be enclosed in parentheses, as in `(a..)`, to clarify it is intended to match against a single slice element. A range pattern with both lower and upper bound, like `a..=b`, is not required to be enclosed in parentheses. -## Path patterns - r[patterns.path] +## Path patterns r[patterns.path.syntax] > **Syntax**\ @@ -962,9 +946,8 @@ r[patterns.path.refutable] Path patterns are irrefutable when they refer to structs or an enum variant when the enum has only one variant or a constant whose type is irrefutable. They are refutable when they refer to refutable constants or enum variants for enums with multiple variants. -### Constant patterns - r[patterns.const] +### Constant patterns r[patterns.const.partial-eq] When a constant `C` of type `T` is used as a pattern, we first check that `T: PartialEq`. @@ -1004,17 +987,15 @@ After ensuring all conditions are met, the constant value is translated into a p In particular, it fully participates in exhaustiveness checking. (For raw pointers, constants are the only way to write such patterns. Only `_` is ever considered exhaustive for these types.) -## Or-patterns - r[patterns.or] +## Or-patterns _Or-patterns_ are patterns that match on one of two or more sub-patterns (for example `A | B | C`). They can nest arbitrarily. Syntactically, or-patterns are allowed in any of the places where other patterns are allowed (represented by the _Pattern_ production), with the exceptions of `let`-bindings and function and closure arguments (represented by the _PatternNoTopAlt_ production). -### Static semantics - r[patterns.constraints] +### Static semantics r[patterns.constraints.pattern] 1. Given a pattern `p | q` at some depth for some arbitrary patterns `p` and `q`, the pattern is considered ill-formed if: @@ -1040,9 +1021,8 @@ r[patterns.constraints.exhaustiveness-or-pattern] Note that by *"constructor"* we do not refer to tuple struct patterns, but rather we refer to a pattern for any product type. This includes enum variants, tuple structs, structs with named fields, arrays, tuples, and slices. -### Dynamic semantics - r[patterns.behavior] +### Dynamic semantics r[patterns.behavior.nested-or-patterns] 1. The dynamic semantics of pattern matching a scrutinee expression `e_s` against a pattern `c(p | q, ..rest)` at depth `d` where `c` is some constructor, @@ -1050,9 +1030,8 @@ r[patterns.behavior.nested-or-patterns] and `rest` is optionally any remaining potential factors in `c`, is defined as being the same as that of `c(p, ..rest) | c(q, ..rest)`. -### Precedence with other undelimited patterns - r[patterns.precedence] +### Precedence with other undelimited patterns As shown elsewhere in this chapter, there are several types of patterns that are syntactically undelimited, including identifier patterns, reference patterns, and or-patterns. Or-patterns always have the lowest-precedence. diff --git a/src/runtime.md b/src/runtime.md index e49e3403b..22bfd4672 100644 --- a/src/runtime.md +++ b/src/runtime.md @@ -1,12 +1,10 @@ -# The Rust runtime - r[runtime] +# The Rust runtime This section documents features that define some aspects of the Rust runtime. -## The `panic_handler` attribute - r[runtime.panic_handler] +## The `panic_handler` attribute r[runtime.panic_handler.allowed-positions] The *`panic_handler` attribute* can only be applied to a function with signature @@ -55,25 +53,22 @@ fn panic(info: &PanicInfo) -> ! { } ``` -### Standard behavior - r[runtime.panic_handler.std] +### Standard behavior The standard library provides an implementation of `panic_handler` that defaults to unwinding the stack but that can be [changed to abort the process][abort]. The standard library's panic behavior can be modified at runtime with the [set_hook] function. -## The `global_allocator` attribute - r[runtime.global_allocator] +## The `global_allocator` attribute The *`global_allocator` attribute* is used on a [static item] implementing the [`GlobalAlloc`] trait to set the global allocator. -## The `windows_subsystem` attribute - r[runtime.windows_subsystem] +## The `windows_subsystem` attribute r[runtime.windows_subsystem.intro] The *`windows_subsystem` attribute* may be applied at the crate level to set diff --git a/src/special-types-and-traits.md b/src/special-types-and-traits.md index 0547b3681..dc34dffae 100644 --- a/src/special-types-and-traits.md +++ b/src/special-types-and-traits.md @@ -1,15 +1,13 @@ -# Special types and traits - r[lang-types] +# Special types and traits r[lang-types.intro] Certain types and traits that exist in [the standard library] are known to the Rust compiler. This chapter documents the special features of these types and traits. -## `Box` - r[lang-types.box] +## `Box` r[lang-types.box.intro] [`Box`] has a few special features that Rust doesn't currently allow for user @@ -29,30 +27,26 @@ r[lang-types.box.fundamental] -## `Rc` - r[lang-types.rc] +## `Rc` r[lang-types.rc.receiver] [Methods] can take [`Rc`] as a receiver. -## `Arc` - r[lang-types.arc] +## `Arc` r[lang-types.arc.receiver] [Methods] can take [`Arc`] as a receiver. -## `Pin

` - r[lang-types.pin] +## `Pin

` r[lang-types.pin.receiver] [Methods] can take [`Pin

`] as a receiver. -## `UnsafeCell` - r[lang-types.unsafe-cell] +## `UnsafeCell` r[lang-types.unsafe-cell.interior-mut] [`std::cell::UnsafeCell`] is used for [interior mutability]. It ensures that @@ -62,38 +56,33 @@ r[lang-types.unsafe-cell.read-only-alloc] It also ensures that [`static` items] which have a type with interior mutability aren't placed in memory marked as read only. -## `PhantomData` - r[lang-types.phantom-data] +## `PhantomData` [`std::marker::PhantomData`] is a zero-sized, minimum alignment, type that is considered to own a `T` for the purposes of [variance], [drop check], and [auto traits](#auto-traits). -## Operator Traits - r[lang-types.ops] +## Operator Traits The traits in [`std::ops`] and [`std::cmp`] are used to overload [operators], [indexing expressions], and [call expressions]. -## `Deref` and `DerefMut` - r[lang-types.deref] +## `Deref` and `DerefMut` As well as overloading the unary `*` operator, [`Deref`] and [`DerefMut`] are also used in [method resolution] and [deref coercions]. -## `Drop` - r[lang-types.drop] +## `Drop` The [`Drop`] trait provides a [destructor], to be run whenever a value of this type is to be destroyed. -## `Copy` - r[lang-types.copy] +## `Copy` r[lang-types.copy.intro] The [`Copy`] trait changes the semantics of a type implementing it. @@ -121,9 +110,8 @@ r[lang-types.copy.fn-item] r[lang-types.copy.closure] * [Closures] that capture no values or that only capture values of `Copy` types -## `Clone` - r[lang-types.clone] +## `Clone` r[lang-types.clone.intro] The [`Clone`] trait is a supertrait of `Copy`, so it also needs compiler @@ -141,16 +129,14 @@ r[lang-types.clone.tuple] r[lang-types.clone.closure] * [Closures] that only capture values of `Clone` types or capture no values from the environment -## `Send` - r[lang-types.send] +## `Send` The [`Send`] trait indicates that a value of this type is safe to send from one thread to another. -## `Sync` - r[lang-types.sync] +## `Sync` r[lang-types.sync.intro] The [`Sync`] trait indicates that a value of this type is safe to share between @@ -159,15 +145,13 @@ multiple threads. r[lang-types.sync.static-constraint] This trait must be implemented for all types used in immutable [`static` items]. -## `Termination` - r[lang-types.termination] +## `Termination` The [`Termination`] trait indicates the acceptable return types for the [main function] and [test functions]. -## Auto traits - r[lang-types.auto-traits] +## Auto traits The [`Send`], [`Sync`], [`Unpin`], [`UnwindSafe`], and [`RefUnwindSafe`] traits are _auto traits_. Auto traits have special properties. @@ -214,9 +198,8 @@ Auto traits may be added as an additional bound to any [trait object], even though normally only one trait is allowed. For instance, `Box` is a valid type. -## `Sized` - r[lang-types.sized] +## `Sized` r[lang-types.sized.intro] The [`Sized`] trait indicates that the size of this type is known at compile-time; that is, it's not a [dynamically sized type].