From a6bf11a4258c77a30053053161086d873f2d5774 Mon Sep 17 00:00:00 2001 From: funkill2 Date: Tue, 18 Mar 2025 04:00:14 +0300 Subject: [PATCH] update original --- rustbook-en/ci/dictionary.txt | 1 + rustbook-en/ferris.css | 22 +++++++++++++++ rustbook-en/ferris.js | 6 +++-- .../listing-09-05/src/main.rs | 4 +-- .../src/{lib.rs => guessing_game.rs} | 0 .../listing-09-13/src/main.rs | 2 ++ .../listing-17-17/src/main.rs | 2 +- .../listing-17-18/src/main.rs | 24 +++++++++-------- .../listing-17-19/src/main.rs | 12 +++++---- .../listing-17-28/src/main.rs | 2 +- .../listing-17-29/src/main.rs | 2 +- .../src/ch02-00-guessing-game-tutorial.md | 2 +- .../src/ch09-03-to-panic-or-not-to-panic.md | 27 ++++++++++--------- rustbook-en/src/ch10-01-syntax.md | 10 +++---- rustbook-en/src/ch17-03-more-futures.md | 13 ++++----- rustbook-en/src/ch18-03-oo-design-patterns.md | 11 ++++---- rustbook-en/src/ch20-01-unsafe-rust.md | 8 +++--- 17 files changed, 92 insertions(+), 56 deletions(-) rename rustbook-en/listings/ch09-error-handling/listing-09-13/src/{lib.rs => guessing_game.rs} (100%) diff --git a/rustbook-en/ci/dictionary.txt b/rustbook-en/ci/dictionary.txt index 3ce0ea7d..525fa947 100644 --- a/rustbook-en/ci/dictionary.txt +++ b/rustbook-en/ci/dictionary.txt @@ -2,6 +2,7 @@ personal_ws-1.1 en 0 utf-8 abcabcabc abcd abcdefghijklmnopqrstuvwxyz +ABIs AddAssign Addr adfb diff --git a/rustbook-en/ferris.css b/rustbook-en/ferris.css index fb4a553f..513efa14 100644 --- a/rustbook-en/ferris.css +++ b/rustbook-en/ferris.css @@ -43,3 +43,25 @@ body.ayu .not_desired_behavior { .ferris-explain { width: 100px; } + +/* + A bit of a hack to make small Ferris use the existing buttons container but + only show/hide the buttons on hover over the `pre`. Targeting `.listing` + increases the specificity of this rule. +*/ +pre > .buttons { + visibility: visible; + opacity: 1; + transition: none; +} + +pre > .buttons button { + visibility: hidden; + opacity: 0; + transition: visibility 0.1s linear, opacity 0.1s linear; +} + +pre:hover > .buttons button { + visibility: visible; + opacity: 1; +} diff --git a/rustbook-en/ferris.js b/rustbook-en/ferris.js index 08f32928..13b1ceb9 100644 --- a/rustbook-en/ferris.js +++ b/rustbook-en/ferris.js @@ -40,10 +40,12 @@ function attachFerrises(type) { continue; } - let lines = codeBlock.innerText.replace(/\n$/, "").split(/\n/).length; + let codeLines = codeBlock.innerText; + let extra = codeLines.endsWith("\n") ? 1 : 0; + let numLines = codeLines.split("\n").length - extra; /** @type {'small' | 'large'} */ - let size = lines < 4 ? "small" : "large"; + let size = numLines < 4 ? "small" : "large"; let container = prepareFerrisContainer(codeBlock, size == "small"); if (!container) { diff --git a/rustbook-en/listings/ch09-error-handling/listing-09-05/src/main.rs b/rustbook-en/listings/ch09-error-handling/listing-09-05/src/main.rs index e0bc55c3..20f470ba 100644 --- a/rustbook-en/listings/ch09-error-handling/listing-09-05/src/main.rs +++ b/rustbook-en/listings/ch09-error-handling/listing-09-05/src/main.rs @@ -11,8 +11,8 @@ fn main() { Ok(fc) => fc, Err(e) => panic!("Problem creating the file: {e:?}"), }, - other_error => { - panic!("Problem opening the file: {other_error:?}"); + _ => { + panic!("Problem opening the file: {error:?}"); } }, }; diff --git a/rustbook-en/listings/ch09-error-handling/listing-09-13/src/lib.rs b/rustbook-en/listings/ch09-error-handling/listing-09-13/src/guessing_game.rs similarity index 100% rename from rustbook-en/listings/ch09-error-handling/listing-09-13/src/lib.rs rename to rustbook-en/listings/ch09-error-handling/listing-09-13/src/guessing_game.rs diff --git a/rustbook-en/listings/ch09-error-handling/listing-09-13/src/main.rs b/rustbook-en/listings/ch09-error-handling/listing-09-13/src/main.rs index cda38930..6c3e9634 100644 --- a/rustbook-en/listings/ch09-error-handling/listing-09-13/src/main.rs +++ b/rustbook-en/listings/ch09-error-handling/listing-09-13/src/main.rs @@ -3,6 +3,8 @@ use rand::Rng; use std::cmp::Ordering; use std::io; +mod guessing_game; + fn main() { println!("Guess the number!"); diff --git a/rustbook-en/listings/ch17-async-await/listing-17-17/src/main.rs b/rustbook-en/listings/ch17-async-await/listing-17-17/src/main.rs index 1888a535..b58c7493 100644 --- a/rustbook-en/listings/ch17-async-await/listing-17-17/src/main.rs +++ b/rustbook-en/listings/ch17-async-await/listing-17-17/src/main.rs @@ -1,6 +1,6 @@ extern crate trpl; // required for mdbook test -use std::{future::Future, time::Duration}; +use std::time::Duration; fn main() { trpl::run(async { diff --git a/rustbook-en/listings/ch17-async-await/listing-17-18/src/main.rs b/rustbook-en/listings/ch17-async-await/listing-17-18/src/main.rs index a5576283..37c0c167 100644 --- a/rustbook-en/listings/ch17-async-await/listing-17-18/src/main.rs +++ b/rustbook-en/listings/ch17-async-await/listing-17-18/src/main.rs @@ -1,17 +1,19 @@ extern crate trpl; // required for mdbook test -use std::{ - future::Future, - pin::{Pin, pin}, - time::Duration, -}; +// ANCHOR: here +use std::pin::Pin; + +// -- snip -- + +// ANCHOR_END: here +use std::time::Duration; fn main() { trpl::run(async { let (tx, mut rx) = trpl::channel(); let tx1 = tx.clone(); - let tx1_fut = pin!(async move { + let tx1_fut = async move { let vals = vec![ String::from("hi"), String::from("from"), @@ -23,15 +25,15 @@ fn main() { tx1.send(val).unwrap(); trpl::sleep(Duration::from_secs(1)).await; } - }); + }; - let rx_fut = pin!(async { + let rx_fut = async { while let Some(value) = rx.recv().await { println!("received '{value}'"); } - }); + }; - let tx_fut = pin!(async move { + let tx_fut = async move { let vals = vec![ String::from("more"), String::from("messages"), @@ -43,7 +45,7 @@ fn main() { tx.send(val).unwrap(); trpl::sleep(Duration::from_secs(1)).await; } - }); + }; // ANCHOR: here let futures: Vec>>> = diff --git a/rustbook-en/listings/ch17-async-await/listing-17-19/src/main.rs b/rustbook-en/listings/ch17-async-await/listing-17-19/src/main.rs index 9378d7d7..1133c64e 100644 --- a/rustbook-en/listings/ch17-async-await/listing-17-19/src/main.rs +++ b/rustbook-en/listings/ch17-async-await/listing-17-19/src/main.rs @@ -1,10 +1,12 @@ extern crate trpl; // required for mdbook test -use std::{ - future::Future, - pin::{Pin, pin}, - time::Duration, -}; +// ANCHOR: here +use std::pin::{Pin, pin}; + +// -- snip -- + +// ANCHOR_END: here +use std::time::Duration; fn main() { trpl::run(async { diff --git a/rustbook-en/listings/ch17-async-await/listing-17-28/src/main.rs b/rustbook-en/listings/ch17-async-await/listing-17-28/src/main.rs index d2edded6..8c6348c7 100644 --- a/rustbook-en/listings/ch17-async-await/listing-17-28/src/main.rs +++ b/rustbook-en/listings/ch17-async-await/listing-17-28/src/main.rs @@ -1,6 +1,6 @@ extern crate trpl; // required for mdbook test -use std::{future::Future, time::Duration}; +use std::time::Duration; fn main() { trpl::run(async { diff --git a/rustbook-en/listings/ch17-async-await/listing-17-29/src/main.rs b/rustbook-en/listings/ch17-async-await/listing-17-29/src/main.rs index 9efb5e79..510cbd37 100644 --- a/rustbook-en/listings/ch17-async-await/listing-17-29/src/main.rs +++ b/rustbook-en/listings/ch17-async-await/listing-17-29/src/main.rs @@ -1,6 +1,6 @@ extern crate trpl; // required for mdbook test -use std::{future::Future, time::Duration}; +use std::time::Duration; // ANCHOR: implementation use trpl::Either; diff --git a/rustbook-en/src/ch02-00-guessing-game-tutorial.md b/rustbook-en/src/ch02-00-guessing-game-tutorial.md index be9d6078..015a42a5 100644 --- a/rustbook-en/src/ch02-00-guessing-game-tutorial.md +++ b/rustbook-en/src/ch02-00-guessing-game-tutorial.md @@ -178,7 +178,7 @@ input: {{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:read}} ``` -If we hadn’t imported the `io` library with `use std::io;` at the beginning of +If we hadn’t imported the `io` module with `use std::io;` at the beginning of the program, we could still use the function by writing this function call as `std::io::stdin`. The `stdin` function returns an instance of [`std::io::Stdin`][iostdin], which is a type that represents a diff --git a/rustbook-en/src/ch09-03-to-panic-or-not-to-panic.md b/rustbook-en/src/ch09-03-to-panic-or-not-to-panic.md index 66cba1fd..58f2903b 100644 --- a/rustbook-en/src/ch09-03-to-panic-or-not-to-panic.md +++ b/rustbook-en/src/ch09-03-to-panic-or-not-to-panic.md @@ -159,23 +159,24 @@ program only operated on values between 1 and 100, and it had many functions with this requirement, having a check like this in every function would be tedious (and might impact performance). -Instead, we can make a new type and put the validations in a function to create -an instance of the type rather than repeating the validations everywhere. That -way, it’s safe for functions to use the new type in their signatures and -confidently use the values they receive. Listing 9-13 shows one way to define a -`Guess` type that will only create an instance of `Guess` if the `new` function -receives a value between 1 and 100. +Instead, we can make a new type in a dedicated module and put the validations in +a function to create an instance of the type rather than repeating the +validations everywhere. That way, it’s safe for functions to use the new type in +their signatures and confidently use the values they receive. Listing 9-13 shows +one way to define a `Guess` type that will only create an instance of `Guess` if +the `new` function receives a value between 1 and 100. -+ ```rust -{{#rustdoc_include ../listings/ch09-error-handling/listing-09-13/src/lib.rs}} +{{#rustdoc_include ../listings/ch09-error-handling/listing-09-13/src/guessing_game.rs}} ``` -First we define a struct named `Guess` that has a field named `value` that -holds an `i32`. This is where the number will be stored. +First we create a new module named `guessing_game`. Next we define a struct in +that module named `Guess` that has a field named `value` that holds an `i32`. +This is where the number will be stored. Then we implement an associated function named `new` on `Guess` that creates instances of `Guess` values. The `new` function is defined to have one @@ -197,9 +198,9 @@ a _getter_ because its purpose is to get some data from its fields and return it. This public method is necessary because the `value` field of the `Guess` struct is private. It’s important that the `value` field be private so code using the `Guess` struct is not allowed to set `value` directly: code outside -the module _must_ use the `Guess::new` function to create an instance of -`Guess`, thereby ensuring there’s no way for a `Guess` to have a `value` that -hasn’t been checked by the conditions in the `Guess::new` function. +the `guessing_game` module _must_ use the `Guess::new` function to create an +instance of `Guess`, thereby ensuring there’s no way for a `Guess` to have a +`value` that hasn’t been checked by the conditions in the `Guess::new` function. A function that has a parameter or returns only numbers between 1 and 100 could then declare in its signature that it takes or returns a `Guess` rather than an diff --git a/rustbook-en/src/ch10-01-syntax.md b/rustbook-en/src/ch10-01-syntax.md index 66384442..c064094a 100644 --- a/rustbook-en/src/ch10-01-syntax.md +++ b/rustbook-en/src/ch10-01-syntax.md @@ -55,7 +55,7 @@ same type `T`. Listing 10-5 shows the combined `largest` function definition using the generic data type in its signature. The listing also shows how we can call the function with either a slice of `i32` values or `char` values. Note that this code won’t -compile yet, but we’ll fix it later in this chapter. +compile yet. @@ -77,10 +77,10 @@ states that the body of `largest` won’t work for all possible types that `T` could be. Because we want to compare values of type `T` in the body, we can only use types whose values can be ordered. To enable comparisons, the standard library has the `std::cmp::PartialOrd` trait that you can implement on types -(see Appendix C for more on this trait). By following the help text’s -suggestion, we restrict the types valid for `T` to only those that implement -`PartialOrd` and this example will compile, because the standard library -implements `PartialOrd` on both `i32` and `char`. +(see Appendix C for more on this trait). To fix the example code above, we would +need to follow the help text's suggestions and restrict the types valid for `T` +to only those that implement `PartialOrd`. The example would then compile, because +the standard library implements `PartialOrd` on both `i32` and `char`. ### In Struct Definitions diff --git a/rustbook-en/src/ch17-03-more-futures.md b/rustbook-en/src/ch17-03-more-futures.md index d3c3aa87..6e01a355 100644 --- a/rustbook-en/src/ch17-03-more-futures.md +++ b/rustbook-en/src/ch17-03-more-futures.md @@ -196,9 +196,9 @@ tell us that the first async block (`src/main.rs:8:23: 20:10`) does not implement the `Unpin` trait and suggests using `pin!` or `Box::pin` to resolve it. Later in the chapter, we’ll dig into a few more details about `Pin` and `Unpin`. For the moment, though, we can just follow the compiler’s advice to get -unstuck. In Listing 17-18, we start by updating the type annotation for -`futures`, with a `Pin` wrapping each `Box`. Second, we use `Box::pin` to pin -the futures themselves. +unstuck. In Listing 17-18, we start by importing `Pin` from `std::pin`. Next we +update the type annotation for `futures`, with a `Pin` wrapping each `Box`. +Finally, we use `Box::pin` to pin the futures themselves. @@ -238,9 +238,10 @@ future, using the `std::pin::pin` macro. However, we must still be explicit about the type of the pinned reference; otherwise, Rust will still not know to interpret these as dynamic trait objects, -which is what we need them to be in the `Vec`. We therefore `pin!` each future -when we define it, and define `futures` as a `Vec` containing pinned mutable -references to the dynamic future type, as in Listing 17-19. +which is what we need them to be in the `Vec`. We therefore add `pin` to our +list of imports from `std::pin`. Then we can `pin!` each future when we define +it and define `futures` as a `Vec` containing pinned mutable references to the +dynamic future type, as in Listing 17-19. diff --git a/rustbook-en/src/ch18-03-oo-design-patterns.md b/rustbook-en/src/ch18-03-oo-design-patterns.md index 34fea1f0..a689a6ab 100644 --- a/rustbook-en/src/ch18-03-oo-design-patterns.md +++ b/rustbook-en/src/ch18-03-oo-design-patterns.md @@ -359,11 +359,12 @@ known at compile time. (This is one of the dyn compatibility rules mentioned earlier.) Other duplication includes the similar implementations of the `request_review` -and `approve` methods on `Post`. Both methods delegate to the implementation of -the same method on the value in the `state` field of `Option` and set the new -value of the `state` field to the result. If we had a lot of methods on `Post` -that followed this pattern, we might consider defining a macro to eliminate the -repetition (see [“Macros”][macros] in Chapter 20). +and `approve` methods on `Post`. Both methods use `Option::take` with the +`state` field of `Post`, and if `state` is `Some`, they delegate to the wrapped +value’s implementation of the same method and set the new value of the `state` +field to the result. If we had a lot of methods on `Post` that followed this +pattern, we might consider defining a macro to eliminate the repetition (see +[“Macros”][macros] in Chapter 20). By implementing the state pattern exactly as it’s defined for object-oriented languages, we’re not taking as full advantage of Rust’s strengths as we could. diff --git a/rustbook-en/src/ch20-01-unsafe-rust.md b/rustbook-en/src/ch20-01-unsafe-rust.md index f9de46a5..99f689ad 100644 --- a/rustbook-en/src/ch20-01-unsafe-rust.md +++ b/rustbook-en/src/ch20-01-unsafe-rust.md @@ -329,7 +329,8 @@ Within the `unsafe extern "C"` block, we list the names and signatures of external functions from another language we want to call. The `"C"` part defines which _application binary interface (ABI)_ the external function uses: the ABI defines how to call the function at the assembly level. The `"C"` ABI is the -most common and follows the C programming language’s ABI. +most common and follows the C programming language’s ABI. Information about all +the ABIs Rust supports is available in [the Rust Reference][ABI]. Every item declared within an `unsafe extern` block is implicitly `unsafe`. However, some FFI functions *are* safe to call. For example, the `abs` function @@ -486,7 +487,7 @@ The final action that works only with `unsafe` is accessing fields of a union. A particular instance at one time. Unions are primarily used to interface with unions in C code. Accessing union fields is unsafe because Rust can’t guarantee the type of the data currently being stored in the union instance. You can learn -more about unions in [the Rust Reference][reference]. +more about unions in [the Rust Reference][unions]. ### Using Miri to Check Unsafe Code @@ -548,10 +549,11 @@ For a much deeper exploration of how to work effectively with unsafe Rust, read Rust’s official guide to the subject, the [Rustonomicon][nomicon]. [dangling-references]: ch04-02-references-and-borrowing.html#dangling-references +[ABI]: ../reference/items/external-blocks.html#abi [differences-between-variables-and-constants]: ch03-01-variables-and-mutability.html#constants [extensible-concurrency-with-the-sync-and-send-traits]: ch16-04-extensible-concurrency-sync-and-send.html#extensible-concurrency-with-the-sync-and-send-traits [the-slice-type]: ch04-03-slices.html#the-slice-type -[reference]: ../reference/items/unions.html +[unions]: ../reference/items/unions.html [miri]: https://github.com/rust-lang/miri [editions]: appendix-05-editions.html [nightly]: appendix-07-nightly-rust.html