diff --git a/src/ch15-01-box.md b/src/ch15-01-box.md index bc16c2504f..548152b5ca 100644 --- a/src/ch15-01-box.md +++ b/src/ch15-01-box.md @@ -35,14 +35,13 @@ syntax and how to interact with values stored within a `Box`. Listing 15-1 shows how to use a box to store an `i32` value on the heap: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-01/src/main.rs}} ``` -Listing 15-1: Storing an `i32` value on the heap using a -box + We define the variable `b` to have the value of a `Box` that points to the value `5`, which is allocated on the heap. This program will print `b = 5`; in @@ -106,14 +105,13 @@ Listing 15-2 contains an enum definition for a cons list. Note that this code won’t compile yet because the `List` type doesn’t have a known size, which we’ll demonstrate. -Filename: src/main.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-02/src/main.rs:here}} ``` -Listing 15-2: The first attempt at defining an enum to -represent a cons list data structure of `i32` values + > Note: We’re implementing a cons list that holds only `i32` values for the > purposes of this example. We could have implemented it using generics, as we @@ -123,14 +121,13 @@ represent a cons list data structure of `i32` values Using the `List` type to store the list `1, 2, 3` would look like the code in Listing 15-3: -Filename: src/main.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-03/src/main.rs:here}} ``` -Listing 15-3: Using the `List` enum to store the list `1, -2, 3` + The first `Cons` value holds `1` and another `List` value. This `List` value is another `Cons` value that holds `2` and another `List` value. This `List` value @@ -140,12 +137,13 @@ is one more `Cons` value that holds `3` and a `List` value, which is finally If we try to compile the code in Listing 15-3, we get the error shown in Listing 15-4: ++ ```console {{#include ../listings/ch15-smart-pointers/listing-15-03/output.txt}} ``` -Listing 15-4: The error we get when attempting to define -a recursive enum + The error shows this type “has infinite size.” The reason is that we’ve defined `List` with a variant that is recursive: it holds another value of itself @@ -215,14 +213,13 @@ rather than inside one another. We can change the definition of the `List` enum in Listing 15-2 and the usage of the `List` in Listing 15-3 to the code in Listing 15-5, which will compile: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-05/src/main.rs}} ``` -Listing 15-5: Definition of `List` that uses `Box` in -order to have a known size + The `Cons` variant needs the size of an `i32` plus the space to store the box’s pointer data. The `Nil` variant stores no values, so it needs less space diff --git a/src/ch15-02-deref.md b/src/ch15-02-deref.md index 5017fca434..449e472dcd 100644 --- a/src/ch15-02-deref.md +++ b/src/ch15-02-deref.md @@ -29,14 +29,13 @@ as an arrow to a value stored somewhere else. In Listing 15-6, we create a reference to an `i32` value and then use the dereference operator to follow the reference to the value: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-06/src/main.rs}} ``` -Listing 15-6: Using the dereference operator to follow a -reference to an `i32` value + The variable `x` holds an `i32` value `5`. We set `y` equal to a reference to `x`. We can assert that `x` is equal to `5`. However, if we want to make an @@ -63,14 +62,13 @@ reference; the dereference operator used on the `Box` in Listing 15-7 functions in the same way as the dereference operator used on the reference in Listing 15-6: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-07/src/main.rs}} ``` -Listing 15-7: Using the dereference operator on a -`Box` + The main difference between Listing 15-7 and Listing 15-6 is that here we set `y` to be an instance of a `Box` pointing to a copied value of `x` rather @@ -91,13 +89,13 @@ The `Box` type is ultimately defined as a tuple struct with one element, so Listing 15-8 defines a `MyBox` type in the same way. We’ll also define a `new` function to match the `new` function defined on `Box`. -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-08/src/main.rs:here}} ``` -Listing 15-8: Defining a `MyBox` type + We define a struct named `MyBox` and declare a generic parameter `T`, because we want our type to hold values of any type. The `MyBox` type is a tuple struct @@ -109,14 +107,13 @@ changing it to use the `MyBox` type we’ve defined instead of `Box`. The code in Listing 15-9 won’t compile because Rust doesn’t know how to dereference `MyBox`. -Filename: src/main.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-09/src/main.rs:here}} ``` -Listing 15-9: Attempting to use `MyBox` in the same -way we used references and `Box` + Here’s the resulting compilation error: @@ -137,13 +134,13 @@ by the standard library, requires us to implement one method named `deref` that borrows `self` and returns a reference to the inner data. Listing 15-10 contains an implementation of `Deref` to add to the definition of `MyBox`: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-10/src/main.rs:here}} ``` -Listing 15-10: Implementing `Deref` on `MyBox` + The `type Target = T;` syntax defines an associated type for the `Deref` trait to use. Associated types are a slightly different way of declaring a @@ -210,27 +207,25 @@ Listing 15-8 as well as the implementation of `Deref` that we added in Listing 15-10. Listing 15-11 shows the definition of a function that has a string slice parameter: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-11/src/main.rs:here}} ``` -Listing 15-11: A `hello` function that has the parameter -`name` of type `&str` + We can call the `hello` function with a string slice as an argument, such as `hello("Rust");` for example. Deref coercion makes it possible to call `hello` with a reference to a value of type `MyBox`, as shown in Listing 15-12: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-12/src/main.rs:here}} ``` -Listing 15-12: Calling `hello` with a reference to a -`MyBox` value, which works because of deref coercion + Here we’re calling the `hello` function with the argument `&m`, which is a reference to a `MyBox` value. Because we implemented the `Deref` trait @@ -244,14 +239,13 @@ If Rust didn’t implement deref coercion, we would have to write the code in Listing 15-13 instead of the code in Listing 15-12 to call `hello` with a value of type `&MyBox`. -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-13/src/main.rs:here}} ``` -Listing 15-13: The code we would have to write if Rust -didn’t have deref coercion + The `(*m)` dereferences the `MyBox` into a `String`. Then the `&` and `[..]` take a string slice of the `String` that is equal to the whole string to diff --git a/src/ch15-03-drop.md b/src/ch15-03-drop.md index 05ab86873b..8c402f408f 100644 --- a/src/ch15-03-drop.md +++ b/src/ch15-03-drop.md @@ -28,14 +28,13 @@ Listing 15-14 shows a `CustomSmartPointer` struct whose only custom functionality is that it will print `Dropping CustomSmartPointer!` when the instance goes out of scope, to show when Rust runs the `drop` function. -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-14/src/main.rs}} ``` -Listing 15-14: A `CustomSmartPointer` struct that -implements the `Drop` trait where we would put our cleanup code + The `Drop` trait is included in the prelude, so we don’t need to bring it into scope. We implement the `Drop` trait on `CustomSmartPointer` and provide an @@ -79,14 +78,13 @@ If we try to call the `Drop` trait’s `drop` method manually by modifying the `main` function from Listing 15-14, as shown in Listing 15-15, we’ll get a compiler error: -Filename: src/main.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-15/src/main.rs:here}} ``` -Listing 15-15: Attempting to call the `drop` method from -the `Drop` trait manually to clean up early + When we try to compile this code, we’ll get this error: @@ -114,14 +112,13 @@ trait. We call it by passing as an argument the value we want to force drop. The function is in the prelude, so we can modify `main` in Listing 15-15 to call the `drop` function, as shown in Listing 15-16: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-16/src/main.rs:here}} ``` -Listing 15-16: Calling `std::mem::drop` to explicitly -drop a value before it goes out of scope + Running this code will print the following: diff --git a/src/ch15-04-rc.md b/src/ch15-04-rc.md index 87a42eb1a5..c5bf9a4897 100644 --- a/src/ch15-04-rc.md +++ b/src/ch15-04-rc.md @@ -48,14 +48,13 @@ words, both lists will share the first list containing 5 and 10. Trying to implement this scenario using our definition of `List` with `Box` won’t work, as shown in Listing 15-17: -Filename: src/main.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-17/src/main.rs}} ``` -Listing 15-17: Demonstrating we’re not allowed to have -two lists using `Box` that try to share ownership of a third list + When we compile this code, we get this error: @@ -84,14 +83,13 @@ we call `Rc::clone`, the reference count to the data within the `Rc` will increase, and the data won’t be cleaned up unless there are zero references to it. -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-18/src/main.rs}} ``` -Listing 15-18: A definition of `List` that uses -`Rc` + We need to add a `use` statement to bring `Rc` into scope because it’s not in the prelude. In `main`, we create the list holding 5 and 10 and store it in @@ -118,13 +116,13 @@ counts changing as we create and drop references to the `Rc` in `a`. In Listing 15-19, we’ll change `main` so it has an inner scope around list `c`; then we can see how the reference count changes when `c` goes out of scope. -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-19/src/main.rs:here}} ``` -Listing 15-19: Printing the reference count + At each point in the program where the reference count changes, we print the reference count, which we get by calling the `Rc::strong_count` function. This diff --git a/src/ch15-05-interior-mutability.md b/src/ch15-05-interior-mutability.md index 4c7d3c4f66..5b103dc0bf 100644 --- a/src/ch15-05-interior-mutability.md +++ b/src/ch15-05-interior-mutability.md @@ -129,14 +129,13 @@ email, send a text message, or something else. The library doesn’t need to kno that detail. All it needs is something that implements a trait we’ll provide called `Messenger`. Listing 15-20 shows the library code: -Filename: src/lib.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-20/src/lib.rs}} ``` -Listing 15-20: A library to keep track of how close a -value is to a maximum value and warn when the value is at certain levels + One important part of this code is that the `Messenger` trait has one method called `send` that takes an immutable reference to `self` and the text of the @@ -156,14 +155,13 @@ mock object, call the `set_value` method on `LimitTracker`, and then check that the mock object has the messages we expect. Listing 15-21 shows an attempt to implement a mock object to do just that, but the borrow checker won’t allow it: -Filename: src/lib.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-21/src/lib.rs:here}} ``` -Listing 15-21: An attempt to implement a `MockMessenger` -that isn’t allowed by the borrow checker + This test code defines a `MockMessenger` struct that has a `sent_messages` field with a `Vec` of `String` values to keep track of the messages it’s told @@ -200,14 +198,13 @@ This is a situation in which interior mutability can help! We’ll store the able to modify `sent_messages` to store the messages we’ve seen. Listing 15-22 shows what that looks like: -Filename: src/lib.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-22/src/lib.rs:here}} ``` -Listing 15-22: Using `RefCell` to mutate an inner -value while the outer value is considered immutable + The `sent_messages` field is now of type `RefCell>` instead of `Vec`. In the `new` function, we create a new `RefCell>` @@ -249,14 +246,13 @@ Listing 15-22. We’re deliberately trying to create two mutable borrows active for the same scope to illustrate that `RefCell` prevents us from doing this at runtime. -Filename: src/lib.rs + ```rust,ignore,panics {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-23/src/lib.rs:here}} ``` -Listing 15-23: Creating two mutable references in the -same scope to see that `RefCell` will panic + We create a variable `one_borrow` for the `RefMut` smart pointer returned from `borrow_mut`. Then we create another mutable borrow in the same way in the @@ -298,14 +294,13 @@ change the values in the lists. Listing 15-24 shows that by using a `RefCell` in the `Cons` definition, we can modify the value stored in all the lists: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-24/src/main.rs}} ``` -Listing 15-24: Using `Rc>` to create a -`List` that we can mutate + We create a value that is an instance of `Rc>` and store it in a variable named `value` so we can access it directly later. Then we create a diff --git a/src/ch15-06-reference-cycles.md b/src/ch15-06-reference-cycles.md index beb2bc2169..2ea12edb6f 100644 --- a/src/ch15-06-reference-cycles.md +++ b/src/ch15-06-reference-cycles.md @@ -15,14 +15,13 @@ Let’s look at how a reference cycle might happen and how to prevent it, starting with the definition of the `List` enum and a `tail` method in Listing 15-25: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-25/src/main.rs}} ``` -Listing 15-25: A cons list definition that holds a -`RefCell` so we can modify what a `Cons` variant is referring to + We’re using another variation of the `List` definition from Listing 15-5. The second element in the `Cons` variant is now `RefCell>`, meaning that @@ -37,14 +36,13 @@ the list in `a`. Then it modifies the list in `a` to point to `b`, creating a reference cycle. There are `println!` statements along the way to show what the reference counts are at various points in this process. -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-26/src/main.rs:here}} ``` -Listing 15-26: Creating a reference cycle of two `List` -values pointing to each other + We create an `Rc` instance holding a `List` value in the variable `a` with an initial list of `5, Nil`. We then create an `Rc` instance holding @@ -163,14 +161,13 @@ Next, we’ll use our struct definition and create one `Node` instance named `leaf` with the value 3 and no children, and another instance named `branch` with the value 5 and `leaf` as one of its children, as shown in Listing 15-27: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-27/src/main.rs:there}} ``` -Listing 15-27: Creating a `leaf` node with no children -and a `branch` node with `leaf` as one of its children + We clone the `Rc` in `leaf` and store that in `branch`, meaning the `Node` in `leaf` now has two owners: `leaf` and `branch`. We can get from @@ -207,14 +204,13 @@ A node will be able to refer to its parent node but doesn’t own its parent. In Listing 15-28, we update `main` to use this new definition so the `leaf` node will have a way to refer to its parent, `branch`: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-28/src/main.rs:there}} ``` -Listing 15-28: A `leaf` node with a weak reference to its -parent node `branch` + Creating the `leaf` node looks similar to Listing 15-27 with the exception of the `parent` field: `leaf` starts out without a parent, so we create a new, @@ -260,14 +256,13 @@ instances change by creating a new inner scope and moving the creation of created and then dropped when it goes out of scope. The modifications are shown in Listing 15-29: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch15-smart-pointers/listing-15-29/src/main.rs:here}} ``` -Listing 15-29: Creating `branch` in an inner scope and -examining strong and weak reference counts + After `leaf` is created, its `Rc` has a strong count of 1 and a weak count of 0. In the inner scope, we create `branch` and associate it with