From 86a09c88a1e74526e1e1a9d49741c049f7e02f0a Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Sat, 10 Aug 2024 13:32:32 +0200 Subject: [PATCH 1/7] const_eval: update for const-fn float stabilization --- src/const_eval.md | 28 +++++----------------------- 1 file changed, 5 insertions(+), 23 deletions(-) diff --git a/src/const_eval.md b/src/const_eval.md index af8d4862c..a494b5c3c 100644 --- a/src/const_eval.md +++ b/src/const_eval.md @@ -61,12 +61,15 @@ A _const context_ is one of the following: * A [const generic argument] * A [const block] +Const contexts that are used as parts of types (array type and repeat length +expressions as well as const generic arguments) can only make restricted use of +surrounding generic type and lifetime parameters. + ## Const Functions A _const fn_ is a function that one is permitted to call from a const context. Declaring a function `const` has no effect on any existing uses, it only restricts the types that arguments and the -return type may use, as well as prevent various expressions from being used within it. You can freely -do anything with a const function that you can do with a regular function. +return type may use, and restricts the function body to constant expressions. When called from a const context, the function is interpreted by the compiler at compile time. The interpretation happens in the @@ -74,27 +77,6 @@ environment of the compilation target and not the host. So `usize` is `32` bits if you are compiling against a `32` bit system, irrelevant of whether you are building on a `64` bit or a `32` bit system. -Const functions have various restrictions to make sure that they can be -evaluated at compile-time. It is, for example, not possible to write a random -number generator as a const function. Calling a const function at compile-time -will always yield the same result as calling it at runtime, even when called -multiple times. There's one exception to this rule: if you are doing complex -floating point operations in extreme situations, then you might get (very -slightly) different results. It is advisable to not make array lengths and enum -discriminants depend on floating point computations. - - -Notable features that are allowed in const contexts but not in const functions include: - -* floating point operations - * floating point values are treated just like generic parameters without trait bounds beyond - `Copy`. So you cannot do anything with them but copy/move them around. - -Conversely, the following are possible in a const function, but not in a const context: - -* Use of generic type and lifetime parameters. - * Const contexts do allow limited use of [const generic parameters]. - [arithmetic]: expressions/operator-expr.md#arithmetic-and-logical-binary-operators [array expressions]: expressions/array-expr.md [array indexing]: expressions/array-expr.md#array-and-slice-indexing-expressions From 76bd77a97f67d4e3fd2d5acd1fa5bed6e1005f61 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Wed, 21 Aug 2024 21:00:41 +0200 Subject: [PATCH 2/7] clarify limitations on type system consts --- src/const_eval.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/const_eval.md b/src/const_eval.md index a494b5c3c..e3cefa5c7 100644 --- a/src/const_eval.md +++ b/src/const_eval.md @@ -63,7 +63,9 @@ A _const context_ is one of the following: Const contexts that are used as parts of types (array type and repeat length expressions as well as const generic arguments) can only make restricted use of -surrounding generic type and lifetime parameters. +surrounding generic parameters: such an expression must either be a single bare +const generic parameter, or an arbitrary expression not making use of any +generics. ## Const Functions From 0c7f99ad200c9cb6eb964d00dd55dc2a9384510f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 22 Aug 2024 08:49:43 -0700 Subject: [PATCH 3/7] Be consistent about how "Edition differences" is capitalized The existing text was inconsistent with whether or not the "d" was capitalized. This goes the route of using a lowercase "d" to match the style of using sentence-case for headings. --- docs/authoring.md | 2 +- src/expressions/method-call-expr.md | 2 +- src/introduction.md | 4 ++-- src/items/associated-items.md | 2 +- src/macros-by-example.md | 6 +++--- src/names/preludes.md | 4 ++-- src/paths.md | 2 +- src/patterns.md | 2 +- src/tokens.md | 6 +++--- src/types/trait-object.md | 4 ++-- src/visibility-and-privacy.md | 2 +- 11 files changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index a01c8a54d..74c9bc962 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -154,4 +154,4 @@ The reference does not document which targets exist, or the properties of specif ### Editions -The main text and flow should document only the current edition. Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block. +The main text and flow should document only the current edition. Whenever there is a difference between editions, the differences should be called out with an "Edition differences" block. diff --git a/src/expressions/method-call-expr.md b/src/expressions/method-call-expr.md index 7f21c497b..ca7f18502 100644 --- a/src/expressions/method-call-expr.md +++ b/src/expressions/method-call-expr.md @@ -66,7 +66,7 @@ Once a method is looked up, if it can't be called for one (or more) of those rea If a step is reached where there is more than one possible method, such as where generic methods or traits are considered the same, then it is a compiler error. These cases require a [disambiguating function call syntax] for method and function invocation. -> **Edition Differences**: Before the 2021 edition, during the search for visible methods, if the candidate receiver type is an [array type], methods provided by the standard library [`IntoIterator`] trait are ignored. +> **Edition differences**: Before the 2021 edition, during the search for visible methods, if the candidate receiver type is an [array type], methods provided by the standard library [`IntoIterator`] trait are ignored. > > The edition used for this purpose is determined by the token representing the method name. > diff --git a/src/introduction.md b/src/introduction.md index 7f01096c6..2bf5bebbc 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -82,9 +82,9 @@ These conventions are documented here. An *example term* is an example of a term being defined. -* Differences in the language by which edition the crate is compiled under are in a blockquote that start with the words "Edition Differences:" in **bold**. +* Differences in the language by which edition the crate is compiled under are in a blockquote that start with the words "Edition differences:" in **bold**. - > **Edition Differences**: In the 2015 edition, this syntax is valid that is disallowed as of the 2018 edition. + > **Edition differences**: In the 2015 edition, this syntax is valid that is disallowed as of the 2018 edition. * Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in blockquotes that start with the word "Note:" in **bold**. diff --git a/src/items/associated-items.md b/src/items/associated-items.md index 2401127b5..c4e7a194f 100644 --- a/src/items/associated-items.md +++ b/src/items/associated-items.md @@ -189,7 +189,7 @@ let circle_shape = Circle::new(); let bounding_box = circle_shape.bounding_box(); ``` -> **Edition Differences**: In the 2015 edition, it is possible to declare trait +> **Edition differences**: In the 2015 edition, it is possible to declare trait > methods with anonymous parameters (e.g. `fn foo(u8)`). This is deprecated and > an error as of the 2018 edition. All parameters must have an argument name. diff --git a/src/macros-by-example.md b/src/macros-by-example.md index 69a236d23..e95cd2e64 100644 --- a/src/macros-by-example.md +++ b/src/macros-by-example.md @@ -148,7 +148,7 @@ 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_]). +> **Edition differences**: Starting with the 2021 edition, `pat` fragment-specifiers match top-level or-patterns (that is, they accept [_Pattern_]). > > Before the 2021 edition, they match exactly the same fragments as `pat_param` (that is, they accept [_PatternNoTopAlt_]). > @@ -421,7 +421,7 @@ macro_rules! call_foo { fn foo() {} ``` -> **Version & Edition Differences**: Prior to Rust 1.30, `$crate` and +> **Version & Edition differences**: Prior to Rust 1.30, `$crate` and > `local_inner_macros` (below) were unsupported. They were added alongside > path-based imports of macros (described above), to ensure that helper macros > did not need to be manually imported by users of a macro-exporting crate. @@ -475,7 +475,7 @@ Matchers like `$i:expr,` or `$i:expr;` would be legal, however, because `,` and `ident`, `ty`, or `path` fragment specifier. * All other fragment specifiers have no restrictions. -> **Edition Differences**: Before the 2021 edition, `pat` may also be followed by `|`. +> **Edition differences**: Before the 2021 edition, `pat` may also be followed by `|`. When repetitions are involved, then the rules apply to every possible number of expansions, taking separators into account. This means: diff --git a/src/names/preludes.md b/src/names/preludes.md index 745b290df..7e6b7d45d 100644 --- a/src/names/preludes.md +++ b/src/names/preludes.md @@ -44,7 +44,7 @@ new_name`, then the symbol `new_name` is instead added to the prelude. The [`core`] crate is always added to the extern prelude. The [`std`] crate is added as long as the [`no_std` attribute] is not specified in the crate root. -> **Edition Differences**: In the 2015 edition, crates in the extern prelude +> **Edition differences**: In the 2015 edition, crates in the extern prelude > cannot be referenced via [use declarations], so it is generally standard > practice to include `extern crate` declarations to bring them into scope. > @@ -132,7 +132,7 @@ module or any of its descendants. This attribute does not affect the [language prelude]. -> **Edition Differences**: In the 2015 edition, the `no_implicit_prelude` +> **Edition differences**: In the 2015 edition, the `no_implicit_prelude` > attribute does not affect the [`macro_use` prelude], and all macros exported > from the standard library are still included in the `macro_use` prelude. > Starting in the 2018 edition, it will remove the `macro_use` prelude. diff --git a/src/paths.md b/src/paths.md index 525a325e5..12748101d 100644 --- a/src/paths.md +++ b/src/paths.md @@ -166,7 +166,7 @@ Paths starting with `::` are considered to be *global paths* where the segments start being resolved from a place which differs based on edition. Each identifier in the path must resolve to an item. -> **Edition Differences**: In the 2015 Edition, identifiers resolve from the "crate root" +> **Edition differences**: In the 2015 Edition, identifiers resolve from the "crate root" > (`crate::` in the 2018 edition), which contains a variety of different items, including > external crates, default crates such as `std` or `core`, and items in the top level of > the crate (including `use` imports). diff --git a/src/patterns.md b/src/patterns.md index 0f186bf79..479bb6233 100644 --- a/src/patterns.md +++ b/src/patterns.md @@ -533,7 +533,7 @@ For example, `0u8..=255u8` is irrefutable. The range of values for an integer type is the closed range from its minimum to maximum value. The range of values for a `char` type are precisely those ranges containing all Unicode Scalar Values: `'\u{0000}'..='\u{D7FF}'` and `'\u{E000}'..='\u{10FFFF}'`. -> **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. +> **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 diff --git a/src/tokens.md b/src/tokens.md index aeafe4b6d..d94464f9f 100644 --- a/src/tokens.md +++ b/src/tokens.md @@ -375,7 +375,7 @@ c"\u{00E6}"; c"\xC3\xA6"; ``` -> **Edition Differences**: C string literals are accepted in the 2021 edition or +> **Edition differences**: C string literals are accepted in the 2021 edition or > later. In earlier additions the token `c""` is lexed as `c ""`. #### Raw C string literals @@ -400,7 +400,7 @@ encoding. The characters `U+0022` (double-quote) (except when followed by at least as many `U+0023` (`#`) characters as were used to start the raw C string literal) or `U+005C` (`\`) do not have any special meaning. -> **Edition Differences**: Raw C string literals are accepted in the 2021 +> **Edition differences**: Raw C string literals are accepted in the 2021 > edition or later. In earlier additions the token `cr""` is lexed as `cr ""`, > and `cr#""#` is lexed as `cr #""#` (which is non-grammatical). @@ -735,7 +735,7 @@ Note that raw identifiers, raw string literals, and raw byte string literals may Similarly the `r`, `b`, `br`, `c`, and `cr` prefixes used in raw string literals, byte literals, byte string literals, raw byte string literals, C string literals, and raw C string literals are not interpreted as reserved prefixes. -> **Edition Differences**: Starting with the 2021 edition, reserved prefixes are reported as an error by the lexer (in particular, they cannot be passed to macros). +> **Edition differences**: Starting with the 2021 edition, reserved prefixes are reported as an error by the lexer (in particular, they cannot be passed to macros). > > Before the 2021 edition, reserved prefixes are accepted by the lexer and interpreted as multiple tokens (for example, one token for the identifier or keyword, followed by a `#` token). > diff --git a/src/types/trait-object.md b/src/types/trait-object.md index 3526b7add..5b8541fa8 100644 --- a/src/types/trait-object.md +++ b/src/types/trait-object.md @@ -31,13 +31,13 @@ For example, given a trait `Trait`, the following are all trait objects: * `dyn 'static + Trait`. * `dyn (Trait)` -> **Edition Differences**: Before the 2021 edition, the `dyn` keyword may be +> **Edition differences**: Before the 2021 edition, the `dyn` keyword may be > omitted. > > Note: For clarity, it is recommended to always use the `dyn` keyword on your > trait objects unless your codebase supports compiling with Rust 1.26 or lower. -> **Edition Differences**: In the 2015 edition, if the first bound of the +> **Edition differences**: In the 2015 edition, if the first bound of the > trait object is a path that starts with `::`, then the `dyn` will be treated > as a part of the path. The first path can be put in parenthesis to get > around this. As such, if you want a trait object with the trait diff --git a/src/visibility-and-privacy.md b/src/visibility-and-privacy.md index 67fd133ce..5ccf8b4b8 100644 --- a/src/visibility-and-privacy.md +++ b/src/visibility-and-privacy.md @@ -156,7 +156,7 @@ follows: - `pub(self)` makes an item visible to the current module. This is equivalent to `pub(in self)` or not using `pub` at all. -> **Edition Differences**: Starting with the 2018 edition, paths for +> **Edition differences**: Starting with the 2018 edition, paths for > `pub(in path)` must start with `crate`, `self`, or `super`. The 2015 edition > may also use paths starting with `::` or modules from the crate root. From 82c9d5ff2f01c2f0f6df3c3a0969659011215df8 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 26 Aug 2024 11:27:50 -0700 Subject: [PATCH 4/7] Sync denied lints with upstream This synchronizes the lints in mdbook-spec that are denied in rust-lang/rust. This unblocks updating the books. --- mdbook-spec/src/lib.rs | 2 ++ mdbook-spec/src/std_links.rs | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/mdbook-spec/src/lib.rs b/mdbook-spec/src/lib.rs index ef1d56501..1a8a919dc 100644 --- a/mdbook-spec/src/lib.rs +++ b/mdbook-spec/src/lib.rs @@ -1,3 +1,5 @@ +#![deny(rust_2018_idioms, unused_lifetimes)] + use mdbook::book::{Book, Chapter}; use mdbook::errors::Error; use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext}; diff --git a/mdbook-spec/src/std_links.rs b/mdbook-spec/src/std_links.rs index d0b017999..28ca6ba51 100644 --- a/mdbook-spec/src/std_links.rs +++ b/mdbook-spec/src/std_links.rs @@ -145,7 +145,7 @@ fn collect_markdown_links(chapter: &Chapter) -> Vec> { // Broken links are collected so that you can write something like // `[std::option::Option]` which in pulldown_cmark's eyes is a broken // link. However, that is the normal syntax for rustdoc. - let broken_link = |broken_link: BrokenLink| { + let broken_link = |broken_link: BrokenLink<'_>| { broken_links.push(Link { link_type: broken_link.link_type, // Necessary due to lifetime issues. @@ -205,7 +205,7 @@ fn collect_markdown_links(chapter: &Chapter) -> Vec> { /// generate intra-doc links on them. /// /// The output will be in the given `tmp` directory. -fn run_rustdoc(tmp: &TempDir, chapter_links: &HashMap<&PathBuf, Vec>) { +fn run_rustdoc(tmp: &TempDir, chapter_links: &HashMap<&PathBuf, Vec>>) { let src_path = tmp.path().join("a.rs"); // Allow redundant since there could some in-scope things that are // technically not necessary, but we don't care about (like From 3e35b90ce65c3bf0e3d7022144b093d9f35a4d41 Mon Sep 17 00:00:00 2001 From: ShalokShalom Date: Tue, 2 May 2023 12:16:16 +0000 Subject: [PATCH 5/7] Update enum.md Haskell uses data. OCaml and F# do use type, and SML does use datatype. There is no "data" in any ML that I know. --- src/types/enum.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/types/enum.md b/src/types/enum.md index 8f81fb1a5..1ee6fc608 100644 --- a/src/types/enum.md +++ b/src/types/enum.md @@ -16,7 +16,7 @@ Enum types cannot be denoted *structurally* as types, but must be denoted by named reference to an [`enum` item]. [^enumtype]: The `enum` type is analogous to a `data` constructor declaration in - ML, or a *pick ADT* in Limbo. + Haskell, or a *pick ADT* in Limbo. [`enum` item]: ../items/enumerations.md [struct expression]: ../expressions/struct-expr.md From 636945859b05a85b00cc6e25162e242d2420aa38 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 28 Aug 2024 13:49:47 -0700 Subject: [PATCH 6/7] Add a prefix to rule HTML IDs This adds the `r-` prefix to HTML IDs generated for rule names. This fixes a problem where the HTML IDs may conflict with existing markdown headers. For example, `## Crate` conflicts with `r[crate]`. This is done with the expectation that no headers will start with just the letter "r". --- mdbook-spec/src/lib.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mdbook-spec/src/lib.rs b/mdbook-spec/src/lib.rs index 1a8a919dc..37fa81521 100644 --- a/mdbook-spec/src/lib.rs +++ b/mdbook-spec/src/lib.rs @@ -84,8 +84,8 @@ impl Spec { } } format!( - "
\ - [{rule_id}]\ + "\n" ) }) @@ -104,7 +104,7 @@ impl Spec { .iter() .map(|(rule_id, (_, path))| { let relative = pathdiff::diff_paths(path, current_path).unwrap(); - format!("[{rule_id}]: {}#{rule_id}\n", relative.display()) + format!("[{rule_id}]: {}#r-{rule_id}\n", relative.display()) }) .collect(); format!( From fc56eb45a2e19b59fdd7a05d1b744512667d6c1c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 28 Aug 2024 14:09:12 -0700 Subject: [PATCH 7/7] Add a description of rule identifiers --- src/introduction.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/introduction.md b/src/introduction.md index 2bf5bebbc..6aae41b81 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -120,6 +120,15 @@ These conventions are documented here. See [Notation] for more detail. +* Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to a specific rule in the language. The rule identifier uses periods to separate sections from most general to most specific ([destructors.scope.nesting.function-body] for example). + + The rule name can be clicked to link to that rule. + +r[example.rule.label] + + > [!WARNING] + > The organization of the rules is currently in flux. For the time being, these identifier names are not stable between releases, and links to these rules may fail if they are changed. We intend to stabilize these once the organization has settled so that links to the rule names will not break between releases. + ## Contributing We welcome contributions of all kinds.