From f8e76ee9368f498f7f044c719de68c7d95da9972 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 7 Nov 2019 16:01:58 -0800 Subject: [PATCH] Audit code blocks. --- src/abi.md | 5 +- src/attributes/codegen.md | 3 +- src/attributes/type_system.md | 6 +- src/conditional-compilation.md | 2 + src/crates-and-source-files.md | 7 +- src/expressions/await-expr.md | 1 + src/expressions/field-expr.md | 1 + src/expressions/if-expr.md | 3 + src/expressions/loop-expr.md | 4 + src/expressions/operator-expr.md | 4 +- src/items/enumerations.md | 4 +- src/items/extern-crates.md | 2 + src/items/external-blocks.md | 9 ++- src/items/functions.md | 6 +- src/items/generics.md | 3 +- src/items/modules.md | 3 + src/items/unions.md | 16 ++-- src/items/use-declarations.md | 9 ++- src/lifetime-elision.md | 135 +++++++++++++++++++------------ src/linkage.md | 8 +- src/macros-by-example.md | 4 + src/paths.md | 17 +++- src/procedural-macros.md | 17 ++-- src/runtime.md | 7 +- src/tokens.md | 2 +- src/trait-bounds.md | 4 +- src/type-layout.md | 1 + src/types/closure.md | 5 +- 28 files changed, 193 insertions(+), 95 deletions(-) diff --git a/src/abi.md b/src/abi.md index 2e9e969ac..e4f1ec031 100644 --- a/src/abi.md +++ b/src/abi.md @@ -68,7 +68,8 @@ The *`link_section` attribute* specifies the section of the object file that a [function] or [static]'s content will be placed into. It uses the [_MetaNameValueStr_] syntax to specify the section name. -```rust,ignore + +```rust,no_run #[no_mangle] #[link_section = ".example_section"] pub static VAR1: u32 = 1; @@ -80,7 +81,7 @@ The *`export_name` attribute* specifies the name of the symbol that will be exported on a [function] or [static]. It uses the [_MetaNameValueStr_] syntax to specify the symbol name. -```rust,ignore +```rust #[export_name = "exported_symbol_name"] pub fn name_in_rust() { } ``` diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index c9ac02d5b..5b504c13a 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -49,7 +49,8 @@ enable code generation of that function for specific platform architecture features. It uses the [_MetaListNameValueStr_] syntax with a single key of `enable` whose value is a string of comma-separated feature names to enable. -```rust,ignore +```rust +# #[cfg(target_feature = "avx2")] #[target_feature(enable = "avx2")] unsafe fn foo_avx2() {} ``` diff --git a/src/attributes/type_system.md b/src/attributes/type_system.md index 52bbb68f1..97938f2d7 100644 --- a/src/attributes/type_system.md +++ b/src/attributes/type_system.md @@ -66,7 +66,8 @@ Non-exhaustive types cannot be constructed outside of the defining crate: with a [_StructExpression_] \(including with [functional update syntax]). - [`enum`][enum] instances can be constructed in an [_EnumerationVariantExpression_]. -```rust,ignore (requires multiple crates) + +```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}; @@ -99,7 +100,8 @@ 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. -```rust, ignore (requires multiple crates) + +```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}; diff --git a/src/conditional-compilation.md b/src/conditional-compilation.md index 505128275..95285e3af 100644 --- a/src/conditional-compilation.md +++ b/src/conditional-compilation.md @@ -264,6 +264,7 @@ When the configuration predicate is true, this attribute expands out to the attributes listed after the predicate. For example, the following module will either be found at `linux.rs` or `windows.rs` based on the target. + ```rust,ignore #[cfg_attr(linux, path = "linux.rs")] #[cfg_attr(windows, path = "windows.rs")] @@ -273,6 +274,7 @@ mod os; Zero, one, or more attributes may be listed. Multiple attributes will each be expanded into separate attributes. For example: + ```rust,ignore #[cfg_attr(feature = "magic", sparkles, crackles)] fn bewitched() {} diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 1ab03d4bc..1fb842555 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -53,7 +53,7 @@ that apply to the containing module, most of which influence the behavior of the compiler. The anonymous crate module can have additional attributes that apply to the crate as a whole. -```rust,no_run +```rust // Specify the crate name. #![crate_name = "projx"] @@ -75,7 +75,8 @@ essentially to treat the source file as an executable script. The shebang can only occur at the beginning of the file (but after the optional _UTF8BOM_). It is ignored by the compiler. For example: -```text,ignore + +```rust,ignore #!/usr/bin/env rustx fn main() { @@ -136,7 +137,7 @@ other object being linked to defines `main`. The *`crate_name` [attribute]* may be applied at the crate level to specify the name of the crate with the [_MetaNameValueStr_] syntax. -```rust,ignore +```rust #![crate_name = "mycrate"] ``` diff --git a/src/expressions/await-expr.md b/src/expressions/await-expr.md index a6e7dc583..85985c6f4 100644 --- a/src/expressions/await-expr.md +++ b/src/expressions/await-expr.md @@ -51,6 +51,7 @@ context, there must be some task context available. Effectively, an `.await` expression is roughly equivalent to the following (this desugaring is not normative): + ```rust,ignore match /* */ { mut pinned => loop { diff --git a/src/expressions/field-expr.md b/src/expressions/field-expr.md index d9a7b9218..4e187a1b4 100644 --- a/src/expressions/field-expr.md +++ b/src/expressions/field-expr.md @@ -10,6 +10,7 @@ A _field expression_ consists of an expression followed by a single dot and an field of a [struct] or [union]. To call a function stored in a struct, parentheses are needed around the field expression. + ```rust,ignore mystruct.myfield; foo().x; diff --git a/src/expressions/if-expr.md b/src/expressions/if-expr.md index efe384996..5d04bb5c7 100644 --- a/src/expressions/if-expr.md +++ b/src/expressions/if-expr.md @@ -97,6 +97,7 @@ assert_eq!(a, 3); An `if let` expression is equivalent to a [`match` expression] as follows: + ```rust,ignore if let PATS = EXPR { /* body */ @@ -107,6 +108,7 @@ if let PATS = EXPR { is equivalent to + ```rust,ignore match EXPR { PATS => { /* body */ }, @@ -135,6 +137,7 @@ of the language (the implementation of if-let chains - see [eRFC 2947][_eRFCIfLe When lazy boolean operator expression is desired, this can be achieved by using parenthesis as below: + ```rust,ignore // Before... if let PAT = EXPR && EXPR { .. } diff --git a/src/expressions/loop-expr.md b/src/expressions/loop-expr.md index 67be5755e..e37235a30 100644 --- a/src/expressions/loop-expr.md +++ b/src/expressions/loop-expr.md @@ -93,6 +93,7 @@ while let _ = 5 { A `while let` loop is equivalent to a `loop` expression containing a [`match` expression] as follows. + ```rust,ignore 'label: while let PATS = EXPR { /* loop body */ @@ -101,6 +102,7 @@ expression] as follows. is equivalent to + ```rust,ignore 'label: loop { match EXPR { @@ -156,6 +158,7 @@ assert_eq!(sum, 55); A for loop is equivalent to the following block expression. + ```rust,ignore 'label: for PATTERN in iter_expr { /* loop body */ @@ -164,6 +167,7 @@ A for loop is equivalent to the following block expression. is equivalent to + ```rust,ignore { let result = match IntoIterator::into_iter(iter_expr) { diff --git a/src/expressions/operator-expr.md b/src/expressions/operator-expr.md index 3635cc032..b0f8c017e 100644 --- a/src/expressions/operator-expr.md +++ b/src/expressions/operator-expr.md @@ -260,7 +260,9 @@ functions and macros in the standard library can then use that assumption above, these operators implicitly take shared borrows of their operands, evaluating them in [place expression context][place expression]: -```rust,ignore +```rust +# let a = 1; +# let b = 1; a == b; // is equivalent to ::std::cmp::PartialEq::eq(&a, &b); diff --git a/src/items/enumerations.md b/src/items/enumerations.md index 8779f61bb..51663b7aa 100644 --- a/src/items/enumerations.md +++ b/src/items/enumerations.md @@ -91,7 +91,7 @@ using a [primitive representation] or the [`C` representation]. It is an error when two variants share the same discriminant. -```rust,ignore +```rust,compile_fail enum SharedDiscriminantError { SharedA = 1, SharedB = 1 @@ -107,7 +107,7 @@ enum SharedDiscriminantError2 { It is also an error to have an unspecified discriminant where the previous discriminant is the maximum value for the size of the discriminant. -```rust,ignore +```rust,compile_fail #[repr(u8)] enum OverflowingDiscriminantError { Max = 255, diff --git a/src/items/extern-crates.md b/src/items/extern-crates.md index ff66d50be..eb5c2eb8c 100644 --- a/src/items/extern-crates.md +++ b/src/items/extern-crates.md @@ -28,6 +28,7 @@ In this case the `as` clause must be used to specify the name to bind it to. Three examples of `extern crate` declarations: + ```rust,ignore extern crate pcre; @@ -43,6 +44,7 @@ details). Here is an example: + ```rust,ignore // Importing the Cargo package hello-world extern crate hello_world; // hyphen replaced with an underscore diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 653708427..211a2fa4c 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -64,7 +64,7 @@ By default external blocks assume that the library they are calling uses the standard C ABI on the specific platform. Other ABIs may be specified using an `abi` string, as shown here: -```rust,ignore +```rust // Interface to the Windows API extern "stdcall" { } ``` @@ -97,7 +97,7 @@ There are also some platform-specific ABI strings: Functions within external blocks may be variadic by specifying `...` after one or more named arguments in the argument list: -```rust,ignore +```rust extern { fn foo(x: i32, ...); } @@ -128,6 +128,7 @@ name for the items within an `extern` block when importing symbols from the host environment. The default module name is `env` if `wasm_import_module` is not specified. + ```rust,ignore #[link(name = "crypto")] extern { @@ -156,7 +157,7 @@ The `link_name` attribute may be specified on declarations inside an `extern` block to indicate the symbol to import for the given function or static. It uses the [_MetaNameValueStr_] syntax to specify the name of the symbol. -```rust,ignore +```rust extern { #[link_name = "actual_symbol_name"] fn name_in_rust(); @@ -184,4 +185,4 @@ restrictions as [regular function parameters]. [_Visibility_]: ../visibility-and-privacy.md [_WhereClause_]: generics.md#where-clauses [attributes]: ../attributes.md -[regular function parameters]: functions.md#attributes-on-function-parameters \ No newline at end of file +[regular function parameters]: functions.md#attributes-on-function-parameters diff --git a/src/items/functions.md b/src/items/functions.md index 4bc48518f..fce59050e 100644 --- a/src/items/functions.md +++ b/src/items/functions.md @@ -58,6 +58,7 @@ the body of the function will short-cut that implicit return, if reached. For example, the function above behaves as if it was written as: + ```rust,ignore // argument_0 is the actual first argument passed from the caller let (value, _) = argument_0; @@ -115,14 +116,16 @@ sufficient context to determine the type parameters. For example, The `extern` function qualifier allows providing function _definitions_ that can be called with a particular ABI: ++ ```rust,ignore -extern "ABI" fn foo() { ... } +extern "ABI" fn foo() { /* ... */ } ``` These are often used in combination with [external block] items which provide function _declarations_ that can be used to call functions without providing their _definition_: ++ ```rust,ignore extern "ABI" { fn foo(); /* no body */ @@ -376,6 +379,7 @@ For example, the following code defines an inert `some_inert_attribute` attribut is not formally defined anywhere and the `some_proc_macro_attribute` procedural macro is responsible for detecting its presence and removing it from the output token stream. + ```rust,ignore #[some_proc_macro_attribute] fn foo_oof(#[some_inert_attribute] arg: u8) { diff --git a/src/items/generics.md b/src/items/generics.md index 6dc8f01d0..ba35e64d2 100644 --- a/src/items/generics.md +++ b/src/items/generics.md @@ -69,7 +69,7 @@ types when defining the item. It is an error to have `Copy` or `Clone`as a bound on a mutable reference, [trait object] or [slice][arrays] or `Sized` as a bound on a trait object or slice. -```rust,ignore +```rust,compile_fail struct A where T: Iterator, // Could use A instead @@ -92,6 +92,7 @@ attributes may give meaning to it. This example shows using a custom derive attribute to modify the meaning of a generic parameter. + ```rust,ignore // Assume that the derive for MyFlexibleClone declared `my_flexible_clone` as // an attribute it understands. diff --git a/src/items/modules.md b/src/items/modules.md index bdcda4905..a58bd37a2 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -74,6 +74,7 @@ For `path` attributes on modules not inside inline module blocks, the file path is relative to the directory the source file is located. For example, the following code snippet would use the paths shown based on where it is located: + ```rust,ignore #[path = "foo.rs"] mod c; @@ -95,6 +96,7 @@ it is the same except the path starts with a directory with the name of the non-mod-rs module. For example, the following code snippet would use the paths shown based on where it is located: + ```rust,ignore mod inline { #[path = "other.rs"] @@ -110,6 +112,7 @@ Source File | `inner`'s File Location | `inner`'s Module Path An example of combining the above rules of `path` attributes on inline modules and nested modules within (applies to both mod-rs and non-mod-rs files): + ```rust,ignore #[path = "thread_files"] mod thread { diff --git a/src/items/unions.md b/src/items/unions.md index d63bf1eec..7555a47b0 100644 --- a/src/items/unions.md +++ b/src/items/unions.md @@ -35,8 +35,11 @@ The expression above creates a value of type `MyUnion` and initializes the storage using field `f1`. The union can be accessed using the same syntax as struct fields: -```rust,ignore -let f = u.f1; +```rust +# union MyUnion { f1: u32, f2: f32 } +# +# let u = MyUnion { f1: 1 }; +let f = unsafe { u.f1 }; ``` ## Reading and writing union fields @@ -135,18 +138,19 @@ have to be adjusted to account for this fact. As a result, if one field of a union is borrowed, all its remaining fields are borrowed as well for the same lifetime. -```rust,ignore +```rust,compile_fail +# union MyUnion { f1: u32, f2: f32 } // ERROR: cannot borrow `u` (via `u.f2`) as mutable more than once at a time fn test() { let mut u = MyUnion { f1: 1 }; unsafe { let b1 = &mut u.f1; - ---- first mutable borrow occurs here (via `u.f1`) +// ---- first mutable borrow occurs here (via `u.f1`) let b2 = &mut u.f2; - ^^^^ second mutable borrow occurs here (via `u.f2`) +// ^^^^ second mutable borrow occurs here (via `u.f2`) *b1 = 5; } - - first borrow ends here +// - first borrow ends here assert_eq!(unsafe { u.f1 }, 5); } ``` diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 4397fc4bd..92bd78084 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -98,7 +98,7 @@ use crate::foo::baz::foobaz; // good: foo is at the root of the crate mod foo { - mod example { + pub mod example { pub mod iter {} } @@ -124,9 +124,14 @@ fn main() {} > accessing items in the crate root. Using the example above, the following > `use` paths work in 2015 but not 2018: > -> ```rust,ignore +> ```rust,edition2015 +> # mod foo { +> # pub mod example { pub mod iter {} } +> # pub mod baz { pub fn foobaz() {} } +> # } > use foo::example::iter; > use ::foo::baz::foobaz; +> # fn main() {} > ``` > > The 2015 edition does not allow use declarations to reference the [extern prelude]. diff --git a/src/lifetime-elision.md b/src/lifetime-elision.md index 51a03ef75..201e34410 100644 --- a/src/lifetime-elision.md +++ b/src/lifetime-elision.md @@ -25,36 +25,52 @@ In method signatures there is another rule Examples: -```rust,ignore -fn print(s: &str); // elided -fn print(s: &'_ str); // also elided -fn print<'a>(s: &'a str); // expanded - -fn debug(lvl: usize, s: &str); // elided -fn debug<'a>(lvl: usize, s: &'a str); // expanded - -fn substr(s: &str, until: usize) -> &str; // elided -fn substr<'a>(s: &'a str, until: usize) -> &'a str; // expanded - -fn get_str() -> &str; // ILLEGAL - -fn frob(s: &str, t: &str) -> &str; // ILLEGAL - -fn get_mut(&mut self) -> &mut T; // elided -fn get_mut<'a>(&'a mut self) -> &'a mut T; // expanded - -fn args(&mut self, args: &[T]) -> &mut Command; // elided -fn args<'a, 'b, T: ToCStr>(&'a mut self, args: &'b [T]) -> &'a mut Command; // expanded +```rust +# trait T {} +# trait ToCStr {} +# struct Thing<'a> {f: &'a i32} +# struct Command; +# +# trait Example { +fn print1(s: &str); // elided +fn print2(s: &'_ str); // also elided +fn print3<'a>(s: &'a str); // expanded + +fn debug1(lvl: usize, s: &str); // elided +fn debug2<'a>(lvl: usize, s: &'a str); // expanded + +fn substr1(s: &str, until: usize) -> &str; // elided +fn substr2<'a>(s: &'a str, until: usize) -> &'a str; // expanded + +fn get_mut1(&mut self) -> &mut dyn T; // elided +fn get_mut2<'a>(&'a mut self) -> &'a mut dyn T; // expanded + +fn args1(&mut self, args: &[T]) -> &mut Command; // elided +fn args2<'a, 'b, T: ToCStr>(&'a mut self, args: &'b [T]) -> &'a mut Command; // expanded + +fn new1(buf: &mut [u8]) -> Thing<'_>; // elided - preferred +fn new2(buf: &mut [u8]) -> Thing; // elided +fn new3<'a>(buf: &'a mut [u8]) -> Thing<'a>; // expanded +# } + +type FunPtr1 = fn(&str) -> &str; // elided +type FunPtr2 = for<'a> fn(&'a str) -> &'a str; // expanded + +type FunTrait1 = dyn Fn(&str) -> &str; // elided +type FunTrait2 = dyn for<'a> Fn(&'a str) -> &'a str; // expanded +``` -fn new(buf: &mut [u8]) -> BufWriter<'_>; // elided - preferred -fn new(buf: &mut [u8]) -> BufWriter; // elided -fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a>; // expanded +```rust,compile_fail +// The following examples show situations where it is not allowed to elide the +// lifetime parameter. -type FunPtr = fn(&str) -> &str; // elided -type FunPtr = for<'a> fn(&'a str) -> &'a str; // expanded +# trait Example { +// Cannot infer, because there are no parameters to infer from. +fn get_str() -> &str; // ILLEGAL -type FunTrait = dyn Fn(&str) -> &str; // elided -type FunTrait = dyn for<'a> Fn(&'a str) -> &'a str; // expanded +// Cannot infer, ambiguous if it is borrowed from the first or second parameter. +fn frob(s: &str, t: &str) -> &str; // ILLEGAL +# } ``` ## Default trait object lifetimes @@ -83,50 +99,54 @@ If neither of those rules apply, then the bounds on the trait are used: * If the trait has no lifetime bounds, then the lifetime is inferred in expressions and is `'static` outside of expressions. -```rust,ignore +```rust // For the following trait... trait Foo { } // These two are the same as Box has no lifetime bound on T -Box -Box +type T1 = Box; +type T2 = Box; // ...and so are these: impl dyn Foo {} impl dyn Foo + 'static {} // ...so are these, because &'a T requires T: 'a -&'a dyn Foo -&'a (dyn Foo + 'a) +type T3<'a> = &'a dyn Foo; +type T4<'a> = &'a (dyn Foo + 'a); // std::cell::Ref<'a, T> also requires T: 'a, so these are the same -std::cell::Ref<'a, dyn Foo> -std::cell::Ref<'a, dyn Foo + 'a> +type T5<'a> = std::cell::Ref<'a, dyn Foo>; +type T6<'a> = std::cell::Ref<'a, dyn Foo + 'a>; +``` -// This is an error: -struct TwoBounds<'a, 'b, T: ?Sized + 'a + 'b> -TwoBounds<'a, 'b, dyn Foo> // Error: the lifetime bound for this object type - // cannot be deduced from context +```rust,compile_fail +// This is an example of an error. +# trait Foo { } +struct TwoBounds<'a, 'b, T: ?Sized + 'a + 'b> { + f1: &'a i32, + f2: &'b i32, + f3: T, +} +type T7<'a, 'b> = TwoBounds<'a, 'b, dyn Foo>; +// ^^^^^^^ +// Error: the lifetime bound for this object type cannot be deduced from context ``` Note that the innermost object sets the bound, so `&'a Box` is still `&'a Box`. -```rust,ignore +```rust // For the following trait... trait Bar<'a>: 'a { } // ...these two are the same: -Box> -Box + 'a> +type T1<'a> = Box>; +type T2<'a> = Box + 'a>; // ...and so are these: -impl<'a> dyn Foo<'a> {} -impl<'a> dyn Foo<'a> + 'a {} - -// This is still an error: -struct TwoBounds<'a, 'b, T: ?Sized + 'a + 'b> -TwoBounds<'a, 'b, dyn Foo<'c>> +impl<'a> dyn Bar<'a> {} +impl<'a> dyn Bar<'a> + 'a {} ``` ## `'static` lifetime elision @@ -157,16 +177,29 @@ references, which themselves include references, the compiler will first try the standard elision rules. If it is unable to resolve the lifetimes by its usual rules, then it will error. By way of example: -```rust,ignore +```rust +# struct Foo; +# struct Bar; +# struct Baz; +# fn somefunc(a: &Foo, b: &Bar, c: &Baz) -> usize {42} // Resolved as `fn<'a>(&'a str) -> &'a str`. -const RESOLVED_SINGLE: fn(&str) -> &str = .. +const RESOLVED_SINGLE: fn(&str) -> &str = |x| x; // Resolved as `Fn<'a, 'b, 'c>(&'a Foo, &'b Bar, &'c Baz) -> usize`. -const RESOLVED_MULTIPLE: &dyn Fn(&Foo, &Bar, &Baz) -> usize = .. +const RESOLVED_MULTIPLE: &dyn Fn(&Foo, &Bar, &Baz) -> usize = &somefunc; +``` +```rust,compile_fail +# struct Foo; +# struct Bar; +# struct Baz; +# fn somefunc<'a,'b>(a: &'a Foo, b: &'b Bar) -> &'a Baz {unimplemented!()} // There is insufficient information to bound the return reference lifetime // relative to the argument lifetimes, so this is an error. -const RESOLVED_STATIC: &dyn Fn(&Foo, &Bar) -> &Baz = .. +const RESOLVED_STATIC: &dyn Fn(&Foo, &Bar) -> &Baz = &somefunc; +// ^ +// this function's return type contains a borrowed value, but the signature +// does not say whether it is borrowed from argument 1 or argument 2 ``` [closure trait]: types/closure.md diff --git a/src/linkage.md b/src/linkage.md index 61a24f2a2..5464aef72 100644 --- a/src/linkage.md +++ b/src/linkage.md @@ -151,13 +151,13 @@ feature. These target features are typically configured from the command line via flags to the compiler itself. For example to enable a static runtime you would execute: -```notrust +```bash rustc -C target-feature=+crt-static foo.rs ``` whereas to link dynamically to the C runtime you would execute: -```notrust +```bash rustc -C target-feature=-crt-static foo.rs ``` @@ -170,7 +170,7 @@ example, needs to be compiled differently (e.g. with `/MT` or `/MD`) depending on the runtime being linked. This is exported currently through the [`cfg` attribute `target_feature` option]: -```rust,ignore +```rust #[cfg(target_feature = "crt-static")] fn foo() { println!("the C runtime should be statically linked"); @@ -206,7 +206,7 @@ To use this feature locally, you typically will use the `RUSTFLAGS` environment variable to specify flags to the compiler through Cargo. For example to compile a statically linked binary on MSVC you would execute: -```ignore,notrust +```bash RUSTFLAGS='-C target-feature=+crt-static' cargo build --target x86_64-pc-windows-msvc ``` diff --git a/src/macros-by-example.md b/src/macros-by-example.md index fd7c33575..34c2d4af9 100644 --- a/src/macros-by-example.md +++ b/src/macros-by-example.md @@ -195,6 +195,7 @@ path), it is first looked up in textual scoping. If this does not yield any results, then it is looked up in path-based scoping. If the macro's name is qualified with a path, then it is only looked up in path-based scoping. + ```rust,ignore use lazy_static::lazy_static; // Path-based import. @@ -216,6 +217,7 @@ be used recursively, since names are looked up from the invocation site), up until its surrounding scope, typically a module, is closed. This can enter child modules and even span across multiple files: + ```rust,ignore //// src/lib.rs mod has_macro { @@ -306,6 +308,7 @@ conflict, the last macro imported wins. Optionally, a list of macros to import can be specified using the [_MetaListIdents_] syntax; this is not supported when `#[macro_use]` is applied to a module. + ```rust,ignore #[macro_use(lazy_static)] // Or #[macro_use] to import all macros. extern crate lazy_static; @@ -351,6 +354,7 @@ refers to an item or macro which isn't in scope at the invocation site. To alleviate this, the `$crate` metavariable can be used at the start of a path to force lookup to occur inside the crate defining the macro. + ```rust,ignore //// Definitions in the `helper_macro` crate. #[macro_export] diff --git a/src/paths.md b/src/paths.md index 5f13598df..af739d708 100644 --- a/src/paths.md +++ b/src/paths.md @@ -8,6 +8,7 @@ item. Two examples of simple paths consisting of only identifier segments: + ```rust,ignore x; x::y::z; @@ -135,10 +136,20 @@ and qualified paths. Although the `::` token is allowed before the generics arguments, it is not required because there is no ambiguity like there is in _PathInExpression_. -```rust,ignore +```rust +# mod ops { +# pub struct Range {f1: T} +# pub trait Index {} +# pub struct Example<'a> {f1: &'a i32} +# } +# struct S; impl ops::Index> for S { /*...*/ } -fn i() -> impl Iterator> { /*...*/ } -type G = std::boxed::Box isize>; +fn i<'a>() -> impl Iterator> { + // ... +# const EXAMPLE: Vec> = Vec::new(); +# EXAMPLE.into_iter() +} +type G = std::boxed::Box isize>; ``` ## Path qualifiers diff --git a/src/procedural-macros.md b/src/procedural-macros.md index ff3f6df1d..2bd3706a2 100644 --- a/src/procedural-macros.md +++ b/src/procedural-macros.md @@ -80,7 +80,9 @@ output [`TokenStream`] replaces the entire macro invocation. For example, the following macro definition ignores its input and outputs a function `answer` into its scope. + ```rust,ignore +# #![crate_type = "proc-macro"] extern crate proc_macro; use proc_macro::TokenStream; @@ -92,6 +94,7 @@ pub fn make_answer(_item: TokenStream) -> TokenStream { And then we use it a binary crate to print "42" to standard output. + ```rust,ignore extern crate proc_macro_examples; use proc_macro_examples::make_answer; @@ -127,7 +130,9 @@ then appended to the [module] or [block] that the item from the input The following is an example of a derive macro. Instead of doing anything useful with its input, it just appends a function `answer`. + ```rust,ignore +# #![crate_type = "proc-macro"] extern crate proc_macro; use proc_macro::TokenStream; @@ -139,6 +144,7 @@ pub fn derive_answer_fn(_item: TokenStream) -> TokenStream { And then using said derive macro: + ```rust,ignore extern crate proc_macro_examples; use proc_macro_examples::AnswerFn; @@ -165,8 +171,9 @@ the names of the helper attributes. For example, the following derive macro defines a helper attribute `helper`, but ultimately doesn't do anything with it. + ```rust,ignore -# #[crate_type="proc-macro"] +# #![crate_type="proc-macro"] # extern crate proc_macro; # use proc_macro::TokenStream; @@ -178,11 +185,8 @@ pub fn derive_helper_attr(_item: TokenStream) -> TokenStream { And then usage on the derive macro on a struct: + ```rust,ignore -# #![crate_type="proc-macro"] -# extern crate proc_macro_examples; -# use proc_macro_examples::HelperAttr; - #[derive(HelperAttr)] struct Struct { #[helper] field: () @@ -207,6 +211,7 @@ replaces the [item] with an arbitrary number of [items]. For example, this attribute macro takes the input stream and returns it as is, effectively being the no-op of attributes. + ```rust,ignore # #![crate_type = "proc-macro"] # extern crate proc_macro; @@ -222,6 +227,7 @@ This following example shows the stringified [`TokenStream`s] that the attribute macros see. The output will show in the output of the compiler. The output is shown in the comments after the function prefixed with "out:". + ```rust,ignore // my-macro/src/lib.rs # extern crate proc_macro; @@ -235,6 +241,7 @@ pub fn show_streams(attr: TokenStream, item: TokenStream) -> TokenStream { } ``` + ```rust,ignore // src/lib.rs extern crate my_macro; diff --git a/src/runtime.md b/src/runtime.md index 57680d051..06966926d 100644 --- a/src/runtime.md +++ b/src/runtime.md @@ -12,9 +12,8 @@ The *`panic_handler` attribute* can only be applied to a function with signature Below is shown a `panic_handler` function that logs the panic message and then halts the thread. - - -``` rust, ignore + +```rust,ignore #![no_std] use core::fmt::{self, Write}; @@ -64,7 +63,7 @@ the [subsystem] when linking on a Windows target. It uses the `console` or `windows`. This attribute is ignored on non-Windows targets, and for non-`bin` [crate types]. -```rust,ignore +```rust #![windows_subsystem = "windows"] ``` diff --git a/src/tokens.md b/src/tokens.md index 649bee435..e4338f06f 100644 --- a/src/tokens.md +++ b/src/tokens.md @@ -414,7 +414,7 @@ let a: u64 = 123; // type u64 Examples of invalid integer literals: -```rust,ignore +```rust,compile_fail // invalid suffixes 0invalidSuffix; diff --git a/src/trait-bounds.md b/src/trait-bounds.md index 6c48e5e6f..fe677a9a1 100644 --- a/src/trait-bounds.md +++ b/src/trait-bounds.md @@ -104,9 +104,11 @@ Type bounds may be *higher ranked* over lifetimes. These bounds specify a bound is true *for all* lifetimes. For example, a bound such as `for<'a> &'a T: PartialEq` would require an implementation like -```rust,ignore +```rust +# struct T; impl<'a> PartialEq for &'a T { // ... +# fn eq(&self, other: &i32) -> bool {true} } ``` diff --git a/src/type-layout.md b/src/type-layout.md index 57e801e10..900c6d4ac 100644 --- a/src/type-layout.md +++ b/src/type-layout.md @@ -195,6 +195,7 @@ multiple of the struct's alignment. Here is this algorithm described in pseudocode. + ```rust,ignore struct.alignment = struct.fields().map(|field| field.alignment).max(); diff --git a/src/types/closure.md b/src/types/closure.md index 6ef5e6b6e..520d90480 100644 --- a/src/types/closure.md +++ b/src/types/closure.md @@ -22,13 +22,15 @@ f(|| { generates a closure type roughly like the following: + ```rust,ignore struct Closure<'a> { s : String, t : &'a String, } -impl<'a> (FnOnce() -> String) for Closure<'a> { +impl<'a> FnOnce<()> for Closure<'a> { + type Output = String; fn call_once(self) -> String { self.s += &*self.t; self.s @@ -38,6 +40,7 @@ impl<'a> (FnOnce() -> String) for Closure<'a> { so that the call to `f` works as if it were: + ```rust,ignore f(Closure{s: s, t: &t}); ```