From ef24de24a82fe681581cc130f342363c47c0969a Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 7 Jun 2024 07:48:48 +0200 Subject: Merging upstream version 1.75.0+dfsg1. Signed-off-by: Daniel Baumann --- src/doc/rust-by-example/src/SUMMARY.md | 4 +-- src/doc/rust-by-example/src/attribute.md | 32 ++++++++++++++++++-- .../rust-by-example/src/custom_types/constants.md | 2 +- .../src/error/option_unwrap/question_mark.md | 3 +- .../rust-by-example/src/flow_control/while_let.md | 34 ++++++++++------------ src/doc/rust-by-example/src/fn/closures.md | 4 +-- src/doc/rust-by-example/src/fn/hof.md | 2 +- src/doc/rust-by-example/src/meta/doc.md | 9 ++++-- src/doc/rust-by-example/src/meta/playground.md | 15 +++++++--- src/doc/rust-by-example/src/primitives/array.md | 2 +- src/doc/rust-by-example/src/scope/lifetime.md | 2 +- src/doc/rust-by-example/src/scope/move.md | 2 +- .../rust-by-example/src/std/hash/alt_key_types.md | 2 +- .../rust-by-example/src/std_misc/arg/matching.md | 3 ++ .../src/std_misc/file/read_lines.md | 8 ++--- .../src/std_misc/threads/testcase_mapreduce.md | 2 +- 16 files changed, 81 insertions(+), 45 deletions(-) (limited to 'src/doc/rust-by-example') diff --git a/src/doc/rust-by-example/src/SUMMARY.md b/src/doc/rust-by-example/src/SUMMARY.md index b1bcf223d..b8e6ada91 100644 --- a/src/doc/rust-by-example/src/SUMMARY.md +++ b/src/doc/rust-by-example/src/SUMMARY.md @@ -161,7 +161,7 @@ - [Unpacking options with `?`](error/option_unwrap/question_mark.md) - [Combinators: `map`](error/option_unwrap/map.md) - [Combinators: `and_then`](error/option_unwrap/and_then.md) - - [Defaults: `or`, `or_else`, `get_or_insert`, 'get_or_insert_with`](error/option_unwrap/defaults.md) + - [Defaults: `or`, `or_else`, `get_or_insert`, `get_or_insert_with`](error/option_unwrap/defaults.md) - [`Result`](error/result.md) - [`map` for `Result`](error/result/result_map.md) - [aliases for `Result`](error/result/result_alias.md) @@ -197,7 +197,7 @@ - [File I/O](std_misc/file.md) - [`open`](std_misc/file/open.md) - [`create`](std_misc/file/create.md) - - [`read lines`](std_misc/file/read_lines.md) + - [`read_lines`](std_misc/file/read_lines.md) - [Child processes](std_misc/process.md) - [Pipes](std_misc/process/pipe.md) - [Wait](std_misc/process/wait.md) diff --git a/src/doc/rust-by-example/src/attribute.md b/src/doc/rust-by-example/src/attribute.md index dcb7d6c1a..d6a49dc01 100644 --- a/src/doc/rust-by-example/src/attribute.md +++ b/src/doc/rust-by-example/src/attribute.md @@ -14,9 +14,34 @@ can be used to/for: * mark functions that will be part of a benchmark * [attribute like macros][macros] -When attributes apply to a whole crate, their syntax is `#![crate_attribute]`, -and when they apply to a module or item, the syntax is `#[item_attribute]` -(notice the missing bang `!`). +Attributes look like `#[outer_attribute]` or `#![inner_attribute]`, +with the difference between them being where they apply. + +- `#[outer_attribute]` applies to the [item][item] immediately + following it. Some examples of items are: a function, a module + declaration, a constant, a structure, an enum. Here is an example + where attribute `#[derive(Debug)]` applies to the struct + `Rectangle`: + ```rust + #[derive(Debug)] + struct Rectangle { + width: u32, + height: u32, + } + ``` + +- `#![inner_attribute]` applies to the enclosing [item][item] (typically a + module or a crate). In other words, this attribute is intepreted as + applying to the entire scope in which it's place. Here is an example + where `#![allow(unusude_variables)]` applies to the whole crate (if + placed in `main.rs`): + ```rust + #![allow(unused_variables)] + + fn main() { + let x = 3; // This would normally warn about an unused variable. + } + ``` Attributes can take arguments with different syntaxes: @@ -36,5 +61,6 @@ Attributes can have multiple values and can be separated over multiple lines, to [cfg]: attribute/cfg.md [crate]: attribute/crate.md +[item]: https://doc.rust-lang.org/stable/reference/items.html [lint]: https://en.wikipedia.org/wiki/Lint_%28software%29 [macros]: https://doc.rust-lang.org/book/ch19-06-macros.html#attribute-like-macros diff --git a/src/doc/rust-by-example/src/custom_types/constants.md b/src/doc/rust-by-example/src/custom_types/constants.md index 8878ba834..c060db734 100644 --- a/src/doc/rust-by-example/src/custom_types/constants.md +++ b/src/doc/rust-by-example/src/custom_types/constants.md @@ -4,7 +4,7 @@ Rust has two different types of constants which can be declared in any scope including global. Both require explicit type annotation: * `const`: An unchangeable value (the common case). -* `static`: A possibly `mut`able variable with [`'static`][static] lifetime. +* `static`: A possibly mutable variable with [`'static`][static] lifetime. The static lifetime is inferred and does not have to be specified. Accessing or modifying a mutable static variable is [`unsafe`][unsafe]. diff --git a/src/doc/rust-by-example/src/error/option_unwrap/question_mark.md b/src/doc/rust-by-example/src/error/option_unwrap/question_mark.md index 831625229..04de93cc7 100644 --- a/src/doc/rust-by-example/src/error/option_unwrap/question_mark.md +++ b/src/doc/rust-by-example/src/error/option_unwrap/question_mark.md @@ -8,7 +8,8 @@ function is being executed and return `None`. ```rust,editable fn next_birthday(current_age: Option) -> Option { // If `current_age` is `None`, this returns `None`. - // If `current_age` is `Some`, the inner `u8` gets assigned to `next_age` + // If `current_age` is `Some`, the inner `u8` value + 1 + // gets assigned to `next_age` let next_age: u8 = current_age? + 1; Some(format!("Next year I will be {}", next_age)) } diff --git a/src/doc/rust-by-example/src/flow_control/while_let.md b/src/doc/rust-by-example/src/flow_control/while_let.md index 897375a8e..745b7ae75 100644 --- a/src/doc/rust-by-example/src/flow_control/while_let.md +++ b/src/doc/rust-by-example/src/flow_control/while_let.md @@ -31,26 +31,24 @@ loop { Using `while let` makes this sequence much nicer: ```rust,editable -fn main() { - // Make `optional` of type `Option` - let mut optional = Some(0); - - // This reads: "while `let` destructures `optional` into - // `Some(i)`, evaluate the block (`{}`). Else `break`. - while let Some(i) = optional { - if i > 9 { - println!("Greater than 9, quit!"); - optional = None; - } else { - println!("`i` is `{:?}`. Try again.", i); - optional = Some(i + 1); - } - // ^ Less rightward drift and doesn't require - // explicitly handling the failing case. +// Make `optional` of type `Option` +let mut optional = Some(0); + +// This reads: "while `let` destructures `optional` into +// `Some(i)`, evaluate the block (`{}`). Else `break`. +while let Some(i) = optional { + if i > 9 { + println!("Greater than 9, quit!"); + optional = None; + } else { + println!("`i` is `{:?}`. Try again.", i); + optional = Some(i + 1); } - // ^ `if let` had additional optional `else`/`else if` - // clauses. `while let` does not have these. + // ^ Less rightward drift and doesn't require + // explicitly handling the failing case. } +// ^ `if let` had additional optional `else`/`else if` +// clauses. `while let` does not have these. ``` ### See also: diff --git a/src/doc/rust-by-example/src/fn/closures.md b/src/doc/rust-by-example/src/fn/closures.md index 82286003b..e7b8c9867 100644 --- a/src/doc/rust-by-example/src/fn/closures.md +++ b/src/doc/rust-by-example/src/fn/closures.md @@ -14,7 +14,7 @@ variable names *must* be specified. Other characteristics of closures include: * using `||` instead of `()` around input variables. -* optional body delimination (`{}`) for a single expression (mandatory otherwise). +* optional body delimitation (`{}`) for a single expression (mandatory otherwise). * the ability to capture the outer environment variables. ```rust,editable @@ -26,7 +26,7 @@ fn main() { // TODO: uncomment the line above and see the compiler error. The compiler // suggests that we define a closure instead. - // Closures are anonymous, here we are binding them to references + // Closures are anonymous, here we are binding them to references. // Annotation is identical to function annotation but is optional // as are the `{}` wrapping the body. These nameless functions // are assigned to appropriately named variables. diff --git a/src/doc/rust-by-example/src/fn/hof.md b/src/doc/rust-by-example/src/fn/hof.md index 88918cb52..9be5b41fe 100644 --- a/src/doc/rust-by-example/src/fn/hof.md +++ b/src/doc/rust-by-example/src/fn/hof.md @@ -10,7 +10,7 @@ fn is_odd(n: u32) -> bool { } fn main() { - println!("Find the sum of all the squared odd numbers under 1000"); + println!("Find the sum of all the numbers with odd squares under 1000"); let upper = 1000; // Imperative approach diff --git a/src/doc/rust-by-example/src/meta/doc.md b/src/doc/rust-by-example/src/meta/doc.md index e9e51186f..b1732f837 100644 --- a/src/doc/rust-by-example/src/meta/doc.md +++ b/src/doc/rust-by-example/src/meta/doc.md @@ -2,7 +2,8 @@ Use `cargo doc` to build documentation in `target/doc`. -Use `cargo test` to run all tests (including documentation tests), and `cargo test --doc` to only run documentation tests. +Use `cargo test` to run all tests (including documentation tests), and `cargo +test --doc` to only run documentation tests. These commands will appropriately invoke `rustdoc` (and `rustc`) as required. @@ -67,7 +68,8 @@ $ rustdoc --test --extern doc="libdoc.rlib" doc.rs ## Doc attributes -Below are a few examples of the most common `#[doc]` attributes used with `rustdoc`. +Below are a few examples of the most common `#[doc]` attributes used with +`rustdoc`. ### `inline` @@ -104,7 +106,8 @@ Using this tells `rustdoc` not to include this in documentation: pub use self::async_await::*; ``` -For documentation, `rustdoc` is widely used by the community. It's what is used to generate the [std library docs](https://doc.rust-lang.org/std/). +For documentation, `rustdoc` is widely used by the community. It's what is used +to generate the [std library docs](https://doc.rust-lang.org/std/). ### See also: diff --git a/src/doc/rust-by-example/src/meta/playground.md b/src/doc/rust-by-example/src/meta/playground.md index 7fcfad1a7..e78552d29 100644 --- a/src/doc/rust-by-example/src/meta/playground.md +++ b/src/doc/rust-by-example/src/meta/playground.md @@ -1,6 +1,7 @@ # Playground -The [Rust Playground](https://play.rust-lang.org/) is a way to experiment with Rust code through a web interface. +The [Rust Playground](https://play.rust-lang.org/) is a way to experiment with +Rust code through a web interface. ## Using it with `mdbook` @@ -12,7 +13,9 @@ fn main() { } ``` -This allows the reader to both run your code sample, but also modify and tweak it. The key here is the adding the word `editable` to your codefence block separated by a comma. +This allows the reader to both run your code sample, but also modify and tweak +it. The key here is the adding the word `editable` to your codefence block +separated by a comma. ````markdown ```rust,editable @@ -20,7 +23,8 @@ This allows the reader to both run your code sample, but also modify and tweak i ``` ```` -Additionally, you can add `ignore` if you want `mdbook` to skip your code when it builds and tests. +Additionally, you can add `ignore` if you want `mdbook` to skip your code when +it builds and tests. ````markdown ```rust,editable,ignore @@ -30,7 +34,10 @@ Additionally, you can add `ignore` if you want `mdbook` to skip your code when i ## Using it with docs -You may have noticed in some of the [official Rust docs][official-rust-docs] a button that says "Run", which opens the code sample up in a new tab in Rust Playground. This feature is enabled if you use the #[doc] attribute called [`html_playground_url`][html-playground-url]. +You may have noticed in some of the [official Rust docs][official-rust-docs] a +button that says "Run", which opens the code sample up in a new tab in Rust +Playground. This feature is enabled if you use the `#[doc]` attribute called +[`html_playground_url`][html-playground-url]. ### See also: diff --git a/src/doc/rust-by-example/src/primitives/array.md b/src/doc/rust-by-example/src/primitives/array.md index 5f5e69944..704a2131c 100644 --- a/src/doc/rust-by-example/src/primitives/array.md +++ b/src/doc/rust-by-example/src/primitives/array.md @@ -6,7 +6,7 @@ at compile time, is part of their type signature `[T; length]`. Slices are similar to arrays, but their length is not known at compile time. Instead, a slice is a two-word object; the first word is a pointer to the data, -the second word the length of the slice. The word size is the same as usize, +the second word is the length of the slice. The word size is the same as usize, determined by the processor architecture, e.g. 64 bits on an x86-64. Slices can be used to borrow a section of an array and have the type signature `&[T]`. diff --git a/src/doc/rust-by-example/src/scope/lifetime.md b/src/doc/rust-by-example/src/scope/lifetime.md index 68b42d380..01c4bf405 100644 --- a/src/doc/rust-by-example/src/scope/lifetime.md +++ b/src/doc/rust-by-example/src/scope/lifetime.md @@ -1,6 +1,6 @@ # Lifetimes -A *lifetime* is a construct of the compiler (or more specifically, its *borrow +A *lifetime* is a construct the compiler (or more specifically, its *borrow checker*) uses to ensure all borrows are valid. Specifically, a variable's lifetime begins when it is created and ends when it is destroyed. While lifetimes and scopes are often referred to together, they are not the same. diff --git a/src/doc/rust-by-example/src/scope/move.md b/src/doc/rust-by-example/src/scope/move.md index 0433e8ac1..df631ee08 100644 --- a/src/doc/rust-by-example/src/scope/move.md +++ b/src/doc/rust-by-example/src/scope/move.md @@ -1,7 +1,7 @@ # Ownership and moves Because variables are in charge of freeing their own resources, -**resources can only have one owner**. This also prevents resources +**resources can only have one owner**. This prevents resources from being freed more than once. Note that not all variables own resources (e.g. [references]). diff --git a/src/doc/rust-by-example/src/std/hash/alt_key_types.md b/src/doc/rust-by-example/src/std/hash/alt_key_types.md index ab94819b2..7e68e8c67 100644 --- a/src/doc/rust-by-example/src/std/hash/alt_key_types.md +++ b/src/doc/rust-by-example/src/std/hash/alt_key_types.md @@ -3,7 +3,7 @@ Any type that implements the `Eq` and `Hash` traits can be a key in `HashMap`. This includes: -* `bool` (though not very useful since there is only two possible keys) +* `bool` (though not very useful since there are only two possible keys) * `int`, `uint`, and all variations thereof * `String` and `&str` (protip: you can have a `HashMap` keyed by `String` and call `.get()` with an `&str`) diff --git a/src/doc/rust-by-example/src/std_misc/arg/matching.md b/src/doc/rust-by-example/src/std_misc/arg/matching.md index 4cb68eabf..4a96fbc21 100644 --- a/src/doc/rust-by-example/src/std_misc/arg/matching.md +++ b/src/doc/rust-by-example/src/std_misc/arg/matching.md @@ -70,6 +70,9 @@ fn main() { } ``` +If you named your program `match_args.rs` and compile it like this `rustc +match_args.rs`, you can execute it as follows: + ```shell $ ./match_args Rust This is not the answer. diff --git a/src/doc/rust-by-example/src/std_misc/file/read_lines.md b/src/doc/rust-by-example/src/std_misc/file/read_lines.md index 216b0181c..1a2a64241 100644 --- a/src/doc/rust-by-example/src/std_misc/file/read_lines.md +++ b/src/doc/rust-by-example/src/std_misc/file/read_lines.md @@ -56,15 +56,13 @@ fn main() { // File hosts.txt must exist in the current path if let Ok(lines) = read_lines("./hosts.txt") { // Consumes the iterator, returns an (Optional) String - for line in lines { - if let Ok(ip) = line { - println!("{}", ip); - } + for line in lines.flatten() { + println!("{}", line); } } } -// The output is wrapped in a Result to allow matching on errors +// The output is wrapped in a Result to allow matching on errors. // Returns an Iterator to the Reader of the lines of the file. fn read_lines

(filename: P) -> io::Result>> where P: AsRef, { diff --git a/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md b/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md index ee25b1661..9cc162f51 100644 --- a/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md +++ b/src/doc/rust-by-example/src/std_misc/threads/testcase_mapreduce.md @@ -30,7 +30,7 @@ use std::thread; fn main() { // This is our data to process. - // We will calculate the sum of all digits via a threaded map-reduce algorithm. + // We will calculate the sum of all digits via a threaded map-reduce algorithm. // Each whitespace separated chunk will be handled in a different thread. // // TODO: see what happens to the output if you insert spaces! -- cgit v1.2.3