From 5824abce2daff08d989d959a3a00770b6424bae3 Mon Sep 17 00:00:00 2001 From: funkill2 Date: Sat, 15 Jun 2024 04:00:14 +0300 Subject: [PATCH] update original --- ...h12-01-accepting-command-line-arguments.md | 10 ++-- rustbook-en/src/ch12-02-reading-a-file.md | 10 ++-- ...improving-error-handling-and-modularity.md | 50 ++++++++----------- ...2-04-testing-the-librarys-functionality.md | 25 ++++------ ...2-05-working-with-environment-variables.md | 20 +++----- ...-06-writing-to-stderr-instead-of-stdout.md | 5 +- rustbook-en/src/ch13-01-closures.md | 44 +++++++--------- rustbook-en/src/ch13-02-iterators.md | 34 ++++++------- .../src/ch13-03-improving-our-io-project.md | 30 +++++------ .../src/ch14-02-publishing-to-crates-io.md | 30 +++++------ rustbook-en/src/ch14-03-cargo-workspaces.md | 5 +- 11 files changed, 108 insertions(+), 155 deletions(-) diff --git a/rustbook-en/src/ch12-01-accepting-command-line-arguments.md b/rustbook-en/src/ch12-01-accepting-command-line-arguments.md index bb6936663..9dc28209b 100644 --- a/rustbook-en/src/ch12-01-accepting-command-line-arguments.md +++ b/rustbook-en/src/ch12-01-accepting-command-line-arguments.md @@ -39,14 +39,13 @@ the iterator produces. The code in Listing 12-1 allows your `minigrep` program to read any command line arguments passed to it and then collect the values into a vector. -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-01/src/main.rs}} ``` -Listing 12-1: Collecting the command line arguments into -a vector and printing them + First, we bring the `std::env` module into scope with a `use` statement so we can use its `args` function. Notice that the `std::env::args` function is @@ -101,14 +100,13 @@ arguments. Now we need to save the values of the two arguments in variables so we can use the values throughout the rest of the program. We do that in Listing 12-2. -Filename: src/main.rs + ```rust,should_panic,noplayground {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-02/src/main.rs}} ``` -Listing 12-2: Creating variables to hold the query -argument and file path argument + As we saw when we printed the vector, the program’s name takes up the first value in the vector at `args[0]`, so we’re starting arguments at index `1`. The diff --git a/rustbook-en/src/ch12-02-reading-a-file.md b/rustbook-en/src/ch12-02-reading-a-file.md index d8340a2a0..910850b06 100644 --- a/rustbook-en/src/ch12-02-reading-a-file.md +++ b/rustbook-en/src/ch12-02-reading-a-file.md @@ -7,26 +7,24 @@ has an Emily Dickinson poem that will work well! Create a file called *poem.txt* at the root level of your project, and enter the poem “I’m Nobody! Who are you?” -Filename: poem.txt + ```text {{#include ../listings/ch12-an-io-project/listing-12-03/poem.txt}} ``` -Listing 12-3: A poem by Emily Dickinson makes a good test -case + With the text in place, edit *src/main.rs* and add code to read the file, as shown in Listing 12-4. -Filename: src/main.rs + ```rust,should_panic,noplayground {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-04/src/main.rs:here}} ``` -Listing 12-4: Reading the contents of the file specified -by the second argument + First, we bring in a relevant part of the standard library with a `use` statement: we need `std::fs` to handle files. diff --git a/rustbook-en/src/ch12-03-improving-error-handling-and-modularity.md b/rustbook-en/src/ch12-03-improving-error-handling-and-modularity.md index 1b67d63d6..0de3ec2c2 100644 --- a/rustbook-en/src/ch12-03-improving-error-handling-and-modularity.md +++ b/rustbook-en/src/ch12-03-improving-error-handling-and-modularity.md @@ -70,14 +70,13 @@ We’ll extract the functionality for parsing arguments into a function that *src/lib.rs*. Listing 12-5 shows the new start of `main` that calls a new function `parse_config`, which we’ll define in *src/main.rs* for the moment. -Filename: src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-05/src/main.rs:here}} ``` -Listing 12-5: Extracting a `parse_config` function from -`main` + We’re still collecting the command line arguments into a vector, but instead of assigning the argument value at index 1 to the variable `query` and the @@ -112,14 +111,13 @@ other and what their purpose is. Listing 12-6 shows the improvements to the `parse_config` function. -Filename: src/main.rs + ```rust,should_panic,noplayground {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-06/src/main.rs:here}} ``` -Listing 12-6: Refactoring `parse_config` to return an -instance of a `Config` struct + We’ve added a struct named `Config` defined to have fields named `query` and `file_path`. The signature of `parse_config` now indicates that it returns a @@ -179,14 +177,13 @@ changing `parse_config` into a `new` function associated with `Config`, we’ll be able to create instances of `Config` by calling `Config::new`. Listing 12-7 shows the changes we need to make. -Filename: src/main.rs + ```rust,should_panic,noplayground {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-07/src/main.rs:here}} ``` -Listing 12-7: Changing `parse_config` into -`Config::new` + We’ve updated `main` where we were calling `parse_config` to instead call `Config::new`. We’ve changed the name of `parse_config` to `new` and moved it @@ -214,14 +211,13 @@ In Listing 12-8, we add a check in the `new` function that will verify that the slice is long enough before accessing index 1 and 2. If the slice isn’t long enough, the program panics and displays a better error message. -Filename: src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-08/src/main.rs:here}} ``` -Listing 12-8: Adding a check for the number of -arguments + This code is similar to [the `Guess::new` function we wrote in Listing 9-13][ch9-custom-types], where we called `panic!` when the @@ -265,14 +261,13 @@ function we’re now calling `Config::build` and the body of the function needed to return a `Result`. Note that this won’t compile until we update `main` as well, which we’ll do in the next listing. -Filename: src/main.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-09/src/main.rs:here}} ``` -Listing 12-9: Returning a `Result` from -`Config::build` + Our `build` function returns a `Result` with a `Config` instance in the success case and a `&'static str` in the error case. Our error values will always be @@ -299,14 +294,13 @@ tool with a nonzero error code away from `panic!` and instead implement it by hand. A nonzero exit status is a convention to signal to the process that called our program that the program exited with an error state. -Filename: src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-10/src/main.rs:here}} ``` -Listing 12-10: Exiting with an error code if building a -`Config` fails + In this listing, we’ve used a method we haven’t covered in detail yet: `unwrap_or_else`, which is defined on `Result` by the standard library. @@ -350,14 +344,13 @@ Listing 12-11 shows the extracted `run` function. For now, we’re just making the small, incremental improvement of extracting the function. We’re still defining the function in *src/main.rs*. -Filename: src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-11/src/main.rs:here}} ``` -Listing 12-11: Extracting a `run` function containing the -rest of the program logic + The `run` function now contains all the remaining logic from `main`, starting from reading the file. The `run` function takes the `Config` instance as an @@ -373,14 +366,13 @@ us further consolidate the logic around handling errors into `main` in a user-friendly way. Listing 12-12 shows the changes we need to make to the signature and body of `run`. -Filename: src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-12/src/main.rs:here}} ``` -Listing 12-12: Changing the `run` function to return -`Result` + We’ve made three significant changes here. First, we changed the return type of the `run` function to `Result<(), Box>`. This function previously @@ -458,14 +450,13 @@ The contents of *src/lib.rs* should have the signatures shown in Listing 12-13 (we’ve omitted the bodies of the functions for brevity). Note that this won’t compile until we modify *src/main.rs* in Listing 12-14. -Filename: src/lib.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-13/src/lib.rs:here}} ``` -Listing 12-13: Moving `Config` and `run` into -*src/lib.rs* + We’ve made liberal use of the `pub` keyword: on `Config`, on its fields and its `build` method, and on the `run` function. We now have a library crate that has @@ -474,14 +465,13 @@ a public API we can test! Now we need to bring the code we moved to *src/lib.rs* into the scope of the binary crate in *src/main.rs*, as shown in Listing 12-14. -Filename: src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-14/src/main.rs:here}} ``` -Listing 12-14: Using the `minigrep` library crate in -*src/main.rs* + We add a `use minigrep::Config` line to bring the `Config` type from the library crate into the binary crate’s scope, and we prefix the `run` function diff --git a/rustbook-en/src/ch12-04-testing-the-librarys-functionality.md b/rustbook-en/src/ch12-04-testing-the-librarys-functionality.md index 129f835aa..c4a435bc0 100644 --- a/rustbook-en/src/ch12-04-testing-the-librarys-functionality.md +++ b/rustbook-en/src/ch12-04-testing-the-librarys-functionality.md @@ -35,14 +35,13 @@ behavior we want the `search` function to have: it will take a query and the text to search, and it will return only the lines from the text that contain the query. Listing 12-15 shows this test, which won’t compile yet. -Filename: src/lib.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-15/src/lib.rs:here}} ``` -Listing 12-15: Creating a failing test for the `search` -function we wish we had + This test searches for the string `"duct"`. The text we’re searching is three lines, only one of which contains `"duct"` (Note that the backslash after the @@ -58,14 +57,13 @@ vector, as shown in Listing 12-16. Then the test should compile and fail because an empty vector doesn’t match a vector containing the line `"safe, fast, productive."` -Filename: src/lib.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-16/src/lib.rs:here}} ``` -Listing 12-16: Defining just enough of the `search` -function so our test will compile + Notice that we need to define an explicit lifetime `'a` in the signature of `search` and use that lifetime with the `contents` argument and the return @@ -128,14 +126,13 @@ Rust has a helpful method to handle line-by-line iteration of strings, conveniently named `lines`, that works as shown in Listing 12-17. Note this won’t compile yet. -Filename: src/lib.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-17/src/lib.rs:here}} ``` -Listing 12-17: Iterating through each line in `contents` - + The `lines` method returns an iterator. We’ll talk about iterators in depth in [Chapter 13][ch13-iterators], but recall that you saw this way @@ -149,14 +146,13 @@ Fortunately, strings have a helpful method named `contains` that does this for us! Add a call to the `contains` method in the `search` function, as shown in Listing 12-18. Note this still won’t compile yet. -Filename: src/lib.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-18/src/lib.rs:here}} ``` -Listing 12-18: Adding functionality to see whether the -line contains the string in `query` + At the moment, we’re building up functionality. To get it to compile, we need to return a value from the body as we indicated we would in the function @@ -169,14 +165,13 @@ to return. For that, we can make a mutable vector before the `for` loop and call the `push` method to store a `line` in the vector. After the `for` loop, we return the vector, as shown in Listing 12-19. -Filename: src/lib.rs + ```rust,ignore {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-19/src/lib.rs:here}} ``` -Listing 12-19: Storing the lines that match so we can -return them + Now the `search` function should return only the lines that contain `query`, and our test should pass. Let’s run the test: diff --git a/rustbook-en/src/ch12-05-working-with-environment-variables.md b/rustbook-en/src/ch12-05-working-with-environment-variables.md index 263c80cd0..f050b5b47 100644 --- a/rustbook-en/src/ch12-05-working-with-environment-variables.md +++ b/rustbook-en/src/ch12-05-working-with-environment-variables.md @@ -16,14 +16,13 @@ the new `search_case_insensitive` function and rename our old test from `one_result` to `case_sensitive` to clarify the differences between the two tests, as shown in Listing 12-20. -Filename: src/lib.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-20/src/lib.rs:here}} ``` -Listing 12-20: Adding a new failing test for the -case-insensitive function we’re about to add + Note that we’ve edited the old test’s `contents` too. We’ve added a new line with the text `"Duct tape."` using a capital D that shouldn’t match the query @@ -48,14 +47,13 @@ the same as the `search` function. The only difference is that we’ll lowercase the `query` and each `line` so whatever the case of the input arguments, they’ll be the same case when we check whether the line contains the query. -Filename: src/lib.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-21/src/lib.rs:here}} ``` -Listing 12-21: Defining the `search_case_insensitive` -function to lowercase the query and the line before comparing them + First, we lowercase the `query` string and store it in a shadowed variable with the same name. Calling `to_lowercase` on the query is necessary so no @@ -101,14 +99,13 @@ function to check the `ignore_case` field’s value and use that to decide whether to call the `search` function or the `search_case_insensitive` function, as shown in Listing 12-22. This still won’t compile yet. -Filename: src/lib.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-22/src/lib.rs:there}} ``` -Listing 12-22: Calling either `search` or -`search_case_insensitive` based on the value in `config.ignore_case` + Finally, we need to check for the environment variable. The functions for working with environment variables are in the `env` module in the standard @@ -117,14 +114,13 @@ we’ll use the `var` function from the `env` module to check if any value has been set for an environment variable named `IGNORE_CASE`, as shown in Listing 12-23. -Filename: src/lib.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-23/src/lib.rs:here}} ``` -Listing 12-23: Checking for any value in an environment -variable named `IGNORE_CASE` + Here, we create a new variable `ignore_case`. To set its value, we call the `env::var` function and pass it the name of the `IGNORE_CASE` environment diff --git a/rustbook-en/src/ch12-06-writing-to-stderr-instead-of-stdout.md b/rustbook-en/src/ch12-06-writing-to-stderr-instead-of-stdout.md index d017fa324..99e50e6f0 100644 --- a/rustbook-en/src/ch12-06-writing-to-stderr-instead-of-stdout.md +++ b/rustbook-en/src/ch12-06-writing-to-stderr-instead-of-stdout.md @@ -54,14 +54,13 @@ the `eprintln!` macro that prints to the standard error stream, so let’s chang the two places we were calling `println!` to print errors to use `eprintln!` instead. -Filename: src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-24/src/main.rs:here}} ``` -Listing 12-24: Writing error messages to standard error -instead of standard output using `eprintln!` + Let’s now run the program again in the same way, without any arguments and redirecting standard output with `>`: diff --git a/rustbook-en/src/ch13-01-closures.md b/rustbook-en/src/ch13-01-closures.md index a1e1cec80..1983fbdac 100644 --- a/rustbook-en/src/ch13-01-closures.md +++ b/rustbook-en/src/ch13-01-closures.md @@ -35,13 +35,13 @@ The method `giveaway` defined on `Inventory` gets the optional shirt color preference of the free shirt winner, and returns the shirt color the person will get. This setup is shown in Listing 13-1: -Filename: src/main.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch13-functional-features/listing-13-01/src/main.rs}} ``` -Listing 13-1: Shirt company giveaway situation + The `store` defined in `main` has two blue shirts and one red shirt remaining to distribute for this limited-edition promotion. We call the `giveaway` method @@ -105,14 +105,13 @@ shown in Listing 13-2. In this example, we’re defining a closure and storing i in a variable rather than defining the closure in the spot we pass it as an argument as we did in Listing 13-1. -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch13-functional-features/listing-13-02/src/main.rs:here}} ``` -Listing 13-2: Adding optional type annotations of the -parameter and return value types in the closure + With type annotations added, the syntax of closures looks more similar to the syntax of functions. Here we define a function that adds 1 to its parameter and @@ -147,14 +146,13 @@ Because there are no type annotations, we can call the closure with any type, which we’ve done here with `String` the first time. If we then try to call `example_closure` with an integer, we’ll get an error. -Filename: src/main.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch13-functional-features/listing-13-03/src/main.rs:here}} ``` -Listing 13-3: Attempting to call a closure whose types -are inferred with two different types + The compiler gives us this error: @@ -179,14 +177,13 @@ In Listing 13-4, we define a closure that captures an immutable reference to the vector named `list` because it only needs an immutable reference to print the value: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch13-functional-features/listing-13-04/src/main.rs}} ``` -Listing 13-4: Defining and calling a closure that -captures an immutable reference + This example also illustrates that a variable can bind to a closure definition, and we can later call the closure by using the variable name and parentheses as @@ -204,14 +201,13 @@ is called. This code compiles, runs, and prints: Next, in Listing 13-5, we change the closure body so that it adds an element to the `list` vector. The closure now captures a mutable reference: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch13-functional-features/listing-13-05/src/main.rs}} ``` -Listing 13-5: Defining and calling a closure that -captures a mutable reference + This code compiles, runs, and prints: @@ -238,14 +234,13 @@ concurrency, but for now, let’s briefly explore spawning a new thread using a closure that needs the `move` keyword. Listing 13-6 shows Listing 13-4 modified to print the vector in a new thread rather than in the main thread: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch13-functional-features/listing-13-06/src/main.rs}} ``` -Listing 13-6: Using `move` to force the closure for the -thread to take ownership of `list` + We spawn a new thread, giving the thread a closure to run as an argument. The closure body prints out the list. In Listing 13-4, the closure only captured @@ -348,14 +343,13 @@ when you want to sort a slice by a particular attribute of each item. In Listing 13-7, we have a list of `Rectangle` instances and we use `sort_by_key` to order them by their `width` attribute from low to high: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch13-functional-features/listing-13-07/src/main.rs}} ``` -Listing 13-7: Using `sort_by_key` to order rectangles by -width + This code prints: @@ -372,14 +366,13 @@ In contrast, Listing 13-8 shows an example of a closure that implements just the `FnOnce` trait, because it moves a value out of the environment. The compiler won’t let us use this closure with `sort_by_key`: -Filename: src/main.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch13-functional-features/listing-13-08/src/main.rs}} ``` -Listing 13-8: Attempting to use an `FnOnce` closure with -`sort_by_key` + This is a contrived, convoluted way (that doesn’t work) to try and count the number of times `sort_by_key` calls the closure when sorting `list`. This code @@ -406,14 +399,13 @@ in Listing 13-9 works with `sort_by_key` because it is only capturing a mutable reference to the `num_sort_operations` counter and can therefore be called more than once: -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch13-functional-features/listing-13-09/src/main.rs}} ``` -Listing 13-9: Using an `FnMut` closure with `sort_by_key` -is allowed + The `Fn` traits are important when defining or using functions or types that make use of closures. In the next section, we’ll discuss iterators. Many diff --git a/rustbook-en/src/ch13-02-iterators.md b/rustbook-en/src/ch13-02-iterators.md index 030ebf48e..c99fcd699 100644 --- a/rustbook-en/src/ch13-02-iterators.md +++ b/rustbook-en/src/ch13-02-iterators.md @@ -11,11 +11,13 @@ Listing 13-10 creates an iterator over the items in the vector `v1` by calling the `iter` method defined on `Vec`. This code by itself doesn’t do anything useful. ++ ```rust {{#rustdoc_include ../listings/ch13-functional-features/listing-13-10/src/main.rs:here}} ``` -Listing 13-10: Creating an iterator + The iterator is stored in the `v1_iter` variable. Once we’ve created an iterator, we can use it in a variety of ways. In Listing 3-5 in Chapter 3, we @@ -28,11 +30,13 @@ the use of the iterator in the `for` loop. When the `for` loop is called using the iterator in `v1_iter`, each element in the iterator is used in one iteration of the loop, which prints out each value. ++ ```rust {{#rustdoc_include ../listings/ch13-functional-features/listing-13-11/src/main.rs:here}} ``` -Listing 13-11: Using an iterator in a `for` loop + In languages that don’t have iterators provided by their standard libraries, you would likely write this same functionality by starting a variable at index @@ -76,14 +80,13 @@ We can call the `next` method on iterators directly; Listing 13-12 demonstrates what values are returned from repeated calls to `next` on the iterator created from the vector. -Filename: src/lib.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch13-functional-features/listing-13-12/src/lib.rs:here}} ``` -Listing 13-12: Calling the `next` method on an -iterator + Note that we needed to make `v1_iter` mutable: calling the `next` method on an iterator changes internal state that the iterator uses to keep track of where @@ -115,14 +118,13 @@ consuming the iterator. As it iterates through, it adds each item to a running total and returns the total when iteration is complete. Listing 13-13 has a test illustrating a use of the `sum` method: -Filename: src/lib.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch13-functional-features/listing-13-13/src/lib.rs:here}} ``` -Listing 13-13: Calling the `sum` method to get the total -of all items in the iterator + We aren’t allowed to use `v1_iter` after the call to `sum` because `sum` takes ownership of the iterator we call it on. @@ -139,14 +141,13 @@ The `map` method returns a new iterator that produces the modified items. The closure here creates a new iterator in which each item from the vector will be incremented by 1: -Filename: src/main.rs + ```rust,not_desired_behavior {{#rustdoc_include ../listings/ch13-functional-features/listing-13-14/src/main.rs:here}} ``` -Listing 13-14: Calling the iterator adaptor `map` to -create a new iterator + However, this code produces a warning: @@ -167,15 +168,13 @@ In Listing 13-15, we collect the results of iterating over the iterator that’s returned from the call to `map` into a vector. This vector will end up containing each item from the original vector incremented by 1. -Filename: src/main.rs + ```rust {{#rustdoc_include ../listings/ch13-functional-features/listing-13-15/src/main.rs:here}} ``` -Listing 13-15: Calling the `map` method to create a new -iterator and then calling the `collect` method to consume the new iterator and -create a vector + Because `map` takes a closure, we can specify any operation we want to perform on each item. This is a great example of how closures let you customize some @@ -201,14 +200,13 @@ In Listing 13-16, we use `filter` with a closure that captures the `shoe_size` variable from its environment to iterate over a collection of `Shoe` struct instances. It will return only shoes that are the specified size. -Filename: src/lib.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch13-functional-features/listing-13-16/src/lib.rs}} ``` -Listing 13-16: Using the `filter` method with a closure -that captures `shoe_size` + The `shoes_in_size` function takes ownership of a vector of shoes and a shoe size as parameters. It returns a vector containing only shoes of the specified diff --git a/rustbook-en/src/ch13-03-improving-our-io-project.md b/rustbook-en/src/ch13-03-improving-our-io-project.md index e4deec562..4c1a50845 100644 --- a/rustbook-en/src/ch13-03-improving-our-io-project.md +++ b/rustbook-en/src/ch13-03-improving-our-io-project.md @@ -13,14 +13,13 @@ values, allowing the `Config` struct to own those values. In Listing 13-17, we’ve reproduced the implementation of the `Config::build` function as it was in Listing 12-23: -Filename: src/lib.rs + ```rust,ignore {{#rustdoc_include ../listings/ch13-functional-features/listing-12-23-reproduced/src/lib.rs:ch13}} ``` -Listing 13-17: Reproduction of the `Config::build` -function from Listing 12-23 + At the time, we said not to worry about the inefficient `clone` calls because we would remove them in the future. Well, that time is now! @@ -54,14 +53,13 @@ We’ll first change the start of the `main` function that we had in Listing 12-24 to the code in Listing 13-18, which this time uses an iterator. This won’t compile until we update `Config::build` as well. -Filename: src/main.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch13-functional-features/listing-13-18/src/main.rs:here}} ``` -Listing 13-18: Passing the return value of `env::args` to -`Config::build` + The `env::args` function returns an iterator! Rather than collecting the iterator values into a vector and then passing a slice to `Config::build`, now @@ -73,14 +71,13 @@ project’s *src/lib.rs* file, let’s change the signature of `Config::build` t look like Listing 13-19. This still won’t compile because we need to update the function body. -Filename: src/lib.rs + ```rust,ignore,does_not_compile {{#rustdoc_include ../listings/ch13-functional-features/listing-13-19/src/lib.rs:here}} ``` -Listing 13-19: Updating the signature of `Config::build` -to expect an iterator + The standard library documentation for the `env::args` function shows that the type of the iterator it returns is `std::env::Args`, and that type implements @@ -103,14 +100,13 @@ Next, we’ll fix the body of `Config::build`. Because `args` implements the `Iterator` trait, we know we can call the `next` method on it! Listing 13-20 updates the code from Listing 12-23 to use the `next` method: -Filename: src/lib.rs + ```rust,noplayground {{#rustdoc_include ../listings/ch13-functional-features/listing-13-20/src/lib.rs:here}} ``` -Listing 13-20: Changing the body of `Config::build` to use -iterator methods + Remember that the first value in the return value of `env::args` is the name of the program. We want to ignore that and get to the next value, so first we call @@ -125,14 +121,13 @@ the same thing for the `file_path` value. We can also take advantage of iterators in the `search` function in our I/O project, which is reproduced here in Listing 13-21 as it was in Listing 12-19: -Filename: src/lib.rs + ```rust,ignore {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-19/src/lib.rs:ch13}} ``` -Listing 13-21: The implementation of the `search` -function from Listing 12-19 + We can write this code in a more concise way using iterator adaptor methods. Doing so also lets us avoid having a mutable intermediate `results` vector. The @@ -141,14 +136,13 @@ make code clearer. Removing the mutable state might enable a future enhancement to make searching happen in parallel, because we wouldn’t have to manage concurrent access to the `results` vector. Listing 13-22 shows this change: -Filename: src/lib.rs + ```rust,ignore {{#rustdoc_include ../listings/ch13-functional-features/listing-13-22/src/lib.rs:here}} ``` -Listing 13-22: Using iterator adaptor methods in the -implementation of the `search` function + Recall that the purpose of the `search` function is to return all lines in `contents` that contain the `query`. Similar to the `filter` example in Listing diff --git a/rustbook-en/src/ch14-02-publishing-to-crates-io.md b/rustbook-en/src/ch14-02-publishing-to-crates-io.md index d4d33babc..b4cfb22d6 100644 --- a/rustbook-en/src/ch14-02-publishing-to-crates-io.md +++ b/rustbook-en/src/ch14-02-publishing-to-crates-io.md @@ -26,14 +26,13 @@ Markdown notation for formatting the text. Place documentation comments just before the item they’re documenting. Listing 14-1 shows documentation comments for an `add_one` function in a crate named `my_crate`. -Filename: src/lib.rs + ```rust,ignore {{#rustdoc_include ../listings/ch14-more-about-cargo/listing-14-01/src/lib.rs}} ``` -Listing 14-1: A documentation comment for a -function + Here, we give a description of what the `add_one` function does, start a section with the heading `Examples`, and then provide code that demonstrates @@ -115,14 +114,13 @@ crate that contains the `add_one` function, we add documentation comments that start with `//!` to the beginning of the *src/lib.rs* file, as shown in Listing 14-2: -Filename: src/lib.rs + ```rust,ignore {{#rustdoc_include ../listings/ch14-more-about-cargo/listing-14-02/src/lib.rs:here}} ``` -Listing 14-2: Documentation for the `my_crate` crate as a -whole + Notice there isn’t any code after the last line that begins with `//!`. Because we started the comments with `//!` instead of `///`, we’re documenting the item @@ -172,14 +170,13 @@ Within this library are two modules: a `kinds` module containing two enums named `PrimaryColor` and `SecondaryColor` and a `utils` module containing a function named `mix`, as shown in Listing 14-3: -Filename: src/lib.rs + ```rust,noplayground,test_harness {{#rustdoc_include ../listings/ch14-more-about-cargo/listing-14-03/src/lib.rs:here}} ``` -Listing 14-3: An `art` library with items organized into -`kinds` and `utils` modules + Figure 14-3 shows what the front page of the documentation for this crate generated by `cargo doc` would look like: @@ -198,14 +195,13 @@ bring the items from `art` into scope, specifying the module structure that’s currently defined. Listing 14-4 shows an example of a crate that uses the `PrimaryColor` and `mix` items from the `art` crate: -Filename: src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch14-more-about-cargo/listing-14-04/src/main.rs}} ``` -Listing 14-4: A crate using the `art` crate’s items with -its internal structure exported + The author of the code in Listing 14-4, which uses the `art` crate, had to figure out that `PrimaryColor` is in the `kinds` module and `mix` is in the @@ -220,14 +216,13 @@ To remove the internal organization from the public API, we can modify the `art` crate code in Listing 14-3 to add `pub use` statements to re-export the items at the top level, as shown in Listing 14-5: -Filename: src/lib.rs + ```rust,ignore {{#rustdoc_include ../listings/ch14-more-about-cargo/listing-14-05/src/lib.rs:here}} ``` -Listing 14-5: Adding `pub use` statements to re-export -items + The API documentation that `cargo doc` generates for this crate will now list and link re-exports on the front page, as shown in Figure 14-4, making the @@ -242,14 +237,13 @@ The `art` crate users can still see and use the internal structure from Listing 14-3 as demonstrated in Listing 14-4, or they can use the more convenient structure in Listing 14-5, as shown in Listing 14-6: -Filename: src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch14-more-about-cargo/listing-14-06/src/main.rs:here}} ``` -Listing 14-6: A program using the re-exported items from -the `art` crate + In cases where there are many nested modules, re-exporting the types at the top level with `pub use` can make a significant difference in the experience of diff --git a/rustbook-en/src/ch14-03-cargo-workspaces.md b/rustbook-en/src/ch14-03-cargo-workspaces.md index cbece8233..afc9c65a7 100644 --- a/rustbook-en/src/ch14-03-cargo-workspaces.md +++ b/rustbook-en/src/ch14-03-cargo-workspaces.md @@ -142,14 +142,13 @@ Next, let’s use the `add_one` function (from the `add_one` crate) in the top to bring the new `add_one` library crate into scope. Then change the `main` function to call the `add_one` function, as in Listing 14-7. -Filename: adder/src/main.rs + ```rust,ignore {{#rustdoc_include ../listings/ch14-more-about-cargo/listing-14-07/add/adder/src/main.rs}} ``` -Listing 14-7: Using the `add_one` library crate from the - `adder` crate + Let’s build the workspace by running `cargo build` in the top-level *add* directory!