diff --git a/nostarch/chapter02.md b/nostarch/chapter02.md index d4642c52d9..671e986231 100644 --- a/nostarch/chapter02.md +++ b/nostarch/chapter02.md @@ -23,7 +23,7 @@ correct, the game will print a congratulatory message and exit. ## Setting Up a New Project -To set up a new project, go to the projects* directory that you created in +To set up a new project, go to the *projects* directory that you created in Chapter 1 and make a new project using Cargo, like so: ``` @@ -52,7 +52,7 @@ https://doc.rust-lang.org/cargo/reference/manifest.html ``` As you saw in Chapter 1, `cargo new` generates a “Hello, world!” program for -you. Check out the src/main.rs* file: +you. Check out the *src/main.rs* file: Filename: src/main.rs @@ -84,7 +84,7 @@ Reopen the *src/main.rs* file. You’ll be writing all the code in this file. The first part of the guessing game program will ask for user input, process that input, and check that the input is in the expected form. To start, we’ll allow the player to input a guess. Enter the code in Listing 2-1 into -src/main.rs*. +*src/main.rs*. Filename: src/main.rs @@ -121,8 +121,9 @@ use std::io; ``` By default, Rust has a set of items defined in the standard library that it -brings into the scope of every program. This set is called the prelude, and you -can see everything in it at *https://doc.rust-lang.org/std/prelude/index.html*. +brings into the scope of every program. This set is called the *prelude*, and +you can see everything in it at +*https://doc.rust-lang.org/std/prelude/index.html*. If a type you want to use isn’t in the prelude, you have to bring that type into scope explicitly with a `use` statement. Using the `std::io` library @@ -153,7 +154,7 @@ from the user. ### Storing Values with Variables -Next, we’ll create a variable* to store the user input, like this: +Next, we’ll create a *variable* to store the user input, like this: ``` let mut guess = String::new(); @@ -190,7 +191,7 @@ is a string type provided by the standard library that is a growable, UTF-8 encoded bit of text. The `::` syntax in the `::new` line indicates that `new` is an associated -function of the `String` type. An associated function is a function that’s +function of the `String` type. An *associated function is a function that’s implemented on a type, in this case `String`. This `new` function creates a new, empty string. You’ll find a `new` function on many types because it’s a common name for a function that makes a new value of some kind. @@ -224,7 +225,7 @@ standard input and append that into a string (without overwriting its contents), so we therefore pass that string as an argument. The string argument needs to be mutable so the method can change the string’s content. -The `& indicates that this argument is a reference, which gives you a way to +The `& indicates that this argument is a *reference*, which gives you a way to let multiple parts of your code access one piece of data without needing to copy that data into memory multiple times. References are a complex feature, and one of Rust’s major advantages is how safe and easy it is to use @@ -257,8 +258,8 @@ discuss what this line does. As mentioned earlier, `read_line` puts whatever the user enters into the string we pass to it, but it also returns a `Result` value. `Result` is an -enumeration, often called an enum, which is a type that can be in one of -multiple possible states. We call each possible state a variant*. +*enumeration*, often called an *enum*, which is a type that can be in one of +multiple possible states. We call each possible state a *variant*. Chapter 6 will cover enums in more detail. The purpose of these `Result` types is to encode error-handling information. @@ -360,12 +361,12 @@ library. However, the Rust team does provide a `rand` crate at ### Using a Crate to Get More Functionality Remember that a crate is a collection of Rust source code files. The project -we’ve been building is a binary crate , which is an executable. The `rand` -crate is a library crate*, which contains code that is intended to be used in +we’ve been building is a *binary crate , which is an executable. The `rand` +crate is a *library crate*, which contains code that is intended to be used in other programs and can’t be executed on its own. Cargo’s coordination of external crates is where Cargo really shines. Before we -can write code that uses `rand`, we need to modify the Cargo.toml file to +can write code that uses `rand`, we need to modify the *Cargo.toml* file to include the `rand` crate as a dependency. Open that file now and add the following line to the bottom, beneath the `[dependencies]` section header that Cargo created for you. Be sure to specify `rand` exactly as we have here, with @@ -378,14 +379,14 @@ Filename: Cargo.toml rand = "0.8.5" ``` -In the Cargo.toml file, everything that follows a header is part of that +In the *Cargo.toml* file, everything that follows a header is part of that section that continues until another section starts. In `[dependencies]` you tell Cargo which external crates your project depends on and which versions of those crates you require. In this case, we specify the `rand` crate with the semantic version specifier `0.8.5`. Cargo understands Semantic Versioning -(sometimes called SemVer), which is a standard for writing version numbers. The -specifier `0.8.5` is actually shorthand for `^0.8.5`, which means any version -that is at least 0.8.5 but below 0.9.0. +(sometimes called *SemVer*), which is a standard for writing version numbers. +The specifier `0.8.5` is actually shorthand for `^0.8.5`, which means any +version that is at least 0.8.5 but below 0.9.0. Cargo considers these versions to have public APIs compatible with version 0.8.5, and this specification ensures you’ll get the latest patch release that @@ -424,7 +425,7 @@ code, thanks to SemVer!) and different lines (depending on the operating system), and the lines may be in a different order. When we include an external dependency, Cargo fetches the latest versions of -everything that dependency needs from the registry, which is a copy of data +everything that dependency needs from the *registry*, which is a copy of data from Crates.io at *https://crates.io*. Crates.io is where people in the Rust ecosystem post their open source Rust projects for others to use. @@ -437,7 +438,7 @@ them and then compiles the project with the dependencies available. If you immediately run `cargo build` again without making any changes, you won’t get any output aside from the `Finished` line. Cargo knows it has already downloaded and compiled the dependencies, and you haven’t changed anything -about them in your Cargo.toml* file. Cargo also knows that you haven’t changed +about them in your *Cargo.toml* file. Cargo also knows that you haven’t changed anything about your code, so it doesn’t recompile that either. With nothing to do, it simply exits. @@ -451,7 +452,7 @@ $ cargo build ``` These lines show that Cargo only updates the build with your tiny change to the -src/main.rs* file. Your dependencies haven’t changed, so Cargo knows it can +*src/main.rs* file. Your dependencies haven’t changed, so Cargo knows it can reuse what it has already downloaded and compiled for those. #### Ensuring Reproducible Builds with the Cargo.lock File @@ -461,28 +462,29 @@ you or anyone else builds your code: Cargo will use only the versions of the dependencies you specified until you indicate otherwise. For example, say that next week version 0.8.6 of the `rand` crate comes out, and that version contains an important bug fix, but it also contains a regression that will -break your code. To handle this, Rust creates the Cargo.lock file the first -time you run `cargo build`, so we now have this in the guessing_game* directory. +break your code. To handle this, Rust creates the *Cargo.lock* file the first +time you run `cargo build`, so we now have this in the *guessing_game* +directory. When you build a project for the first time, Cargo figures out all the versions of the dependencies that fit the criteria and then writes them to the -Cargo.lock file. When you build your project in the future, Cargo will see that -the Cargo.lock file exists and will use the versions specified there rather -than doing all the work of figuring out versions again. This lets you have a -reproducible build automatically. In other words, your project will remain at -0.8.5 until you explicitly upgrade, thanks to the Cargo.lock file. Because the -Cargo.lock* file is important for reproducible builds, it’s often checked into -source control with the rest of the code in your project. +*Cargo.lock* file. When you build your project in the future, Cargo will see +that the *Cargo.lock* file exists and will use the versions specified there +rather than doing all the work of figuring out versions again. This lets you +have a reproducible build automatically. In other words, your project will +remain at 0.8.5 until you explicitly upgrade, thanks to the *Cargo.lock* file. +Because the *Cargo.lock* file is important for reproducible builds, it’s often +checked into source control with the rest of the code in your project. #### Updating a Crate to Get a New Version -When you do want to update a crate, Cargo provides the command `update, which -will ignore the Cargo.lock file and figure out all the latest versions that fit -your specifications in Cargo.toml. Cargo will then write those versions to the -Cargo.lock file. Otherwise, by default, Cargo will only look for versions -greater than 0.8.5 and less than 0.9.0. If the `rand` crate has released the -two new versions 0.8.6 and 0.9.0, you would see the following if you ran `cargo -update`: +When you *do* want to update a crate, Cargo provides the command `update, which +will ignore the *Cargo.lock* file and figure out all the latest versions that +fit your specifications in *Cargo.toml*. Cargo will then write those versions +to the *Cargo.lock* file. Otherwise, by default, Cargo will only look for +versions greater than 0.8.5 and less than 0.9.0. If the `rand` crate has +released the two new versions 0.8.6 and 0.9.0, you would see the following if +you ran `cargo update`: ``` $ cargo update @@ -491,9 +493,9 @@ $ cargo update ``` Cargo ignores the 0.9.0 release. At this point, you would also notice a change -in your Cargo.lock file noting that the version of the `rand` crate you are now -using is 0.8.6. To use `rand` version 0.9.0 or any version in the 0.9.x series, -you’d have to update the Cargo.toml* file to look like this instead: +in your *Cargo.lock* file noting that the version of the `rand` crate you are +now using is 0.8.6. To use `rand` version 0.9.0 or any version in the 0.9.*x* +series, you’d have to update the *Cargo.toml* file to look like this instead: ``` [dependencies] @@ -512,7 +514,7 @@ assembled from a number of packages. ### Generating a Random Number Let’s start using `rand` to generate a number to guess. The next step is to -update src/main.rs*, as shown in Listing 2-3. +update *src/main.rs*, as shown in Listing 2-3. Filename: src/main.rs @@ -637,12 +639,12 @@ comparing `guess` to `secret_number`. Then it returns a variant of the `Ordering` was returned from the call to `cmp` with the values in `guess` and `secret_number`. -A `match` expression is made up of arms. An arm consists of a pattern to match -against, and the code that should be run if the value given to `match` fits -that arm’s pattern. Rust takes the value given to `match` and looks through -each arm’s pattern in turn. Patterns and the `match` construct are powerful -Rust features: they let you express a variety of situations your code might -encounter and they make sure you handle them all. These features will be +A `match` expression is made up of *arms*. An arm consists of a *pattern* to +match against, and the code that should be run if the value given to `match` +fits that arm’s pattern. Rust takes the value given to `match` and looks +through each arm’s pattern in turn. Patterns and the `match` construct are +powerful Rust features: they let you express a variety of situations your code +might encounter and they make sure you handle them all. These features will be covered in detail in Chapter 6 and Chapter 18, respectively. Let’s walk through an example with the `match` expression we use here. Say that @@ -655,8 +657,8 @@ the `Ordering::Greater` value and starts checking each arm’s pattern. It looks at the first arm’s pattern, `Ordering::Less`, and sees that the value `Ordering::Greater` does not match `Ordering::Less`, so it ignores the code in that arm and moves to the next arm. The next arm’s pattern is -`Ordering::Greater`, which does match `Ordering::Greater`! The associated code -in that arm will execute and print `Too big!` to the screen. The `match` +`Ordering::Greater`, which *does* match `Ordering::Greater`! The associated +code in that arm will execute and print `Too big!` to the screen. The `match` expression ends after the first successful match, so it won’t look at the last arm in this scenario. @@ -675,7 +677,7 @@ error[E0308]: mismatched types found reference `&{integer}` ``` -The core of the error states that there are mismatched types. Rust has a +The core of the error states that there are *mismatched types*. Rust has a strong, static type system. However, it also has type inference. When we wrote `let mut guess = String::new()`, Rust was able to infer that `guess` should be a `String` and didn’t make us write the type. The `secret_number`, on the other @@ -717,7 +719,7 @@ match guess.cmp(&secret_number) { We create a variable named `guess`. But wait, doesn’t the program already have a variable named `guess`? It does, but helpfully Rust allows us to shadow the -previous value of `guess` with a new one. Shadowing lets us reuse the `guess` +previous value of `guess` with a new one. *Shadowing* lets us reuse the `guess` variable name rather than forcing us to create two unique variables, such as `guess_str` and `guess`, for example. We’ll cover this in more detail in Chapter 3, but for now, know that this feature is often used when you want to @@ -913,7 +915,7 @@ match the first arm’s pattern, and the `match` expression will just return the `num` value that `parse` produced and put inside the `Ok` value. That number will end up right where we want it in the new `guess` variable we’re creating. -If `parse` is not able to turn the string into a number, it will return an +If `parse` is *not* able to turn the string into a number, it will return an `Err` value that contains more information about the error. The `Err` value does not match the `Ok(num)` pattern in the first `match` arm, but it does match the `Err(_)` pattern in the second arm. The underscore, `_, is a catchall diff --git a/tools/docx-to-md.xsl b/tools/docx-to-md.xsl index a620a32219..8cfd507562 100644 --- a/tools/docx-to-md.xsl +++ b/tools/docx-to-md.xsl @@ -273,13 +273,13 @@ Unmatched: - + * - + *