閱讀 Rust 文件

知道如何閱讀 Rust 文件是很重要的，這樣你才能理解其他人寫的東西。這裡有一些 Rust 文件中需要知道的事情：

assert_eq!

你會看到 assert_eq! 被用在做測試的時候。你把兩個元素放進函數裡面，如果它們不相等程式就會恐慌。這裡是我們需要偶數的簡單範例：

fn main() {
    prints_number(56);
}

fn prints_number(input: i32) {
    assert_eq!(input % 2, 0); // 數字必須相等.
                              // 如果數字 % 2 不是 0 就恐慌
    println!("The number is not odd. It is {}", input);
}

也許你沒有任何計劃要在你的程式碼中使用 assert_eq!，但它在 Rust 文件中隨處可見。這是因為在文件中，你需要非常大的空間來 println! 所有東西。另外，對於你想印的東西也要具備 Display 或 Debug 才行。這就是為什麼文件中到處都有 assert_eq! 的原因。這裡的範例來自https://doc.rust-lang.org/std/vec/struct.Vec.html，展示如何使用向量：

fn main() {
    let mut vec = Vec::new();
    vec.push(1);
    vec.push(2);

    assert_eq!(vec.len(), 2);
    assert_eq!(vec[0], 1);

    assert_eq!(vec.pop(), Some(2));
    assert_eq!(vec.len(), 1);

    vec[0] = 7;
    assert_eq!(vec[0], 7);

    vec.extend([1, 2, 3].iter().copied());

    for x in &vec {
        println!("{}", x);
    }
    assert_eq!(vec, [7, 1, 2, 3]);
}

在這些範例中，你可以只把 assert_eq!(a, b) 想成是在說 "a 是 b"。現在來看看右邊帶有註解的相同範例。註解顯示了它的實際含義。

fn main() {
    let mut vec = Vec::new();
    vec.push(1);
    vec.push(2);

    assert_eq!(vec.len(), 2); // "向量長度是 2"
    assert_eq!(vec[0], 1); // "vec[0] 是 1"

    assert_eq!(vec.pop(), Some(2)); // "當你使用 .pop(), 你得到 Some()"
    assert_eq!(vec.len(), 1); // "向量長度現在是 1"

    vec[0] = 7;
    assert_eq!(vec[0], 7); // "Vec[0] 是 7"

    vec.extend([1, 2, 3].iter().copied());

    for x in &vec {
        println!("{}", x);
    }
    assert_eq!(vec, [7, 1, 2, 3]); // "向量現在有 [7, 1, 2, 3]"
}

搜尋

Rust 文件的頂端是搜尋欄。它在你一邊輸入時一邊顯示結果。當你往下翻頁時，你沒辨法再看到搜尋欄，但如果你按鍵盤上的 s 鍵就可以再次搜尋。所以在任何地方按下 s 鍵可以讓你馬上搜索。

[src] 按鈕

通常方法、結構體等的程式碼不會是完整的。這是因為你通常不需要看到完整的原始碼就能知道它是如何工作的，而完整的程式碼可能會讓人困惑。但如果你想知道更多，你可以點選 [src] 就可以看到所有的內容。例如，在 String 的頁面上，你可以看到 .with_capacity() 的這個簽名：

#![allow(unused)]
fn main() {
// 🚧
pub fn with_capacity(capacity: usize) -> String
}

好了，你輸入數字，它給你 String。這很容易，但也許我們很好奇，想看更多。如果你點選 [src] 你可以看到這個：

#![allow(unused)]
fn main() {
// 🚧
pub fn with_capacity(capacity: usize) -> String {
    String { vec: Vec::with_capacity(capacity) }
}
}

有趣吧！現在你可以看到，字串是一種 Vec。而實際上 String 是 u8 位元組的向量，這很有意思。你不需要知道就可以使用 with_capacity 的方法，你只有點選 [src] 才能看到。所以如果文件沒有太多細節，而你又想知道更多的話，點選 [src] 是個好主意。

特徵資訊

特徵的文件最重要部分在於左邊的 "Required Methods"。如果你有看到 "Required Methods"，可能意味著你必須自己寫出方法。例如，對於 Iterator，你需要實作 .next() 方法。而對於 From，你需要實作 .from() 方法。但是有些特徵只需要屬性就可以被實作出來，比如我們見過的 #[derive(Debug)]。Debug 需要 .fmt() 方法，但通常你只需要使用 #[derive(Debug)]，除非你想自己動手做。這就是為什麼在 std::fmt::Debug 的頁面上有說"一般來說，你應該只需要推導出 Debug 的實作"。

Easy Rust