入门

[package]
name = "hello_cargo"
version = "0.1.0"
authors = ["i514692 <klose.wu@sap.com>"]
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

这个文件使用 TOML 格式，这是 Cargo 配置文件的格式：

• 第一行 [package] ，是一个片段标题，表明下面的语句用来 配置一个包
  • 随着在这个文件增加更多的信息，还将增加其他片段
• 接下来的四行设置了 Cargo 编译程序所需的配置：
  • 项目的名称
  • 版本
  • 作者
  • 要使用的 Rust 版本

Cargo 从环境中获取你的名字和 email 信息，所以如果这些信息不正确，请修改并保存此文件

• 最后一行 [dependencies] ，是罗列 项目依赖 的片段的开始

      在 Rust 中，代码包被称为 crates

      这个项目并不需要其他的 crate

fn main() {
    println!("Hello, world!");
}

Cargo 自动生成了一个 “Hello, world!” 程序

Cargo 期望源文件存放在 src 目录中。项目根目录只存放 README、license 信息、配置文件和其他跟代码无关的文件

使用 Cargo 帮助你保持项目干净整洁，一切井井有条。

为了获取用户输入并打印结果作为输出，需要将 io （ 输入/输出 ）库引入当前作用域。io 库来自于 标准库 （也被称为 std ）

use std::io;

默认情况下，Rust 将 prelude 模块中少量的类型引入到每个程序的作用域中。如果需要的类型不在 prelude 中，你必须使用 use 语句显式地将其引入作用域

std::io 库提供很多有用的功能，包括接收用户输入的功能

创建一个储存用户输入的地方：

let mut guess = String::new();

这是一个 let 语句，用来 创建变量 。这里是另外一个例子：

let foo = 5; // 不可变的

在 Rust 中，变量 默认是不可变 的，程序里的 mut 用来定义 可变的 变量

      注意：// 语法开始一个注释，持续到行尾。Rust 忽略注释中的所有内容

现在已经知道了 let mut guess 会引入一个叫做 guess 的可变变量。等号(=) 的右边是 guess 所绑定的值，它是 String::new 的结果，这个函数会返回一个 String 的新实例

String 是一个标准库提供的字符串类型，它是 UTF-8 编码的可增长文本块

::new 那一行的 :: 语法表明 new 是 String 类型的一个 关联函数 ，关联函数是针对类型实现的

一些语言中把它称为 静态方法

在这个例子中 new 函数是 String，而不是 String 的某个特定实例

new 函数创建了一个新的空字符串，很多类型上有 new 函数，因为它是创建类型实例的惯用函数名

在程序的第一行使用 use std::io ; 从标准库中引入了输入/输出功能。现在调用 io 的关联函数 stdin ：

io::stdin().read_line(&mut guess)
    .expect("Failed to read line");

stdin 函数返回一个 std::io::Stdin 的实例，这代表 终端标准输入句柄的类型

      如果程序的开头没有 use std::io 这一行，可以把函数调用写成 std::io::stdin

.read_line(&mut guess) : 调用 read_line 方法从 标准输入句柄 获取 用户输入 ，向 read_line() 传递了一个 参数 &mut guess

• 无论用户在标准输入中键入什么内容，都将其存入一个字符串中，因此它需要字符串作为参数
• 这个字符串参数应该是 可变的 ，以便 read_line 将用户输入附加上去

      引用是一个复杂的特性，Rust 的一个主要优势就是安全而简单的操纵引用

      当然完成当前程序并不需要了解如此多细节

& 表示这个参数是一个 引用 ，它允许 多处代码访问同一处数据 ，而 无需在内存中多次拷贝

• 它像变量一样，*默认是不可变的*
• 所以要写成 &mut guess 来使其可变，而不是 &guess

read_line 将用户输入附加到传递给它的字符串中，不过它也 返回一个值 ：在这个例子中是 io::Result

Rust 标准库中有很多叫做 Result 的类型

一个 Result 泛型以及对应子模块的特定版本，比如 io::Result

Result 类型是 枚举 ，通常也写作 enums 。枚举类型 持有固定集合的值 ，这些值被称为枚举的 成员 。Result 的成员是 Ok 和 Err

• Ok 成员表示操作成功，内部包含成功时产生的值
• Err 成员则意味着操作失败，并且包含失败的前因后果

      这些 Result 类型的作用是编码错误处理信息

Result 类型的值，像其他类型一样，拥有定义于其上的方法。 io::Result 的实例拥有 expect 方法：

• 如果 io::Result 实例的值是 Err，expect 会导致 程序崩溃 ，并 显示当做参数传递给 expect 的信息
  • 如果 read_line 方法返回 Err，则可能是来源于 底层操作系统错误的结果
• 如果 io::Result 实例的值是 Ok，expect 会 获取 Ok 中的值 并 原样返回
  • 这里这个值是 用户输入到标准输入中的字节数

如果不调用 expect，程序也能编译，不过会出现一个警告：


$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
warning: unused `std::result::Result` which must be used
  --> src/main.rs:10:5
   |
10 |     io::stdin().read_line(&mut guess);
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: #[warn(unused_must_use)] on by default

Rust 警告没有使用 read_line 的返回值 Result，说明有一个可能的错误没有处理

消除警告的正确做法是实际编写错误处理代码，不过由于就是希望程序在出现问题时立即崩溃，所以直接使用 expect。

println!("You guessed: {}", guess);

这行代码打印存储用户输入的字符串。第一个参数是 格式化字符串 ：

• 里面的 {} 是 预留在特定位置的占位符
• 使用 {} 也可以打印多个值：第一对 {} 使用格式化字符串之后的第一个值，第二对则使用第二个值，依此类推

调用一次 println! 打印多个值看起来像这样：

#![allow(unused_variables)]
fn main() {
let x = 5;
let y = 10;

println!("x = {} and y = {}", x, y);
}

这行代码会打印出 x = 5 and y = 10

使用 cargo run 运行：

$ cargo run
   Compiling guessing_game v0.1.0 (/home/i514692/Documents/programming/html/klose911.github.io/src/rust/src/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 0.76s
     Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
8
You guessed: 8

crate 是一个 Rust 代码包 ：

• 正在构建的项目是一个 二进制 crate ，它 生成一个可执行文件
• rand crate 是一个 库 crate ，可以 包含任意能被其他程序使用的代码

Cargo 对外部 crate 的运用是其真正闪光的地方

使用 rand 编写代码之前，需要修改 Cargo.toml 文件， 引入一个 rand 依赖 。现在打开这个文件并在底部的 [dependencies] 片段标题之下添加：

[dependencies]

rand = "0.5.5"

      在 Cargo.toml 文件中，标题以及之后的内容属同一个片段，直到遇到下一个标题才开始新的片段

[dependencies] 片段告诉 Cargo 本项目 依赖了哪些外部 crate 及其版本 ：这里使用语义化版本 0.5.5 来指定 rand crate

Cargo 理解语义化版本（有时也称为 SemVer），这是一种定义版本号的标准

0.5.5 事实上是 ^0.5.5 的简写，它表示 “任何与 0.5.5 版本公有 API 相兼容的版本”

现在，不修改任何代码，构建项目：

$ cargo build
    Updating crates.io index
  Downloaded rand v0.5.6
  Downloaded rand_core v0.3.1
  Downloaded rand_core v0.4.2
  Downloaded libc v0.2.66
   Compiling libc v0.2.66
   Compiling rand_core v0.4.2
   Compiling rand_core v0.3.1
   Compiling rand v0.5.6
   Compiling guessing_game v0.1.0 (/home/i514692/Documents/programming/html/klose911.github.io/src/rust/src/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 30.78s

可能会出现不同的版本号（多亏了语义化版本，它们与代码是兼容的！），同时显示顺序也可能会有所不同

Cargo 从 registry 上获取所有包的最新版本信息，这是一份来自 Crates.io 的数据拷贝

Crates.io 是 Rust 生态环境中的开发者们向他人贡献 Rust 开源项目的地方

在更新完 registry 后，Cargo 检查 [dependencies] 片段并下载缺失的 crate

      本例中，虽然只声明了 rand 一个依赖，然而 Cargo 还是额外获取了 libc 和 rand_core 的拷贝，因为 rand 依赖 libc 来正常工作

      下载完成后，Rust 编译依赖，然后使用这些依赖编译项目

如果不做任何修改，立刻再次运行 cargo build，则不会看到任何除了 Finished 行之外的输出。Cargo 知道它已经下载并编译了依赖，同时 Cargo.toml 文件也没有变动。Cargo 还知道代码也没有任何修改，所以它不会重新编译代码。因为无事可做，它简单的退出了。如果打开 src/main.rs 文件，做一些无关紧要的修改，保存并再次构建，则会出现两行输出：

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 2.53 secs

这一行表示 Cargo 只针对 src/main.rs 文件的微小修改而更新构建。依赖没有变化，所以 Cargo 知道它可以复用已经为此下载并编译的代码。它只是重新构建了部分（项目）代码

使用 rand，更新 src/main.rs :

use std::io;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1, 101);

    println!("The secret number is: {}", secret_number);

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin().read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

新增了一行 use rand::Rng ：Rng 是一个 trait ，它定义了随机数生成器应实现的方法，想使用这些方法的话，此 trait 必须在作用域中

注意：不可能凭空就知道应该 use 哪个 trait 以及该从 crate 中调用哪个方法。crate 的使用说明位于其文档中

Cargo 有一个很棒的功能是：运行 cargo doc --open 命令来构建所有本地依赖提供的文档，并在浏览器中打开

例如，假设你对 rand crate 中的其他功能感兴趣，你可以运行 cargo doc --open 并点击左侧导航栏中的 rand

接下来，在中间还新增加了两行：

• rand::thread_rng 函数 提供实际使用的随机数生成器 ：它位于 当前执行线程的本地环境 中，并从 操作系统 获取 seed
  • 调用随机数生成器的 gen_range 方法。这个方法由刚才引入到作用域的 Rng::trait 定义：
    • 获取两个数字作为参数，并生成一个范围在两者之间的随机数
    • 它包含下限但不包含上限，所以需要指定 1 和 101 来请求一个 1 和 100 之间的数
• 第二行就是打印出这个随机数字

$ cargo run
   Compiling guessing_game v0.1.0 (/home/i514692/Documents/programming/html/klose911.github.io/src/rust/src/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 0.95s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 24
Please input your guess.
8
You guessed: 8

一个 match 表达式 由 分支 构成

• 一个分支包含一个 模式 和 表达式开头的值与分支模式 相 匹配 时应该 执行的代码
• Rust 获取提供给 match 的值并挨个检查每个分支的模式
• match 结构和模式是 Rust 中强大的功能，它体现了代码可能遇到的多种情形，并确保没有遗漏处理

假设用户猜了 50，这时随机生成的秘密数字是 38，比较 50 与 38 时，因为 50 比 38 要大，cmp 方法会返回 Ordering::Greater

Ordering::Greater 是 match 表达式得到的值：
1. 它检查第一个分支的模式，Ordering::Less 与 Ordering::Greater并不匹配，所以它忽略了这个分支的代码并来到下一个分支
2. 下一个分支的模式是 Ordering::Greater，正确匹配！这个分支关联的代码被执行，在屏幕打印出 Too big!

match 表达式就此终止，因为该场景下没有检查最后一个分支的必要

然而上面的代码却不能通过编译：

$ cargo build
   Compiling guessing_game v0.1.0 (/home/i514692/Documents/programming/html/klose911.github.io/src/rust/src/guessing_game)
error[E0308]: mismatched types
  --> src/main.rs:21:21
   |
21 |     match guess.cmp(&secret_number) {
   |                     ^^^^^^^^^^^^^^ expected struct `std::string::String`, found integer
   |
   = note: expected type `&std::string::String`
              found type `&{integer}`

error: aborting due to previous error

For more information about this error, try `rustc --explain E0308`.
error: could not compile `guessing_game`.

To learn more, run the command again with --verbose.

错误的核心表明这里有 不匹配的类型

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 函数体中增加如下两行代码来实现：

// --snip--

    let mut guess = String::new();

    io::stdin().read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse()
        .expect("Please type a number!");

    println!("You guessed: {}", guess);

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

这里创建了一个叫做 guess 的变量

      不过等等，不是已经有了一个叫做 guess 的变量了吗？

确实如此，不过 Rust 允许用一个新值来 隐藏 guess 之前的值

      这个功能常用在需要转换值类型之类的场景。它允许我们复用 guess 变量的名字，而不是被迫创建两个不同变量，诸如 guess_str 和 guess 之类

将 guess 绑定到 guess.trim().parse() 表达式上：

• 表达式中的 guess 是包含输入的 原始 String 类型
• String 实例的 trim 方法会 去除字符串开头和结尾的空白字符

u32 只能由数字字符转换，不过用户必须输入 enter 键才能让 read_line 返回，然而用户按下 enter 键时，会在字符串中增加一个换行符

例如，用户输入 5 并按下 enter，guess 看起来像这样：5\n。\n 代表 “换行”，回车键。trim 方法消除 \n，只留下 5

• 字符串的 parse 方法 将 字符串解析成数字 ：
  • 因为这个方法可以解析多种数字类型，因此 需要告诉 Rust 具体的数字类型 ，这里通过 let guess: u32 指定
    • guess 后面的冒号 : 告诉 Rust 指定了 变量的类型

Rust 有一些内建的数字类型；u32 是一个无符号的 32 位整型

对于不大的正整数来说，它是不错的类型

另外，程序中的 u32 注解以及与 secret_number 的比较，意味着 Rust 会推断出 secret_number 也是 u32 类型

现在可以使用相同类型比较两个值了

• parse 调用很容易产生错误：
  • 例如，字符串中包含 A👍% ，就无法将其转换为一个数字
  • parse 方法返回一个 Result 类型，再次用 expect 方法处理即可：
    • 如果 parse 不能从字符串生成一个数字，返回一个 Result 的 Err 成员时，expect 会使游戏崩溃并打印附带的信息
    • 如果 parse 成功地将字符串转换为一个数字，它会返回 Result 的 Ok 成员，然后 expect 会返回 Ok 值中的数字

现在运行程序：

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 83
Please input your guess.
99
You guessed: 99
Too big!

增加一个 break 语句，在用户猜对时退出游戏：

// --snip--

match guess.cmp(&secret_number) {
    Ordering::Less => println!("Too small!"),
    Ordering::Greater => println!("Too big!"),
    Ordering::Equal => {
        println!("You win!");
        break;
    }
}

通过在 You win! 之后增加一行 break，用户猜对了神秘数字后会退出循环

$ cargo run
   Compiling guessing_game v0.1.0 (/home/i514692/Documents/programming/html/klose911.github.io/src/rust/src/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 1.10s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 2
Please input your guess.
5
You guessed: 5
Too big!
Please input your guess.
1
You guessed: 1
Too small!
Please input your guess.
2
You guessed: 2
You win!

为了进一步改善游戏性，不要在用户输入非数字时崩溃，需要忽略非数字，让用户可以继续猜测。可以通过修改 guess 将 String 转化为 u32 那部分代码来实现：

// --snip--

io::stdin().read_line(&mut guess)
    .expect("Failed to read line");

let guess: u32 = match guess.trim().parse() {
    Ok(num) => num,
    Err(_) => continue,
};

println!("You guessed: {}", guess);

// --snip--

将 expect 调用换成 match 语句，是从遇到错误就崩溃转换到真正处理错误的惯用方法

parse 返回一个 Result 类型，而 Result 是一个拥有 Ok 或 Err 成员的枚举

这里使用的 match 表达式，和之前处理 cmp 方法返回 Ordering 时用的一样

• 如果 parse 能够成功的将字符串转换为一个数字，它会返回一个包含结果数字的 Ok
  • 这个 Ok 值与 match 第一个分支的模式相匹配，该分支对应的动作返回 Ok 值中的数字 num，最后如愿变成新创建的 guess 变量
• 如果 parse 不能将字符串转换为一个数字，它会返回一个包含更多错误信息的 Err
  • Err 值不能匹配第一个 match 分支的 Ok(num) 模式，但是会匹配第二个分支的 Err(_) 模式： _ 是一个通配符值，本例中用来匹配所有 Err 值，不管其中有何种信息
    • 程序会执行第二个分支的动作， continue 意味着 进入 loop 的下一次循环 ，请求另一个猜测。这样程序就有效的忽略了 parse 可能遇到的所有错误！

$ cargo run
   Compiling guessing_game v0.1.0 (/home/i514692/Documents/programming/html/klose911.github.io/src/rust/src/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 1.07s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 32
Please input your guess.
exit
Please input your guess.
qqq
Please input your guess.
12
You guessed: 12
Too small!
Please input your guess.
40
You guessed: 40
Too big!
Please input your guess.
32
You guessed: 32
You win!

      最后，还应该注释掉最开始的生成随机数字的打印语句 :-)