diff --git a/src/ch02-00-guessing-game-tutorial.md b/src/ch02-00-guessing-game-tutorial.md index b969cc8..15f9001 100644 --- a/src/ch02-00-guessing-game-tutorial.md +++ b/src/ch02-00-guessing-game-tutorial.md @@ -2,7 +2,7 @@ > [ch02-00-guessing-game-tutorial.md](https://github.com/rust-lang/book/blob/main/src/ch02-00-guessing-game-tutorial.md) >
-> commit c427a676393d001edc82f1a54a3b8026abcf9690 +> commit cba828634ec75fe6e61f34f3dd933ef1d78cffc6 让我们一起动手完成一个项目，来快速上手 Rust！本章将介绍 Rust 中一些常用概念，并通过真实的程序来展示如何运用它们。你将会学到 `let`、`match`、方法、关联函数、外部 crate 等知识！后续章节会深入探讨这些概念的细节。在这一章，我们将做基础练习。 @@ -12,7 +12,7 @@ 要创建一个新项目，进入第一章中创建的 *projects* 目录，使用 Cargo 新建一个项目，如下： -```text +```console $ cargo new guessing_game $ cd guessing_game ``` @@ -27,14 +27,13 @@ $ cd guessing_game [package] name = "guessing_game" version = "0.1.0" -authors = ["Your Name "] edition = "2018" +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + [dependencies] ``` -如果 Cargo 从环境中获取的开发者信息不正确，修改这个文件并再次保存。 - 正如第一章那样，`cargo new` 生成了一个 “Hello, world!” 程序。查看 *src/main.rs* 文件： 文件名: src/main.rs @@ -47,10 +46,10 @@ fn main() { 现在使用 `cargo run` 命令，一步完成 “Hello, world!” 程序的编译和运行： -```text +```console $ cargo run Compiling guessing_game v0.1.0 (file:///projects/guessing_game) - Finished dev [unoptimized + debuginfo] target(s) in 1.50 secs + Finished dev [unoptimized + debuginfo] target(s) in 1.50s Running `target/debug/guessing_game` Hello, world! ``` @@ -123,14 +122,14 @@ let mut guess = String::new(); 现在程序开始变得有意思了！这一小行代码发生了很多事。注意这是一个 `let` 语句，用来创建 **变量**（*variable*）。这里是另外一个例子： ```rust,ignore -let foo = bar; +let apples = 5; ``` -这行代码新建了一个叫做 `foo` 的变量并把它绑定到值 `bar` 上。在 Rust 中，变量默认是不可变的。我们将会在第三章的 [“变量与可变性”][variables-and-mutability] 部分详细讨论这个概念。下面的例子展示了如何在变量名前使用 `mut` 来使一个变量可变： +这行代码新建了一个叫做 `apples` 的变量并把它绑定到值 `5` 上。在 Rust 中，变量默认是不可变的。我们将会在第三章的 [“变量与可变性”][variables-and-mutability] 部分详细讨论这个概念。下面的例子展示了如何在变量名前使用 `mut` 来使一个变量可变： ```rust,ignore -let foo = 5; // 不可变 -let mut bar = 5; // 可变 +let apples = 5; // immutable +let mut bananas = 5; // mutable ``` > 注意：`//` 语法开始一个注释，持续到行尾。Rust 忽略注释中的所有内容，第三章将会详细介绍注释。 @@ -139,7 +138,7 @@ let mut bar = 5; // 可变 [string]: https://doc.rust-lang.org/std/string/struct.String.html -`::new` 那一行的 `::` 语法表明 `new` 是 `String` 类型的一个 **关联函数**（*associated function*）。关联函数是针对类型实现的，在这个例子中是 `String`，而不是 `String` 的某个特定实例。一些语言中把它称为 **静态方法**（*static method*）。 +`::new` 那一行的 `::` 语法表明 `new` 是 `String` 类型的一个 **关联函数**（*associated function*）。关联函数是针对类型实现的，在这个例子中是 `String`。 `new` 函数创建了一个新的空字符串，你会发现很多类型上有 `new` 函数，因为它是创建类型实例的惯用函数名。 @@ -160,7 +159,7 @@ io::stdin().read_line(&mut guess) [read_line]: https://doc.rust-lang.org/std/io/struct.Stdin.html#method.read_line -`read_line` 的工作是，无论用户在标准输入中键入什么内容，都将其存入一个字符串中，因此它需要字符串作为参数。这个字符串参数应该是可变的，以便 `read_line` 将用户输入附加上去。 +`read_line` 的工作是接收用户在标准输入中输入的任何内容，并将其追加到一个字符串中（不覆盖其内容），因此它将该字符串作为参数。这个字符串参数需要是可变的，以便该方法可以通过添加用户输入来改变字符串的内容。 `&` 表示这个参数是一个 **引用**（*reference*），它允许多处代码访问同一处数据，而无需在内存中多次拷贝。引用是一个复杂的特性，Rust 的一个主要优势就是安全而简单的操纵引用。完成当前程序并不需要了解如此多细节。现在，我们只需知道它像变量一样，默认是不可变的。因此，需要写成 `&mut guess` 来使其可变，而不是 `&guess`。（第四章会更全面的解释引用。） @@ -172,7 +171,7 @@ io::stdin().read_line(&mut guess) .expect("Failed to read line"); ``` -当使用 `.foo()` 语法调用方法时，通过换行加缩进来把长行拆开是明智的。我们完全可以这样写： +当使用 `.method_name()` 语法调用方法时，通过换行加缩进来把长行拆开是明智的。我们完全可以这样写： ```rust,ignore io::stdin().read_line(&mut guess).expect("Failed to read line"); @@ -197,16 +196,21 @@ io::stdin().read_line(&mut guess).expect("Failed to read line"); 如果不调用 `expect`，程序也能编译，不过会出现一个警告： -```text +```console $ cargo build Compiling guessing_game v0.1.0 (file:///projects/guessing_game) -warning: unused `std::result::Result` which must be used +warning: unused `Result` that must be used --> src/main.rs:10:5 | 10 | io::stdin().read_line(&mut guess); | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | - = note: #[warn(unused_must_use)] on by default + = note: `#[warn(unused_must_use)]` on by default + = note: this `Result` may be an `Err` variant, which should be handled + +warning: 1 warning emitted + + Finished dev [unoptimized + debuginfo] target(s) in 0.59s ``` Rust 警告我们没有使用 `read_line` 的返回值 `Result`，说明有一个可能的错误没有处理。 @@ -215,7 +219,7 @@ Rust 警告我们没有使用 `read_line` 的返回值 `Result`，说明有一 ### 使用 `println!` 占位符打印值 -除了位于结尾的大括号，目前为止就只有这一行代码值得讨论一下了，就是这一行： +除了位于结尾的右花括号，目前为止就只有这一行代码值得讨论一下了，就是这一行： ```rust,ignore println!("You guessed: {}", guess); @@ -236,10 +240,10 @@ println!("x = {} and y = {}", x, y); 让我们来测试下猜猜看游戏的第一部分。使用 `cargo run` 运行： -```text +```console $ cargo run Compiling guessing_game v0.1.0 (file:///projects/guessing_game) - Finished dev [unoptimized + debuginfo] target(s) in 2.53 secs + Finished dev [unoptimized + debuginfo] target(s) in 6.44s Running `target/debug/guessing_game` Guess the number! Please input your guess. @@ -259,7 +263,7 @@ You guessed: 6 记住，*crate* 是一个 Rust 代码包。我们正在构建的项目是一个 **二进制 crate**，它生成一个可执行文件。 `rand` crate 是一个 **库 crate**，库 crate 可以包含任意能被其他程序使用的代码。 -Cargo 对外部 crate 的运用是其真正闪光的地方。在我们使用 `rand` 编写代码之前，需要修改 *Cargo.toml* 文件，引入一个 `rand` 依赖。现在打开这个文件并在底部的 `[dependencies]` 片段标题之下添加： +Cargo 对外部 crate 的运用是其真正的亮点所在。在我们使用 `rand` 编写代码之前，需要修改 *Cargo.toml* 文件，引入一个 `rand` 依赖。现在打开这个文件并将下面这一行添加到 `[dependencies]` 片段标题之下。请确保按照我们这里的方式指定 `rand`，否则本教程中的代码示例可能无法工作。 文件名: Cargo.toml @@ -275,7 +279,7 @@ rand = "0.8.3" 现在，不修改任何代码，构建项目，如示例 2-2 所示： -```text +```console $ cargo build Updating crates.io index Downloaded rand v0.8.3 @@ -298,19 +302,19 @@ $ cargo build 示例 2-2: 将 rand crate 添加为依赖之后运行 `cargo build` 的输出 -可能会出现不同的版本号（多亏了语义化版本，它们与代码是兼容的！），同时显示顺序也可能会有所不同。 +可能会出现不同的版本号（多亏了语义化版本，它们与代码是兼容的！），不同的行(取决于操作系统)，同时显示顺序也可能会有所不同。 因为我们有了一个外部依赖，Cargo 从 *registry* 上获取所有包的最新版本信息，这是一份来自 [Crates.io][cratesio] 的数据拷贝。Crates.io 是 Rust 生态环境中的开发者们向他人贡献 Rust 开源项目的地方。 [cratesio]: https://crates.io -在更新完 registry 后，Cargo 检查 `[dependencies]` 片段并下载缺失的 crate 。本例中，虽然只声明了 `rand` 一个依赖，然而 Cargo 还是额外获取了 `libc` 和 `rand_core` 的拷贝，因为 `rand` 依赖 `libc` 和 `rand_core` 来正常工作。下载完成后，Rust 编译依赖，然后使用这些依赖编译项目。 +在更新完 registry 后，Cargo 检查 `[dependencies]` 片段并下载缺失的 crate 。本例中，虽然只声明了 `rand` 一个依赖，然而 Cargo 还是额外获取了 `rand` 所需要的其他 crates，因为 `rand` 依赖它们来正常工作。下载完成后，Rust 编译依赖，然后使用这些依赖编译项目。 如果不做任何修改，立刻再次运行 `cargo build`，则不会看到任何除了 `Finished` 行之外的输出。Cargo 知道它已经下载并编译了依赖，同时 *Cargo.toml* 文件也没有变动。Cargo 还知道代码也没有任何修改，所以它不会重新编译代码。因为无事可做，它简单的退出了。 如果打开 *src/main.rs* 文件，做一些无关紧要的修改，保存并再次构建，则会出现两行输出： -```text +```console $ cargo build Compiling guessing_game v0.1.0 (file:///projects/guessing_game) Finished dev [unoptimized + debuginfo] target(s) in 2.53 secs @@ -330,7 +334,7 @@ Cargo 有一个机制来确保任何人在任何时候重新构建代码，都 不过，Cargo 默认只会寻找大于 `0.8.3` 而小于 `0.9.0` 的版本。如果 `rand` crate 发布了两个新版本，`0.8.4` 和 `0.9.0`，在运行 `cargo update` 时会出现如下内容： -```text +```console $ cargo update Updating crates.io index Updating rand v0.8.3 -> v0.8.4 @@ -386,7 +390,7 @@ fn main() { 首先，我们新增了一行 `use`：`use rand::Rng`。`Rng` 是一个 trait，它定义了随机数生成器应实现的方法，想使用这些方法的话，此 trait 必须在作用域中。第十章会详细介绍 trait。 -接下来，我们在中间还新增加了两行。`rand::thread_rng` 函数提供实际使用的随机数生成器：它位于当前执行线程的本地环境中，并从操作系统获取 seed。接下来，调用随机数生成器的 `gen_range` 方法。这个方法由刚才引入到作用域的 `Rng` trait 定义。`gen_range` 方法获取两个数字作为参数，并生成一个范围在两者之间的随机数。它包含下限但不包含上限，所以需要指定 `1` 和 `101` 来请求一个 1 和 100 之间的数。 +接下来，我们在中间还新增加了两行。`rand::thread_rng` 函数提供实际使用的随机数生成器：它位于当前执行线程的本地环境中，并从操作系统获取 seed。接下来，调用随机数生成器的 `gen_range` 方法。这个方法由刚才引入到作用域的 `Rng` trait 定义。`gen_range` 方法接受一个范围表达式作为参数，并在该范围内生成一个随机数。我们在这里使用的范围表达式采用 `start..end` 形式，它包含下限但不包含上限，所以需要指定 `1..101` 来请求一个 1 和 100 之间的数。另外，我们也可以传递 `1..=100`，这是等价的。 > 注意：你不可能凭空就知道应该 use 哪个 trait 以及该从 crate 中调用哪个方法。crate 的使用说明位于其文档中。Cargo 有一个很棒的功能是：运行 `cargo doc --open` 命令来构建所有本地依赖提供的文档，并在浏览器中打开。例如，假设你对 `rand` crate 中的其他功能感兴趣，你可以运行 `cargo doc --open` 并点击左侧导航栏中的 `rand`。 @@ -394,17 +398,19 @@ fn main() { 尝试运行程序几次： -```text +```console $ cargo run Compiling guessing_game v0.1.0 (file:///projects/guessing_game) - Finished dev [unoptimized + debuginfo] target(s) in 2.53 secs + Finished dev [unoptimized + debuginfo] target(s) in 2.53s Running `target/debug/guessing_game` Guess the number! The secret number is: 7 Please input your guess. 4 You guessed: 4 + $ cargo run + Finished dev [unoptimized + debuginfo] target(s) in 0.02s Running `target/debug/guessing_game` Guess the number! The secret number is: 83 @@ -454,7 +460,7 @@ fn main() { 然而，示例 2-4 的代码并不能编译，可以尝试一下： -```text +```console $ cargo build Compiling guessing_game v0.1.0 (file:///projects/guessing_game) error[E0308]: mismatched types @@ -472,7 +478,7 @@ Could not compile `guessing_game`. 错误的核心表明这里有 **不匹配的类型**（*mismatched types*）。Rust 有一个静态强类型系统，同时也有类型推断。当我们写出 `let guess = String::new()` 时，Rust 推断出 `guess` 应该是 `String` 类型，并不需要我们写出类型。另一方面，`secret_number`，是数字类型。几个数字类型拥有 1 到 100 之间的值：32 位数字 `i32`；32 位无符号数字 `u32`；64 位数字 `i64` 等等。Rust 默认使用 `i32`，所以它是 `secret_number` 的类型，除非增加类型信息，或任何能让 Rust 推断出不同数值类型的信息。这里错误的原因在于 Rust 不会比较字符串类型和数字类型。 -所以我们必须把从输入中读取到的 `String` 转换为一个真正的数字类型，才好与秘密数字进行比较。这可以通过在 `main` 函数体中增加如下两行代码来实现： +所以我们必须把从输入中读取到的 `String` 转换为一个真正的数字类型，才好与秘密数字进行比较。这可以通过在 `main` 函数体中增加另一行代码来实现： 文件名: src/main.rs @@ -497,16 +503,15 @@ Could not compile `guessing_game`. } ``` -这两行新代码是： +这行新代码是： ```rust,ignore -let guess: u32 = guess.trim().parse() - .expect("Please type a number!"); +let guess: u32 = guess.trim().parse().expect("Please type a number!"); ``` 这里创建了一个叫做 `guess` 的变量。不过等等，不是已经有了一个叫做 `guess` 的变量了吗？确实如此，不过 Rust 允许用一个新值来 **隐藏** （*shadow*） `guess` 之前的值。这个功能常用在需要转换值类型之类的场景。它允许我们复用 `guess` 变量的名字，而不是被迫创建两个不同变量，诸如 `guess_str` 和 `guess` 之类。（第三章会介绍 shadowing 的更多细节。） -我们将 `guess` 绑定到 `guess.trim().parse()` 表达式上。表达式中的 `guess` 是包含输入的原始 `String` 类型。`String` 实例的 `trim` 方法会去除字符串开头和结尾的空白字符。`u32` 只能由数字字符转换，不过用户必须输入 enter 键才能让 `read_line` 返回，然而用户按下 enter 键时，会在字符串中增加一个换行（newline）符。例如，用户输入 5 并按下 enter，`guess` 看起来像这样：`5\n`。`\n` 代表 “换行”，回车键。`trim` 方法消除 `\n`，只留下 `5`。 +我们将 `guess` 绑定到 `guess.trim().parse()` 表达式上。表达式中的 `guess` 是包含输入的原始 `String` 类型。`String` 实例的 `trim` 方法会去除字符串开头和结尾的空白字符。`u32` 只能由数字字符转换，不过用户必须输入 enter 键才能让 `read_line` 返回，然而用户按下 enter 键时，会在字符串中增加一个换行（newline）符。例如，用户输入 5 并按下 enter（在 Windows 上，按下 enter 键会得到一个回车符和一个换行符，`\r\n`），`guess` 看起来像这样：`5\n` 或者 `5\r\n`。`\n` 代表 “换行”，回车键；`\r` 代表 “回车”，回车键。`trim` 方法会消除 `\n` 或者 `\r\n`，只留下 `5`。 [字符串的 `parse` 方法][parse] 将字符串解析成数字。因为这个方法可以解析多种数字类型，因此需要告诉 Rust 具体的数字类型，这里通过 `let guess: u32` 指定。`guess` 后面的冒号（`:`）告诉 Rust 我们指定了变量的类型。Rust 有一些内建的数字类型；`u32` 是一个无符号的 32 位整型。对于不大的正整数来说，它是不错的类型，第三章还会讲到其他数字类型。另外，程序中的 `u32` 注解以及与 `secret_number` 的比较，意味着 Rust 会推断出 `secret_number` 也是 `u32` 类型。现在可以使用相同类型比较两个值了！ @@ -516,10 +521,10 @@ let guess: u32 = guess.trim().parse() 现在让我们运行程序！ -```text +```console $ cargo run Compiling guessing_game v0.1.0 (file:///projects/guessing_game) - Finished dev [unoptimized + debuginfo] target(s) in 0.43 secs + Finished dev [unoptimized + debuginfo] target(s) in 0.43s Running `target/debug/guessing_game` Guess the number! The secret number is: 58 @@ -562,10 +567,10 @@ Too big! 用户总能使用 ctrl-c 终止程序。不过还有另一个方法跳出无限循环，就是 [“比较猜测与秘密数字”](#comparing-the-guess-to-the-secret-number) 部分提到的 `parse`：如果用户输入的答案不是一个数字，程序会崩溃。用户可以利用这一点来退出，如下所示： -```text +```console $ cargo run Compiling guessing_game v0.1.0 (file:///projects/guessing_game) - Finished dev [unoptimized + debuginfo] target(s) in 1.50 secs + Finished dev [unoptimized + debuginfo] target(s) in 1.50s Running `target/debug/guessing_game` Guess the number! The secret number is: 59 @@ -583,9 +588,8 @@ You guessed: 59 You win! Please input your guess. quit -thread 'main' panicked at 'Please type a number!: ParseIntError { kind: InvalidDigit }', src/libcore/result.rs:785 -note: Run with `RUST_BACKTRACE=1` for a backtrace. -error: Process didn't exit successfully: `target/debug/guess` (exit code: 101) +thread 'main' panicked at 'Please type a number!: ParseIntError { kind: InvalidDigit }', src/main.rs:28:47 +note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` 输入 `quit` 确实退出了程序，同时其他任何非数字输入也一样。然而，这并不理想，我们想要当猜测正确的数字时游戏能自动退出。 @@ -645,9 +649,10 @@ println!("You guessed: {}", guess); 现在万事俱备，只需运行 `cargo run`： -```text +```console $ cargo run Compiling guessing_game v0.1.0 (file:///projects/guessing_game) + Finished dev [unoptimized + debuginfo] target(s) in 4.45s Running `target/debug/guessing_game` Guess the number! The secret number is: 61 @@ -714,7 +719,7 @@ fn main() { 此时此刻，你顺利完成了猜猜看游戏。恭喜！ -本项目通过动手实践，向你介绍了 Rust 新概念：`let`、`match`、方法、关联函数、使用外部 crate 等等，接下来的几章，你会继续深入学习这些概念。第三章介绍大部分编程语言都有的概念，比如变量、数据类型和函数，以及如何在 Rust 中使用它们。第四章探索所有权（ownership），这是一个 Rust 同其他语言大不相同的功能。第五章讨论结构体和方法的语法，而第六章侧重解释枚举。 +本项目通过动手实践，向你介绍了 Rust 新概念：`let`、`match`、方法、函数、使用外部 crate 等等，接下来的几章，你会继续深入学习这些概念。第三章介绍大部分编程语言都有的概念，比如变量、数据类型和函数，以及如何在 Rust 中使用它们。第四章探索所有权（ownership），这是一个 Rust 同其他语言大不相同的功能。第五章讨论结构体和方法的语法，而第六章侧重解释枚举。 [variables-and-mutability]: ch03-01-variables-and-mutability.html#variables-and-mutability