Rust 语法基础 ¶

变量 ¶

标识符命名 ¶

• 原生标识符（raw identifiers）
  • 关键字不能作为标识符名称
  • 加上 r# 前缀后可以使用，比如 r#match
• 命名规范：

变量绑定与可变性 ¶

rust 使用 let 关键字来进行变量绑定，即 let a = 1;

而 rust 的变量默认是不可变（immutable）的，使之变成可变的需要在 let 后面加上 mut，如果后面不会改变的变量被声明为了 mutable 的，编译器会给出警告

存在没有使用的变量的话编译器也会给出警告，在变量名前加上单下划线即可忽略

变量解构 ¶

类似于 python 的元素解包

let (a, mut b): (bool, bool) = (true, false);
let (a, b, c, d);
(a, b) = (1, 2);
[c, .., d, _] = [1, 2, 3, 4, 5]; // c = 1, d = 4

常量 ¶

常量使用 const 关键字来定义，且必须指定类型，命名通常为蛇形全大写，const 后面也不允许使用 mut，可以在任意作用域内声明

const MAX_VALUE: u32 = 100_000;

变量遮蔽 ¶

rust 中可以重复声明同一名称的变量，这会再次分配内存，并完全遮蔽掉前面的同名变量

基本类型 ¶

整型 ¶

i长度（有符号）、u长度（无符号）

• i8、i16、i32、i64、i128、u8、u16、u32、u64、u128
• isize、usize 长度由 CPU 决定，32 位 CPU 则是 32 位，64 位 CPU 则是 64 位
• 整型字面量中间可以插入 _
• 字面量结尾可以接类型，例如 10i32, 10_i32
• 字面量，十六进制 0x...、八进制 0o...、二进制 0b...、字节（仅 u8）b'A'
• 整型默认使用 i32 类型
• 使用 as 来转换类型，例如 let a: u16 = 1_u8 as u16;

debug 模式编译时产生溢出会 panic，而在 release 模式下则不会 panic，按照补码循环溢出。但不能依赖这种行为，想要这样的效果应该标准库的一些方法：

• wrapping_* 方法，按照补码循环溢出，例如 a.wrapping_add(1)
• checked_* 方法，如果产生溢出了，则会返回 None
• overflowing_* 方法，返回结果以及指示是否溢出的布尔值
• saturating_* 方法，如果会溢出则保持在最大 / 最小值上

布尔类型 ¶

类型名为 bool，值为 true 或 false，占用 1 字节内存

浮点型 ¶

• f32 单精度浮点型、f64 双精度浮点型，默认情况下为 f64
• 应该避免判断浮点数相等
• 可以使用 .is_nan() 方法来判断一个数值是否是 NaN
• 数值上也可以使用方法，比如 3.14_f32.round()

运算 ¶

• + - * / %：加减乘除取模
• & | ^ ! << >>：位运算
• 同样类型才能进行计算、类型转换必须是显式的
• 其它运算可以通过方法实现，.pow() 计算指数，.log() 取对数、.div_euclid() 整除、.div_floor() 等等

序列 ¶

在 for 循环中常用，用来生成连续的数值，仅可以使用整数、字符等连续的类型，例如：

for i in 1..5 {
    ...; // i = 1, 2, 3, 4
}
for j in 'a'..='d' {
    ...; // i = 'a', 'b', 'c', 'd'
}

字符类型 ¶

rust 中的字符类型是 char，字面量写法为单引号（双引号表示字符串）

• 一个 char 占四个字节（而不是 C/C++ 中的一个字节）
• 所有 unicode 码元都是一个字符
• 直接存储 unicode 值（即 UCS-4），而不使用 UTF-8 编码

单元类型 ¶

• 单元类型就是 ()，唯一的值也是 ()，不占内存
• main 函数返回的就是单元类型 ()

语句与表达式 ¶

• 简单理解就是，带分号的是一个语句，不带分号的是一个表达式，能返回值的就是表达式
• 表达式可以是语句的一部分，比如 let a = 1; 中 1 就是一个表达式，而整体是一个语句
• 函数调用是表达式，因为会有返回值，即使“无”返回值也会返回单元类型
• 用大括号包裹的返回一个值的语句块也是表达式：

  let a = {
      let b = 1;
      b + 1
  };
  

函数 ¶

fn add(i: i32, j: i32) -> i32 {
    i + j  // 不带分号，返回值；带分号了会返回 ()
}

• 定义函数使用关键字 fn
• 函数名、参数名使用蛇形命名
• 必须显式指定参数类型，除了返回 () 外要显式指定返回值类型
• 中途返回使用 return 关键字（带不带分号均可）
• 永不返回的函数类型为 !（相当于 python 类型标注中的 NoReturn），一般用于一定会抛出 panic 的函数或者无限循环：

  fn dead_end() -> ! {
      panic!("...");
  }
  fn forever() -> ! {
      loop { /*...*/ };
  }
  

所有权与借用 ¶

所有权 ¶

1. Rust 中每一个值都被一个变量所拥有，该变量被称为值的所有者
2. 一个值同时只能被一个变量所拥有，或者说一个值只能拥有一个所有者
3. 当所有者（变量）离开作用域范围时，这个值将被丢弃（drop）

其中作用域的概念和其他语言类似

String 类型 ¶

let s = "abc" 中 s 的类型为 &str，并不是 String，"abc" 是被硬编码的不可变的字面量。存储的时候是一个指针和字符串长度

而 String 则是通过堆来动态分配内存。比如 let s = String::from("abc")，调用 String 的 from 方法来创建一个 String

如果 s 是 mut 的，则可以通过 s.push_str("...") 来追加字面量

所有权转移 ¶

let x = 1;
let y = x;

let x = String::from("abc");
let y = x;

let x: &str = "abc";
let y = x;

• rust 永远不会自动创建数据的深拷贝
• 使用 .clone() 可以深拷贝存在堆上的数据，但性能降低

  let x = String::from("abc");
  let y = x.clone(); // 后面 x、y 均可用，因为是所有的是不同数据
  

函数传值与返回 ¶

向函数中传值也会发生移动或者复制

fn main() {
    let s = String::from("abc");
    print(s);
    // 这里 s 将不能使用
}

fn print(string: String) {
    println!("{}", string); // s 的所有权到这里
} // string 被释放

fn main() {
    let mut s = String::from("abc");
    s = print(s);
    println!("{}", s); // 这里 s 可用
}

fn print(string: String) -> String {
    println!("{}", string);
    string
}

引用与借用 ¶

rust 中也有引用的概念，获取一个变量的引用也称为借用（borrowing），使用 & 来进行引用，* 来解引用：

let x: i32 = 1;
let y: &i32 = &x; // 引用类型
assert_eq!(x, *y);

fn main() {
    let s = String::from("abc");
    let len = func(&s);    // 创建 s 的引用，并传入
    println!("{} {}", s, len); // s 仍可用
}

fn func(string: &String) -> usize { // 接收引用
    string.len()  // 直接调用方法
} // string 离开作用域，但它并不拥有任何值，所以不会发生什么

使用 &mut 可以创建可变引用，例如：

let mut x: i32 = 1;
let y: &mut i32 = &mut x;

fn main() {
    let mut s = String::from("abc");
    func(&mut s); // 创建 s 的可变引用
    println!("{}", s) // 输出 abc...
}

fn func(string: &mut String) { // 接收可变引用
    string.push_str("...")  // 可以进行更改
}

• 在同一个作用域内，一个数据只能有一个可变引用
• 可变引用和不可变引用不能同时存在

这样做的目的是避免产生数据竞争，以及防止不可变引用的值被可变引用所改变

以及如果存在引用，且后面用到了这个引用，则被引用的即使是 mut 的，也不能被修改，例如：

fn main() {
    let mut x = 1;
    let y = &x; //borrow later used here
    println!("{}, {}", x, *y);
    x = 2; // assignment to borrowed `x` occurs here
    println!("{}, {}", x, *y); // borrow later used here
}

以及如下代码也会编译错误：

fn main() {
    let mut x = 1;
    let y = &mut x;
    println!("{}, {}", x, *y); // cannot borrow `x` as immutable because it is also borrowed as mutable
}

避免悬垂引用 ¶

悬垂引用（dangling references）也称悬垂指针，意思是指针指向的值被释放掉了，导致指针指的位置不存在期望的内容。rust 不会允许这种情况发生，比如

fn dangle() -> &String {
    let s = String::from("abc");
    &s
}

复合类型 ¶

字符串 ¶

• &str 与 String 是两个不同的类型
• 可以使用 &s[a..b] 的方式来获取切片的引用，切片使用的是前面的 range 类型，语法和 python 的切片类似，同样可以省略头尾
  • 对一个 String 使用切片获得的引用类型也是 &str
  • 切片是按字节进行的，需要精确切到字符边界。例如对中文字符串进行切片，&s[0..3] 会切出一个汉字字符，而 &s[0..2] 没切完整会导致 panic
• 字符是 UCS-4 编码，字符串是 UTF-8 编码（每个字符字节数不定）
• String 与 &str 转换
  • &str -> String
    • String::from("...")
    • "...".to_string()
  • String -> &str
    • &s / &s[..]
    • s.as_str()
• String 操作
  • .push('a') 追加字符 / .push_str("...") 追加字符串
  • .insert(n, 'a') 在索引 n 的位置插入字符 / .insert(n, "...") 同理插入字符串
  • .replace("aaa", "AAA") 全局替换所有 "aaa" 到 "AAA"，返回替换后的新字符串，原字符串不变
  • .replacen("aaa", "AAA") 同上，但只替换 n 次
  • .replace_range(a..b, "...") 将索引 a..b 的范围替换为新字符串 "..."，直接操作原字符串
  • .pop() 删除并返回最后一个字符，返回值为一个 Option，若字符串为空则返回 None
  • .remove(n) 删除以索引 n 开头的一个字符
  • .truncate(n) 删除索引 n 开头及之后的所有字符
  • .clear() 清空字符串
  • 使用 + 或 += 连接一个 &str 字符串（不能是 String）
    • + 运算符左侧的变量将失效，因为所有权转移到了 .add() 方法中然后被释放
  • 可以使用 let s = format!("{} {}", s1, s2) 来连接创建新的字符串
• 字符串转义
  • "\x.." 十六进制表示，必须在 \x00 到 \x7f 之间
  • "\u{....}" 用 codepoint 表示一个 unicode 字符
  • 可以直接换行，但从下一行行首开始就记录文本（也就是不当作缩进忽略），行尾加 不换行，且下一行行首空格忽略
  • 其它转义和其它语言均类似
  • r"..." 中的 不参与转义（和 python 类似）
  • r#"..."# 中的双引号不会提前结束字符串（也就相当于不需要转义双引号）
  • r##"..."## 中的 "# 也不会提前结束字符串（双引号前后的井号加多少都可以，只需要匹配即可）
• 操作 UTF-8 字符串
  • 循环遍历字符可以使用 for c in "...".chars()
  • 循环遍历字节可以使用 for c in "...".bytes()
  • 其它操作标准库中没有，需要通过别的 crates

元组 ¶

• 长度固定，元素顺序及类型固定的复合类型，例如 let t: (i32, f64) = (1, 1.1);
• 使用模式匹配获取元组中的值：let (a, b) = t;
• 使用 . 来访问元组内容：t.0 == 1

结构体 ¶

使用 struct 关键字来定义结构体，指明字段名与类型：

struct User {
    name: String,
    age: u32,
    email: String,
}

let user1 = User {
    age: 19_u32,
    name: String::from("TonyCrane"),
    email: String::from("tonycrane@foxmail.com"),
};

另外，在结构体中使用引用类型需要用到生命周期

简化创建 ¶

fn build_user(name: String, age: u32) -> User {
    User {
        name,  // name: name 缩写
        age,   // age: age 缩写
        email: String::from(""),
    }
}

更新结构体 ¶

通过已有结构体实例创建新实例：

let user2 = User {
    email: String::from("another@example.com"),
    ..user1 // 必须写在后面
};

元组结构体 ¶

可以定义像元组一样没有字段名的结构体：

struct Point(i32, i32, i32);
let point = Point(0, 0, 0);

单元结构体 ¶

像单元类型一样，没有任何字段和属性的结构体。作用上来看就是不关心数据，但关心行为（后面 impl 之类的）

struct UnitLikeStruct;
let a = UnitLikeStruct;

打印结构体 ¶

结构体不能直接被放在 {} 中打印，因为没有实现 Display trait

一种方便的输出方式是利用 #[derive(Debug)] 来自动实现 Debug trait 来利用 {:?} 格式化或 dbg! 宏进行 debug 打印：

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect = Rectangle { width: 30, height: 50 };
    println!("{:?}", rect);
    dbg!(rect); // 输出到 stderr 流中
}

Rectangle { width: 30, height: 50 }
[src/main.rs:10] rect = Rectangle {
    width: 30,
    height: 50,
}

枚举 ¶

使用 enum 关键字来定义枚举类型，用 :: 来访问成员，可以包含值：

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {
    let m1 = Message::Quit;
    let m2 = Message::Move{ x: 1, y: 1 };
    let m3 = Message::ChangeColor(255, 255, 0);
}

Option¶

类似 Haskell 中的 Maybe，定义是：

enum Option<T> {
    Some(T),
    None,
}

数组 ¶

• rust 中数组长度固定，必须有相同类型，存储线性排列在栈上，速度快
• 一个数组的类型是 [元素类型; 元素个数]，例如 [i32; 5] 表示包含 5 个 i32 的数组
• 使用同一个重复元素初始化数组，例 let a = [3; 5] 即 a 为包含 5 个 3 的数组
• 索引使用 []，与其它语言相同
• 越界访问会触发 panic
• 和字符串一样可以创建切片引用

流程控制 ¶

分支 ¶

• if - else if - else 结构
• 条件不需要加括号
• if 语句块是表达式，可以用来赋值

循环 ¶

• for 循环
  • for ... in ... 结构
  • in 后面的集合一般需要使用引用，否则会将所有权移至 for 块内（实现了 Copy trait 的除外）
  • 循环中修改元素的话一般需要使用可变引用
  • 带索引循环

    let a = [4, 3, 2, 1];
    for (i, v) in a.iter().enumerate() {
        // ...
    }
    

  • 仅循环多少次：for _ in 0..10 循环 10 次
  • 可以使用 continue 和 break 控制循环
• while 循环
  • 没什么特别的
• loop 循环
  • 不会自动停止，需要靠 break
  • 是一个表达式，可以利用 break 来返回一个值

    let result = loop {
        cnt += 1;
        if cnt == 10 {
            break cnt * 2;
        }
    };
    

rust 中可以使用 label 来指定多重循环中 break 或 continue 哪一层循环：

'outer: for i in 0..10 {
    println!("Outer: #i = {}", i);
    'inner: for j in 0..10 {
        println!("Inner: #j = {}", j);
        if j == i { continue 'outer; }
        if i == 5 { break 'outer; }
        if j != 0 { continue 'inner; }
        println!("...");
    }
}

模式匹配 ¶

rust 中有很多模式匹配，比如 let 语句、for 循环本身就相当于模式匹配：

let (x, y) = (1, 2);
for (index, value) in v.iter().enumerate() { /* ... */ }

fn func(&(x, y): &(i32, i32)) {
    // x 和 y 会从这一个参数中匹配出来
}

match 语句 ¶

类似 python 的 match-case 语句，以及 Haskell 的模式匹配以及守卫语法

match target {
    pattern1 => expression1,
    pattern2 => {
        statements1;
        statements2;
        expression2
    },
    pattern3 | pattern4 => expression3,
    _ => expression4,
}

• 整个 match 语句块是一个表达式
• match 必须穷举出所有模式，未列出的剩余部分使用通配符 _ 表示其它所有可能性
  • _ 不会被绑定，可以多次使用，其匹配到的值都会被忽略
• match 的每一个分支都必须是一个表达式，且所有分支的表达式返回值类型需要相同
• | 表示或，即匹配二者中的一个即可
• 可以利用模式匹配来绑定新变量
• 序列也可以作为模式，比如 x = 5 就可以匹配模式 1..=5
• 可以使用 .. 来忽略剩余值

  let origin = Point { x: 0, y: 0, z: 0 };
  match origin {
      Point { x, .. } => println!("x is {}", x),
  }
  let numbers = (2, 4, 8, 16, 32);
  match numbers {
      (first, .., last) => println!("Some numbers: {}, {}", first, last),
  }
  

• 可以在模式后面增加额外的 if 条件，称为匹配守卫（match guard）

  let num = Some(4);
  match num {
      Some(x) if x >= 0 & x < 5 => println!("less than five: {}", x),
      Some(x) => println!("{}", x),
      None => (),
  }
  

  • 在有 | 的情况下，if 语句的条件会作用于所有的模式，而不是最后一个
• 可以使用 @ 来为字段绑定变量，比如上面的例子里第一个匹配可以写为 Some(x @ 0..5)
  • Rust 1.53 新语法：如 num @ (1 | 2) => ... 将 1 或 2 绑定到 num 变量上
  • Rust 1.56 新语法：和 Haskell 中 @ 用法类似，在解构的同时保留原值，如

    let p @ Point {x: px, y: py} = Point {x: 10, y: 20};
    // p = Point {x: 10, y: 20}, px = 10, py = 20
    

if let / while let¶

只需要匹配一个模式、忽略其它模式时，可以使用 if let 语句来简化，比如下面代码

let v = Some(1);
match v {
    Some(1) => println!("!"),
    _ => (),
}

let v = Some(1);
if let Some(1) = v { // 是一个等号，不是双等号
    println!("!");
}

let mut stack = Vec::new();
// ...
while let Some(top) = stack.pop() {
    println!("pop {}", top);
}

matches! 宏 ¶

仅仅需要判断一个值是否和一个模式匹配的话可以使用 matches! 宏：

matches!(value, pattern)

方法 ¶

Rust 中使用 impl 块来为结构体定义方法，可以当作，struct 定义“类”的属性，impl 块中定义“类”的方法

impl StructName {
    fn new(...) -> StructName {
        StructName {
            ...
        }
    }
    fn method(&self, ...) -> ... {
        ...
    }
}

• 一个方法的第一个参数为 self 等，表示自身，且服从所有权规则
  • self：将调用者的所有权转移到方法中，少用（类型为 Self，表示结构体自身类型）
  • &self：在方法中使用调用者的不可变借用，常用（实际上是 self: &Self 的语法糖）
  • &mut self：在方法中使用调用者的可变借用，常用
• 方法名可以与字段名相同（一般用来实现 getter）
• rust 会为 &self 等自动引用与解引用
• impl 块中没有 self 参数的函数称为关联函数（如上面的 new）
  • 不能使用 . 来以方法的形式调用
  • 应该使用 :: 来调用（相当于调用这个结构体命名空间中的函数）
  • new 一般用来作为构造器，即从参数返回一个结构体
• 可以在多个 impl 块中为同一个结构体定义方法
• impl 也可以为枚举类型定义方法

泛型 Generics ¶

fn add<T: std::ops::Add<Output = T>>(a: T, b: T) -> T {
    a + b         // ^ 保证可以 T 相加并得到 T 类型的结果
}

• <T> 为一个函数规定一个泛型 T，冒号后面接需要的 trait 来添加限制
• 可以通识定义多个泛型，用逗号隔开即可
• 结构体、枚举等都可以使用泛型

  struct Point<T> {
      x: T,
      y: T,
  }
  impl<T> Point<T> {
      //... 这里可以使用 T
  }
  enum Option<T> {
      Some(T),
      None,
  }
  

• 可以为带泛型的结构体针对某一具体类型实现方法：

  impl Point<f32> {
      // only for Point<f32>
  }
  

• 调用泛型函数

  struct SGen<T>(T);
  fn func<T>(arg: SGen<T>) { /* ... */}
  fn main() {
      func(SGen('a'));         // 隐式指定类型参数 T 为 char
      func::<char>(SGen('a')); // 显式指定类型参数 T 为 char
  }
  

• const 泛型，定义一个基于值的泛型参数

  fn func<T: ..., const N: usize>(arr: [T; N]) {
      // ...
  }
  

  • const 泛型参数只能接受不带其它泛型参数的实参

特征 Trait ¶

特征类似于 python 中的抽象基类，规定一些必须有的方法，但差别还是很大

• 定义 trait

  pub trait MyTrait {
      fn func1(&self) -> ...; // 分号结尾，不用写函数内容
      fn func2(&self) -> ... {
          ... // 提供默认实现
      }
  }
  

  • pub 关键字使之可以从外部导入
  • trait 块中对于需要实现的方法可以只写签名，也可以将函数写完整来提供一个默认实现
• 为类型实现特征

  impl MyTrait for MyType {
      fn func1(&self) -> ... {
          ...
      }
  }
  

  • 孤儿规则：为 A 类型实现特征 T，则 A 和 T 中至少有一个在当前作用域中定义，例如不可以为标准库中的类型实现其它标准库中的特征。确保某一库中的代码不会被在被使用的时候破坏
  • 如果一个特征的方法都有默认实现，则花括号内可以不写任何东西
• 特征约束
  • 参数里直接写特征是泛型的一个语法糖，以下两行代码效果一样

    pub fn func(arg: &impl MyTrait) {}
    pub fn func<T: MyTrait>(arg: &T) {}
    

  • 参数里有特征时不会强制所有这样的参数为同一类型，比如以下三行代码 1 和 2 等价、和 3 不等价

    pub fn func(a: &impl MyTrait, b: &impl MyTrait) {}
    pub fn func<T: MyTrait, U: MyTrait>(a: &T, b: &U) {}
    pub fn func<T: MyTrait>(a: &T, b: &T) {}
    

  • 多重约束

    pub fn func(arg: &(impl Trait1 + Trait2)) {}
    pub fn func<T: Trait1 + Trait2>(arg: &T) {}
    

  • where 约束

    pub fn func<T, U>(t: &T, u: &U) -> ...
        where T: Trait1 + Trait2 + Trait3,
              U: Trait4 + Trait5 + Trait6
    {}
    

  • 函数返回值可以只说实现了某个特征的类型，而不明确规定

    fn func() -> impl MyTrait {}
    

• derive 可以派生特征，使用默认实现，如前面写过的 #[derive(Debug)]
  • Debug、PartialEq、Eq、PartialOrd、Ord、Clone、Copy、Hash、Default
  • 多个的话中间逗号分隔
• 调用实现了某一特征的类型的方法时需要先用 use 将特征引入
• 例子
  • 为 Point 实现加法

    use std::ops::Add;
    #[derive(Debug)]
    struct Point<T: Add<T, Output = T>> {
        x: T,
        y: T,
    }
    impl<T: Add<T, Output = T>> Add for Point<T> {
        type Output = Point<T>; // 关联类型
        fn add(self, p: Point<T>) -> Point<T> {
            Point {
                x: self.x + p.x,
                y: self.y + p.y,
            }
        }
    }
    

  • 为 Point 实现格式化输出

    use std::fmt;
    use std::fmt::Display;
    impl Display for Point {
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
            write!(f, "({}, {})", self.x, self.y)
        }
    }
    

特征对象 ¶

比如使用一个 Vec 来存储实现同一个特征的不同类型的时候，就需要用到特征对象，例如 Vec<Box<dyn MyTrait>>

• 使用泛型来代替的话，Vec 中的所有值类型必须一致
• 只能使用 & 引用或者使用 Box 智能指针来创建特征对象
  • &dyn MyTrait 在用的时候需要用 & 借用
  • Box<dyn MyTrait> 在用的时候需要通过 Box::new(...) 来基于某个值创建智能指针
  • 创建的时候不需要加 dyn
  • 不使用这两种方法的话，大小会未知，但 &dyn 和 Box<dyn> 大小都已知
  • dyn 代表动态分发（dynamic dispatch）
• 特征对象的限制：只有对象安全的特征才能创建特征对象
  • 对象安全：
    • 方法的返回类型不能是 Self
    • 方法没有任何泛型参数
  • Clone 特征的 clone 方法返回的就是 Self，因此它不是对象安全的。Box<dyn Clone> 的写法会报错

关联类型 ¶

关联类型定义 trait 块中，可以在后续的方法中使用该类型。例如 Iterator 的定义：

pub trait Iterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
}

这种写法比为 Iterator 增加一个泛型更有可读性，而且写起来也简便

默认泛型类型参数 ¶

例如 Add 这个 trait：

trait Add<RHS=Self> {
    type Output;
    fn add(self, rhs: RHS) -> Self::Output;
}

Add 的 RHS 泛型参数带有一个默认值 Self，也就是说，在 impl 的时候，如果不为 Add 指定类型，则默认 RHS 是 Self，即要加的东西类型和被加的东西类型一致。例如：

struct Point {
    x: i32,
    y: i32,
}
impl Add for Point { // 默认就是要加 Point
    type Output = Point;
    fn add(self, other: Point) -> Point {
        ...
    }
}

同名方法调用 ¶

当一个类型的方法与它实现的 trait 的方法名重名时，直接调用会调用类型上的方法。想要调用 trait 上的方法时需要使用 :: 来显式调用，如：

trait A { fn func(&self); }
trait B { fn func(&self); }
struct C;

impl A for C {
    fn func(&self) { println!("A"); }
}
impl B for C {
    fn func(&self) { println!("B"); }
}
impl C {
    fn func(&self) { println!("C"); }
}

fn main() {
    let c = C;
    c.func();       // C
    A::func(&c);    // A
    B::func(&c);    // B
    C::func(&c);    // C 与第一个相同，但显式调用
}

这样调用的一个条件是方法的第一个参数是 self（又叫方法接收器 receiver），但如果是关联函数的话，就没有这个 receiver，rust 也就自然不知道是调用哪个类型实现的特征上的方法

这时需要使用完全限定语法：

<Type as Trait>::function(receiver_if_method, next_arg, ...);

trait A { fn func(); }
struct B;

impl A for B {
    fn func() { println!("A"); }
}
impl B {
    fn func() { println!("B"); }
}

fn main() {
    B::func();          // B
//  A::func();          // 报错
    <B as A>::func();   // A
}

trait 定义中的 trait 约束 ¶

如果在定义特征 A 的时候需要使用特征 B 的方法，则 A 和 B 都要实现（实现了就好，先后无所谓）。在定义 A 的时候就可以在后面加上约束 B：

trait A: B {
    ...
}

绕过孤儿规则 ¶

绕过孤儿规则，也就是在外部类型上实现外部特征，一种方法是使用 newtype 模式，即创建一个元祖结构体来包装外部类型，这样就构造了一个在当前作用域内的新类型

比如想要为 Vec<String> 实现 Display trait，二者都在标准库中，无法直接实现。使用 newtype 模式：

use std::fmt;
struct Wrapper(Vec<String>);
impl fmt::Display for Wrapper {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "[{}]", self.0.join(", "))
    }
}

fn main() {
    let w = Wrapper(vec![String::from("abc"), String::from("def")]);
    println!("w = {}", w);
}

集合类型 ¶

Vector¶

• 动态数组，类型 Vec<T>
• 创建
  • 使用 Vec::new() 创建
    • 如果预先知道容量，可以使用 Vec::with_capacity(cap) 创建，会提升性能
  • 使用 vec! 宏来创建，同时给予初值

    let v = vec![1, 2, 3]; // 自动推断类型
    

  • 使用 Vec::from(...) 来从数组创建
• Vector 类型在移出作用域后会自动删除，其存储的内容也会被删除
• 操作
  • .push(...) 在末尾添加元素
  • .pop() 剔除末尾元素
  • .extend(...) 扩展
  • .len() 获取长度
  • 可以使用切片来借用元素（越界会 panic）
  • .get(index) 来根据索引访问元素，返回类型是 Option<&T>（越界返回 None）
  • for i in &v 遍历
  • 利用 enum 或特征对象来存储不同类型的

HashMap¶

• 存储键值对，类型 HashMap<K, V>
• 需要使用 std::collections::HashMap 引入
• key 一定要实现 Hash 和 Eq trait
  • f32 和 f64 不可以
• 创建
  • HashMap::new()
  • HashMap::with_capacity(cap)
  • 使用迭代器和 collect

    let lst = vec![(key1, value1), (key2, value2), ...];
    let map: HashMap<_, _> = lst.into_iter().collect();
    

• 操作
  • .insert(key, value) 插入一个键值对
  • .get(key) 获取值，返回 Option<V> 类型
  • 直接使用 [key] 获取值，没有 key 会 panic
  • .entry(key).or_insert(value)
    • 如果存在 key，则返回 key 对应的值
    • 如果不存在 key，则插入 key-value 键值对
    • 返回一个 &mut V 引用，可以直接修改 map 中内容
  • .contains_key(key) 查询是否存在 key

类型转换 ¶

• 一般情况下（方法调用除外）Rust 不会进行隐式的类型转换
• 使用 as type 进行显式的转换
• 超过最大值会溢出，如 300_i32 as i8 会得到 44，而不会 panic
• 内存地址转换为指针

  let mut values: [i32; 2] = [1, 2];
  let p1: *mut i32 = values.as_mut_ptr();
  let first_address = p1 as usize; // 将 p1 内存地址转换为一个整数
  let second_address = first_address + 4;
  let p2 = second_address as *mut i32; // 访问该地址指向的下一个整数 p2
  unsafe {
      *p2 += 1;
  }
  assert_eq!(values[1], 3);
  

• TryInto 转换
  • use std::convert::TryInto，但不必要，在 prelude 中
  • TryInto trait 有 .try_into 方法，返回一个 Result，使用 .unwrap() 提取

    let a: u16 = 1500;
    let b: u8 = b.try_into().unwrap();
    

  • 大类型转换为小类型会返回 Err(e)

方法调用时的强制类型转换 ¶

例如在调用 a.func() 时（a 的类型为 T），编译器会进行以下操作

1. 尝试值方法调用，即 T::func(a)
2. 如果上一步无法完成，则尝试引用方法调用，即
   • <&T>::func(a)
   • <&mut T>::func(a)
3. 如果上一步仍然无法完成，则试着解引用 T，如果 T 满足 Deref<Target = U>，即 T 可以被解引用为 U，则编译器会使用 U 类型尝试调用（从 1 开始同样的步骤），称为解引用方法调用
4. 如果 T 不能被解引用，且 T 是一个定长类型，则编译器会尝试将 T 转为不定长类型（例如 [i32; 2] 转为 [i32]）
5. 如果上面都不行，则不能通过编译

let array: Rc<Box<[T; 3]>> = ...;
let a = array[0]; // 可以获取第一个元素

fn func<T: Clone>(value: &T) {
    let cloned = value.clone();
}

fn func<T>(value: &T) {
    let cloned = value.clone();
}

返回值与错误处理 ¶

Rust 认为的两种错误：

• 可恢复错误，只影响用户自身的操作，不会对系统产生影响
• 不可恢复错误，全局性或者系统性的错误，对于系统影响很大

Rust 推荐可恢复错误使用 Result<T, E> 返回值等待后续处理异常，不可恢复错误直接 panic 终端程序

panic¶

• 可以通过 panic! 宏来直接抛出一个 panic
• 运行时带有 RUST_BACKTRACE=1 环境变量的话，会显示回溯栈（需要开启 debug 标志）
• panic 时有两种方式来终止：
  • 栈展开：回溯栈上数据和函数调用，可以提供充分报错信息和栈调用信息
  • 直接终止：不清理数据，直接退出程序，交给系统来清理
  • 默认情况是栈展开
  • 直接终止编译出的可执行文件更小，可以在 release 时指定使用直接终止：

    [profile.release]
    panic = 'abort'
    

• 如果是 main 线程 panic 了，则程序终止。如果子线程 panic 了，则线程终止，main 线程仍然运行，程序不会结束

Result¶

Result 是一个枚举类型，定义为：

enum Result<T, E> {
    Ok(T),
    Err(E),
}

• 使用 match 来处理 Result 类型
  • 例如 IO 错误，可以对于 Err(error) 再匹配 error.kind()，其可能的值在 std::io::ErrorKind 中
  • 可以配合 panic，将 error 用 debug 模式（{:?}）进行输出
• 对于 Result，如果失败就 panic
  • 使用 .unwrap()：如果是 Err 则会 panic，并输出错误内容
  • 使用 .expect("...")：同样 panic，但会显示为 panicked at '...: Err 内容'
• ? 传播错误
  • 在函数中判断 Result，并传递返回 Err 可以写为

    fn func() -> Result<String, io::Error> {
        let f = File::open("test.txt");
        let mut f = match f {
            Ok(file) => file,
            Err(e) => return Err(e),
        };
        let mut s = String::new();
        match f.read_to_string(&mut s) {
            Ok(_) => Ok(s),
            Err(e) => Err(e),
        }
    }
    

  • 其中 match-return Err 部分可以利用 ? 来简写：

    let mut f = File.open("test.txt")?;
    

  • ? 在返回 Err 的时候会自动转换错误类型，例如：

    fn func() -> Result<File, Box<dyn std::error::Error>> {
        let mut f = File::open("test.txt")?;
        Ok(f)
    }
    

    • 在 ? 处理返回错误的时候，得到的是 std::io::Error 类型，? 可以自动调用 From trait 的 from 方法，将 std::io::Error 转为需要的 Box<dyn std::error::Error>
  • ? 可以进行链式调用：

    fn func() -> Result<String, std::io::Error> {
        let mut s = String::new();
        File::open("test.txt")?.read_to_string(&mut s)?;
        Ok(s)
    }
    

    • 对于这个操作，Rust 标准库提供了 std::fs::read_to_string(filename) 函数，而且返回的就是 Result<String, std::io::Error>
• ? 结合 Option
  • 和 Result 同理，? 也适用于 Option 的返回，也就是得到 None 就立即返回 None，否则展开出 Some 中的值
• main 函数返回值
  • main 函数可以有返回值类型 Result<(), Box<dyn std::error::Error>>
  • 只有声明了这种返回值的 main 函数中才可以使用 ? 来提前探测错误终止 main 函数：

    use std::error::Error;
    use std::fs::File;
    fn main() -> Result<(), Box<dyn Error>> {
        let f = File::open("test.txt")?;
        Ok(())
    }
    

• try! 宏
  • ? 的早期版本，避免使用
  • 定义：

    macro_rules! try {
        ($e:expr) => (match $e {
            Ok(val) => val,
            Err(err) => return Err(::std::convert::From::from(err)),
        });
    }
    

  • 使用方法，以下两行等价：

    let x = func()?;
    let x = try!(func());
    

包和模块 ¶

crate 与 package ¶

• crate 是一个独立的可编译单元，可以编译出可执行文件或者一个库
• package 是 cargo 创建的包含 Cargo.toml 的“项目”，可以包含因为功能性被组织在一起的一个 crate 或多个 crate
  • 一个 package 只能包含一个库（library）类型的 crate，可以包含多个二进制类型的 crate
  • cargo new 默认创建的就是二进制 package
    • src/main.rs 是二进制 crate 的根文件，其包名和所属 package 相同，入口点在 main 函数
  • cargo new <name> --lib 创建库 package
    • 库 package 只能作为第三方库被引用，不能使用 cargo run 运行
    • src/lib.rs 是库类型同名 crate 的根文件

典型 package 结构 ¶

.
├── Cargo.toml
├── Cargo.lock
├── src
│   ├── main.rs    // 默认二进制 crate（编译生成 package 同名可执行文件）
│   ├── lib.rs     // 唯一库 crate
│   └── bin        // 其余二进制 crate（分别生成文件名同名可执行文件）
│       └── main1.rs
│       └── main2.rs
├── tests     // 集成测试
│   └── some_integration_tests.rs
├── benches   // 基准性能测试 benchmark 文件
│   └── simple_bench.rs
└── examples  // 示例
    └── simple_example.rs

模块 Module ¶

• 在 lib.rs 中使用 mod 关键字创建模块，后接模块名
• mod 可以嵌套，模块中可以定义各种 rust 类型
• src/main.rs 和 src/lib.rs 称为 crate root
• 模块使用 :: 逐级访问
  • crate 指根，使用 crate 也就相当于使用绝对路径
  • super 指父模块（上一级），相当于文件系统中的 ..
  • self 指自身模块

如下 lib.rs：

mod A {
    mod B {
        fn func_a() {
            self::func_b();
        }
        fn func_b() {
            super::C::func_c();
        }
    }
    mod C {
        fn func_c() {}
    }
}
pub fn func() {
    crate::A::B::func_a(); // 绝对路径引用
    A::B::func_b();        // 相对路径引用
    self::A::C::func_c();  
}

crate
  ├── func
  └── A
      ├── B
      │   ├── func_a
      │   └── func_b
      └── C
          └── func_c

• 仅使用 mod name; 将创建一个模块，并从同目录下同名的 name.rs 中加载模块内容

代码可见性 ¶

• 默认情况下，所有类型（函数、方法、结构体、枚举……）都是私有的
• 父模块无法访问子模块中的私有项，而子模块可以访问父模块及更上层的模块的私有项
• 使用 pub 关键字将模块、函数等标为对外可见的
• 结构体与枚举的可见性
  • 仅将结构体设置为 pub，其内部所有字段仍然是私有的
  • 仅将枚举设置为 pub，则其内部所有字段都对外可见

use 引入 ¶

• 使用 use 关键字来引入模块或类型，来简化调用
• 要避免同名调用
• 使用 as 来设置别名解决冲突问题，例如：

  use std::fmt::Result;
  use std::io::Result as IoResult;
  

• 利用 use 导出，如：

  mod A {
      pub mod B {
          pub fn func_b() {}
      }
  }
  pub use crate::A::B;
  pub fn func() {
      B::func_b();
  }
  

  • 从外部调用的时候也可以直接使用 B 模块
• 可以使用 {} 来简化

  use std::collections::{
      HashMap,
      BTreeMap,
      HashSet
  };
  use std::{cmp::Ordering, io};
  

  • {} 中可以使用 self：

    use std::io::{self, Write}
    // 即 use std::io 以及 use std::io::Write
    

• 使用 * 引入模块下所有公开项，如 use std::collections::*;，但要小心名称冲突

使用第三方包 ¶

例如使用 rand 包：

1. 修改 Cargo.toml，在 [dependencies] 中添加 rand = "0.8.3"
2. 在代码中使用 rand::... 即可

   use rand::Rng; // trait
   fn main() {
       let n = rand::thread_rng().gen_range(1..101);
   }
   

可以在 crates.io 或 lib.rs 中检索使用第三方包

受限可见性 ¶

• pub 表示无任何限制的完全可见
• pub(crate) 表示在当前包内可见
• pub(self) 表示在当前模块中可见
• pub(super) 表示在父模块中可见
• pub(in <path>) 表示在 <path> 代表的模块中可见

三种模块目录组织方式 ¶

• Rust 2015

  .
  ├── lib.rs
  └── foo/
      ├── mod.rs
      └── bar.rs
  

  • lib.rs 中 mod foo; 会引入 foo/mod.rs 中内容
  • 需要在 foo/mod.rs 中继续为 bar.rs 创建同名 mod
• Rust 2018

  .
  ├── lib.rs
  ├── foo.rs
  └── foo/
      └── bar.rs
  

  • lib.rs 中 mod foo; 会引入 foo.rs
  • 在 foo.rs 中 mod bar;
  • 与 2015 的模式相比就相当于将 mod.rs 提到文件夹外的同名文件了
• 使用 #[path = ...] 创建模块（慎用）

  .
  ├── lib.rs       
  └── pkg/        // 任意
      ├── foo.rs
      └── bar.rs
  

  • lib.rs 中在 mod foo; 前指定路径：

    #[path = "./pkg/foo.rs"]
    pub mod foo;
    
    #[path = "./pkg/bar.rs"]
    pub mod bar;
    

注释与文档 ¶

Rust 中注释分为两类：

• 代码注释：说明某一段代码的作用（// 行注释和 /* ... */ 块注释）
• 文档注释：使用 markdown 语法，描述项目、介绍功能、生成文档
  • 包和模块注释：说明当前包和模块的功能

文档注释 ¶

• 文档行注释 /// 与文档块注释 /** ... */
  • 文档注释需要位于库类型的 crate 中
  • 可以使用 markdown 语法，以及代码块高亮显示
  • 写在被注释类型上方
  • 被注释的对象需要 pub 对外可见
  • 文档注释中可以直接使用多个一级标题，常用的有
    • # Examples
    • # Panics：描述函数可能会出现的 panic 情况
    • # Errors：描述可能会出现的错误以及触发情况
    • # Safety：unsafe 代码需要注意的使用条件
• 包 / 模块级别行注释 //! 与包 / 模块级别块注释 /*! ... */
  • 写在 crate root 的最上方
• 使用 cargo doc 构建文档，生成在 target/doc 目录下
  • 使用 cargo doc --open 构建并打开
• 文档测试
  • 文档注释中的代码块可以用作测试，直接写 assert 等宏就可以
  • 使用 cargo test 会进行测试，并显示 "Doc-tests ..."
  • 预期会造成 panic 等代码块需要在代码块语言后加上 should_panic：

    /// # Panics
    /// 
    /// ```rust,should_panic
    /// ...
    /// ```
    

  • 仅测试，不显示在文档中的行开头加 # 就可以：

    /// ```
    /// # fn try_main() -> Result<(), String> {
    /// let res = ...::func()?;
    /// #     Ok(())
    /// # }
    /// # fn main() {
    /// #     try_main().unwrap();
    /// # }
    

    • 如上述例子，最终在文档中只会显示 let 那一行，但在进行 doc-test 时全部代码都会运行
• 代码跳转（自动链接）
  • 文档中写 [`Option`] 会在文档中创建一个指向标准库中 Option 类型的链接
  • 也可以指定具体的路径来创建指向自己代码或其它库中指定项的链接
  • 同名项可以标示类型：

    /// 跳转到结构体  [`Foo`](struct@Foo)
    pub struct Bar;
    
    /// 跳转到同名函数 [`Foo`](fn@Foo)
    pub struct Foo {}
    
    /// 跳转到同名宏 [`foo!`]
    pub fn Foo() {}
    
    #[macro_export]
    macro_rules! foo {
      () => {}
    }
    

• 文档搜索别名

  #[doc(alias = "x")]
  #[doc(alias = "big")]
  pub struct BigX;
  
  #[doc(alias("y", "big"))]
  pub struct BigY;
  

  • 如上代码，在文档中搜索的时候，搜索 x 就会命中 BigX

格式化输出 ¶

Rust 的格式化就比较类似于 python 的 format 了

• 格式化宏
  • print!：格式化文本到标准输出，不换行
  • println!：格式化文本到标准输出，换行
  • format!：格式化文本，返回 String
  • eprint! 与 eprintln!：格式化到标准错误输出
• 占位符
  • {} 适用于实现了 std::fmt::Display trait 的类型，用于展示给用户
  • {:?} 适用于实现了 std::fmt::Debug trait 的类型，用于调试
  • {:#?} 同上，不过显示更优美（自动换行一类）
• 实现 Display trait

  use std::fmt;
  impl fmt::Display for ... {
      fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
          write!(f, "...{}...", ...)
      }
  }
  

  • 只能为当前作用域中的类型实现 Display trait
  • 为外部类型实现 Display 可以使用 newtype 模式
• 位置参数

  fn main() {
      println!("{}{}", 1, 2); // =>"12"
      println!("{1}{0}", 1, 2); // =>"21"
      // => Alice, this is Bob. Bob, this is Alice
      println!("{0}, this is {1}. {1}, this is {0}", "Alice", "Bob");
      println!("{1}{}{0}{}", 1, 2); // => 2112
  }
  

  • 对于 {:?} 或 {:#?}，将位置参数加在冒号前就可以
• 具名参数

  fn main() {
      println!("{argument}", argument = "test"); // => "test"
      println!("{name} {}", 1, name = 2); // => "2 1"
      println!("{a} {c} {b}", a = "a", b = 'b', c = 3); // => "a 3 b"
  }
  

  • 带名称的参数只能放在不带名称的后面
• 格式化参数
  • 宽度填充
    • 字符串

      //-----------------------------------
      // 以下全部输出 "Hello x    !"
      // 为"x"后面填充空格，补齐宽度5
      println!("Hello {:5}!", "x");
      // 使用参数5来指定宽度
      println!("Hello {:1$}!", "x", 5);
      // 使用x作为占位符输出内容，同时使用5作为宽度
      println!("Hello {1:0$}!", 5, "x");
      // 使用有名称的参数作为宽度
      println!("Hello {:width$}!", "x", width = 5);
      //-----------------------------------
      
      // 使用参数5为参数x指定宽度，同时在结尾输出参数5 => Hello x    !5
      println!("Hello {:1$}!{}", "x", 5);
      

    • 数字

      // 宽度是5 => Hello     5!
      println!("Hello {:5}!", 5);
      // 显式的输出正号 => Hello +5!
      println!("Hello {:+}!", 5);
      // 宽度5，使用0进行填充 => Hello 00005!
      println!("Hello {:05}!", 5);
      // 负号也要占用一位宽度 => Hello -0005!
      println!("Hello {:05}!", -5);
      

    • 对齐

      // 以下全部都会补齐5个字符的长度
      // 左对齐 => Hello x    !
      println!("Hello {:<5}!", "x");
      // 右对齐 => Hello     x!
      println!("Hello {:>5}!", "x");
      // 居中对齐 => Hello   x  !
      println!("Hello {:^5}!", "x");
      
      // 对齐并使用指定符号填充 => Hello x&&&&!
      // 指定符号填充的前提条件是必须有对齐字符
      println!("Hello {:&<5}!", "x");
      

  • 精度

    let v = 3.1415926;
    // 保留小数点后两位 => 3.14
    println!("{:.2}", v);
    // 带符号保留小数点后两位 => +3.14
    println!("{:+.2}", v);
    // 不带小数 => 3
    println!("{:.0}", v);
    // 通过参数来设定精度 => 3.1416，相当于{:.4}
    println!("{:.1$}", v, 4);
    
    let s = "abcded";
    // 保留字符串前三个字符 => abc
    println!("{:.3}", s);
    // {:.*}接收两个参数，第一个是精度，第二个是被格式化的值 => Hello abc!
    println!("Hello {:.*}!", 3, "abcdefg");
    

  • 进制

    // 二进制 => 0b11011!
    println!("{:#b}!", 27);
    // 八进制 => 0o33!
    println!("{:#o}!", 27);
    // 十进制 => 27!
    println!("{}!", 27);
    // 小写十六进制 => 0x1b!
    println!("{:#x}!", 27);
    // 大写十六进制 => 0x1B!
    println!("{:#X}!", 27);
    
    // 不带前缀的十六进制 => 1b!
    println!("{:x}!", 27);
    
    // 使用0填充二进制，宽度为10 => 0b00011011!
    println!("{:#010b}!", 27);
    

  • 指数

    println!("{:2e}", 1000000000); // => 1e9
    println!("{:2E}", 1000000000); // => 1E9
    

  • 指针地址

    let v = vec![1, 2, 3];
    println!("{:p}", v.as_ptr()) // => 0x600002324050
    

  • 输出 { 或 } 要写两次进行转义
• 1.58 中新增捕获环境值
  • 类似 python 中的 f-string，不过不需要特殊标注
  • 捕获变量可以替换在任何位置

    let (width, precision) = get_format();
    for (name, score) in get_scores() {
        println!("{name}: {score:width$.precision$}");
    }
    

  • panic! 在 2021 版本下才可以这样使用