From fdee1043caa7b77cde6cbc031266d7da46bc08bf Mon Sep 17 00:00:00 2001 From: David Rheinsberg Date: Fri, 11 Aug 2023 10:08:46 +0200 Subject: [PATCH 01/25] type-layout: be more specific about 32-bit alignments The rust-reference implies that 64-bit types are aligned to 32-bit for platforms with 32-bit addresses. This is not necessarily correct. Fix the wording. Note that there is no general rule how data-types greater than the native address size are aligned. On most Unix'y systems, they use the native alignment of the platform. However, the Windows ABI aligns them to their size (up to at least 64-bit). There are advantages for either of those decisions. But we should at least make clear that there is no fixed rule for 32-bit platforms. Signed-off-by: David Rheinsberg --- src/type-layout.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/type-layout.md b/src/type-layout.md index 4c87954f3..3b6c0c33b 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -53,8 +53,8 @@ target platform. For example, on a 32 bit target, this is 4 bytes and on a 64 bit target, this is 8 bytes. Most primitives are generally aligned to their size, although this is -platform-specific behavior. In particular, on x86 u64 and f64 are only -aligned to 32 bits. +platform-specific behavior. In particular, on many 32-bit platforms `u64` +and `f64` are only aligned to 32 bits. ## Pointers and References Layout From d035af92a1991057eecd06e3c46166913262654a Mon Sep 17 00:00:00 2001 From: daxpedda Date: Wed, 1 Nov 2023 00:19:00 +0100 Subject: [PATCH 02/25] Stabilize Wasm target features that are in phase 4 and 5 --- src/attributes/codegen.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 7a50fe26f..0d3d6ad2e 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -273,10 +273,20 @@ attempting to use instructions unsupported by the Wasm engine will fail at load time without the risk of being interpreted in a way different from what the compiler expected. -Feature | Description -------------|------------------- -`simd128` | [WebAssembly simd proposal][simd128] - +Feature | Description +----------------------|------------------- +`bulk-memory` | [WebAssembly bulk memory operations proposal][bulk-memory] +`extended-const` | [WebAssembly extended const expressions proposal][extended-const] +`mutable-globals` | [WebAssembly mutable global proposal][mutable-globals] +`nontrapping-fptoint` | [WebAssembly non-trapping float-to-int conversion proposal][nontrapping-fptoint] +`sign-ext` | [WebAssembly sign extension operators Proposal][sign-ext] +`simd128` | [WebAssembly simd proposal][simd128] + +[bulk-memory]: https://github.com/WebAssembly/bulk-memory-operations +[extended-const]: https://github.com/WebAssembly/extended-const +[mutable-globals]: https://github.com/WebAssembly/mutable-global +[nontrapping-fptoint]: https://github.com/WebAssembly/nontrapping-float-to-int-conversions +[sign-ext]: https://github.com/WebAssembly/sign-extension-ops [simd128]: https://github.com/webassembly/simd ### Additional information From 0bf5d4e44c5f55092dfabb0f7b7f1a03352a4fe8 Mon Sep 17 00:00:00 2001 From: Vadim Petrochenkov Date: Tue, 13 Feb 2024 16:26:42 +0300 Subject: [PATCH 03/25] Add docs for `#[collapse_debuginfo]` attribute --- src/attributes/debugger.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 6ea80221e..468a1b2cf 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -139,3 +139,26 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil [Natvis documentation]: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects [pretty printing documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax + +## The `collapse_debuginfo` attribute + +This attribute controls whether code locations from this macro definition are collapsed into a +single location associated with the macro's call site, when generating debuginfo for code calling +this macro. + +The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can only be applied to +macro definitions. + +Accepted options: +- `#[collapse_debuginfo(yes)]` - code locations in debuginfo are collapsed. +- `#[collapse_debuginfo(no)]` - code locations in debuginfo are not collapsed. +- `#[collapse_debuginfo(external)]` - code locations in debuginfo are collapsed only if the macro + comes from a different crate. + +The `external` behavior is the default for macros that don't have this attribute, unless they are +built-in macros. For built-in macros the default is `yes`. + +Both the default collapsing behavior and `#[collapse_debuginfo]` attributes can be overridden from +command line using the `-C collapse-macro-debuginfo` option. + +[_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax From bb166095d19e4f7906d30a07e552917da6c047d1 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:16:23 -0800 Subject: [PATCH 04/25] Use standard template introducing an attribute. --- src/attributes/debugger.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 468a1b2cf..6b2eef6e5 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -142,7 +142,7 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil ## The `collapse_debuginfo` attribute -This attribute controls whether code locations from this macro definition are collapsed into a +The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a single location associated with the macro's call site, when generating debuginfo for code calling this macro. @@ -161,4 +161,5 @@ built-in macros. For built-in macros the default is `yes`. Both the default collapsing behavior and `#[collapse_debuginfo]` attributes can be overridden from command line using the `-C collapse-macro-debuginfo` option. +[attribute]: ../attributes.md [_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax From 224b6c5306b6141e2bd0020de155bb272cfd1e5b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:16:40 -0800 Subject: [PATCH 05/25] Use em-dash separator --- src/attributes/debugger.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 6b2eef6e5..f92db1e1d 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -150,9 +150,9 @@ The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can macro definitions. Accepted options: -- `#[collapse_debuginfo(yes)]` - code locations in debuginfo are collapsed. -- `#[collapse_debuginfo(no)]` - code locations in debuginfo are not collapsed. -- `#[collapse_debuginfo(external)]` - code locations in debuginfo are collapsed only if the macro +- `#[collapse_debuginfo(yes)]` — code locations in debuginfo are collapsed. +- `#[collapse_debuginfo(no)]` — code locations in debuginfo are not collapsed. +- `#[collapse_debuginfo(external)]` — code locations in debuginfo are collapsed only if the macro comes from a different crate. The `external` behavior is the default for macros that don't have this attribute, unless they are From 4e9c91f0ec870e69242505e1692875e993f1a96c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:17:29 -0800 Subject: [PATCH 06/25] Place `rustc` behavior in a side note. Generally the reference tries to stay focused on the language, and only provide implementation notes as side-information. --- src/attributes/debugger.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index f92db1e1d..b1dec97ef 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -158,8 +158,7 @@ Accepted options: The `external` behavior is the default for macros that don't have this attribute, unless they are built-in macros. For built-in macros the default is `yes`. -Both the default collapsing behavior and `#[collapse_debuginfo]` attributes can be overridden from -command line using the `-C collapse-macro-debuginfo` option. +> **Note**: `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes. [attribute]: ../attributes.md [_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax From 860fe4acc154f788189910a01b0b3db108e1dbe7 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:18:40 -0800 Subject: [PATCH 07/25] Use semantic line wrapping. --- src/attributes/debugger.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index b1dec97ef..60dc16b6a 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -142,21 +142,18 @@ When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` wil ## The `collapse_debuginfo` attribute -The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a -single location associated with the macro's call site, when generating debuginfo for code calling -this macro. +The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a single location associated with the macro's call site, +when generating debuginfo for code calling this macro. -The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can only be applied to -macro definitions. +The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can only be applied to macro definitions. Accepted options: - `#[collapse_debuginfo(yes)]` — code locations in debuginfo are collapsed. - `#[collapse_debuginfo(no)]` — code locations in debuginfo are not collapsed. -- `#[collapse_debuginfo(external)]` — code locations in debuginfo are collapsed only if the macro - comes from a different crate. +- `#[collapse_debuginfo(external)]` — code locations in debuginfo are collapsed only if the macro comes from a different crate. -The `external` behavior is the default for macros that don't have this attribute, unless they are -built-in macros. For built-in macros the default is `yes`. +The `external` behavior is the default for macros that don't have this attribute, unless they are built-in macros. +For built-in macros the default is `yes`. > **Note**: `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes. From c495b9660f6d8c1d6753cf2271dbfd54cc5acd9c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 14 Feb 2024 10:21:12 -0800 Subject: [PATCH 08/25] Link `collapse_debuginfo` in the index of built-in attributes. --- src/attributes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/attributes.md b/src/attributes.md index a1ad5c60c..b3879d46f 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -273,6 +273,7 @@ The following is an index of all built-in attributes. added in future. - Debugger - [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type. + - [`collapse_debuginfo`] — Controls how macro invocations are encoded in debuginfo. [Doc comments]: comments.md#doc-comments [ECMA-334]: https://www.ecma-international.org/publications-and-standards/standards/ecma-334/ @@ -291,6 +292,7 @@ The following is an index of all built-in attributes. [`cfg_attr`]: conditional-compilation.md#the-cfg_attr-attribute [`cfg`]: conditional-compilation.md#the-cfg-attribute [`cold`]: attributes/codegen.md#the-cold-attribute +[`collapse_debuginfo`]: attributes/debugger.md#the-collapse_debuginfo-attribute [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute [`crate_type`]: linkage.md [`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute From 81fe01a11108a5e50bd51b7d22d638435ad687fd Mon Sep 17 00:00:00 2001 From: Georg Semmler Date: Thu, 18 Jan 2024 08:08:27 +0100 Subject: [PATCH 09/25] Add the `#[diagnostic]` attribute namespace and the `#[diagnostic::on_unimplemented]` feature to the reference --- src/attributes.md | 5 +++- src/attributes/diagnostics.md | 54 +++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 1 deletion(-) diff --git a/src/attributes.md b/src/attributes.md index a1ad5c60c..3b26a319a 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -196,7 +196,7 @@ struct S { pub fn f() {} ``` -> Note: `rustc` currently recognizes the tools "clippy" and "rustfmt". +> Note: `rustc` currently recognizes the tools "clippy", "rustfmt" and "diagnostics". ## Built-in attributes index @@ -224,6 +224,8 @@ The following is an index of all built-in attributes. - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level. - [`deprecated`] — Generates deprecation notices. - [`must_use`] — Generates a lint for unused values. + - [`diagnostic::on_unimplemented`] - Hints the compiler to emit a certain error + message if a trait is not implemented. - ABI, linking, symbols, and FFI - [`link`] — Specifies a native library to link with an `extern` block. - [`link_name`] — Specifies the name of the symbol for functions or statics @@ -352,3 +354,4 @@ The following is an index of all built-in attributes. [closure]: expressions/closure-expr.md [function pointer]: types/function-pointer.md [variadic functions]: items/external-blocks.html#variadic-functions +[`diagnostic::on_unimplemented`]: attributes/diagnostics.md#the-diagnosticon_unimplemented-attribute diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 506e2848b..142b78f0f 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -301,6 +301,60 @@ When used on a function in a trait implementation, the attribute does nothing. > let _ = five(); > ``` +## The `diagnostic` tool attribute namespace + +The `#[diagnostic]` attribute namespace is meant to provide a home for attribute that allow users to influence error messages emitted by the compiler. The compiler is not guaranteed to use any of this hints, however it should accept any (non-)existing attribute in this namespace and potentially emit lint-warnings for unused attributes and options. This is meant to allow discarding certain attributes/options in the future to allow fundamental changes to the compiler without the need to keep then non-meaningful options working. + +### The `diagnostic::on_unimplemented` attribute + +The `#[diagnostic::on_unimplemented]` attribute is allowed to appear on trait definitions. This allows crate authors to hint the compiler to emit a specific worded error message if a certain trait is not implemented. The hinted message is supposed to replace the otherwise emitted error message. For the `#[diagnostic::on_unimplemented]` attribute the following options are implemented: + +* `message` which provides the text for the top level error message +* `label` which provides the text for the label shown inline in the broken code in the error message +* `note` which provides additional notes. + +The `note` option can appear several times, which results in several note messages being emitted. If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. + +All three options accept a text as argument. This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax. For any non-existing argument a lint warning is generated. + +This allows to have a trait definition like: + +```rust +#[diagnostic::on_unimplemented( + message = "My Message for `ImportantTrait<{A}>` implemented for `{Self}`", + label = "My Label", + note = "Note 1", + note = "Note 2" +)] +trait ImportantTrait {} +``` + +which then generates the for the following code + +```rust +fn use_my_trait(_: impl ImportantTrait) {} + +fn main() { + use_my_trait(String::new()); +} +``` + +this error message: + +``` +error[E0277]: My Message for `ImportantTrait` implemented for `String` + --> src/main.rs:14:18 + | +14 | use_my_trait(String::new()); + | ------------ ^^^^^^^^^^^^^ My Label + | | + | required by a bound introduced by this call + | + = help: the trait `ImportantTrait` is not implemented for `String` + = note: Note 1 + = note: Note 2 +``` + [Clippy]: https://github.com/rust-lang/rust-clippy [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax [_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax From 5baf87cdd925f4ca569570658d7fe55e783942ce Mon Sep 17 00:00:00 2001 From: Georg Semmler Date: Fri, 19 Jan 2024 08:11:40 +0000 Subject: [PATCH 10/25] Apply suggestions from code review Co-authored-by: Eric Huss --- src/attributes.md | 4 ++-- src/attributes/diagnostics.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/attributes.md b/src/attributes.md index 3b26a319a..1218fcbd0 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -196,7 +196,7 @@ struct S { pub fn f() {} ``` -> Note: `rustc` currently recognizes the tools "clippy", "rustfmt" and "diagnostics". +> Note: `rustc` currently recognizes the tools "clippy", "rustfmt" and "diagnostic". ## Built-in attributes index @@ -224,7 +224,7 @@ The following is an index of all built-in attributes. - [`allow`], [`warn`], [`deny`], [`forbid`] — Alters the default lint level. - [`deprecated`] — Generates deprecation notices. - [`must_use`] — Generates a lint for unused values. - - [`diagnostic::on_unimplemented`] - Hints the compiler to emit a certain error + - [`diagnostic::on_unimplemented`] — Hints the compiler to emit a certain error message if a trait is not implemented. - ABI, linking, symbols, and FFI - [`link`] — Specifies a native library to link with an `extern` block. diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 142b78f0f..a70436876 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -315,7 +315,7 @@ The `#[diagnostic::on_unimplemented]` attribute is allowed to appear on trait de The `note` option can appear several times, which results in several note messages being emitted. If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. -All three options accept a text as argument. This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax. For any non-existing argument a lint warning is generated. +All three options accept a text as argument. This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax. Any other format parameter will generate a warning, but will otherwise be included in the string as-is. This allows to have a trait definition like: From 99b19d92c138d633c6ae9c41d863112def6c377a Mon Sep 17 00:00:00 2001 From: Georg Semmler Date: Fri, 19 Jan 2024 09:43:09 +0100 Subject: [PATCH 11/25] Apply more review suggestions manually Co-authored-by: Eric Huss --- src/attributes/diagnostics.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index a70436876..c0c5c82f8 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -303,19 +303,29 @@ When used on a function in a trait implementation, the attribute does nothing. ## The `diagnostic` tool attribute namespace -The `#[diagnostic]` attribute namespace is meant to provide a home for attribute that allow users to influence error messages emitted by the compiler. The compiler is not guaranteed to use any of this hints, however it should accept any (non-)existing attribute in this namespace and potentially emit lint-warnings for unused attributes and options. This is meant to allow discarding certain attributes/options in the future to allow fundamental changes to the compiler without the need to keep then non-meaningful options working. +The `#[diagnostic]` attribute namespace is meant to provide a home for attributes to influence compile-time error messages. +The hints provides by these attributes are not guaranteed to be used. +Unknown attributes in this namespace are accepted, though tey may emit warings for unused attributes. +Additionally, invalid input to known attributes will typically be a warning (see the attribute definitions for details). +This is meant to allow adding or discarding attributes and changing inputs in the future to allow changes without the need to keep the non-meaningful attributes or options working. ### The `diagnostic::on_unimplemented` attribute -The `#[diagnostic::on_unimplemented]` attribute is allowed to appear on trait definitions. This allows crate authors to hint the compiler to emit a specific worded error message if a certain trait is not implemented. The hinted message is supposed to replace the otherwise emitted error message. For the `#[diagnostic::on_unimplemented]` attribute the following options are implemented: +The `#[diagnostic::on_unimplemented]` attribute is designed to appear on trait definitions. +This attribute hints to hint the compiler to supplement a specific worded error message that would normally be generated in scenarios where the trait is required but not implemented on a type +The attribute uses the [_MetaListNameValueStr_] syntax to specify its inputs, though any malformed input to the attribute is not considered as an error to provide both forwards and backwards compatibility. The following keys have the given meaning: * `message` which provides the text for the top level error message * `label` which provides the text for the label shown inline in the broken code in the error message * `note` which provides additional notes. -The `note` option can appear several times, which results in several note messages being emitted. If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. +The `note` option can appear several times, which results in several note messages being emitted. +If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. +For any other non-existing option a lint-warning is generated. -All three options accept a text as argument. This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax. Any other format parameter will generate a warning, but will otherwise be included in the string as-is. +All three options accept a text as argument. +This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax, where `{Self}` is resolved to the name of the type implementing the trait and `{NameOfGenericArgument}` is resolved to the relevant type name that replaces the `{NameOfGenericArgument}` argument if the error message is emitted. +Any other format parameter will generate a warning, but will otherwise be included in the string as-is. This allows to have a trait definition like: @@ -327,11 +337,7 @@ This allows to have a trait definition like: note = "Note 2" )] trait ImportantTrait {} -``` - -which then generates the for the following code -```rust fn use_my_trait(_: impl ImportantTrait) {} fn main() { @@ -339,7 +345,7 @@ fn main() { } ``` -this error message: +which might generate this error message: ``` error[E0277]: My Message for `ImportantTrait` implemented for `String` From 5e29b0135ed0353d7d9f4c2db9feba82f580cf50 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 12 Mar 2024 09:21:17 -0700 Subject: [PATCH 12/25] Various fixes and editing. --- src/attributes/diagnostics.md | 42 ++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index c0c5c82f8..45ed64534 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -303,33 +303,39 @@ When used on a function in a trait implementation, the attribute does nothing. ## The `diagnostic` tool attribute namespace -The `#[diagnostic]` attribute namespace is meant to provide a home for attributes to influence compile-time error messages. -The hints provides by these attributes are not guaranteed to be used. -Unknown attributes in this namespace are accepted, though tey may emit warings for unused attributes. -Additionally, invalid input to known attributes will typically be a warning (see the attribute definitions for details). +The `#[diagnostic]` attribute namespace is a home for attributes to influence compile-time error messages. +The hints provided by these attributes are not guaranteed to be used. +Unknown attributes in this namespace are accepted, though they may emit warnings for unused attributes. +Additionally, invalid inputs to known attributes will typically be a warning (see the attribute definitions for details). This is meant to allow adding or discarding attributes and changing inputs in the future to allow changes without the need to keep the non-meaningful attributes or options working. ### The `diagnostic::on_unimplemented` attribute -The `#[diagnostic::on_unimplemented]` attribute is designed to appear on trait definitions. -This attribute hints to hint the compiler to supplement a specific worded error message that would normally be generated in scenarios where the trait is required but not implemented on a type -The attribute uses the [_MetaListNameValueStr_] syntax to specify its inputs, though any malformed input to the attribute is not considered as an error to provide both forwards and backwards compatibility. The following keys have the given meaning: +The `#[diagnostic::on_unimplemented]` attribute is a hint to the compiler to supplement the error message that would normally be generated in scenarios where a trait is required but not implemented on a type. +The attribute should be placed on a [trait declaration], though it is not an error to be located in other positions. +The attribute uses the [_MetaListNameValueStr_] syntax to specify its inputs, though any malformed input to the attribute is not considered as an error to provide both forwards and backwards compatibility. +The following keys have the given meaning: -* `message` which provides the text for the top level error message -* `label` which provides the text for the label shown inline in the broken code in the error message -* `note` which provides additional notes. +* `message` — The text for the top level error message. +* `label` — The text for the label shown inline in the broken code in the error message. +* `note` — Provides additional notes. -The `note` option can appear several times, which results in several note messages being emitted. -If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. Any other occurrence generates an lint warning. +The `note` option can appear several times, which results in several note messages being emitted. +If any of the other options appears several times the first occurrence of the relevant option specifies the actually used value. +Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. -All three options accept a text as argument. -This text is allowed to contain format parameters referring to generic argument or `Self` by name via the `{Self}` or `{NameOfGenericArgument}` syntax, where `{Self}` is resolved to the name of the type implementing the trait and `{NameOfGenericArgument}` is resolved to the relevant type name that replaces the `{NameOfGenericArgument}` argument if the error message is emitted. +All three options accept a string as an argument. +The text in the string may contain the following format parameters which provide substitutions in the generated message: + +* `{Self}` — The name of the type implementing the trait. +* `{` *GenericParameterName* `}` — The name of the generic argument's type for the given generic parameter. + Any other format parameter will generate a warning, but will otherwise be included in the string as-is. -This allows to have a trait definition like: +In this example: -```rust +```rust,compile_fail,E0277 #[diagnostic::on_unimplemented( message = "My Message for `ImportantTrait<{A}>` implemented for `{Self}`", label = "My Label", @@ -345,9 +351,9 @@ fn main() { } ``` -which might generate this error message: +the compiler may generate an error message which looks like this: -``` +```text error[E0277]: My Message for `ImportantTrait` implemented for `String` --> src/main.rs:14:18 | From 0b153cb607e981bfa64ec6fcbfc92cefc891d4ed Mon Sep 17 00:00:00 2001 From: Shotaro Aoyama Date: Sun, 24 Mar 2024 14:02:49 +0900 Subject: [PATCH 13/25] fix typo of shebang --- src/input-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/input-format.md b/src/input-format.md index 946e6782c..8d921bf8c 100644 --- a/src/input-format.md +++ b/src/input-format.md @@ -21,7 +21,7 @@ Other occurrences of the character `U+000D` (CR) are left in place (they are tre ## Shebang removal -If the remaining sequence begins with the characters `!#`, the characters up to and including the first `U+000A` (LF) are removed from the sequence. +If the remaining sequence begins with the characters `#!`, the characters up to and including the first `U+000A` (LF) are removed from the sequence. For example, the first line of the following file would be ignored: From a7a86824fa90172340e20053be5e6f217cc466fe Mon Sep 17 00:00:00 2001 From: Yotam Ofek Date: Sat, 30 Mar 2024 23:14:03 +0300 Subject: [PATCH 14/25] Fix clippy warning in procedural macro example I copy+pasted this example into my code and the `clippy::to_string_in_format_args` lint fired. --- src/procedural-macros.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/procedural-macros.md b/src/procedural-macros.md index 7d69ab72d..32b847c0f 100644 --- a/src/procedural-macros.md +++ b/src/procedural-macros.md @@ -234,8 +234,8 @@ shown in the comments after the function prefixed with "out:". #[proc_macro_attribute] pub fn show_streams(attr: TokenStream, item: TokenStream) -> TokenStream { - println!("attr: \"{}\"", attr.to_string()); - println!("item: \"{}\"", item.to_string()); + println!("attr: \"{attr}\""); + println!("item: \"{item}\""); item } ``` From 52874b8312ccbc28710a2532f82032876a08911b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 3 Apr 2024 14:29:34 -0700 Subject: [PATCH 15/25] Update on_unimplemented for format string changes. Updated in https://github.com/rust-lang/rust/pull/122402 --- src/attributes/diagnostics.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/attributes/diagnostics.md b/src/attributes/diagnostics.md index 45ed64534..c636a96cc 100644 --- a/src/attributes/diagnostics.md +++ b/src/attributes/diagnostics.md @@ -325,14 +325,17 @@ If any of the other options appears several times the first occurrence of the re Any other occurrence generates an lint warning. For any other non-existing option a lint-warning is generated. -All three options accept a string as an argument. -The text in the string may contain the following format parameters which provide substitutions in the generated message: +All three options accept a string as an argument, interpreted using the same formatting as a [`std::fmt`] string. +Format parameters with the given named parameter will be replaced with the following text: * `{Self}` — The name of the type implementing the trait. * `{` *GenericParameterName* `}` — The name of the generic argument's type for the given generic parameter. Any other format parameter will generate a warning, but will otherwise be included in the string as-is. +Invalid format strings may generate a warning, but are otherwise allowed, but may not display as intended. +Format specifiers may generate a warning, but are otherwise ignored. + In this example: ```rust,compile_fail,E0277 @@ -367,6 +370,7 @@ error[E0277]: My Message for `ImportantTrait` implemented for `String` = note: Note 2 ``` +[`std::fmt`]: ../../std/fmt/index.html [Clippy]: https://github.com/rust-lang/rust-clippy [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax [_MetaListPaths_]: ../attributes.md#meta-item-attribute-syntax From b4311de6918170a2606bdd6e6cb4bf086badb0ef Mon Sep 17 00:00:00 2001 From: Jamie Lokier Date: Sun, 14 Apr 2024 14:07:07 +0100 Subject: [PATCH 16/25] Fix link to RISC-V Zkt spec; it was pointing to Zkr --- src/attributes/codegen.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 348f92f37..76ec6fd2a 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -262,7 +262,7 @@ Feature | Implicitly Enables | Description [rv-zks]: https://github.com/riscv/riscv-crypto/blob/e2dd7d98b7f34d477e38cb5fd7a3af4379525189/doc/scalar/riscv-crypto-scalar-zks.adoc [rv-zksed]: https://github.com/riscv/riscv-crypto/blob/e2dd7d98b7f34d477e38cb5fd7a3af4379525189/doc/scalar/riscv-crypto-scalar-zksed.adoc [rv-zksh]: https://github.com/riscv/riscv-crypto/blob/e2dd7d98b7f34d477e38cb5fd7a3af4379525189/doc/scalar/riscv-crypto-scalar-zksh.adoc -[rv-zkt]: https://github.com/riscv/riscv-crypto/blob/e2dd7d98b7f34d477e38cb5fd7a3af4379525189/doc/scalar/riscv-crypto-scalar-zkr.adoc +[rv-zkt]: https://github.com/riscv/riscv-crypto/blob/e2dd7d98b7f34d477e38cb5fd7a3af4379525189/doc/scalar/riscv-crypto-scalar-zkt.adoc #### `wasm32` or `wasm64` From ec0065fd92cae8c0de7a604b6880b7738fbed196 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Sun, 14 Apr 2024 08:45:19 -0700 Subject: [PATCH 17/25] Document how `non_exhaustive` interacts with tuple and unit-like structs. --- src/attributes/type_system.md | 60 +++++++++++++++++++++++++++-------- 1 file changed, 47 insertions(+), 13 deletions(-) diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index 71b0243a6..6ff83d05c 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -20,6 +20,12 @@ pub struct Config { pub window_height: u16, } +#[non_exhaustive] +pub struct Token; + +#[non_exhaustive] +pub struct Id(pub u64); + #[non_exhaustive] pub enum Error { Message(String), @@ -34,11 +40,13 @@ pub enum Message { // Non-exhaustive structs can be constructed as normal within the defining crate. let config = Config { window_width: 640, window_height: 480 }; +let token = Token; +let id = Id(4); // Non-exhaustive structs can be matched on exhaustively within the defining crate. -if let Config { window_width, window_height } = config { - // ... -} +let Config { window_width, window_height } = config; +let Token = token; +let Id(id_number) = id; let error = Error::Other; let message = Message::Reaction(3); @@ -64,30 +72,47 @@ Non-exhaustive types cannot be constructed outside of the defining crate: - Non-exhaustive variants ([`struct`][struct] or [`enum` variant][enum]) cannot be constructed with a [_StructExpression_] \(including with [functional update syntax]). +- The visibility of the same-named constant of a [unit-like struct][struct] + is lowered to `min($vis, pub(crate))`. +- The visibility of the same-named constructor function of a [tuple struct][struct] + is lowered to `min($vis, pub(crate))`. - [`enum`][enum] instances can be constructed. +The following examples of construction do not compile when outside the defining crate: + ```rust,ignore -// `Config`, `Error`, and `Message` are types defined in an upstream crate that have been -// annotated as `#[non_exhaustive]`. -use upstream::{Config, Error, Message}; +// These are types defined in an upstream crate that have been annotated as +// `#[non_exhaustive]`. +use upstream::{Config, Token, Id, Error, Message}; -// Cannot construct an instance of `Config`, if new fields were added in +// Cannot construct an instance of `Config`; if new fields were added in // a new version of `upstream` then this would fail to compile, so it is // disallowed. let config = Config { window_width: 640, window_height: 480 }; -// Can construct an instance of `Error`, new variants being introduced would +// Cannot construct an instance of `Token`; if new fields were added, then +// it would not be a unit-like struct any more, so the same-named constant +// created by it being a unit-like struct is not public outside the crate; +// this code fails to compile. +let token = Token; + +// Cannot construct an instance of `Id`; if new fields were added, then +// its constructor function signature would change, so its constructor +// function is not public outside the crate; this code fails to compile. +let id = Id(5); + +// Can construct an instance of `Error`; new variants being introduced would // not result in this failing to compile. let error = Error::Message("foo".to_string()); -// Cannot construct an instance of `Message::Send` or `Message::Reaction`, +// Cannot construct an instance of `Message::Send` or `Message::Reaction`; // if new fields were added in a new version of `upstream` then this would // fail to compile, so it is disallowed. let message = Message::Send { from: 0, to: 1, contents: "foo".to_string(), }; let message = Message::Reaction(0); -// Cannot construct an instance of `Message::Quit`, if this were converted to +// Cannot construct an instance of `Message::Quit`; if this were converted to // a tuple-variant `upstream` then this would fail to compile. let message = Message::Quit; ``` @@ -100,11 +125,13 @@ There are limitations when matching on non-exhaustive types outside of the defin - When pattern matching on a non-exhaustive [`enum`][enum], matching on a variant does not contribute towards the exhaustiveness of the arms. +The following examples of matching do not compile when outside the defining crate: + ```rust, ignore -// `Config`, `Error`, and `Message` are types defined in an upstream crate that have been -// annotated as `#[non_exhaustive]`. -use upstream::{Config, Error, Message}; +// These are types defined in an upstream crate that have been annotated as +// `#[non_exhaustive]`. +use upstream::{Config, Token, Id, Error, Message}; // Cannot match on a non-exhaustive enum without including a wildcard arm. match error { @@ -118,6 +145,13 @@ if let Ok(Config { window_width, window_height }) = config { // would compile with: `..` } +// Cannot match a non-exhaustive unit-like or tuple struct except by using +// braced struct syntax with a wildcard. +// This would compile as `let Token { .. } = token;` +let Token = token; +// This would compile as `let Id { 0: id_number, .. } = id;` +let Id(id_number) = id; + match message { // Cannot match on a non-exhaustive struct enum variant without including a wildcard. Message::Send { from, to, contents } => { }, From 076a798583ecb450dbb27d46c2e1558228d0fcf1 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Mon, 15 Apr 2024 11:13:52 -0700 Subject: [PATCH 18/25] =?UTF-8?q?Replace=20=E2=80=9Cmin()=E2=80=9D=20visib?= =?UTF-8?q?ility=20notation=20with=20English.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/attributes/type_system.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index 6ff83d05c..dd3ea9874 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -72,10 +72,12 @@ Non-exhaustive types cannot be constructed outside of the defining crate: - Non-exhaustive variants ([`struct`][struct] or [`enum` variant][enum]) cannot be constructed with a [_StructExpression_] \(including with [functional update syntax]). -- The visibility of the same-named constant of a [unit-like struct][struct] - is lowered to `min($vis, pub(crate))`. -- The visibility of the same-named constructor function of a [tuple struct][struct] - is lowered to `min($vis, pub(crate))`. +- The implicitly defined same-named constant of a [unit-like struct][struct], + or the same-named constructor function of a [tuple struct][struct], + has a [visibility] no greater than `pub(crate)`. + That is, if the struct’s visibility is `pub`, then the constant or constructor’s visibility + is `pub(crate)`, and otherwise the visibility of the two items is the same + (as is the case without `#[non_exhaustive]`). - [`enum`][enum] instances can be constructed. The following examples of construction do not compile when outside the defining crate: @@ -120,8 +122,8 @@ let message = Message::Quit; There are limitations when matching on non-exhaustive types outside of the defining crate: - When pattern matching on a non-exhaustive variant ([`struct`][struct] or [`enum` variant][enum]), - a [_StructPattern_] must be used which must include a `..`. Tuple variant constructor visibility - is lowered to `min($vis, pub(crate))`. + a [_StructPattern_] must be used which must include a `..`. A tuple variant's constructor's + [visibility] is reduced to be no greater than `pub(crate)`. - When pattern matching on a non-exhaustive [`enum`][enum], matching on a variant does not contribute towards the exhaustiveness of the arms. @@ -181,3 +183,4 @@ Non-exhaustive types are always considered inhabited in downstream crates. [enum]: ../items/enumerations.md [functional update syntax]: ../expressions/struct-expr.md#functional-update-syntax [struct]: ../items/structs.md +[visibility]: ../visibility-and-privacy.md From 4f47e3ffe75d40fc724741f17dc1cb165dc3c564 Mon Sep 17 00:00:00 2001 From: Conrad Ludgate Date: Tue, 16 Apr 2024 06:55:59 +0100 Subject: [PATCH 19/25] Update clone reference to include closures --- src/special-types-and-traits.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/special-types-and-traits.md b/src/special-types-and-traits.md index 6355f3fb2..cadced52e 100644 --- a/src/special-types-and-traits.md +++ b/src/special-types-and-traits.md @@ -80,6 +80,7 @@ types: * Types with a built-in `Copy` implementation (see above) * [Tuples] of `Clone` types +* [Closures] that only capture values of `Clone` types ## `Send` From a432cf4afdb6f0f452de19c4d123fae81a840d50 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Tue, 16 Apr 2024 09:35:51 -0700 Subject: [PATCH 20/25] Expand and clarify primitive alignment These changes are intended to make the section more informative and readable, without making any new normative claims. * Specify that the alignment might be _less_ than the size, rather than just that it might be different. This is mandatory and stated in the previous section, but I think it's useful to reiterate here. * Mention `u128`/`i128` as another example of alignment less than size, so that this doesn't sound like a mainly 32-bit thing. * Add `usize`/`isize` to the size table, so it can be spotted at a glance. --- src/type-layout.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/type-layout.md b/src/type-layout.md index c21ab622a..c53e9d097 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -44,17 +44,20 @@ The size of most primitives is given in this table. | `u32` / `i32` | 4 | | `u64` / `i64` | 8 | | `u128` / `i128` | 16 | +| `usize` / `isize` | See below | | `f32` | 4 | | `f64` | 8 | | `char` | 4 | `usize` and `isize` have a size big enough to contain every address on the -target platform. For example, on a 32 bit target, this is 4 bytes and on a 64 +target platform. For example, on a 32 bit target, this is 4 bytes, and on a 64 bit target, this is 8 bytes. -Most primitives are generally aligned to their size, although this is -platform-specific behavior. In particular, on many 32-bit platforms `u64` -and `f64` are only aligned to 32 bits. +The alignment of primitives is platform-specific. +In most cases, their alignment is equal to their size, but it may be less. +In particular, `i128` and `u128` are often aligned to 4 or 8 bytes even though +their size is 16, and on many 32-bit platforms, `i64`, `u64`, and `f64` are only +aligned to 4 bytes, not 8. ## Pointers and References Layout From 330ef9569444a7414633ba08cf5090da312f1f18 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 17 Apr 2024 08:04:47 -0700 Subject: [PATCH 21/25] Clone: Also mention closures that don't capture anything --- src/special-types-and-traits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/special-types-and-traits.md b/src/special-types-and-traits.md index cadced52e..21cab3dc8 100644 --- a/src/special-types-and-traits.md +++ b/src/special-types-and-traits.md @@ -80,7 +80,7 @@ types: * Types with a built-in `Copy` implementation (see above) * [Tuples] of `Clone` types -* [Closures] that only capture values of `Clone` types +* [Closures] that only capture values of `Clone` types or capture no values from the environment ## `Send` From 2d51a2aec405dd54a617f5ee1b27cef326f30ced Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 27 Apr 2024 10:53:08 -0700 Subject: [PATCH 22/25] Add an example of collapse_debuginfo --- src/attributes/debugger.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/attributes/debugger.md b/src/attributes/debugger.md index 60dc16b6a..6d184e87e 100644 --- a/src/attributes/debugger.md +++ b/src/attributes/debugger.md @@ -157,5 +157,14 @@ For built-in macros the default is `yes`. > **Note**: `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes. +```rust +#[collapse_debuginfo(yes)] +macro_rules! example { + () => { + println!("hello!"); + }; +} +``` + [attribute]: ../attributes.md [_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax From 01c8196e0120f0577f6aa05ada9d962f0019a86c Mon Sep 17 00:00:00 2001 From: Gary Guo Date: Mon, 7 Nov 2022 04:53:59 +0000 Subject: [PATCH 23/25] Add const blocks --- src/const_eval.md | 4 +++- src/expressions.md | 2 ++ src/expressions/block-expr.md | 40 +++++++++++++++++++++++++++++++++++ src/macros-by-example.md | 2 ++ 4 files changed, 47 insertions(+), 1 deletion(-) diff --git a/src/const_eval.md b/src/const_eval.md index 34e34d703..af8d4862c 100644 --- a/src/const_eval.md +++ b/src/const_eval.md @@ -27,7 +27,7 @@ to be run. * [Tuple expressions]. * [Array expressions]. * [Struct] expressions. -* [Block expressions], including `unsafe` blocks. +* [Block expressions], including `unsafe` and `const` blocks. * [let statements] and thus irrefutable [patterns], including mutable bindings * [assignment expressions] * [compound assignment expressions] @@ -59,6 +59,7 @@ A _const context_ is one of the following: * [statics] * [enum discriminants] * A [const generic argument] +* A [const block] ## Const Functions @@ -106,6 +107,7 @@ Conversely, the following are possible in a const function, but not in a const c [cast]: expressions/operator-expr.md#type-cast-expressions [closure expressions]: expressions/closure-expr.md [comparison]: expressions/operator-expr.md#comparison-operators +[const block]: expressions/block-expr.md#const-blocks [const functions]: items/functions.md#const-functions [const generic argument]: items/generics.md#const-generics [const generic parameters]: items/generics.md#const-generics diff --git a/src/expressions.md b/src/expressions.md index ad4cc5f54..9e10dcea3 100644 --- a/src/expressions.md +++ b/src/expressions.md @@ -35,6 +35,7 @@ >    [_OuterAttribute_]\*[†](#expression-attributes)\ >    (\ >          [_BlockExpression_]\ +>       | [_ConstBlockExpression_]\ >       | [_UnsafeBlockExpression_]\ >       | [_LoopExpression_]\ >       | [_IfExpression_]\ @@ -311,6 +312,7 @@ They are never allowed before: [_ClosureExpression_]: expressions/closure-expr.md [_ComparisonExpression_]: expressions/operator-expr.md#comparison-operators [_CompoundAssignmentExpression_]: expressions/operator-expr.md#compound-assignment-expressions +[_ConstBlockExpression_]: expressions/block-expr.md#const-blocks [_ContinueExpression_]: expressions/loop-expr.md#continue-expressions [_FieldExpression_]: expressions/field-expr.md [_GroupedExpression_]: expressions/grouped-expr.md diff --git a/src/expressions/block-expr.md b/src/expressions/block-expr.md index bd9c0a623..c12e1de53 100644 --- a/src/expressions/block-expr.md +++ b/src/expressions/block-expr.md @@ -117,6 +117,44 @@ loop { } ``` +## `const` blocks + +> **Syntax**\ +> _ConstBlockExpression_ :\ +>    `const` _BlockExpression_ + +A *const block* is a variant of a block expression which evaluates in the compile time instead of in the run time. + +Const blocks allows you to define a constant value without having to define new [constant items], and thus they are also sometimes referred as *inline consts*. +It also supports type inference so there is no need to specify the type, unlike [constant items]. + +Const blocks have ability to reference generic parameters in scope, unlike [free][free item] constant items. +They are desugared to associated constant items with generic parameters in scope. +For example, this code: + +```rust +fn foo() -> usize { + const { std::mem::size_of::() + 1 } +} +``` + +is equivalent to: + +```rust +fn foo() -> usize { + { + struct Const(T); + impl Const { + const CONST: usize = std::mem::size_of::() + 1; + } + Const::::CONST + } +} +``` + +This also means that const blocks are treated similarly to associated constants. +For example, they are not guaranteed to be evaluated when the enclosing function is unused. + ## `unsafe` blocks > **Syntax**\ @@ -181,6 +219,8 @@ fn is_unix_platform() -> bool { [array expressions]: array-expr.md [call expressions]: call-expr.md [capture modes]: ../types/closure.md#capture-modes +[constant items]: ../items/constant-items.md +[free item]: ../glossary.md#free-item [function]: ../items/functions.md [inner attributes]: ../attributes.md [method]: ../items/associated-items.md#methods diff --git a/src/macros-by-example.md b/src/macros-by-example.md index 51aa919fc..014fb852b 100644 --- a/src/macros-by-example.md +++ b/src/macros-by-example.md @@ -146,6 +146,7 @@ For reasons of backwards compatibility, though `_` [is also an expression][_UnderscoreExpression_], a standalone underscore is not matched by the `expr` fragment specifier. However, `_` is matched by the `expr` fragment specifier when it appears as a subexpression. +For the same reason, a standalone [const block] is not matched but it is matched when appearing as a subexpression. > **Edition Differences**: Starting with the 2021 edition, `pat` fragment-specifiers match top-level or-patterns (that is, they accept [_Pattern_]). > @@ -492,6 +493,7 @@ expansions, taking separators into account. This means: For more detail, see the [formal specification]. +[const block]: expressions/block-expr.md#const-blocks [Hygiene]: #hygiene [IDENTIFIER]: identifiers.md [IDENTIFIER_OR_KEYWORD]: identifiers.md From 95ab92091f775889d150cb9b78c3b36ea650c08d Mon Sep 17 00:00:00 2001 From: MultisampledNight Date: Fri, 22 Mar 2024 23:35:01 +0100 Subject: [PATCH 24/25] patterns: include new exclusive range patterns See also https://github.com/rust-lang/rust/issues/37854. --- src/patterns.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/patterns.md b/src/patterns.md index c92e2dcda..4e68e0aee 100644 --- a/src/patterns.md +++ b/src/patterns.md @@ -397,6 +397,9 @@ match tuple { >    | _RangeToInclusivePattern_\ >    | _ObsoleteRangePattern_ > +> _RangeExclusivePattern_ :\ +>       _RangePatternBound_ `..` _RangePatternBound_ +> > _RangeInclusivePattern_ :\ >       _RangePatternBound_ `..=` _RangePatternBound_ > @@ -422,10 +425,11 @@ A bound on the left of the sigil is a *lower bound*. A bound on the right is an *upper bound*. A range pattern with both a lower and upper bound will match all values between and including both of its bounds. -It is written as its lower bound, followed by `..=`, followed by its upper bound. +It is written as its lower bound, followed by `..` for end-exclusive or `..=` for end-inclusive, followed by its upper bound. The type of the range pattern is the type unification of its upper and lower bounds. For example, a pattern `'m'..='p'` will match only the values `'m'`, `'n'`, `'o'`, and `'p'`. +Similarly, `'m'..'p'` will match only `'m'`, `'n'` and `'o'`, specifically **not** including `'p'`. The lower bound cannot be greater than the upper bound. That is, in `a..=b`, a ≤ b must be the case. @@ -467,7 +471,7 @@ let valid_variable = match c { # let ph = 10; println!("{}", match ph { - 0..=6 => "acid", + 0..7 => "acid", 7 => "neutral", 8..=14 => "base", _ => unreachable!(), @@ -539,9 +543,6 @@ See [issue #41620](https://github.com/rust-lang/rust/issues/41620) for more info > **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. -> **Note**: Although range patterns use the same syntax as [range expressions], there are no exclusive range patterns. -> That is, neither `x .. y` nor `.. x` are valid range patterns. - ## Reference patterns > **Syntax**\ From efdc9b6fe3e794bf3d668429cbf6ad68e302b679 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 8 May 2024 09:50:26 -0700 Subject: [PATCH 25/25] Small editorial updates for const blocks. --- src/expressions/block-expr.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/expressions/block-expr.md b/src/expressions/block-expr.md index c12e1de53..890cf856d 100644 --- a/src/expressions/block-expr.md +++ b/src/expressions/block-expr.md @@ -123,12 +123,12 @@ loop { > _ConstBlockExpression_ :\ >    `const` _BlockExpression_ -A *const block* is a variant of a block expression which evaluates in the compile time instead of in the run time. +A *const block* is a variant of a block expression which evaluates at compile-time instead of at runtime. Const blocks allows you to define a constant value without having to define new [constant items], and thus they are also sometimes referred as *inline consts*. It also supports type inference so there is no need to specify the type, unlike [constant items]. -Const blocks have ability to reference generic parameters in scope, unlike [free][free item] constant items. +Const blocks have the ability to reference generic parameters in scope, unlike [free][free item] constant items. They are desugared to associated constant items with generic parameters in scope. For example, this code: