這是「演講者備忘稿」的範例。我們會透過這些備忘稿補充投影片中未提到的資訊。這可能包括老師應提及的重點，以及課堂上典型問題的解答。

• On Debian/Ubuntu, you can also install Cargo, the Rust source and the Rust formatter via apt. However, this gets you an outdated rust version and may lead to unexpected behavior. The command would be:

  sudo apt install cargo rust-src rustfmt
  

重要須知：

• Rust 的發布時程相當緊湊，每六週就會推出新版本。新版本可與舊版本回溯相容，且會啟用新功能。

• 發布版本 (release channel) 分為三種：「穩定版」、「Beta 版」和「Nightly 版」。

• 「Nightly 版」會用於測試新功能，「Beta 版」則會每六週成為「穩定版」。

• 您也可以透過其他註冊資料庫、git、資料夾等管道解析依附元件。

• Rust 還具有[版本] (edition)：目前版本為 Rust 2021。先前版本為 Rust 2015 和 Rust 2018。

  • 這些版本可針對語言進行回溯不相容的變更。

  • 為避免破壞程式碼，版本皆為自行選擇採用：您可以透過 Cargo.toml 檔案選擇所需版本。

  • 為避免分割生態系統，Rust 編譯器可混合寫給不同版本的程式碼。

  • 請說明很少會略過 cargo 直接使用編譯器，大部分使用者都不會這麼做。

  • It might be worth alluding that Cargo itself is an extremely powerful and comprehensive tool. It is capable of many advanced features including but not limited to:

    • 專案/套件結構
    • [工作區]
    • 開發人員依附元件和執行階段依附元件管理/快取
    • [建構指令碼]
    • [全域安裝]
    • 此外，還可以擴充使用子指令外掛程式，例如 cargo clippy

  • 詳情請參閱[官方的 Cargo 手冊]。

大部分程式碼範例都可供編輯，如上所示。有些程式碼範例無法編輯，原因如下：

• 嵌入式遊樂場無法執行單元測試。請複製貼上程式碼，然後在實際的 Playground 中開啟，即可示範單元測試。

• 當您一離開頁面，嵌入式遊樂場就會失去目前狀態！因此，學生應使用本機 Rust 安裝項目或透過 Playground 來做習題。

建議您鼓勵課程參與者安裝 Cargo 及使用本機編輯器。這麼做能提供正常的開發環境，降低操作難度。

請提醒學生以下事項：

• 應該一有問題就提問，不要留到最後。
• 本課程的宗旨是互動，非常鼓勵大家討論！
  • As an instructor, you should try to keep the discussions relevant, i.e., keep the discussions related to how Rust does things vs some other language. It can be hard to find the right balance, but err on the side of allowing discussions since they engage people much more than one-way communication.
• 我們討論的議題，可能會超前投影片進度。
  • 這完全沒問題！複習是學習的重要一環。請記得，投影片只是輔助，您可以視情況略過不需要的部分。

第一天的規畫是說明 Rust 中能夠直接對應到其他語言的「基礎」概念。後續幾天則會介紹更進階的部分。

如果您是在教室授課，就很適合參考這裡的時間表。請注意，每個主題結束後都有練習，然後才是休息時間。請規劃在休息後講解練習的解決方案。此處列出的時程建議是要確保課程進度。您可以視需要彈性調整！

Rust 適合用於與 C++ 同樣的領域，且具有以下特色：

• 高靈活性。
• 提供高度主控權。
• 可縮減到十分受限的裝置規模，例如微控制器。
• 沒有執行階段，也不使用垃圾收集機制。
• 著重可靠性和安全性，但不犧牲效能。

這裡不要花太多時間。這幾點稍後全都會深入介紹。

請務必詢問全班同學，瞭解他們具備哪些語言的使用經驗。根據學生答覆，您可以強調不同的 Rust 功能：

• 具備 C 或 C++ 經驗：Rust 會透過借用檢查器，徹底刪除一整類的「執行階段錯誤」。這不僅可讓您獲得像是 C 和 C++ 的效能，也不會造成記憶體安全問題。此外，您還能取得具備模式配對、內建依附元件管理機制等結構的新型語言。

• 具備 Java、Go、Python、JavaScript...經驗：Rust 能讓您享有與這些語言相同的記憶體安全性，而且還可帶來使用類似高階語言的感受。此外，您也能獲得像 C 和 C++ 一樣快速可預期的成效 (無垃圾收集器)，以及低階硬體的存取權限 (如有需要)。

學員準備休息時，請鼓勵他們開啟 Playground 略微試驗一下。在剩餘的課堂時間，建議他們持續開啟 Playground 分頁嘗試操作。如果學生程度較高，想進一步瞭解 Rust 的最佳化作業或產生的組語，就特別適合採用這個授課方式。

我們會藉由這張投影片，試著讓學生熟悉 Rust 程式碼。在接下來的四天裡，他們會大量接觸到這些內容，所以我們得從他們熟悉的小地方著手。

重要須知：

• Rust 與 C/C++/Java 傳統中的其他語言非常相似。它是指令式的程式語言，除非絕對必要，否則不會嘗試改編任何內容。

• Rust 是現代的程式語言，可完整支援萬國碼等等。

• Rust uses macros for situations where you want to have a variable number of arguments (no function overloading).

• 所謂「衛生」巨集，是指這類巨集不會誤從自身所用於的範圍內擷取 ID。Rust 巨集實際上只能算是部分衛生的巨集。

• Rust 是多範式的語言。舉例來說，它具備強大的物件導向程式設計功能，雖然並非函式語言，卻涉及各式各樣的函式概念。

• 取消註解 x = 20，證明變數預設為不可變動。如要允許變更，請加入 mut 關鍵字。

• 這裡的 i32 是變數型別。這是編譯器必須在編譯期間掌握的資訊，但透過型別推斷 (稍後會說明)，程式設計師在許多情況下都能省略其型別宣告。

除此之外，還有一些其他語法：

• 數字中的底線全都可以省略，寫出來只是為了方便閱讀。換句話說，1_000 可以寫成 1000 (或 10_00)，而 123_i64 則可寫成 123i64。

這是我們第一次看到 main 以外的函式，但此函式的含意應該很清楚，那就是它需要三個整數，且會傳回整數。我們稍後會詳細說明函式的細節。

在其他語言中，算數的方法非常相似，運算的優先順序也雷同。

那麼整數溢位現象呢？在 C 和 C++ 中，「有號」整數的溢位現象實際上並未定義，而且在不同的平台或編譯器上可能有不同行為。但在 Rust 中，整數溢位會經過定義。

將 i32 變更為 i16，即可查看整數溢位現象，這在偵錯版本中會造成恐慌 (checked)，並納入發布子版本中。此外，Rust 還提供溢位、飽和與進位等其他選項，可透過方法語法存取，例如 (a * b).saturating_add(b * c).saturating_add(c * a)。

事實上，編譯器會偵測常數運算式的溢位，這也是本例中需要另一個函式的原因。

這張投影片用於介紹字串。我們稍後會深入介紹此處提及的所有內容，但目前這些就已足夠用於後續的投影片和使用字串的練習題中。

• 字串中的無效 UTF-8 屬於 UB，而安全的 Rust 環境不允許此行為。

• String 是使用者定義的型別，具備建構函式 (::new()) 和 s.push_str(..) 等方法。

• &str 中的 & 表示這是參照。我們稍後會講解何謂參照，因此現在只需將 &str 視為代表「唯讀字串」的單位就行了。

• 被註解掉的那行程式碼會按照位元組位置建立索引到字串中。12..13 的結尾不是字元邊界，因此程式會發生恐慌。請根據錯誤訊息，將其調整至結尾為字元邊界的範圍。

• 原形字串可讓您建立停用逸出功能的 &str 值：r"\n" == "\\n"。只要在引號兩側使用等量的 #，即可嵌入雙引號：

  fn main() {
      println!(r#"<a href="link.html">link</a>"#);
      println!("<a href=\"link.html\">link</a>");
  }

• Using {:?} is a convenient way to print array/vector/struct of values for debugging purposes, and it's commonly used in code.

這張投影片展示了 Rust 編譯器如何根據變數宣告和用法設下的限制來推斷型別。

請務必強調，以這種方式宣告的變數，並非「任一型別」這類可存放任何資料的動態型別。此類宣告產生的機器碼與型別的明確宣告相同。編譯器會替我們執行工作，並協助編寫更精簡的程式碼。

當整數常量的型別無任何限制時，Rust 會預設使用 i32。這有時會在錯誤訊息中顯示為「{integer}」。同樣地，浮點常量會預設為 f64。

fn main() {
    let x = 3.14;
    let y = 20;
    assert_eq!(x, y);
    // ERROR: no implementation for `{float} == {integer}`
}

Because if is an expression and must have a particular type, both of its branch blocks must have the same type. Show what happens if you add ; after "small" in the second example.

在運算式中使用 if 時，運算式須有 ;，才能與下一個陳述式分隔。移除 println! 前的 ; 即可查看編譯器錯誤。

• Under the hood for loops use a concept called "iterators" to handle iterating over different kinds of ranges/collections. Iterators will be discussed in more detail later.
• 請注意，for 迴圈只會疊代至 4。您可以示範 1..=5 語法，這代表含頭尾的範圍。

• 請注意，loop 是唯一會傳回重要值的迴圈結構。這是因為系統保證至少會輸入一次此迴圈結構，這一點不同於 while 和 for 迴圈。

• 你可以藉由改變區塊中的最後一行來觀察區塊數值的變化。舉例來說，新增或刪除一個分號，或者使用 return。

• 請說明變數的範疇受到限制，做法是在最後一個範例的內部區塊中新增 b，然後嘗試在該區塊外部存取 b。
• Shadowing is different from mutation, because after shadowing both variable's memory locations exist at the same time. Both are available under the same name, depending where you use it in the code.
• A shadowing variable can have a different type.
• 遮蔽一開始看起來模糊不清，但對於保留 .unwrap() 之後的值很方便。

• 宣告參數後面接有型別 (與某些程式設計語言相反)，然後才是傳回型別。
• The last expression in a function body (or any block) becomes the return value. Simply omit the ; at the end of the expression. The return keyword can be used for early return, but the "bare value" form is idiomatic at the end of a function (refactor gcd to use a return).
• 某些函式沒有回傳值，會傳回 () 這個「單位型別」。如果省略 -> () 傳回型別，編譯器則會推斷出這點。
• Overloading is not supported -- each function has a single implementation.
  • 請一律採用定量參數。系統不支援預設引數。如要支援可變參數函式，請使用巨集。
  • Always takes a single set of parameter types. These types can be generic, which will be covered later.

本節的重點在於，上述的便利性不僅常見，而且確實存在，學員需瞭解如何運用。至於為何將便利性定義為巨集，以及巨集展開後會變成什麼內容，則沒有那麼重要。

本課程不會探討如何定義巨集，但後續章節將說明衍生巨集的用法。

• A value of the array type [T; N] holds N (a compile-time constant) elements of the same type T. Note that the length of the array is part of its type, which means that [u8; 3] and [u8; 4] are considered two different types. Slices, which have a size determined at runtime, are covered later.

• 請嘗試存取超出範圍的陣列元素。系統會在執行階段檢查存取陣列的行為。Rust 通常可對這類檢查進行最佳化處理，避免使用不安全的 Rust 執行這些檢查。

• 我們可以使用常值將值指派給陣列。

• The println! macro asks for the debug implementation with the ? format parameter: {} gives the default output, {:?} gives the debug output. Types such as integers and strings implement the default output, but arrays only implement the debug output. This means that we must use debug output here.

• 加入 # (例如 {a:#?}) 可叫用方便閱讀的「美化排版」格式。

• 和陣列一樣，元組有固定的長度。

• 元組會將不同型別的值組成複合型別。

• 元組的欄位可透過點號和值的索引存取，例如 t.0、t.1。

• The empty tuple () is referred to as the "unit type" and signifies absence of a return value, akin to void in other languages.

這項功能使用 IntoIterator 特徵，但這部分我們尚未介紹。

assert_ne! 是這裡的新巨集。此外還有 assert_eq! 和 assert! 巨集。系統一律會檢查這些巨集，但如果是 debug_assert! 這類僅供偵錯的變體，在發布子版本中會編譯為空白內容。

• The patterns used here are "irrefutable", meaning that the compiler can statically verify that the value on the right of = has the same structure as the pattern.
• A variable name is an irrefutable pattern that always matches any value, hence why we can also use let to declare a single variable.
• Rust also supports using patterns in conditionals, allowing for equality comparison and destructuring to happen at the same time. This form of pattern matching will be discussed in more detail later.
• Edit the examples above to show the compiler error when the pattern doesn't match the value being matched on.

• 參照可說是「借用」自身參照的值，對不熟悉指標的學生而言，這是不錯的模型，因為程式碼可以使用參照來存取值，但仍歸原始的變數所「擁有」。本課程將在第 3 天進一步說明擁有權。

• 參照需以指標的形式實作，主要優點是大小會比指向的目標小得多。熟悉 C 或 C++ 的學生會覺得參照很像指標。在稍後的課程中，我們將介紹 Rust 如何避免使用原始指標導致的記憶體安全錯誤。

• Rust 不會自動為您建立參照，一律須使用 &。

• Rust will auto-dereference in some cases, in particular when invoking methods (try r.is_ascii()). There is no need for an -> operator like in C++.

• 這個範例中的 r 可變動，因此可以重新指派 (r = &b)。請注意，這會重新繫結 r，因此會參照其他內容。此方式與 C++ 不同，在 C++ 中，對參照的賦值會變更參照的值。

• 共用參照不允許修改其參照的值，即使該值可變動也一樣。請嘗試使用 *r = 'X'。

• Rust 會追蹤所有參照的生命週期，確保其存留時間夠長。在安全的 Rust 中不會發生迷途參照。x_axis 會傳回對 point 的參照，但在函式傳回時會釋放 point ，因此不會編譯。

• 我們會在講到擁有權時進一步探討「借用」。

重要須知：

• 「專屬」表示只有這個參照可用來存取值。任何其他參照 (不論是共用或專屬參照) 都不可以同時存在，此外，在專屬參照存在的情況下，就無法存取參照的值。請嘗試在 x_coord 運作時建立 &point.0 或變更 point.0。

• Be sure to note the difference between let mut x_coord: &i32 and let x_coord: &mut i32. The first one represents a shared reference which can be bound to different values, while the second represents an exclusive reference to a mutable value.

重點：

• 結構體的運作方式與在 C 或 C++ 中類似。
  • 不需要 typedef 即可定義型別。這與 C++ 類似，但與 C 不同。
  • 與 C++ 不同的是，結構體之間沒有繼承關係。
• This may be a good time to let people know there are different types of structs.
  • Zero-sized structs (e.g. struct Foo;) might be used when implementing a trait on some type but don’t have any data that you want to store in the value itself.
  • 在下一張投影片中，我們會介紹元組結構體，可於欄位名稱不重要時使用。
• If you already have variables with the right names, then you can create the struct using a shorthand.
• The syntax ..avery allows us to copy the majority of the fields from the old struct without having to explicitly type it all out. It must always be the last element.

• 如要對原始型別中值的額外資訊進行編碼，Newtypes 是絕佳的方式，舉例來說：
  • 此數字會採用某些測量單位：在上例中為 Newtons。
  • The value passed some validation when it was created, so you no longer have to validate it again at every use: PhoneNumber(String) or OddNumber(u32).
• 示範如何透過存取 newtype 中的單一欄位，將 “f64” 值新增至 Newtons 類型。
  • Rust 通常不太能接受不明確的內容，例如自動展開或使用布林值做為整數。
  • 運算子超載會在第 3 天 (泛型) 討論。
• 此範例巧妙地以 Mars Climate Orbiter 的失敗經驗做為參照。

重點：

• Enumerations allow you to collect a set of values under one type.
• Direction 是含變體的型別，有Direction::Left 和 Direction::Right 這兩個值。
• PlayerMove 是含三種變體的型別。除了酬載之外，Rust 還會儲存判別值，以便在執行階段瞭解哪個變體屬於 PlayerMove 值。
• This might be a good time to compare structs and enums:
  • In both, you can have a simple version without fields (unit struct) or one with different types of fields (variant payloads).
  • You could even implement the different variants of an enum with separate structs but then they wouldn’t be the same type as they would if they were all defined in an enum.
• Rust 會以最少的空間來儲存判別值。

  • 如有需要，Rust 會儲存最小所需大小的整數

  • 如果允許的變體值未涵蓋所有位元模式，Rust 會使用無效的位元模式來編碼判別值 (即「區位最佳化」)。舉例來說，Option<&u8> 可儲存指向整數的指標，也可儲存 None 變體適用的 NULL。

  • 您可以視需要控制判別值，例如為了與 C 相容：

    #[repr(u32)]
    enum Bar {
        A, // 0
        B = 10000,
        C, // 10001
    }
    
    fn main() {
        println!("A: {}", Bar::A as u32);
        println!("B: {}", Bar::B as u32);
        println!("C: {}", Bar::C as u32);
    }

    如果沒有 repr，判別值型別會需要 2 個位元組，因為 10001 適合 2 個位元組。

探索更多內容

Rust 支援多種最佳化做法，可用於縮減列舉占用的空間。

• 空值指標最佳化：針對部分型別，Rust 保證 size_of::<T>() 等於 size_of::<Option<T>>().

  如果想示範位元表示法實際運作時「可能」的樣子，可以使用下列範例程式碼。請務必注意，編譯器並無對這個表示法提供保證，因此這完全不安全。

  use std::mem::transmute;
  
  macro_rules! dbg_bits {
      ($e:expr, $bit_type:ty) => {
          println!("- {}: {:#x}", stringify!($e), transmute::<_, $bit_type>($e));
      };
  }
  
  fn main() {
      unsafe {
          println!("bool:");
          dbg_bits!(false, u8);
          dbg_bits!(true, u8);
  
          println!("Option<bool>:");
          dbg_bits!(None::<bool>, u8);
          dbg_bits!(Some(false), u8);
          dbg_bits!(Some(true), u8);
  
          println!("Option<Option<bool>>:");
          dbg_bits!(Some(Some(false)), u8);
          dbg_bits!(Some(Some(true)), u8);
          dbg_bits!(Some(None::<bool>), u8);
          dbg_bits!(None::<Option<bool>>, u8);
  
          println!("Option<&i32>:");
          dbg_bits!(None::<&i32>, usize);
          dbg_bits!(Some(&0i32), usize);
      }
  }

• 別忘了提到 const 的行為在語意上與 C++ 的 constexpr 相似。
• 另一方面，static 則更類似於 C++ 中的 const 或可變動的全域變數。
• static 提供物件識別子，也就是記憶體中的位址，和具有內部可變動性型別 (例如 Mutex<T>) 所需的狀態。
• 需要在執行階段評估常數的情況雖不常見，但這會比使用靜態項目更有用且安全。

屬性表：

探索更多內容

Because static variables are accessible from any thread, they must be Sync. Interior mutability is possible through a Mutex, atomic or similar.

Thread-local data can be created with the macro std::thread_local.

別名在 C 語言的程式設計師眼中類似於 typedef。

重點：

• 建議您特別指出某些特定字元在模式中的使用方式

  • | 可做為 or
  • .. 可以視需要展開
  • 1..=5 代表含頭尾的範圍
  • _ 是萬用字元

• 有些概念比模式本身所允許的更加複雜，如果我們希望簡要地表達這些想法，就必須把配對守衛視為獨立的語法功能。

• 這與配對分支內的個別 if 運算式不同。分支區塊中的 if 運算式 (位於 => 之後) 會在選取配對分支後發生。即使該區塊內的 if 條件失敗，系統也不會考量原始 match 運算式的其他分支。

• 只要運算式隸屬於具備 | 的模式之中，就會套用守衛定義的條件。

結構體

• 請變更 foo 中的常值，與其他模式配對。
• 在 Foo 中新增一個欄位，並視需要變更模式。
• 捕獲和常數運算式之間的區別可能不容易發現。請嘗試將第二個分支的 2 變更為變數，您會發現它幾乎無法運作。現在將其變更為 const，您會看到它再次運作。

列舉

重要須知：

• if/else 運算式會傳回列舉，之後列舉會透過 match 解除封裝。
• 您可以嘗試在列舉定義中加入第三個變體，並在執行程式碼時顯示錯誤。請向學員指出程式碼現在有哪些地方還不詳盡，並說明編譯器會如何嘗試給予提示。
• The values in the enum variants can only be accessed after being pattern matched.
• Demonstrate what happens when the search is inexhaustive. Note the advantage the Rust compiler provides by confirming when all cases are handled.
• 將 divide_in_two 的結果儲存在 result 變數中，並在迴圈中 match 結果。由於配對符合時會耗用 msg，因此這麼做並不會執行編譯。如要修正此問題，請配對 &result，而非 result。這會讓 msg 成為參照，因此就不會遭到耗用。這個「人因工程學的配對」功能已於 Rust 2018 推出。如要支援舊版 Rust，請在模式中將 msg 替換成 ref msg。

if-let

• Unlike match, if let does not have to cover all branches. This can make it more concise than match.
• 常見用途是在使用 Option 時處理 Some 值。
• 與 match 不同，if let 不會為模式比對支援成立條件子句。

let-else

如上所示，if-let 可能會越加越多。let-else 結構支援壓平合併這個巢狀程式碼。請為學生重新編寫這個冗長的版本，讓他們見識改寫的效果。

重新編寫的版本如下：

#![allow(unused)]
fn main() {
fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    let Some(s) = maybe_string else {
        return Err(String::from("got None"));
    };

    let Some(first_byte_char) = s.chars().next() else {
        return Err(String::from("got empty string"));
    };

    let Some(digit) = first_byte_char.to_digit(16) else {
        return Err(String::from("not a hex digit"));
    };

    return Ok(digit);
}
}

while-let

• 請指出只要值符合模式，while let 迴圈就會持續運作。
• You could rewrite the while let loop as an infinite loop with an if statement that breaks when there is no value to unwrap for name.pop(). The while let provides syntactic sugar for the above scenario.

重點：

• 導入方法時，若將方法比做函式，會很有幫助。
  • 系統會在型別的執行個體 (例如結構體或列舉) 上呼叫方法，第一個參數以 self 代表執行個體。
  • 開發人員可以選擇透過方法來充分利用方法接收器語法，以更有條理的方式進行整理。藉由使用方法，我們可以將所有實作程式碼存放在可預測的位置。
• 指出我們會使用關鍵字 self，也就是方法接收器。
  • 說明 self 是 self: Self 的縮寫，或許也能示範結構體名稱的可能用法。
  • 講解 Self 是 impl 區塊所屬型別的型別別名，可用於該區塊的其他位置。
  • 提醒學員如何以類似於其他結構體的方式來使用 self，並指出點標記法可用來參照個別欄位，
  • This might be a good time to demonstrate how the &self differs from self by trying to run finish twice.
  • 除了 self 的變體以外，您還可以使用特殊的包裝函式型別做為接收器型別，例如 Box<Self>。

• 特徵用於定義型別必須具有哪幾個方法，才能實作該特徵。

• In the "Generics" segment, next, we will see how to build functionality that is generic over all types implementing a trait.

• To implement Trait for Type, you use an impl Trait for Type { .. } block.

• Unlike Go interfaces, just having matching methods is not enough: a Cat type with a talk() method would not automatically satisfy Pet unless it is in an impl Pet block.

• Traits may provide default implementations of some methods. Default implementations can rely on all the methods of the trait. In this case, greet is provided, and relies on talk.

• Associated types are sometimes also called "output types". The key observation is that the implementer, not the caller, chooses this type.

• Many standard library traits have associated types, including arithmetic operators and Iterator.

衍生會透過巨集實作，許多 Crate 都提供實用的衍生巨集，以便新增實用功能。例如，serde 可以使用 #[derive(Serialize)]，為結構體衍生序列化支援。

練習：泛型 Logger

我們來設計一個簡單的記錄公用程式，使用 Logger 特徵搭配 log 方法。如果程式碼可能會記錄相關進度，就可以採用 &impl Logger。在測試過程中，這可能會將訊息置於測試記錄檔中；而在實際版本中，則會將訊息傳送至記錄伺服器。

不過，下方的 StderrLogger 會記錄詳細程度不限的所有訊息。您的任務是編寫 VerbosityFilter 型別，忽略超出詳細程度上限的訊息。

以下是常見模式：結構體包裝一個特徵實作項目，並實作該相同特徵，在程序中加入行為。想一想，還有哪些其他類型的包裝函式可能在記錄公用程式中派上用場？

use std::fmt::Display;

pub trait Logger {
    /// Log a message at the given verbosity level.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: impl Display) {
        eprintln!("verbosity={verbosity}: {message}");
    }
}

fn do_things(logger: &impl Logger) {
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

// TODO: Define and implement `VerbosityFilter`.

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

解決方案

use std::fmt::Display;

pub trait Logger {
    /// Log a message at the given verbosity level.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: impl Display) {
        eprintln!("verbosity={verbosity}: {message}");
    }
}

fn do_things(logger: &impl Logger) {
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

/// Only log messages up to the given verbosity level.
struct VerbosityFilter<L: Logger> {
    max_verbosity: u8,
    inner: L,
}

impl<L: Logger> Logger for VerbosityFilter<L> {
    fn log(&self, verbosity: u8, message: impl Display) {
        if verbosity <= self.max_verbosity {
            self.inner.log(verbosity, message);
        }
    }
}

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

泛型

This segment should take about 40 minutes. It contains:

Extern 函式

Rust supports generics, which lets you abstract algorithms or data structures (such as sorting or a binary tree) over the types used or stored.

/// Pick `even` or `odd` depending on the value of `n`.
fn pick<T>(n: i32, even: T, odd: T) -> T {
    if n % 2 == 0 {
        even
    } else {
        odd
    }
}

fn main() {
    println!("picked a number: {:?}", pick(97, 222, 333));
    println!("picked a tuple: {:?}", pick(28, ("dog", 1), ("cat", 2)));
}

泛型資料型別

你可以使用泛型將具體的欄位型別抽象化：

#[derive(Debug)]
struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn coords(&self) -> (&T, &T) {
        (&self.x, &self.y)
    }

    // fn set_x(&mut self, x: T)
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
    println!("{integer:?} and {float:?}");
    println!("coords: {:?}", integer.coords());
}

特徵界限

使用泛型時，您通常會需要該型別實作 某些特徵，這樣才能呼叫該特徵的方法。

您可以使用 T: Trait 或 impl Trait 執行此操作：

fn duplicate<T: Clone>(a: T) -> (T, T) {
    (a.clone(), a.clone())
}

// struct NotClonable;

fn main() {
    let foo = String::from("foo");
    let pair = duplicate(foo);
    println!("{pair:?}");
}

impl Trait

與特徵界限類似，impl Trait 語法可用於 函式引數和回傳值中：

// Syntactic sugar for:
//   fn add_42_millions<T: Into<i32>>(x: T) -> i32 {
fn add_42_millions(x: impl Into<i32>) -> i32 {
    x.into() + 42_000_000
}

fn pair_of(x: u32) -> impl std::fmt::Debug {
    (x + 1, x - 1)
}

fn main() {
    let many = add_42_millions(42_i8);
    println!("{many}");
    let many_more = add_42_millions(10_000_000);
    println!("{many_more}");
    let debuggable = pair_of(27);
    println!("debuggable: {debuggable:?}");
}

練習：泛型 min

在這個簡短練習中，您將使用 LessThan 特徵實作泛型 min 函式，藉此判定兩個值中的最小值。

trait LessThan {
    /// Return true if self is less than other.
    fn less_than(&self, other: &Self) -> bool;
}

#[derive(Debug, PartialEq, Eq, Clone, Copy)]
struct Citation {
    author: &'static str,
    year: u32,
}

impl LessThan for Citation {
    fn less_than(&self, other: &Self) -> bool {
        if self.author < other.author {
            true
        } else if self.author > other.author {
            false
        } else {
            self.year < other.year
        }
    }
}

// TODO: implement the `min` function used in `main`.

fn main() {
    let cit1 = Citation { author: "Shapiro", year: 2011 };
    let cit2 = Citation { author: "Baumann", year: 2010 };
    let cit3 = Citation { author: "Baumann", year: 2019 };
    debug_assert_eq!(min(cit1, cit2), cit2);
    debug_assert_eq!(min(cit2, cit3), cit2);
    debug_assert_eq!(min(cit1, cit3), cit3);
}

解決方案

trait LessThan {
    /// Return true if self is less than other.
    fn less_than(&self, other: &Self) -> bool;
}

#[derive(Debug, PartialEq, Eq, Clone, Copy)]
struct Citation {
    author: &'static str,
    year: u32,
}

impl LessThan for Citation {
    fn less_than(&self, other: &Self) -> bool {
        if self.author < other.author {
            true
        } else if self.author > other.author {
            false
        } else {
            self.year < other.year
        }
    }
}

fn min<T: LessThan>(l: T, r: T) -> T {
    if l.less_than(&r) {
        l
    } else {
        r
    }
}

fn main() {
    let cit1 = Citation { author: "Shapiro", year: 2011 };
    let cit2 = Citation { author: "Baumann", year: 2010 };
    let cit3 = Citation { author: "Baumann", year: 2019 };
    debug_assert_eq!(min(cit1, cit2), cit2);
    debug_assert_eq!(min(cit2, cit3), cit2);
    debug_assert_eq!(min(cit1, cit3), cit3);
}

Welcome Back

Including 10 minute breaks, this session should take about 3 hours and 10 minutes. It contains:

標準函式庫

This segment should take about 1 hour and 20 minutes. It contains:

標準函式庫

Rust comes with a standard library which helps establish a set of common types used by Rust libraries and programs. This way, two libraries can work together smoothly because they both use the same String type.

In fact, Rust contains several layers of the Standard Library: core, alloc and std.

• core includes the most basic types and functions that don't depend on libc, allocator or even the presence of an operating system.
• alloc 包括需要全域堆積配置器的型別，例如 Vec、Box 和 Arc。
• 嵌入式 Rust 應用程式通常只使用 core，偶爾會使用 alloc。

說明文件測試

Rust 說明文件的主題涵蓋甚廣，包括：

• All of the details about loops.
• 基本型別，例如 u8。
• Standard library types like Option or BinaryHeap.

您其實可以將程式碼記錄下來：

/// Determine whether the first argument is divisible by the second argument.
///
/// If the second argument is zero, the result is false.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;
    }
    lhs % rhs == 0
}

系統會將內容視為 Markdown。所有已發布的 Rust 程式庫 Crate，都會使用 rustdoc 工具自動記錄於 docs.rs 中。這種記錄 API 中所有公開項目的模式是慣用做法。

如要從項目內部 (例如在模組內) 記錄項目，請使用 //! 或 /*! .. */，這也稱做「內部文件註解」：

//! This module contains functionality relating to divisibility of integers.

Option

我們已看過 Option<T> 的某些用法，包括儲存型別為 T 的值，或不儲存任何東西。舉例來說，String::find 會傳回 Option<usize>。

fn main() {
    let name = "Löwe 老虎 Léopard Gepardi";
    let mut position: Option<usize> = name.find('é');
    println!("find returned {position:?}");
    assert_eq!(position.unwrap(), 14);
    position = name.find('Z');
    println!("find returned {position:?}");
    assert_eq!(position.expect("Character not found"), 0);
}

Result

Result 和 Option 類似，但會指出作業成功或失敗，且各自都有不同的型別。雖然和運算式練習中定義的 Res 很像，但這屬於泛型，也就是 Result<T, E>，其中 T 用於 Ok 變體，而 E 則會出現在 Err 變數中。

use std::fs::File;
use std::io::Read;

fn main() {
    let file: Result<File, std::io::Error> = File::open("diary.txt");
    match file {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("Dear diary: {contents} ({bytes} bytes)");
            } else {
                println!("Could not read file content");
            }
        }
        Err(err) => {
            println!("The diary could not be opened: {err}");
        }
    }
}

String

String 是標準堆積配置的可成長 UTF-8 字串緩衝區：

fn main() {
    let mut s1 = String::new();
    s1.push_str("Hello");
    println!("s1: len = {}, capacity = {}", s1.len(), s1.capacity());

    let mut s2 = String::with_capacity(s1.len() + 1);
    s2.push_str(&s1);
    s2.push('!');
    println!("s2: len = {}, capacity = {}", s2.len(), s2.capacity());

    let s3 = String::from("🇨🇭");
    println!("s3: len = {}, number of chars = {}", s3.len(), s3.chars().count());
}

String 會實作 Deref<Target = str>。也就是說，您可以在 String 上呼叫所有 str 方法。

Vec

Vec 是可調整大小的標準堆積配置緩衝區：

fn main() {
    let mut v1 = Vec::new();
    v1.push(42);
    println!("v1: len = {}, capacity = {}", v1.len(), v1.capacity());

    let mut v2 = Vec::with_capacity(v1.len() + 1);
    v2.extend(v1.iter());
    v2.push(9999);
    println!("v2: len = {}, capacity = {}", v2.len(), v2.capacity());

    // Canonical macro to initialize a vector with elements.
    let mut v3 = vec![0, 0, 1, 2, 3, 4];

    // Retain only the even elements.
    v3.retain(|x| x % 2 == 0);
    println!("{v3:?}");

    // Remove consecutive duplicates.
    v3.dedup();
    println!("{v3:?}");
}

Vec 會實作 Deref<Target = [T]>。也就是說，您可以在 Vec 上呼叫切片方法。

HashMap

標準雜湊映射，可防範 HashDoS 攻擊：

use std::collections::HashMap;

fn main() {
    let mut page_counts = HashMap::new();
    page_counts.insert("Adventures of Huckleberry Finn".to_string(), 207);
    page_counts.insert("Grimms' Fairy Tales".to_string(), 751);
    page_counts.insert("Pride and Prejudice".to_string(), 303);

    if !page_counts.contains_key("Les Misérables") {
        println!(
            "We know about {} books, but not Les Misérables.",
            page_counts.len()
        );
    }

    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        match page_counts.get(book) {
            Some(count) => println!("{book}: {count} pages"),
            None => println!("{book} is unknown."),
        }
    }

    // Use the .entry() method to insert a value if nothing is found.
    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        let page_count: &mut i32 = page_counts.entry(book.to_string()).or_insert(0);
        *page_count += 1;
    }

    println!("{page_counts:#?}");
}

練習：計數器

在本練習中，您要使用非常簡單的資料結構並將其設為泛型。此結構會使用 std::collections::HashMap 追蹤出現過的值和出現次數。

Counter 的初始版本經過硬式編碼，僅適用於 u32 值。請設法讓結構體和相應的方法成為泛型，而非所追蹤值的型別，這樣 Counter 就可以追蹤任何型別的值。

如果您提前完成操作，不妨試著使用 entry 方法將實作 count 方法所需的雜湊查詢數量減半。

use std::collections::HashMap;

/// Counter counts the number of times each value of type T has been seen.
struct Counter {
    values: HashMap<u32, u64>,
}

impl Counter {
    /// Create a new Counter.
    fn new() -> Self {
        Counter {
            values: HashMap::new(),
        }
    }

    /// Count an occurrence of the given value.
    fn count(&mut self, value: u32) {
        if self.values.contains_key(&value) {
            *self.values.get_mut(&value).unwrap() += 1;
        } else {
            self.values.insert(value, 1);
        }
    }

    /// Return the number of times the given value has been seen.
    fn times_seen(&self, value: u32) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("saw {} values equal to {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("got {} apples", strctr.times_seen("apple"));
}

解決方案

use std::collections::HashMap;
use std::hash::Hash;

/// Counter counts the number of times each value of type T has been seen.
struct Counter<T: Eq + Hash> {
    values: HashMap<T, u64>,
}

impl<T: Eq + Hash> Counter<T> {
    /// Create a new Counter.
    fn new() -> Self {
        Counter { values: HashMap::new() }
    }

    /// Count an occurrence of the given value.
    fn count(&mut self, value: T) {
        *self.values.entry(value).or_default() += 1;
    }

    /// Return the number of times the given value has been seen.
    fn times_seen(&self, value: T) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("saw {} values equal to {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("got {} apples", strctr.times_seen("apple"));
}

標準函式庫

This segment should take about 1 hour and 40 minutes. It contains:

比較

以下特徵可用於比較不同的值。如果欄位會實作這些特徵，您可以針對含有這類欄位的型別衍生所有特徵。

PartialEq 和 Eq

PartialEq 代表部分對等關係，具有必要方法 eq 和提供的方法 ne。== 和 != 運算子會呼叫這些方法。

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq for Key {
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id
    }
}

Eq 代表完整對等關係 (自反、對稱和傳遞性)，並且隱含 PartialEq。需要完整對等關係的函式會使用 Eq 做為特徵界線。

PartialOrd 和 Ord

PartialOrd 會透過 partial_cmp 方法定義偏序，可用於實作 <、<=、>= 和 > 運算子。

use std::cmp::Ordering;
#[derive(Eq, PartialEq)]
struct Citation {
    author: String,
    year: u32,
}
impl PartialOrd for Citation {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        match self.author.partial_cmp(&other.author) {
            Some(Ordering::Equal) => self.year.partial_cmp(&other.year),
            author_ord => author_ord,
        }
    }
}

Ord 是全序，其中 cmp 會傳回 Ordering。

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq<u32> for Key {
    fn eq(&self, other: &u32) -> bool {
        self.id == *other
    }
}

疊代器

運算子超載會透過 std::ops: 內的特徵實作：

#[derive(Debug, Copy, Clone)]
struct Point {
    x: i32,
    y: i32,
}

impl std::ops::Add for Point {
    type Output = Self;

    fn add(self, other: Self) -> Self {
        Self { x: self.x + other.x, y: self.y + other.y }
    }
}

fn main() {
    let p1 = Point { x: 10, y: 20 };
    let p2 = Point { x: 100, y: 200 };
    println!("{:?} + {:?} = {:?}", p1, p2, p1 + p2);
}

From 和 Into

型別會實作 From 和 Into 以利型別轉換作業執行：

fn main() {
    let s = String::from("hello");
    let addr = std::net::Ipv4Addr::from([127, 0, 0, 1]);
    let one = i16::from(true);
    let bigger = i32::from(123_i16);
    println!("{s}, {addr}, {one}, {bigger}");
}

實作 From 時，Into 也會自動實作：

fn main() {
    let s: String = "hello".into();
    let addr: std::net::Ipv4Addr = [127, 0, 0, 1].into();
    let one: i16 = true.into();
    let bigger: i32 = 123_i16.into();
    println!("{s}, {addr}, {one}, {bigger}");
}

測試

Rust 沒有「隱含」型別的轉換，但支援使用 as 明確轉換。後者通常會遵循定義前者時所用的 C 語意。

fn main() {
    let value: i64 = 1000;
    println!("as u16: {}", value as u16);
    println!("as i16: {}", value as i16);
    println!("as u8: {}", value as u8);
}

在 Rust 中，as 的結果「一律」會經過定義，且在不同平台間保持一致。這可能不符合您變更符號或轉換到較小型別時的直觀做法，請檢查文件並加註說明內容。

雖然使用 as 進行型別相當簡單，但是非常容易出錯；舉例來說，如果往後的維護作業改變了所用型別或型別中值的範圍，這常常就是某些細微錯誤的來源。只有在意圖用於指明無條件截斷時，我們才建議使用型別轉換。舉例來說，如果無論高位元中的內容為何，您都只需要 u64 的底部 32 位元，就可以使用 as u32。

如果是 u32 到 u64 這類絕對無誤的型別轉換，適合先使用 From 或 Into (而非 as) 確認轉換確實無誤。對於容易出錯的轉換，如果您想以不同的方式處理，可以使用 TryFrom 和 TryInto。

Read 和 Write

使用 Read 和 BufRead 即可對 u8 來源進行抽象化處理：

use std::io::{BufRead, BufReader, Read, Result};

fn count_lines<R: Read>(reader: R) -> usize {
    let buf_reader = BufReader::new(reader);
    buf_reader.lines().count()
}

fn main() -> Result<()> {
    let slice: &[u8] = b"foo\nbar\nbaz\n";
    println!("lines in slice: {}", count_lines(slice));

    let file = std::fs::File::open(std::env::current_exe()?)?;
    println!("lines in file: {}", count_lines(file));
    Ok(())
}

同樣地，Write 則可讓您將 u8 接收器抽象化：

use std::io::{Result, Write};

fn log<W: Write>(writer: &mut W, msg: &str) -> Result<()> {
    writer.write_all(msg.as_bytes())?;
    writer.write_all("\n".as_bytes())
}

fn main() -> Result<()> {
    let mut buffer = Vec::new();
    log(&mut buffer, "Hello")?;
    log(&mut buffer, "World")?;
    println!("Logged: {:?}", buffer);
    Ok(())
}

Default 特徵

Default 特徵會產生型別的預設值。

#[derive(Debug, Default)]
struct Derived {
    x: u32,
    y: String,
    z: Implemented,
}

#[derive(Debug)]
struct Implemented(String);

impl Default for Implemented {
    fn default() -> Self {
        Self("John Smith".into())
    }
}

fn main() {
    let default_struct = Derived::default();
    println!("{default_struct:#?}");

    let almost_default_struct =
        Derived { y: "Y is set!".into(), ..Derived::default() };
    println!("{almost_default_struct:#?}");

    let nothing: Option<Derived> = None;
    println!("{:#?}", nothing.unwrap_or_default());
}

閉包

無論是閉包還是 lambda 運算式，都含有無法命名的型別。不過，這兩者 都會實作特殊的 Fn、 FnMut 和 FnOnce 特徵：

fn apply_with_log(func: impl FnOnce(i32) -> i32, input: i32) -> i32 {
    println!("Calling function on {input}");
    func(input)
}

fn main() {
    let add_3 = |x| x + 3;
    println!("add_3: {}", apply_with_log(add_3, 10));
    println!("add_3: {}", apply_with_log(add_3, 20));

    let mut v = Vec::new();
    let mut accumulate = |x: i32| {
        v.push(x);
        v.iter().sum::<i32>()
    };
    println!("accumulate: {}", apply_with_log(&mut accumulate, 4));
    println!("accumulate: {}", apply_with_log(&mut accumulate, 5));

    let multiply_sum = |x| x * v.into_iter().sum::<i32>();
    println!("multiply_sum: {}", apply_with_log(multiply_sum, 3));
}

fn make_greeter(prefix: String) -> impl Fn(&str) {
    return move |name| println!("{} {}", prefix, name);
}

fn main() {
    let hi = make_greeter("Hi".to_string());
    hi("Greg");
}

練習：ROT13 (迴轉13位)

在這個範例中，您將實作傳統的「ROT13」加密方式。請將此程式碼複製到 Playground，並實作缺少的位元。記得僅能旋轉 ASCII 字母字元，確保結果仍為有效的 UTF-8。

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

// Implement the `Read` trait for `RotDecoder`.

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

如果將兩個 RotDecoder 例項鏈結在一起，每個都以 13 個字元旋轉，會怎麼樣？

解決方案

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

impl<R: Read> Read for RotDecoder<R> {
    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
        let size = self.input.read(buf)?;
        for b in &mut buf[..size] {
            if b.is_ascii_alphabetic() {
                let base = if b.is_ascii_uppercase() { 'A' } else { 'a' } as u8;
                *b = (*b - base + self.rot) % 26 + base;
            }
        }
        Ok(size)
    }
}

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

歡迎參加第 3 天課程

今天我們將講解以下內容：

• 記憶體管理、生命週期和借用檢查器：Rust 如何確保記憶體安全。
• 智慧指標：標準程式庫指標型別。

課程時間表

Including 10 minute breaks, this session should take about 2 hours and 20 minutes. It contains:

記憶體管理

This segment should take about 1 hour. It contains:

檢查程式記憶體

程式分配記憶體的方式有兩種：

• 堆疊 (Stack)：本機變數的連續記憶體區域。

  • 值在編譯期間具有已知的固定大小。
  • 相當快速：只需移動堆疊指標。
  • 易於管理：追蹤函式呼叫。
  • 良好的記憶體區域性。

• 堆積 (Heap)：函式呼叫外的值儲存空間。

  • 值在執行階段中以動態方式判斷大小。
  • 速度稍慢於堆疊：需要作一些記錄。
  • 不保證記憶體區域性。

範例

Creating a String puts fixed-sized metadata on the stack and dynamically sized data, the actual string, on the heap:

fn main() {
    let s1 = String::from("Hello");
}

fn main() {
    let mut s1 = String::from("Hello");
    s1.push(' ');
    s1.push_str("world");
    // DON'T DO THIS AT HOME! For educational purposes only.
    // String provides no guarantees about its layout, so this could lead to
    // undefined behavior.
    unsafe {
        let (capacity, ptr, len): (usize, usize, usize) = std::mem::transmute(s1);
        println!("capacity = {capacity}, ptr = {ptr:#x}, len = {len}");
    }
}

自動記憶體管理

傳統上，語言大致可分為兩種：

• 透過手動管理記憶體，取得完整掌控權：C、C++、Pascal...
  • 程式設計師會決定何時分配或釋出堆積記憶體。
  • 程式設計師必須判斷指標是否仍指向有效記憶體。
  • 研究顯示，程式設計師難免會出錯。
• 透過在執行階段中自動管理記憶體，取得完整安全性：Java、Python、Go、Haskell...
  • 執行階段系統會確保在可以參照記憶體之後，才釋出記憶體。
  • 通常透過參照計算、垃圾收集或 RAII 的方式實作。

Rust 則融合這兩種做法：

透過正確的記憶體管理編譯時間強制執行措施，「同時」取得完整的掌控權和安全性。

Rust 運用明確所有權的概念實現這一點。

所有權

所有變數繫結都會在特定「範圍」內有效，在範圍外使用變數會是錯誤：

struct Point(i32, i32);

fn main() {
    {
        let p = Point(3, 4);
        println!("x: {}", p.0);
    }
    println!("y: {}", p.1);
}

We say that the variable owns the value. Every Rust value has precisely one owner at all times.

At the end of the scope, the variable is dropped and the data is freed. A destructor can run here to free up resources.

移動語意

An assignment will transfer ownership between variables:

fn main() {
    let s1: String = String::from("Hello!");
    let s2: String = s1;
    println!("s2: {s2}");
    // println!("s1: {s1}");
}

• 將 s1 指派給 s2 會轉移所有權。
• When s1 goes out of scope, nothing happens: it does not own anything.
• 當 s2 超出範圍時，系統會釋放字串資料。

移至 s2 前：

移至 s2 後：

將值傳遞至函式時，該值會指派給函式參數。這麼做會轉移所有權：

fn say_hello(name: String) {
    println!("Hello {name}")
}

fn main() {
    let name = String::from("Alice");
    say_hello(name);
    // say_hello(name);
}

std::string s1 = "Cpp";
std::string s2 = s1;  // Duplicate the data in s1.

Clone

有時候，您可能會「想要」複製一個值。Clone 特徵可完成這項作業。

#[derive(Default)]
struct Backends {
    hostnames: Vec<String>,
    weights: Vec<f64>,
}

impl Backends {
    fn set_hostnames(&mut self, hostnames: &Vec<String>) {
        self.hostnames = hostnames.clone();
        self.weights = hostnames.iter().map(|_| 1.0).collect();
    }
}

Copy 型別

雖然移動語意是預設做法，但某些型別的預設做法為複製：

fn main() {
    let x = 42;
    let y = x;
    println!("x: {x}"); // would not be accessible if not Copy
    println!("y: {y}");
}

這些型別會實作 Copy 特徵。

您可以自行選擇加入型別，使用複製語意的做法：

#[derive(Copy, Clone, Debug)]
struct Point(i32, i32);

fn main() {
    let p1 = Point(3, 4);
    let p2 = p1;
    println!("p1: {p1:?}");
    println!("p2: {p2:?}");
}

• 指派後，p1 和 p2 都會擁有自己的資料。
• 我們也能使用 p1.clone() 明確複製資料。

Drop 特徵

如果值實作了 Drop，即可在超出範圍時指定要執行哪個程式碼：

struct Droppable {
    name: &'static str,
}

impl Drop for Droppable {
    fn drop(&mut self) {
        println!("Dropping {}", self.name);
    }
}

fn main() {
    let a = Droppable { name: "a" };
    {
        let b = Droppable { name: "b" };
        {
            let c = Droppable { name: "c" };
            let d = Droppable { name: "d" };
            println!("Exiting block B");
        }
        println!("Exiting block A");
    }
    drop(a);
    println!("Exiting main");
}

練習：建構工具型別

在本範例中，我們將實作一個包含自身所有資料的複雜資料型別。透過「建構工具模式」，我們會以便利函式逐段建構新值。

請填補缺漏的片段。

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// A representation of a software package.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Return a representation of this package as a dependency, for use in
    /// building other packages.
    fn as_dependency(&self) -> Dependency {
        todo!("1")
    }
}

/// A builder for a Package. Use `build()` to create the `Package` itself.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        todo!("2")
    }

    /// Set the package version.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Set the package authors.
    fn authors(mut self, authors: Vec<String>) -> Self {
        todo!("3")
    }

    /// Add an additional dependency.
    fn dependency(mut self, dependency: Dependency) -> Self {
        todo!("4")
    }

    /// Set the language. If not set, language defaults to None.
    fn language(mut self, language: Language) -> Self {
        todo!("5")
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

解決方案

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// A representation of a software package.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Return a representation of this package as a dependency, for use in
    /// building other packages.
    fn as_dependency(&self) -> Dependency {
        Dependency {
            name: self.name.clone(),
            version_expression: self.version.clone(),
        }
    }
}

/// A builder for a Package. Use `build()` to create the `Package` itself.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        Self(Package {
            name: name.into(),
            version: "0.1".into(),
            authors: vec![],
            dependencies: vec![],
            language: None,
        })
    }

    /// Set the package version.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Set the package authors.
    fn authors(mut self, authors: Vec<String>) -> Self {
        self.0.authors = authors;
        self
    }

    /// Add an additional dependency.
    fn dependency(mut self, dependency: Dependency) -> Self {
        self.0.dependencies.push(dependency);
        self
    }

    /// Set the language. If not set, language defaults to None.
    fn language(mut self, language: Language) -> Self {
        self.0.language = Some(language);
        self
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

智慧指標

This segment should take about 55 minutes. It contains:

Box<T>

Box 是具有所有權的指向堆積上的資料的指標：

fn main() {
    let five = Box::new(5);
    println!("five: {}", *five);
}

Box<T> 會實作 Deref<Target = T>。也就是說，您可以直接在 Box<T> 上透過 T 呼叫方法。

遞迴資料型別或含有動態大小的資料型別必須使用 Box：

#[derive(Debug)]
enum List<T> {
    /// A non-empty list: first element and the rest of the list.
    Element(T, Box<List<T>>),
    /// An empty list.
    Nil,
}

fn main() {
    let list: List<i32> =
        List::Element(1, Box::new(List::Element(2, Box::new(List::Nil))));
    println!("{list:?}");
}

#[derive(Debug)]
enum List<T> {
    Element(T, Box<List<T>>),
    Nil,
}

fn main() {
    let list: List<i32> =
        List::Element(1, Box::new(List::Element(2, Box::new(List::Nil))));
    println!("{list:?}");
}

Rc

Rc 是參考計數的共用指標。如要在多個位置參考相同的資料，可以使用這個指標：

use std::rc::Rc;

fn main() {
    let a = Rc::new(10);
    let b = Rc::clone(&a);

    println!("a: {a}");
    println!("b: {b}");
}

• 如果您處於多執行緒的環境，請參閱 Arc 和 Mutex。
• 您可以將共用指標「降級」為 Weak 指標，以便建立之後會捨棄的循環。

特徵物件

特徵物件可接受不同型別的值，舉例來說，在集合中會是這樣：

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Woof, my name is {}!", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("Miau!")
    }
}

fn main() {
    let pets: Vec<Box<dyn Pet>> = vec![
        Box::new(Cat { lives: 9 }),
        Box::new(Dog { name: String::from("Fido"), age: 5 }),
    ];
    for pet in pets {
        println!("Hello, who are you? {}", pet.talk());
    }
}

以下是配置 pets 後的記憶體配置：

練習：二元樹

二元樹是一種樹狀資料結構，其中每個節點都有左右兩個子節點。我們會建立每個節點都儲存一個值的樹狀結構。以指定節點 N 來說，N 左側子樹狀結構中的所有節點都包含較小的值，而 N 右側子樹狀結構中的所有節點都含有較大的值。

請實作以下型別，讓指定的測試通過。

加分題：在二元數上實作疊代器，依序傳回值。

/// A node in the binary tree.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// A possibly-empty subtree.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// A container storing a set of values, using a binary tree.
///
/// If the same value is added multiple times, it is only stored once.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

// Implement `new`, `insert`, `len`, and `has`.

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // not a unique item
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

解決方案

use std::cmp::Ordering;

/// A node in the binary tree.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// A possibly-empty subtree.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// A container storing a set of values, using a binary tree.
///
/// If the same value is added multiple times, it is only stored once.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

impl<T: Ord> Subtree<T> {
    fn new() -> Self {
        Self(None)
    }

    fn insert(&mut self, value: T) {
        match &mut self.0 {
            None => self.0 = Some(Box::new(Node::new(value))),
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.insert(value),
                Ordering::Equal => {}
                Ordering::Greater => n.right.insert(value),
            },
        }
    }

    fn has(&self, value: &T) -> bool {
        match &self.0 {
            None => false,
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.has(value),
                Ordering::Equal => true,
                Ordering::Greater => n.right.has(value),
            },
        }
    }

    fn len(&self) -> usize {
        match &self.0 {
            None => 0,
            Some(n) => 1 + n.left.len() + n.right.len(),
        }
    }
}

impl<T: Ord> Node<T> {
    fn new(value: T) -> Self {
        Self { value, left: Subtree::new(), right: Subtree::new() }
    }
}

fn main() {
    let mut tree = BinaryTree::new();
    tree.insert("foo");
    assert_eq!(tree.len(), 1);
    tree.insert("bar");
    assert!(tree.has(&"foo"));
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // not a unique item
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

Welcome Back

Including 10 minute breaks, this session should take about 2 hours and 10 minutes. It contains:

借用

This segment should take about 50 minutes. It contains:

借用

As we saw before, instead of transferring ownership when calling a function, you can let a function borrow the value:

#[derive(Debug)]
struct Point(i32, i32);

fn add(p1: &Point, p2: &Point) -> Point {
    Point(p1.0 + p2.0, p1.1 + p2.1)
}

fn main() {
    let p1 = Point(3, 4);
    let p2 = Point(10, 20);
    let p3 = add(&p1, &p2);
    println!("{p1:?} + {p2:?} = {p3:?}");
}

• add 函式會「借用」兩個點，並傳回新的點。
• 呼叫端會保留輸入內容的所有權。

借用

Rust's borrow checker puts constraints on the ways you can borrow values. For a given value, at any time:

• You can have one or more shared references to the value, or
• You can have exactly one exclusive reference to the value.

fn main() {
    let mut a: i32 = 10;
    let b: &i32 = &a;

    {
        let c: &mut i32 = &mut a;
        *c = 20;
    }

    println!("a: {a}");
    println!("b: {b}");
}

內部可變性 (Interior Mutability)

在某些情況下，您必須修改共用 (唯讀) 參照背後的資料：比方說，共用的資料結構可能含有內部快取，並想透過唯讀方法更新該快取。

「內部可變動性」模式可以在共用參照背後提供專屬 (可變動的) 存取權。標準程式庫支援以多種方式執行此操作，同時仍可確保安全，做法通常是執行執行階段檢查。

RefCell

use std::cell::RefCell;
use std::rc::Rc;

#[derive(Debug, Default)]
struct Node {
    value: i64,
    children: Vec<Rc<RefCell<Node>>>,
}

impl Node {
    fn new(value: i64) -> Rc<RefCell<Node>> {
        Rc::new(RefCell::new(Node { value, ..Node::default() }))
    }

    fn sum(&self) -> i64 {
        self.value + self.children.iter().map(|c| c.borrow().sum()).sum::<i64>()
    }
}

fn main() {
    let root = Node::new(1);
    root.borrow_mut().children.push(Node::new(5));
    let subtree = Node::new(10);
    subtree.borrow_mut().children.push(Node::new(11));
    subtree.borrow_mut().children.push(Node::new(12));
    root.borrow_mut().children.push(subtree);

    println!("graph: {root:#?}");
    println!("graph sum: {}", root.borrow().sum());
}

Cell

Cell 會納入值，並允許取得或設定該值，即使具有對 Cell 的共用參照也一樣。但是，它不允許對該值進行任何參照。由於沒有參照，因此借用規則不得違反。

練習：衛生統計資料

您正在實作健康監控系統，因此須追蹤使用者的健康統計資料。

You'll start with a stubbed function in an impl block as well as a User struct definition. Your goal is to implement the stubbed out method on the User struct defined in the impl block.

Copy the code below to https://play.rust-lang.org/ and fill in the missing method:

// TODO: remove this when you're done with your implementation.
#![allow(unused_variables, dead_code)]


#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        todo!("Update a user's statistics based on measurements from a visit to the doctor")
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("I'm {} and my age is {}", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
}

解決方案

#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        self.visit_count += 1;
        let bp = measurements.blood_pressure;
        let report = HealthReport {
            patient_name: &self.name,
            visit_count: self.visit_count as u32,
            height_change: measurements.height - self.height,
            blood_pressure_change: match self.last_blood_pressure {
                Some(lbp) => {
                    Some((bp.0 as i32 - lbp.0 as i32, bp.1 as i32 - lbp.1 as i32))
                }
                None => None,
            },
        };
        self.height = measurements.height;
        self.last_blood_pressure = Some(bp);
        report
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("I'm {} and my age is {}", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
}

生命週期

This segment should take about 1 hour and 10 minutes. It contains:

切片

切片能讓您查看更大的集合：

fn main() {
    let mut a: [i32; 6] = [10, 20, 30, 40, 50, 60];
    println!("a: {a:?}");

    let s: &[i32] = &a[2..4];

    println!("s: {s:?}");
}

• 切片會從切片型別借用資料。
• 問題：如果在輸出 s 前修改 a[3]，會有什麼影響？

迷途參照

我們現在可以瞭解 Rust 中有兩種字串型別，&str 幾近於 &[char]，但其資料是以可變長度編碼 (UTF-8) 儲存。

fn main() {
    let s1: &str = "World";
    println!("s1: {s1}");

    let mut s2: String = String::from("Hello ");
    println!("s2: {s2}");
    s2.push_str(s1);
    println!("s2: {s2}");

    let s3: &str = &s2[6..];
    println!("s3: {s3}");
}

以 Rust 術語來說會是這樣：

• &str 是對字串切片的不可變參照。
• String 是可變動的字串緩衝區。

函式呼叫中的生命週期

參照的「生命週期」不得「超過」其所參照的值。此由借用檢查器負責驗證。

按照我們目前所見，生命週期可以隱晦表示。不過，&'a Point、&'document str 也可以明確表示生命週期。生命週期的開頭為 '，一般預設名稱為 'a。請將 ``&'a Point讀做「至少對生命週期a有效的借用Point`」。

Lifetimes are always inferred by the compiler: you cannot assign a lifetime yourself. Explicit lifetime annotations create constraints where there is ambiguity; the compiler verifies that there is a valid solution.

在考慮與函式間傳遞值時，生命週期會變得比較複雜。

#[derive(Debug)]
struct Point(i32, i32);

fn left_most(p1: &Point, p2: &Point) -> &Point {
    if p1.0 < p2.0 {
        p1
    } else {
        p2
    }
}

fn main() {
    let p1: Point = Point(10, 10);
    let p2: Point = Point(20, 20);
    let p3 = left_most(&p1, &p2); // What is the lifetime of p3?
    println!("p3: {p3:?}");
}

fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point {

函式呼叫中的生命週期

Lifetimes for function arguments and return values must be fully specified, but Rust allows lifetimes to be elided in most cases with a few simple rules. This is not inference -- it is just a syntactic shorthand.

• 凡是沒有生命週期註解的引數都會獲得一個註解。
• 如果只有一個引數生命週期，則會提供給所有未加註的回傳值。
• 如果有多個引數生命週期，但第一個是要給 self，這個生命週期會提供給所有未加註的回傳值。

#[derive(Debug)]
struct Point(i32, i32);

fn cab_distance(p1: &Point, p2: &Point) -> i32 {
    (p1.0 - p2.0).abs() + (p1.1 - p2.1).abs()
}

fn nearest<'a>(points: &'a [Point], query: &Point) -> Option<&'a Point> {
    let mut nearest = None;
    for p in points {
        if let Some((_, nearest_dist)) = nearest {
            let dist = cab_distance(p, query);
            if dist < nearest_dist {
                nearest = Some((p, dist));
            }
        } else {
            nearest = Some((p, cab_distance(p, query)));
        };
    }
    nearest.map(|(p, _)| p)
}

fn main() {
    println!(
        "{:?}",
        nearest(
            &[Point(1, 0), Point(1, 0), Point(-1, 0), Point(0, -1),],
            &Point(0, 2)
        )
    );
}

fn nearest<'a, 'q>(points: &'a [Point], query: &'q Point) -> Option<&'q Point> {

資料結構中的生命週期

如果資料型別會儲存借用的資料，則必須使用生命週期註解：

#[derive(Debug)]
struct Highlight<'doc>(&'doc str);

fn erase(text: String) {
    println!("Bye {text}!");
}

fn main() {
    let text = String::from("The quick brown fox jumps over the lazy dog.");
    let fox = Highlight(&text[4..19]);
    let dog = Highlight(&text[35..43]);
    // erase(text);
    println!("{fox:?}");
    println!("{dog:?}");
}

練習：Protobuf 剖析

在本練習中，您將建構 protobuf 二進位編碼的剖析器。請放心，這比看起來容易！這個練習也會舉例說明常見的剖析模式，也就是傳遞資料切片。基礎資料本身一律不會複製。

如要完整剖析 protobuf 訊息，您必須瞭解欄位型別，這會依欄位編號建立索引，通常位於 proto 檔案內。在本練習中，我們會在針對各欄位呼叫的函式中，將該資訊編碼為 match 陳述式。

我們將使用以下 proto：

message PhoneNumber {
  optional string number = 1;
  optional string type = 2;
}

message Person {
  optional string name = 1;
  optional int32 id = 2;
  repeated PhoneNumber phones = 3;
}

proto 訊息會編碼為一系列的欄位，一個接著一個。每個欄位都以後方加上值的「標記」形式實作。此標記含有欄位編號 (例如 Person 訊息的 id 欄位編號是 2) 以及有線型別，後者負責定義應如何從位元組資料流中決定酬載。

整數 (包含標記) 會以稱為 VARINT 的可變長度編碼表示。好消息是，以下程式碼已為您定義 parse_varint。該程式碼也定義了回呼，藉此處理 Person 和 PhoneNumber 欄位，並將訊息剖析為對這些回呼的一系列呼叫。

您剩下的就只是為 Person 和 PhoneNumber 實作 parse_field 函式和 ProtoMessage 特徵即可。

use std::convert::TryFrom;
use thiserror::Error;

#[derive(Debug, Error)]
enum Error {
    #[error("Invalid varint")]
    InvalidVarint,
    #[error("Invalid wire-type")]
    InvalidWireType,
    #[error("Unexpected EOF")]
    UnexpectedEOF,
    #[error("Invalid length")]
    InvalidSize(#[from] std::num::TryFromIntError),
    #[error("Unexpected wire-type)")]
    UnexpectedWireType,
    #[error("Invalid string (not UTF-8)")]
    InvalidString,
}

/// A wire type as seen on the wire.
enum WireType {
    /// The Varint WireType indicates the value is a single VARINT.
    Varint,
    //I64,  -- not needed for this exercise
    /// The Len WireType indicates that the value is a length represented as a
    /// VARINT followed by exactly that number of bytes.
    Len,
    /// The I32 WireType indicates that the value is precisely 4 bytes in
    /// little-endian order containing a 32-bit signed integer.
    I32,
}

#[derive(Debug)]
/// A field's value, typed based on the wire type.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- not needed for this exercise
    Len(&'a [u8]),
    I32(i32),
}

#[derive(Debug)]
/// A field, containing the field number and its value.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default + 'a {
    fn add_field(&mut self, field: Field<'a>) -> Result<(), Error>;
}

impl TryFrom<u64> for WireType {
    type Error = Error;

    fn try_from(value: u64) -> Result<WireType, Error> {
        Ok(match value {
            0 => WireType::Varint,
            //1 => WireType::I64,  -- not needed for this exercise
            2 => WireType::Len,
            5 => WireType::I32,
            _ => return Err(Error::InvalidWireType),
        })
    }
}

impl<'a> FieldValue<'a> {
    fn as_string(&self) -> Result<&'a str, Error> {
        let FieldValue::Len(data) = self else {
            return Err(Error::UnexpectedWireType);
        };
        std::str::from_utf8(data).map_err(|_| Error::InvalidString)
    }

    fn as_bytes(&self) -> Result<&'a [u8], Error> {
        let FieldValue::Len(data) = self else {
            return Err(Error::UnexpectedWireType);
        };
        Ok(data)
    }

    fn as_u64(&self) -> Result<u64, Error> {
        let FieldValue::Varint(value) = self else {
            return Err(Error::UnexpectedWireType);
        };
        Ok(*value)
    }
}

/// Parse a VARINT, returning the parsed value and the remaining bytes.
fn parse_varint(data: &[u8]) -> Result<(u64, &[u8]), Error> {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            return Err(Error::InvalidVarint);
        };
        if b & 0x80 == 0 {
            // This is the last byte of the VARINT, so convert it to
            // a u64 and return it.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return Ok((value, &data[i + 1..]));
        }
    }

    // More than 7 bytes is invalid.
    Err(Error::InvalidVarint)
}

/// Convert a tag into a field number and a WireType.
fn unpack_tag(tag: u64) -> Result<(u64, WireType), Error> {
    let field_num = tag >> 3;
    let wire_type = WireType::try_from(tag & 0x7)?;
    Ok((field_num, wire_type))
}


/// Parse a field, returning the remaining bytes
fn parse_field(data: &[u8]) -> Result<(Field, &[u8]), Error> {
    let (tag, remainder) = parse_varint(data)?;
    let (field_num, wire_type) = unpack_tag(tag)?;
    let (fieldvalue, remainder) = match wire_type {
        _ => todo!("Based on the wire type, build a Field, consuming as many bytes as necessary.")
    };
    todo!("Return the field, and any un-consumed bytes.")
}

/// Parse a message in the given data, calling `T::add_field` for each field in
/// the message.
///
/// The entire input is consumed.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> Result<T, Error> {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data)?;
        result.add_field(parsed.0)?;
        data = parsed.1;
    }
    Ok(result)
}

#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

// TODO: Implement ProtoMessage for Person and PhoneNumber.

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ])
    .unwrap();
    println!("{:#?}", person);
}

解決方案

use std::convert::TryFrom;
use thiserror::Error;

#[derive(Debug, Error)]
enum Error {
    #[error("Invalid varint")]
    InvalidVarint,
    #[error("Invalid wire-type")]
    InvalidWireType,
    #[error("Unexpected EOF")]
    UnexpectedEOF,
    #[error("Invalid length")]
    InvalidSize(#[from] std::num::TryFromIntError),
    #[error("Unexpected wire-type)")]
    UnexpectedWireType,
    #[error("Invalid string (not UTF-8)")]
    InvalidString,
}

/// A wire type as seen on the wire.
enum WireType {
    /// The Varint WireType indicates the value is a single VARINT.
    Varint,
    //I64,  -- not needed for this exercise
    /// The Len WireType indicates that the value is a length represented as a
    /// VARINT followed by exactly that number of bytes.
    Len,
    /// The I32 WireType indicates that the value is precisely 4 bytes in
    /// little-endian order containing a 32-bit signed integer.
    I32,
}

#[derive(Debug)]
/// A field's value, typed based on the wire type.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- not needed for this exercise
    Len(&'a [u8]),
    I32(i32),
}

#[derive(Debug)]
/// A field, containing the field number and its value.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default + 'a {
    fn add_field(&mut self, field: Field<'a>) -> Result<(), Error>;
}

impl TryFrom<u64> for WireType {
    type Error = Error;

    fn try_from(value: u64) -> Result<WireType, Error> {
        Ok(match value {
            0 => WireType::Varint,
            //1 => WireType::I64,  -- not needed for this exercise
            2 => WireType::Len,
            5 => WireType::I32,
            _ => return Err(Error::InvalidWireType),
        })
    }
}

impl<'a> FieldValue<'a> {
    fn as_string(&self) -> Result<&'a str, Error> {
        let FieldValue::Len(data) = self else {
            return Err(Error::UnexpectedWireType);
        };
        std::str::from_utf8(data).map_err(|_| Error::InvalidString)
    }

    fn as_bytes(&self) -> Result<&'a [u8], Error> {
        let FieldValue::Len(data) = self else {
            return Err(Error::UnexpectedWireType);
        };
        Ok(data)
    }

    fn as_u64(&self) -> Result<u64, Error> {
        let FieldValue::Varint(value) = self else {
            return Err(Error::UnexpectedWireType);
        };
        Ok(*value)
    }
}

/// Parse a VARINT, returning the parsed value and the remaining bytes.
fn parse_varint(data: &[u8]) -> Result<(u64, &[u8]), Error> {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            return Err(Error::InvalidVarint);
        };
        if b & 0x80 == 0 {
            // This is the last byte of the VARINT, so convert it to
            // a u64 and return it.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return Ok((value, &data[i + 1..]));
        }
    }

    // More than 7 bytes is invalid.
    Err(Error::InvalidVarint)
}

/// Convert a tag into a field number and a WireType.
fn unpack_tag(tag: u64) -> Result<(u64, WireType), Error> {
    let field_num = tag >> 3;
    let wire_type = WireType::try_from(tag & 0x7)?;
    Ok((field_num, wire_type))
}

/// Parse a field, returning the remaining bytes
fn parse_field(data: &[u8]) -> Result<(Field, &[u8]), Error> {
    let (tag, remainder) = parse_varint(data)?;
    let (field_num, wire_type) = unpack_tag(tag)?;
    let (fieldvalue, remainder) = match wire_type {
        WireType::Varint => {
            let (value, remainder) = parse_varint(remainder)?;
            (FieldValue::Varint(value), remainder)
        }
        WireType::Len => {
            let (len, remainder) = parse_varint(remainder)?;
            let len: usize = len.try_into()?;
            if remainder.len() < len {
                return Err(Error::UnexpectedEOF);
            }
            let (value, remainder) = remainder.split_at(len);
            (FieldValue::Len(value), remainder)
        }
        WireType::I32 => {
            if remainder.len() < 4 {
                return Err(Error::UnexpectedEOF);
            }
            let (value, remainder) = remainder.split_at(4);
            // Unwrap error because `value` is definitely 4 bytes long.
            let value = i32::from_le_bytes(value.try_into().unwrap());
            (FieldValue::I32(value), remainder)
        }
    };
    Ok((Field { field_num, value: fieldvalue }, remainder))
}

/// Parse a message in the given data, calling `T::add_field` for each field in
/// the message.
///
/// The entire input is consumed.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> Result<T, Error> {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data)?;
        result.add_field(parsed.0)?;
        data = parsed.1;
    }
    Ok(result)
}

#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

impl<'a> ProtoMessage<'a> for Person<'a> {
    fn add_field(&mut self, field: Field<'a>) -> Result<(), Error> {
        match field.field_num {
            1 => self.name = field.value.as_string()?,
            2 => self.id = field.value.as_u64()?,
            3 => self.phone.push(parse_message(field.value.as_bytes()?)?),
            _ => {} // skip everything else
        }
        Ok(())
    }
}

impl<'a> ProtoMessage<'a> for PhoneNumber<'a> {
    fn add_field(&mut self, field: Field<'a>) -> Result<(), Error> {
        match field.field_num {
            1 => self.number = field.value.as_string()?,
            2 => self.type_ = field.value.as_string()?,
            _ => {} // skip everything else
        }
        Ok(())
    }
}

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ])
    .unwrap();
    println!("{:#?}", person);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn as_string() {
        assert!(FieldValue::Varint(10).as_string().is_err());
        assert!(FieldValue::I32(10).as_string().is_err());
        assert_eq!(FieldValue::Len(b"hello").as_string().unwrap(), "hello");
    }

    #[test]
    fn as_bytes() {
        assert!(FieldValue::Varint(10).as_bytes().is_err());
        assert!(FieldValue::I32(10).as_bytes().is_err());
        assert_eq!(FieldValue::Len(b"hello").as_bytes().unwrap(), b"hello");
    }

    #[test]
    fn as_u64() {
        assert_eq!(FieldValue::Varint(10).as_u64().unwrap(), 10u64);
        assert!(FieldValue::I32(10).as_u64().is_err());
        assert!(FieldValue::Len(b"hello").as_u64().is_err());
    }
}

歡迎參加第 4 天課程

Today we will cover topics relating to building large-scale software in Rust:

• 疊代器：深入探討 Iterator 特徵。
• 模組和可見性。
• 測試。
• 錯誤處理：恐慌、Result，以及 try 運算子 ?。
• 不安全的 Rust：不能寫出安全的 Rust 時的應急方法。

課程時間表

Including 10 minute breaks, this session should take about 2 hours and 40 minutes. It contains:

疊代器

This segment should take about 45 minutes. It contains:

Iterator

Iterator 特徵可讓您對集合中的值進行疊代作業。這需要用到 next 方法，且會提供大量方法。許多標準程式庫型別都能實作 Iterator，而您也可以自行實作：

struct Fibonacci {
    curr: u32,
    next: u32,
}

impl Iterator for Fibonacci {
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        let new_next = self.curr + self.next;
        self.curr = self.next;
        self.next = new_next;
        Some(self.curr)
    }
}

fn main() {
    let fib = Fibonacci { curr: 0, next: 1 };
    for (i, n) in fib.enumerate().take(5) {
        println!("fib({i}): {n}");
    }
}

IntoIterator

The Iterator trait tells you how to iterate once you have created an iterator. The related trait IntoIterator defines how to create an iterator for a type. It is used automatically by the for loop.

struct Grid {
    x_coords: Vec<u32>,
    y_coords: Vec<u32>,
}

impl IntoIterator for Grid {
    type Item = (u32, u32);
    type IntoIter = GridIter;
    fn into_iter(self) -> GridIter {
        GridIter { grid: self, i: 0, j: 0 }
    }
}

struct GridIter {
    grid: Grid,
    i: usize,
    j: usize,
}

impl Iterator for GridIter {
    type Item = (u32, u32);

    fn next(&mut self) -> Option<(u32, u32)> {
        if self.i >= self.grid.x_coords.len() {
            self.i = 0;
            self.j += 1;
            if self.j >= self.grid.y_coords.len() {
                return None;
            }
        }
        let res = Some((self.grid.x_coords[self.i], self.grid.y_coords[self.j]));
        self.i += 1;
        res
    }
}

fn main() {
    let grid = Grid { x_coords: vec![3, 5, 7, 9], y_coords: vec![10, 20, 30, 40] };
    for (x, y) in grid {
        println!("point = {x}, {y}");
    }
}

FromIterator

FromIterator 可讓您透過 Iterator 建構集合。

fn main() {
    let primes = vec![2, 3, 5, 7];
    let prime_squares = primes.into_iter().map(|p| p * p).collect::<Vec<_>>();
    println!("prime_squares: {prime_squares:?}");
}

fn collect<B>(self) -> B
where
    B: FromIterator<Self::Item>,
    Self: Sized

練習：疊代器方法鏈結

In this exercise, you will need to find and use some of the provided methods in the Iterator trait to implement a complex calculation.

Copy the following code to https://play.rust-lang.org/ and make the tests pass. Use an iterator expression and collect the result to construct the return value.

#![allow(unused)]
fn main() {
/// Calculate the differences between elements of `values` offset by `offset`,
/// wrapping around from the end of `values` to the beginning.
///
/// Element `n` of the result is `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    unimplemented!()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}
}

解決方案

/// Calculate the differences between elements of `values` offset by `offset`,
/// wrapping around from the end of `values` to the beginning.
///
/// Element `n` of the result is `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    let a = (&values).into_iter();
    let b = (&values).into_iter().cycle().skip(offset);
    a.zip(b).map(|(a, b)| *b - *a).collect()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}

fn main() {}

模組

This segment should take about 40 minutes. It contains:

模組

我們已介紹 impl 區塊如何讓我們將函式的命名空間建立為型別。

同樣地，mod 可讓我們建立型別和函式的命名空間：

mod foo {
    pub fn do_something() {
        println!("In the foo module");
    }
}

mod bar {
    pub fn do_something() {
        println!("In the bar module");
    }
}

fn main() {
    foo::do_something();
    bar::do_something();
}

檔案系統階層

如果您省略模組內容，系統會指示 Rust 在其他檔案中尋找該內容：

mod garden;

這會讓 Rust 知道 garden 模組內容是在 src/garden.rs 中找到的。同樣地，garden::vegetables 模組可在 src/garden/vegetables.rs 中找到。

crate 根層級位於：

• src/lib.rs (適用於程式庫 Crate)
• src/main.rs (適用於二進位檔 Crate)

您也可以使用 "inner doc comments" 記錄檔案中定義的模組。這些會記錄包含它們的項目，在本例中就是模組。

//! This module implements the garden, including a highly performant germination
//! implementation.

// Re-export types from this module.
pub use garden::Garden;
pub use seeds::SeedPacket;

/// Sow the given seed packets.
pub fn sow(seeds: Vec<SeedPacket>) {
    todo!()
}

/// Harvest the produce in the garden that is ready.
pub fn harvest(garden: &mut Garden) {
    todo!()
}

能見度

我們可將模組視為隱私邊界：

• 模組項目預設為不公開 (會隱藏實作詳細資料)。
• 父項和同層項目一律會顯示。
• 換句話說，如果項目顯示在 foo 模組中，則會出現在 foo 的所有子系中。

mod outer {
    fn private() {
        println!("outer::private");
    }

    pub fn public() {
        println!("outer::public");
    }

    mod inner {
        fn private() {
            println!("outer::inner::private");
        }

        pub fn public() {
            println!("outer::inner::public");
            super::private();
        }
    }
}

fn main() {
    outer::public();
}

use、super、self

模組可以使用 use 將其他模組的符號帶進範圍內。您通常會在每個模組的頂端看到類似下方的內容：

use std::collections::HashSet;
use std::process::abort;

路徑

路徑的解析方式包括：

1. 做為相對路徑：

   • foo 或 self::foo 是指目前模組中的 foo。
   • super::foo 是指父項模組中的 foo。

2. 做為絕對路徑：

   • crate::foo 是指目前 Crate 根目錄中的 foo。
   • bar::foo 是指 bar Crate 中的 foo。

練習：GUI 程式庫的模組

在本練習中，您將重新編排小型的 GUI 程式庫實作項目。這個程式庫定義了 Widget 特徵、該特徵的幾個實作項目，以及 main 函式。

通常，每種型別 (或一組密切相關的型別) 會放入各自的模組中，因此每個小工具型別應該都有自己的模組。

Cargo Setup

Rust Playground 僅支援一個檔案，因此您需要在本機檔案系統中建立 Cargo 專案：

cargo init gui-modules
cd gui-modules
cargo run

請編輯產生的 src/main.rs，新增 mod 陳述式並在 src 目錄中新增其他檔案。

來源

以下是 GUI 程式庫的單一模組實作項目：

pub trait Widget {
    /// Natural width of `self`.
    fn width(&self) -> usize;

    /// Draw the widget into a buffer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Draw the widget on standard output.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub struct Label {
    label: String,
}

impl Label {
    fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

pub struct Button {
    label: Label,
}

impl Button {
    fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // Add 4 paddings for borders
        self.inner_width() + 4
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: Change draw_into to return Result<(), std::fmt::Error>. Then use the
        // ?-operator here instead of .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        self.label.width() + 8 // add a bit of padding
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

fn main() {
    let mut window = Window::new("Rust GUI Demo 1.23");
    window.add_widget(Box::new(Label::new("This is a small text GUI demo.")));
    window.add_widget(Box::new(Button::new("Click me!")));
    window.draw();
}

解決方案

src
├── main.rs
├── widgets
│   ├── button.rs
│   ├── label.rs
│   └── window.rs
└── widgets.rs

// ---- src/widgets.rs ----
mod button;
mod label;
mod window;

pub trait Widget {
    /// Natural width of `self`.
    fn width(&self) -> usize;

    /// Draw the widget into a buffer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Draw the widget on standard output.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub use button::Button;
pub use label::Label;
pub use window::Window;

// ---- src/widgets/label.rs ----
use super::Widget;

pub struct Label {
    label: String,
}

impl Label {
    pub fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        // ANCHOR_END: Label-width
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    // ANCHOR: Label-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Label-draw_into
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

// ---- src/widgets/button.rs ----
use super::{Label, Widget};

pub struct Button {
    label: Label,
}

impl Button {
    pub fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        // ANCHOR_END: Button-width
        self.label.width() + 8 // add a bit of padding
    }

    // ANCHOR: Button-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Button-draw_into
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

// ---- src/widgets/window.rs ----
use super::Widget;

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    pub fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    pub fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // ANCHOR_END: Window-width
        // Add 4 paddings for borders
        self.inner_width() + 4
    }

    // ANCHOR: Window-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Window-draw_into
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: after learning about error handling, you can change
        // draw_into to return Result<(), std::fmt::Error>. Then use
        // the ?-operator here instead of .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

// ---- src/main.rs ----
mod widgets;

use widgets::Widget;

fn main() {
    let mut window = widgets::Window::new("Rust GUI Demo 1.23");
    window
        .add_widget(Box::new(widgets::Label::new("This is a small text GUI demo.")));
    window.add_widget(Box::new(widgets::Button::new("Click me!")));
    window.draw();
}

測試

This segment should take about 45 minutes. It contains:

單元測試

Rust 和 Cargo 提供了一個簡單的單元測試 (unit test) 框架：

• 在你的程式碼的任何地方都可添加單元測試。

• 整合測試 (integration test) 則可放置在 tests/ 資料夾下。

測試會以 #[test] 標示。單元測試通常會位於巢狀的 tests 模組中，使用 #[cfg(test)] 可有條件地編譯測試 (僅限在建構測試時)。

fn first_word(text: &str) -> &str {
    match text.find(' ') {
        Some(idx) => &text[..idx],
        None => &text,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_empty() {
        assert_eq!(first_word(""), "");
    }

    #[test]
    fn test_single_word() {
        assert_eq!(first_word("Hello"), "Hello");
    }

    #[test]
    fn test_multiple_words() {
        assert_eq!(first_word("Hello World"), "Hello");
    }
}

• 這有助於您對私人輔助程式進行單元測試。
• 只有在執行 cargo test 時，#[cfg(test)] 屬性才會生效。

其他資源

整合測試

如果您要以用戶端身分測試程式庫，請採用整合測試。

在 tests/ 之下建立一個 .rs 檔案：

// tests/my_library.rs
use my_library::init;

#[test]
fn test_init() {
    assert!(init().is_ok());
}

這些測試只能存取 crate 的公用 API。

說明文件測試

Rust 內建說明文件測試相關支援：

#![allow(unused)]
fn main() {
/// Shortens a string to the given length.
///
/// ```
/// # use playground::shorten_string;
/// assert_eq!(shorten_string("Hello World", 5), "Hello");
/// assert_eq!(shorten_string("Hello World", 20), "Hello World");
/// ```
pub fn shorten_string(s: &str, length: usize) -> &str {
    &s[..std::cmp::min(length, s.len())]
}
}

• 系統會自動將 /// 註解中的程式碼區塊視為 Rust 程式碼。
• 系統會編譯程式碼，執行 cargo test 時會一併執行這些程式碼。
• 程式碼中新增 # 後，即可從文件中隱藏，但仍會編譯/執行。
• 請在 Rust Playground 上測試上述程式碼。

編譯器檢查 (Lint) 和 Clippy

Rust 編譯器會產生高品質的錯誤訊息，以及實用的內建 Lint。Clippy 則提供更多 Lint，且會整理成可供每個專案啟用的群組。

#[deny(clippy::cast_possible_truncation)]
fn main() {
    let x = 3;
    while (x < 70000) {
        x *= 2;
    }
    println!("X probably fits in a u16, right? {}", x as u16);
}

盧恩演算法

盧恩演算法

盧恩演算法可用於驗證信用卡號碼。這個演算法會將字串做為輸入內容，並執行下列操作來驗證信用卡號碼：

• Ignore all spaces. Reject number with fewer than two digits.

• 從右到左，將偶數位的數字乘二。以數字 1234 為例，請將 3 和 1 乘二；若為數字 98765，請將 6 和 8 乘二。

• 將數字乘二後，如果結果大於 9，請將每位數字相加。所以，7 乘二等於 14，那麼也就是 1 + 4 = 5。

• 將所有數字 (無論是否已乘二) 相加。

• 如果加總所得數字的末位是 0，代表信用卡卡號有效。

這裡提供的程式碼是盧恩演算法的錯誤實作示例，另外還有兩個基本單元測試，用於確認大部分演算法已正確實作。

Copy the code below to https://play.rust-lang.org/ and write additional tests to uncover bugs in the provided implementation, fixing any bugs you find.

#![allow(unused)]
fn main() {
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }
}
}

解決方案

// This is the buggy version that appears in the problem.
#[cfg(never)]
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

// This is the solution and passes all of the tests below.
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;
    let mut digits = 0;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            digits += 1;
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else if c.is_whitespace() {
            continue;
        } else {
            return false;
        }
    }

    digits >= 2 && sum % 10 == 0
}

fn main() {
    let cc_number = "1234 5678 1234 5670";
    println!(
        "Is {cc_number} a valid credit card number? {}",
        if luhn(cc_number) { "yes" } else { "no" }
    );
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }

    #[test]
    fn test_non_digit_cc_number() {
        assert!(!luhn("foo"));
        assert!(!luhn("foo 0 0"));
    }

    #[test]
    fn test_empty_cc_number() {
        assert!(!luhn(""));
        assert!(!luhn(" "));
        assert!(!luhn("  "));
        assert!(!luhn("    "));
    }

    #[test]
    fn test_single_digit_cc_number() {
        assert!(!luhn("0"));
    }

    #[test]
    fn test_two_digit_cc_number() {
        assert!(luhn(" 0 0 "));
    }
}

Welcome Back

Including 10 minute breaks, this session should take about 2 hours and 10 minutes. It contains:

錯誤處理

This segment should take about 55 minutes. It contains:

恐慌

Rust 會透過「恐慌」來處理嚴重錯誤。

如果執行階段發生重大錯誤，Rust 就會觸發恐慌：

fn main() {
    let v = vec![10, 20, 30];
    println!("v[100]: {}", v[100]);
}

• 恐慌代表發生無法復原的非預期錯誤。
  • 恐慌可以反映程式中的錯誤。
  • 執行階段失敗 (例如失敗的邊界檢查) 可能會觸發恐慌
  • 斷言 (例如 assert!) 會在失敗時發生恐慌
  • 針對特定用途的恐慌可以使用 panic! 巨集。
• 恐慌會「解開」堆疊，此行為捨棄值的方式就像函式已傳回一樣。
• 如果無法接受程式崩潰，請使用不會觸發恐慌的 API，例如 Vec::get。

use std::panic;

fn main() {
    let result = panic::catch_unwind(|| "No problem here!");
    println!("{result:?}");

    let result = panic::catch_unwind(|| {
        panic!("oh no!");
    });
    println!("{result:?}");
}

疊代器

連線遭拒或找不到檔案等執行階段錯誤，都是透過 Result 型別來處理，但每次呼叫時都比對此類型可能相當麻煩。try 運算子 ? 的用途是將錯誤傳回呼叫端，可讓您將下列常見的程式碼

match some_expression {
    Ok(value) => value,
    Err(err) => return Err(err),
}

轉換成以下較簡潔的程式碼：

some_expression?

We can use this to simplify our error handling code:

use std::io::Read;
use std::{fs, io};

fn read_username(path: &str) -> Result<String, io::Error> {
    let username_file_result = fs::File::open(path);
    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(err) => return Err(err),
    };

    let mut username = String::new();
    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(err) => Err(err),
    }
}

fn main() {
    //fs::write("config.dat", "alice").unwrap();
    let username = read_username("config.dat");
    println!("username or error: {username:?}");
}

隱含轉換

比起先前提到的下列程式碼，? 的有效擴展稍微更複雜一點：

expression?

運作方式與以下程式碼相同：

match expression {
    Ok(value) => value,
    Err(err)  => return Err(From::from(err)),
}

The From::from call here means we attempt to convert the error type to the type returned by the function. This makes it easy to encapsulate errors into higher-level errors.

範例

use std::error::Error;
use std::fmt::{self, Display, Formatter};
use std::fs::File;
use std::io::{self, Read};

#[derive(Debug)]
enum ReadUsernameError {
    IoError(io::Error),
    EmptyUsername(String),
}

impl Error for ReadUsernameError {}

impl Display for ReadUsernameError {
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        match self {
            Self::IoError(e) => write!(f, "IO error: {e}"),
            Self::EmptyUsername(path) => write!(f, "Found no username in {path}"),
        }
    }
}

impl From<io::Error> for ReadUsernameError {
    fn from(err: io::Error) -> Self {
        Self::IoError(err)
    }
}

fn read_username(path: &str) -> Result<String, ReadUsernameError> {
    let mut username = String::with_capacity(100);
    File::open(path)?.read_to_string(&mut username)?;
    if username.is_empty() {
        return Err(ReadUsernameError::EmptyUsername(String::from(path)));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    let username = read_username("config.dat");
    println!("username or error: {username:?}");
}

動態錯誤型別

Sometimes we want to allow any type of error to be returned without writing our own enum covering all the different possibilities. The std::error::Error trait makes it easy to create a trait object that can contain any error.

use std::error::Error;
use std::fs;
use std::io::Read;

fn read_count(path: &str) -> Result<i32, Box<dyn Error>> {
    let mut count_str = String::new();
    fs::File::open(path)?.read_to_string(&mut count_str)?;
    let count: i32 = count_str.parse()?;
    Ok(count)
}

fn main() {
    fs::write("count.dat", "1i3").unwrap();
    match read_count("count.dat") {
        Ok(count) => println!("Count: {count}"),
        Err(err) => println!("Error: {err}"),
    }
}

thiserror and anyhow

The thiserror and anyhow crates are widely used to simplify error handling.

• thiserror 經常在程式庫中使用，目的是建立可實作 From<T> 的自訂錯誤型別。
• anyhow 經常由應用程式使用，目的是協助函式中的錯誤處理機制，包括為錯誤加上背景資訊。

use anyhow::{bail, Context, Result};
use std::fs;
use std::io::Read;
use thiserror::Error;

#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[error("Found no username in {0}")]
struct EmptyUsernameError(String);

fn read_username(path: &str) -> Result<String> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)
        .with_context(|| format!("Failed to open {path}"))?
        .read_to_string(&mut username)
        .context("Failed to read")?;
    if username.is_empty() {
        bail!(EmptyUsernameError(path.to_string()));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    match read_username("config.dat") {
        Ok(username) => println!("Username: {username}"),
        Err(err) => println!("Error: {err:?}"),
    }
}

使用 Result 進行結構化錯誤處理

以下程式碼實作一個非常簡單的運算式語言剖析器，但會藉由恐慌來處理錯誤。請重新編寫，改用慣用的錯誤處理機制，並將錯誤傳播至 main 的回傳陳述式。您可以自由使用 thiserror 和 anyhow。

提示：首先請修正 parse 函式中的錯誤處理機制。確認一切正常運作後，更新 Tokenizer 即可實作 Iterator<Item=Result<Token, TokenizerError>>，並在剖析器中處理。

use std::iter::Peekable;
use std::str::Chars;

/// An arithmetic operator.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// A token in the expression language.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// An expression in the expression language.
#[derive(Debug, PartialEq)]
enum Expression {
    /// A reference to a variable.
    Var(String),
    /// A literal number.
    Number(u32),
    /// A binary operation.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Token;

    fn next(&mut self) -> Option<Token> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => {
                let mut num = String::from(c);
                while let Some(c @ '0'..='9') = self.0.peek() {
                    num.push(*c);
                    self.0.next();
                }
                Some(Token::Number(num))
            }
            'a'..='z' => {
                let mut ident = String::from(c);
                while let Some(c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
                    ident.push(*c);
                    self.0.next();
                }
                Some(Token::Identifier(ident))
            }
            '+' => Some(Token::Operator(Op::Add)),
            '-' => Some(Token::Operator(Op::Sub)),
            _ => panic!("Unexpected character {c}"),
        }
    }
}

fn parse(input: &str) -> Expression {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(tokens: &mut Tokenizer<'a>) -> Expression {
        let Some(tok) = tokens.next() else {
            panic!("Unexpected end of input");
        };
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse().expect("Invalid 32-bit integer'");
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => panic!("Unexpected token {tok:?}"),
        };
        // Look ahead to parse a binary operation if present.
        match tokens.next() {
            None => expr,
            Some(Token::Operator(op)) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)),
            ),
            Some(tok) => panic!("Unexpected token {tok:?}"),
        }
    }

    parse_expr(&mut tokens)
}

fn main() {
    let expr = parse("10+foo+20-30");
    println!("{expr:?}");
}

解決方案

use thiserror::Error;
use std::iter::Peekable;
use std::str::Chars;

/// An arithmetic operator.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// A token in the expression language.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// An expression in the expression language.
#[derive(Debug, PartialEq)]
enum Expression {
    /// A reference to a variable.
    Var(String),
    /// A literal number.
    Number(u32),
    /// A binary operation.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

#[derive(Debug, Error)]
enum TokenizerError {
    #[error("Unexpected character '{0}' in input")]
    UnexpectedCharacter(char),
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Result<Token, TokenizerError>;

    fn next(&mut self) -> Option<Result<Token, TokenizerError>> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => {
                let mut num = String::from(c);
                while let Some(c @ '0'..='9') = self.0.peek() {
                    num.push(*c);
                    self.0.next();
                }
                Some(Ok(Token::Number(num)))
            }
            'a'..='z' => {
                let mut ident = String::from(c);
                while let Some(c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
                    ident.push(*c);
                    self.0.next();
                }
                Some(Ok(Token::Identifier(ident)))
            }
            '+' => Some(Ok(Token::Operator(Op::Add))),
            '-' => Some(Ok(Token::Operator(Op::Sub))),
            _ => Some(Err(TokenizerError::UnexpectedCharacter(c))),
        }
    }
}

#[derive(Debug, Error)]
enum ParserError {
    #[error("Tokenizer error: {0}")]
    TokenizerError(#[from] TokenizerError),
    #[error("Unexpected end of input")]
    UnexpectedEOF,
    #[error("Unexpected token {0:?}")]
    UnexpectedToken(Token),
    #[error("Invalid number")]
    InvalidNumber(#[from] std::num::ParseIntError),
}

fn parse(input: &str) -> Result<Expression, ParserError> {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(
        tokens: &mut Tokenizer<'a>,
    ) -> Result<Expression, ParserError> {
        let tok = tokens.next().ok_or(ParserError::UnexpectedEOF)??;
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse()?;
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => return Err(ParserError::UnexpectedToken(tok)),
        };
        // Look ahead to parse a binary operation if present.
        Ok(match tokens.next() {
            None => expr,
            Some(Ok(Token::Operator(op))) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)?),
            ),
            Some(Err(e)) => return Err(e.into()),
            Some(Ok(tok)) => return Err(ParserError::UnexpectedToken(tok)),
        })
    }

    parse_expr(&mut tokens)
}

fn main() -> anyhow::Result<()> {
    let expr = parse("10+foo+20-30")?;
    println!("{expr:?}");
    Ok(())
}

不安全的 Rust

This segment should take about 1 hour and 5 minutes. It contains:

不安全的 Rust

Rust 語言包含兩個部分：

• **安全的 Rust：**可確保記憶體安全，無法觸發未定義的行為。
• **不安全的 Rust：**如果違反先決條件，便可能觸發未定義的行為。

We saw mostly safe Rust in this course, but it's important to know what Unsafe Rust is.

不安全的程式碼通常都很簡短、受到隔離，而且封裝在安全的抽象層中。您應該仔細記錄這類程式碼的正確性。

透過不安全的 Rust，可以使用五項新功能：

• 對裸指標解參考。
• 存取或修改可變的靜態變數。
• 存取 union 欄位。
• 呼叫 unsafe 函式 (包括 extern 函式)。
• 實作 unsafe 特徵。

接下來將簡單介紹不安全的功能。如需瞭解詳情，請參閱 Rust Book 的第 19.1 章，以及 Rustonomicon。

對裸指標解參考

建立指標相當安全，不過對指標解參考就需要使用 unsafe：

fn main() {
    let mut s = String::from("careful!");

    let r1 = &mut s as *mut String;
    let r2 = r1 as *const String;

    // Safe because r1 and r2 were obtained from references and so are
    // guaranteed to be non-null and properly aligned, the objects underlying
    // the references from which they were obtained are live throughout the
    // whole unsafe block, and they are not accessed either through the
    // references or concurrently through any other pointers.
    unsafe {
        println!("r1 is: {}", *r1);
        *r1 = String::from("uhoh");
        println!("r2 is: {}", *r2);
    }

    // NOT SAFE. DO NOT DO THIS.
    /*
    let r3: &String = unsafe { &*r1 };
    drop(s);
    println!("r3 is: {}", *r3);
    */
}

可變的靜態變數

您可以放心讀取不可變的靜態變數：

static HELLO_WORLD: &str = "Hello, world!";

fn main() {
    println!("HELLO_WORLD: {HELLO_WORLD}");
}

不過，讀取並寫入可變的靜態變數並不安全，因為可能發生資料競爭：

static mut COUNTER: u32 = 0;

fn add_to_counter(inc: u32) {
    unsafe {
        COUNTER += inc;
    }
}

fn main() {
    add_to_counter(42);

    unsafe {
        println!("COUNTER: {COUNTER}");
    }
}

聯合體

聯合體和列舉很像，但您需要自行追蹤可用欄位：

#[repr(C)]
union MyUnion {
    i: u8,
    b: bool,
}

fn main() {
    let u = MyUnion { i: 42 };
    println!("int: {}", unsafe { u.i });
    println!("bool: {}", unsafe { u.b }); // Undefined behavior!
}

呼叫不安全的函式

呼叫不安全的函式

如果函式或方法具有額外先決條件，而您必須遵循這些條件才能避免未定義的行為，那麼就可以將該函式或方法標示為 unsafe：

extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    let emojis = "🗻∈🌏";

    // Safe because the indices are in the correct order, within the bounds of
    // the string slice, and lie on UTF-8 sequence boundaries.
    unsafe {
        println!("emoji: {}", emojis.get_unchecked(0..4));
        println!("emoji: {}", emojis.get_unchecked(4..7));
        println!("emoji: {}", emojis.get_unchecked(7..11));
    }

    println!("char count: {}", count_chars(unsafe { emojis.get_unchecked(0..7) }));

    unsafe {
        // Undefined behavior if abs misbehaves.
        println!("Absolute value of -3 according to C: {}", abs(-3));
    }

    // Not upholding the UTF-8 encoding requirement breaks memory safety!
    // println!("emoji: {}", unsafe { emojis.get_unchecked(0..3) });
    // println!("char count: {}", count_chars(unsafe {
    // emojis.get_unchecked(0..3) }));
}

fn count_chars(s: &str) -> usize {
    s.chars().count()
}

編寫不安全的函式

如果您的函式必須滿足特定條件才能避免未定義的行為，您可以將其標示為 unsafe。

/// Swaps the values pointed to by the given pointers.
///
/// # Safety
///
/// The pointers must be valid and properly aligned.
unsafe fn swap(a: *mut u8, b: *mut u8) {
    let temp = *a;
    *a = *b;
    *b = temp;
}

fn main() {
    let mut a = 42;
    let mut b = 66;

    // Safe because ...
    unsafe {
        swap(&mut a, &mut b);
    }

    println!("a = {}, b = {}", a, b);
}

實作不安全的特徵

與函式類似，如果實作程序必須保證符合特定條件才能避免未定義的行為，您可以將特徵標示為 unsafe。

舉例來說，zerocopy crate 就具有不安全的特徵，如這個頁面所示：

use std::mem::size_of_val;
use std::slice;

/// ...
/// # Safety
/// The type must have a defined representation and no padding.
pub unsafe trait AsBytes {
    fn as_bytes(&self) -> &[u8] {
        unsafe {
            slice::from_raw_parts(
                self as *const Self as *const u8,
                size_of_val(self),
            )
        }
    }
}

// Safe because u32 has a defined representation and no padding.
unsafe impl AsBytes for u32 {}

安全的 FFI 包裝函式

Rust has great support for calling functions through a foreign function interface (FFI). We will use this to build a safe wrapper for the libc functions you would use from C to read the names of files in a directory.

建議您參閱以下手冊頁面：

• opendir(3)
• readdir(3)
• closedir(3)

建議您一併瀏覽 std::ffi 模組。其中會有練習需用到的幾個字串型別：

您將在以下所有型別之間轉換：

• &str 到 CString：您需要為結尾的 \0 字元分配空間。
• CString 到 *const i8：您需要指標才能呼叫 C 函式。
• *const i8 到 &CStr：您需要一些可以找到結尾 \0 字元的內容。
• &CStr to &[u8]: a slice of bytes is the universal interface for "some unknown data",
• &[u8] 到 &OsStr：&OsStr 是通往 OsString 的一步，請以 OsStrExt 建立。
• &OsStr 到 OsString：您需複製 &OsStr 中的資料，才能傳回資料並再次呼叫 readdir。

Nomicon 也有關於 FFI 的實用章節可供參閱。

請將以下程式碼複製到 https://play.rust-lang.org/，並填入缺少的函式和方法：

// TODO: remove this when you're done with your implementation.
#![allow(unused_imports, unused_variables, dead_code)]

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // Opaque type. See https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Layout according to the Linux man page for readdir(3), where ino_t and
    // off_t are resolved according to the definitions in
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}.
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Layout according to the macOS man page for dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // See https://github.com/rust-lang/libc/issues/414 and the section on
        // _DARWIN_FEATURE_64_BIT_INODE in the macOS man page for stat(2).
        //
        // "Platforms that existed before these updates were available" refers
        // to macOS (as opposed to iOS / wearOS / etc.) on Intel and PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Call opendir and return a Ok value if that worked,
        // otherwise return Err with a message.
        unimplemented!()
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Keep calling readdir until we get a NULL pointer back.
        unimplemented!()
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Call closedir as needed.
        unimplemented!()
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

解決方案

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // Opaque type. See https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Layout according to the Linux man page for readdir(3), where ino_t and
    // off_t are resolved according to the definitions in
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}.
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Layout according to the macOS man page for dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // See https://github.com/rust-lang/libc/issues/414 and the section on
        // _DARWIN_FEATURE_64_BIT_INODE in the macOS man page for stat(2).
        //
        // "Platforms that existed before these updates were available" refers
        // to macOS (as opposed to iOS / wearOS / etc.) on Intel and PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Call opendir and return a Ok value if that worked,
        // otherwise return Err with a message.
        let path =
            CString::new(path).map_err(|err| format!("Invalid path: {err}"))?;
        // SAFETY: path.as_ptr() cannot be NULL.
        let dir = unsafe { ffi::opendir(path.as_ptr()) };
        if dir.is_null() {
            Err(format!("Could not open {:?}", path))
        } else {
            Ok(DirectoryIterator { path, dir })
        }
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Keep calling readdir until we get a NULL pointer back.
        // SAFETY: self.dir is never NULL.
        let dirent = unsafe { ffi::readdir(self.dir) };
        if dirent.is_null() {
            // We have reached the end of the directory.
            return None;
        }
        // SAFETY: dirent is not NULL and dirent.d_name is NUL
        // terminated.
        let d_name = unsafe { CStr::from_ptr((*dirent).d_name.as_ptr()) };
        let os_str = OsStr::from_bytes(d_name.to_bytes());
        Some(os_str.to_owned())
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Call closedir as needed.
        if !self.dir.is_null() {
            // SAFETY: self.dir is not NULL.
            if unsafe { ffi::closedir(self.dir) } != 0 {
                panic!("Could not close {:?}", self.path);
            }
        }
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error;

    #[test]
    fn test_nonexisting_directory() {
        let iter = DirectoryIterator::new("no-such-directory");
        assert!(iter.is_err());
    }

    #[test]
    fn test_empty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Non UTF-8 character in path")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", ".."]);
        Ok(())
    }

    #[test]
    fn test_nonempty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        std::fs::write(tmp.path().join("foo.txt"), "The Foo Diaries\n")?;
        std::fs::write(tmp.path().join("bar.png"), "<PNG>\n")?;
        std::fs::write(tmp.path().join("crab.rs"), "//! Crab\n")?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Non UTF-8 character in path")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", "..", "bar.png", "crab.rs", "foo.txt"]);
        Ok(())
    }
}

歡迎在 Android 中使用 Rust

Android 的系統軟體支援 Rust。也就是說，您可以在 Rust 中編寫新的服務、程式庫、驅動程式，甚至是韌體，也可以視需要強化現有程式碼。

今天我們會嘗試在您擁有的其中一項專案中呼叫 Rust。因此，請盡量在程式碼集中找出一小段來改寫成 Rust。請注意，依附元件和「獨特」型別越少越好。理想情況是確保程式碼能剖析部分原始位元組。

設定

我們會使用 Cuttlefish Android 虛擬裝置來測試程式碼。請確認您可以存取這項裝置，或是使用下方程式碼建立新裝置：

source build/envsetup.sh
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
acloud create

詳情請參閱 Android 開發人員程式碼研究室。

建構規則

Android 的建構系統 (Soong) 透過以下模組支援 Rust：

接下來我們會探討 rust_binary 及 rust_library。

Rust 二進位檔

我們從一個簡單的應用程式開始著手。請在 Android 開放原始碼計畫程式庫的根層級，建立下列檔案：

hello_rust/Android.bp：

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/main.rs"],
}

hello_rust/src/main.rs：

//! Rust demo.

/// Prints a greeting to standard output.
fn main() {
    println!("Hello from Rust!");
}

您現在可以建構、推送及執行二進位檔：

m hello_rust
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust" /data/local/tmp
adb shell /data/local/tmp/hello_rust

Hello from Rust!

Rust 程式庫

您可以使用 rust_library 為 Android 建立一個新的 Rust 程式庫。

這裡，我們會宣告兩個需要依附的程式庫：

• libgreeting (定義如下)
• libtextwrap (隨附於 external/rust/crates/ 的 Crate 中)

hello_rust/Android.bp：

rust_binary {
    name: "hello_rust_with_dep",
    crate_name: "hello_rust_with_dep",
    srcs: ["src/main.rs"],
    rustlibs: [
        "libgreetings",
        "libtextwrap",
    ],
    prefer_rlib: true, // Need this to avoid dynamic link error.
}

rust_library {
    name: "libgreetings",
    crate_name: "greetings",
    srcs: ["src/lib.rs"],
}

hello_rust/src/main.rs：

//! Rust demo.

use greetings::greeting;
use textwrap::fill;

/// Prints a greeting to standard output.
fn main() {
    println!("{}", fill(&greeting("Bob"), 24));
}

hello_rust/src/lib.rs：

//! Greeting library.

/// Greet `name`.
pub fn greeting(name: &str) -> String {
    format!("Hello {name}, it is very nice to meet you!")
}

請按照之前的方式，建構、推送及執行二進位檔：

m hello_rust_with_dep
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_with_dep" /data/local/tmp
adb shell /data/local/tmp/hello_rust_with_dep

Hello Bob, it is very
nice to meet you!

AIDL

Rust 支援 Android 介面定義語言 (AIDL)：

• Rust 程式碼可以呼叫現有的 AIDL 服務。
• 您可以在 Rust 中建立新的 AIDL 服務。

Birthday Service Tutorial

To illustrate how to use Rust with Binder, we're going to walk through the process of creating a Binder interface. We're then going to both implement the described service and write client code that talks to that service.

AIDL 介面

您可以使用 AIDL 介面宣告服務的 API：

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl：

/** Birthday service interface. */
interface IBirthdayService {
    /** Generate a Happy Birthday message. */
    String wishHappyBirthday(String name, int years);
}

birthday_service/aidl/Android.bp：

aidl_interface {
    name: "com.example.birthdayservice",
    srcs: ["com/example/birthdayservice/*.aidl"],
    unstable: true,
    backend: {
        rust: { // Rust is not enabled by default
            enabled: true,
        },
    },
}

Generated Service API

Binder generates a trait corresponding to the interface definition. trait to talk to the service.

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl：

/** Birthday service interface. */
interface IBirthdayService {
    /** Generate a Happy Birthday message. */
    String wishHappyBirthday(String name, int years);
}

Generated trait:

trait IBirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String>;
}

Your service will need to implement this trait, and your client will use this trait to talk to the service.

服務實作

我們現在可以實作 AIDL 服務了：

birthday_service/src/lib.rs：

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

/// The `IBirthdayService` implementation.
pub struct BirthdayService;

impl binder::Interface for BirthdayService {}

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String> {
        Ok(format!("Happy Birthday {name}, congratulations with the {years} years!"))
    }
}

birthday_service/Android.bp：

rust_library {
    name: "libbirthdayservice",
    srcs: ["src/lib.rs"],
    crate_name: "birthdayservice",
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
}

AIDL 伺服器

最後，我們可以建立伺服器來公開服務：

birthday_service/src/server.rs：

//! Birthday service.
use birthdayservice::BirthdayService;
use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::BnBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Entry point for birthday service.
fn main() {
    let birthday_service = BirthdayService;
    let birthday_service_binder = BnBirthdayService::new_binder(
        birthday_service,
        binder::BinderFeatures::default(),
    );
    binder::add_service(SERVICE_IDENTIFIER, birthday_service_binder.as_binder())
        .expect("Failed to register service");
    binder::ProcessState::join_thread_pool()
}

birthday_service/Android.bp：

rust_binary {
    name: "birthday_server",
    crate_name: "birthday_server",
    srcs: ["src/server.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
        "libbirthdayservice",
    ],
    prefer_rlib: true, // To avoid dynamic link error.
}

部署

現在我們可以建構、推送及啟動服務：

m birthday_server
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_server" /data/local/tmp
adb root
adb shell /data/local/tmp/birthday_server

在另一個終端機中，檢查服務是否能執行：

adb shell service check birthdayservice

Service birthdayservice: found

藉由 service call 呼叫，您也可以呼叫服務：

adb shell service call birthdayservice 1 s16 Bob i32 24

Result: Parcel(
  0x00000000: 00000000 00000036 00610048 00700070 '....6...H.a.p.p.'
  0x00000010: 00200079 00690042 00740072 00640068 'y. .B.i.r.t.h.d.'
  0x00000020: 00790061 00420020 0062006f 0020002c 'a.y. .B.o.b.,. .'
  0x00000030: 006f0063 0067006e 00610072 00750074 'c.o.n.g.r.a.t.u.'
  0x00000040: 0061006c 00690074 006e006f 00200073 'l.a.t.i.o.n.s. .'
  0x00000050: 00690077 00680074 00740020 00650068 'w.i.t.h. .t.h.e.'
  0x00000060: 00320020 00200034 00650079 00720061 ' .2.4. .y.e.a.r.'
  0x00000070: 00210073 00000000                   's.!.....        ')

AIDL 用戶端

最後，我們可以為新服務建立 Rust 用戶端。

birthday_service/src/client.rs：

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Call the birthday service.
fn main() -> Result<(), Box<dyn Error>> {
    let name = std::env::args().nth(1).unwrap_or_else(|| String::from("Bob"));
    let years = std::env::args()
        .nth(2)
        .and_then(|arg| arg.parse::<i32>().ok())
        .unwrap_or(42);

    binder::ProcessState::start_thread_pool();
    let service = binder::get_interface::<dyn IBirthdayService>(SERVICE_IDENTIFIER)
        .map_err(|_| "Failed to connect to BirthdayService")?;

    // Call the service.
    let msg = service.wishHappyBirthday(&name, years)?;
    println!("{msg}");
}

birthday_service/Android.bp：

rust_binary {
    name: "birthday_client",
    crate_name: "birthday_client",
    srcs: ["src/client.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
    prefer_rlib: true, // To avoid dynamic link error.
}

請注意，用戶端並不依賴 libbirthdayservice。

建構、推送及在裝置裡執行用戶端程式：

m birthday_client
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_client" /data/local/tmp
adb shell /data/local/tmp/birthday_client Charlie 60

Happy Birthday Charlie, congratulations with the 60 years!

改寫 API

讓我們為這個 API 擴充更多功能：我們想要讓用戶能在生日卡上指定幾行字：

package com.example.birthdayservice;

/** Birthday service interface. */
interface IBirthdayService {
    /** Generate a Happy Birthday message. */
    String wishHappyBirthday(String name, int years, in String[] text);
}

This results in an updated trait definition for IBirthdayService:

trait IBirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String>;
}

Updating Client and Service

Update the client and server code to account for the new API.

birthday_service/src/lib.rs：

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String> {
        let mut msg = format!(
            "Happy Birthday {name}, congratulations with the {years} years!",
        );

        for line in text {
            msg.push('\n');
            msg.push_str(line);
        }

        Ok(msg)
    }
}

birthday_service/src/client.rs：

let msg = service.wishHappyBirthday(
    &name,
    years,
    &[
        String::from("Habby birfday to yuuuuu"),
        String::from("And also: many more"),
    ],
)?;

Working With AIDL Types

AIDL types translate into the appropriate idiomatic Rust type:

• Primitive types map (mostly) to idiomatic Rust types.
• Collection types like slices, Vecs and string types are supported.
• References to AIDL objects and file handles can be sent between clients and services.
• File handles and parcelables are fully supported.

Primitive Types

Primitive types map (mostly) idiomatically:

陣列

The array types (T[], byte[], and List<T>) get translated to the appropriate Rust array type depending on how they are used in the function signature:

特徵物件

AIDL objects can be sent either as a concrete AIDL type or as the type-erased IBinder interface:

birthday_service/aidl/com/example/birthdayservice/IBirthdayInfoProvider.aidl:

package com.example.birthdayservice;

interface IBirthdayInfoProvider {
    String name();
    int years();
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.IBirthdayInfoProvider;

interface IBirthdayService {
    /** The same thing, but using a binder object. */
    String wishWithProvider(IBirthdayInfoProvider provider);

    /** The same thing, but using `IBinder`. */
    String wishWithErasedProvider(IBinder provider);
}

birthday_service/src/client.rs:

/// Rust struct implementing the `IBirthdayInfoProvider` interface.
struct InfoProvider {
    name: String,
    age: u8,
}

impl binder::Interface for InfoProvider {}

impl IBirthdayInfoProvider for InfoProvider {
    fn name(&self) -> binder::Result<String> {
        Ok(self.name.clone())
    }

    fn years(&self) -> binder::Result<i32> {
        Ok(self.age as i32)
    }
}

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Failed to connect to BirthdayService");

    // Create a binder object for the `IBirthdayInfoProvider` interface.
    let provider = BnBirthdayInfoProvider::new_binder(
        InfoProvider { name: name.clone(), age: years as u8 },
        BinderFeatures::default(),
    );

    // Send the binder object to the service.
    service.wishWithProvider(&provider)?;

    // Perform the same operation but passing the provider as an `SpIBinder`.
    service.wishWithErasedProvider(&provider.as_binder())?;
}

變數

Binder for Rust supports sending parcelables directly:

birthday_service/aidl/com/example/birthdayservice/BirthdayInfo.aidl:

package com.example.birthdayservice;

parcelable BirthdayInfo {
    String name;
    int years;
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.BirthdayInfo;

interface IBirthdayService {
    /** The same thing, but with a parcelable. */
    String wishWithInfo(in BirthdayInfo info);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Failed to connect to BirthdayService");

    service.wishWithInfo(&BirthdayInfo { name: name.clone(), years })?;
}

Sending Files

Files can be sent between Binder clients/servers using the ParcelFileDescriptor type:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

interface IBirthdayService {
    /** The same thing, but loads info from a file. */
    String wishFromFile(in ParcelFileDescriptor infoFile);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Failed to connect to BirthdayService");

    // Open a file and put the birthday info in it.
    let mut file = File::create("/data/local/tmp/birthday.info").unwrap();
    writeln!(file, "{name}")?;
    writeln!(file, "{years}")?;

    // Create a `ParcelFileDescriptor` from the file and send it.
    let file = ParcelFileDescriptor::new(file);
    service.wishFromFile(&file)?;
}

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishFromFile(
        &self,
        info_file: &ParcelFileDescriptor,
    ) -> binder::Result<String> {
        // Convert the file descriptor to a `File`. `ParcelFileDescriptor` wraps
        // an `OwnedFd`, which can be cloned and then used to create a `File`
        // object.
        let mut info_file = info_file
            .as_ref()
            .try_clone()
            .map(File::from)
            .expect("Invalid file handle");

        let mut contents = String::new();
        info_file.read_to_string(&mut contents).unwrap();

        let mut lines = contents.lines();
        let name = lines.next().unwrap();
        let years: i32 = lines.next().unwrap().parse().unwrap();

        Ok(format!("Happy Birthday {name}, congratulations with the {years} years!"))
    }
}

Testing in Android

Building on Testing, we will now look at how unit tests work in AOSP. Use the rust_test module for your unit tests:

testing/Android.bp:

rust_library {
    name: "libleftpad",
    crate_name: "leftpad",
    srcs: ["src/lib.rs"],
}

rust_test {
    name: "libleftpad_test",
    crate_name: "leftpad_test",
    srcs: ["src/lib.rs"],
    host_supported: true,
    test_suites: ["general-tests"],
}

testing/src/lib.rs:

#![allow(unused)]
fn main() {
//! Left-padding library.

/// Left-pad `s` to `width`.
pub fn leftpad(s: &str, width: usize) -> String {
    format!("{s:>width$}")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn short_string() {
        assert_eq!(leftpad("foo", 5), "  foo");
    }

    #[test]
    fn long_string() {
        assert_eq!(leftpad("foobar", 6), "foobar");
    }
}
}

You can now run the test with

atest --host libleftpad_test

The output looks like this:

INFO: Elapsed time: 2.666s, Critical Path: 2.40s
INFO: 3 processes: 2 internal, 1 linux-sandbox.
INFO: Build completed successfully, 3 total actions
//comprehensive-rust-android/testing:libleftpad_test_host            PASSED in 2.3s
    PASSED  libleftpad_test.tests::long_string (0.0s)
    PASSED  libleftpad_test.tests::short_string (0.0s)
Test cases: finished with 2 passing and 0 failing out of 2 test cases

Notice how you only mention the root of the library crate. Tests are found recursively in nested modules.

GoogleTest

The GoogleTest crate allows for flexible test assertions using matchers:

use googletest::prelude::*;

#[googletest::test]
fn test_elements_are() {
    let value = vec!["foo", "bar", "baz"];
    expect_that!(value, elements_are!(eq("foo"), lt("xyz"), starts_with("b")));
}

If we change the last element to "!", the test fails with a structured error message pin-pointing the error:

---- test_elements_are stdout ----
Value of: value
Expected: has elements:
  0. is equal to "foo"
  1. is less than "xyz"
  2. starts with prefix "!"
Actual: ["foo", "bar", "baz"],
  where element #2 is "baz", which does not start with "!"
  at src/testing/googletest.rs:6:5
Error: See failure output above

#[test]
fn test_multiline_string_diff() {
    let haiku = "Memory safety found,\n\
                 Rust's strong typing guides the way,\n\
                 Secure code you'll write.";
    assert_that!(
        haiku,
        eq("Memory safety found,\n\
            Rust's silly humor guides the way,\n\
            Secure code you'll write.")
    );
}

    Value of: haiku
Expected: is equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Actual: "Memory safety found,\nRust's strong typing guides the way,\nSecure code you'll write.",
  which isn't equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Difference(-actual / +expected):
 Memory safety found,
-Rust's strong typing guides the way,
+Rust's silly humor guides the way,
 Secure code you'll write.
  at src/testing/googletest.rs:17:5

模擬 (Mocking)

For mocking, Mockall is a widely used library. You need to refactor your code to use traits, which you can then quickly mock:

use std::time::Duration;

#[mockall::automock]
pub trait Pet {
    fn is_hungry(&self, since_last_meal: Duration) -> bool;
}

#[test]
fn test_robot_dog() {
    let mut mock_dog = MockPet::new();
    mock_dog.expect_is_hungry().return_const(true);
    assert_eq!(mock_dog.is_hungry(Duration::from_secs(10)), true);
}

#[test]
fn test_robot_cat() {
    let mut mock_cat = MockPet::new();
    mock_cat
        .expect_is_hungry()
        .with(mockall::predicate::gt(Duration::from_secs(3 * 3600)))
        .return_const(true);
    mock_cat.expect_is_hungry().return_const(false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(1 * 3600)), false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(5 * 3600)), true);
}

記錄

您應使用 log Crate，自動將記錄印出到 logcat (裝置端) 或 stdout (主機端)：

hello_rust_logs/Android.bp：

rust_binary {
    name: "hello_rust_logs",
    crate_name: "hello_rust_logs",
    srcs: ["src/main.rs"],
    rustlibs: [
        "liblog_rust",
        "liblogger",
    ],
    host_supported: true,
}

hello_rust_logs/src/main.rs：

//! Rust logging demo.

use log::{debug, error, info};

/// Logs a greeting.
fn main() {
    logger::init(
        logger::Config::default()
            .with_tag_on_device("rust")
            .with_min_level(log::Level::Trace),
    );
    debug!("Starting program.");
    info!("Things are going fine.");
    error!("Something went wrong!");
}

建構、推送及在裝置上執行二進位檔：

m hello_rust_logs
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_logs" /data/local/tmp
adb shell /data/local/tmp/hello_rust_logs

記錄會顯示在 adb logcat 中：

adb logcat -s rust

09-08 08:38:32.454  2420  2420 D rust: hello_rust_logs: Starting program.
09-08 08:38:32.454  2420  2420 I rust: hello_rust_logs: Things are going fine.
09-08 08:38:32.454  2420  2420 E rust: hello_rust_logs: Something went wrong!

互通性

Rust 能充分支援與其他程式語言互通。也就是說，您可以：

• 透過其他語言呼叫 Rust 函式。
• 透過 Rust 呼叫以其他語言編寫的函式。

當您以其他語言呼叫函式時，我們稱之為使用「外部函式介面」，亦稱 FFI (Foreign Function Interface)。

與 C 的互通性

Rust 能完整支援以 C 語言的呼叫慣例來連結物件檔案。同樣地，您可以匯出 Rust 函式，然後透過 C 語言呼叫這些函式。

您可以視需要手動完成操作：

extern "C" {
    fn abs(x: i32) -> i32;
}

fn main() {
    let x = -42;
    let abs_x = unsafe { abs(x) };
    println!("{x}, {abs_x}");
}

我們已在「安全的 FFI 包裝函式」練習中看過此例。

執行這項操作的前提是要充分瞭解目標平台。此法不建議用於正式環境。

我們接下來會討論更好的選項。

使用 Bindgen

bindgen 工具可從 C 標頭檔案自動產生繫結。

首先，請建立小型 C 程式庫：

__interoperability/bindgen/libbirthday.h：

typedef struct card {
  const char* name;
  int years;
} card;

void print_card(const card* card);

__interoperability/bindgen/libbirthday.c：

#include <stdio.h>
#include "libbirthday.h"

void print_card(const card* card) {
  printf("+--------------\n");
  printf("| Happy Birthday %s!\n", card->name);
  printf("| Congratulations with the %i years!\n", card->years);
  printf("+--------------\n");
}

請將以下內容加入 Android.bp 檔案：

__interoperability/bindgen/Android.bp：

cc_library {
    name: "libbirthday",
    srcs: ["libbirthday.c"],
}

為程式庫建立包裝函式標頭檔案 (在此範例中不一定需要)：

__interoperability/bindgen/libbirthday_wrapper.h：

#include "libbirthday.h"

您現在可以自動產生繫結：

__interoperability/bindgen/Android.bp：

rust_bindgen {
    name: "libbirthday_bindgen",
    crate_name: "birthday_bindgen",
    wrapper_src: "libbirthday_wrapper.h",
    source_stem: "bindings",
    static_libs: ["libbirthday"],
}

最後，我們可以在 Rust 程式中使用繫結：

__interoperability/bindgen/Android.bp：

rust_binary {
    name: "print_birthday_card",
    srcs: ["main.rs"],
    rustlibs: ["libbirthday_bindgen"],
}

__interoperability/bindgen/main.rs：

//! Bindgen demo.

use birthday_bindgen::{card, print_card};

fn main() {
    let name = std::ffi::CString::new("Peter").unwrap();
    let card = card { name: name.as_ptr(), years: 42 };
    // SAFETY: `print_card` is safe to call with a valid `card` pointer.
    unsafe {
        print_card(&card as *const card);
    }
}

建構、推送及在裝置上執行二進位檔：

m print_birthday_card
adb push "$ANDROID_PRODUCT_OUT/system/bin/print_birthday_card" /data/local/tmp
adb shell /data/local/tmp/print_birthday_card

最後，我們可以執行自動產生的測試，確保繫結正常運作：

__interoperability/bindgen/Android.bp：

rust_test {
    name: "libbirthday_bindgen_test",
    srcs: [":libbirthday_bindgen"],
    crate_name: "libbirthday_bindgen_test",
    test_suites: ["general-tests"],
    auto_gen_config: true,
    clippy_lints: "none", // Generated file, skip linting
    lints: "none",
}

atest libbirthday_bindgen_test

呼叫 Rust

您可以輕鬆將 Rust 函式和型別匯出至 C：

__interoperability/rust/libanalyze/analyze.rs

//! Rust FFI demo.
#![deny(improper_ctypes_definitions)]

use std::os::raw::c_int;

/// Analyze the numbers.
#[no_mangle]
pub extern "C" fn analyze_numbers(x: c_int, y: c_int) {
    if x < y {
        println!("x ({x}) is smallest!");
    } else {
        println!("y ({y}) is probably larger than x ({x})");
    }
}

__interoperability/rust/libanalyze/analyze.h

#ifndef ANALYSE_H
#define ANALYSE_H

extern "C" {
void analyze_numbers(int x, int y);
}

#endif

__interoperability/rust/libanalyze/Android.bp

rust_ffi {
    name: "libanalyze_ffi",
    crate_name: "analyze_ffi",
    srcs: ["analyze.rs"],
    include_dirs: ["."],
}

我們現在可以從 C 二進位檔呼叫此介面：

__interoperability/rust/analyze/main.c

#include "analyze.h"

int main() {
  analyze_numbers(10, 20);
  analyze_numbers(123, 123);
  return 0;
}

__interoperability/rust/analyze/Android.bp

cc_binary {
    name: "analyze_numbers",
    srcs: ["main.c"],
    static_libs: ["libanalyze_ffi"],
}

建構、推送及在裝置上執行二進位檔：

m analyze_numbers
adb push "$ANDROID_PRODUCT_OUT/system/bin/analyze_numbers" /data/local/tmp
adb shell /data/local/tmp/analyze_numbers

與 C++ 的互通性

透過 CXX Crate，您可以在 Rust 和 C++ 之間實現安全的互通性。

整體方法大致如下：

測試模組

CXX 的運作需要依照函式的型別敘述。這些敘述定義了從一種語言公開至另一種語言的介面。您會在具有 #[cxx::bridge] 屬性巨集註解的 Rust 模組中，使用外部區塊提供這項說明。

#[allow(unsafe_op_in_unsafe_fn)]
#[cxx::bridge(namespace = "org::blobstore")]
mod ffi {
    // Shared structs with fields visible to both languages.
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    // Rust types and signatures exposed to C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    // C++ types and signatures exposed to Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

Rust 橋接器宣告

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MyType; // Opaque type
        fn foo(&self); // Method on `MyType`
        fn bar() -> Box<MyType>; // Free function
    }
}

struct MyType(i32);

impl MyType {
    fn foo(&self) {
        println!("{}", self.0);
    }
}

fn bar() -> Box<MyType> {
    Box::new(MyType(123))
}

產生的 C++

#[cxx::bridge]
mod ffi {
    // Rust types and signatures exposed to C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }
}

(大致) 產生下列 C++：

struct MultiBuf final : public ::rust::Opaque {
  ~MultiBuf() = delete;

private:
  friend ::rust::layout;
  struct layout {
    static ::std::size_t size() noexcept;
    static ::std::size_t align() noexcept;
  };
};

::rust::Slice<::std::uint8_t const> next_chunk(::org::blobstore::MultiBuf &buf) noexcept;

C++ 橋接器宣告

#[cxx::bridge]
mod ffi {
    // C++ types and signatures exposed to Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

(大致) 產生下列 Rust：

#[repr(C)]
pub struct BlobstoreClient {
    _private: ::cxx::private::Opaque,
}

pub fn new_blobstore_client() -> ::cxx::UniquePtr<BlobstoreClient> {
    extern "C" {
        #[link_name = "org$blobstore$cxxbridge1$new_blobstore_client"]
        fn __new_blobstore_client() -> *mut BlobstoreClient;
    }
    unsafe { ::cxx::UniquePtr::from_raw(__new_blobstore_client()) }
}

impl BlobstoreClient {
    pub fn put(&self, parts: &mut MultiBuf) -> u64 {
        extern "C" {
            #[link_name = "org$blobstore$cxxbridge1$BlobstoreClient$put"]
            fn __put(
                _: &BlobstoreClient,
                parts: *mut ::cxx::core::ffi::c_void,
            ) -> u64;
        }
        unsafe {
            __put(self, parts as *mut MultiBuf as *mut ::cxx::core::ffi::c_void)
        }
    }
}

// ...

共用型別

#[cxx::bridge]
mod ffi {
    #[derive(Clone, Debug, Hash)]
    struct PlayingCard {
        suit: Suit,
        value: u8,  // A=1, J=11, Q=12, K=13
    }

    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

共用列舉

#[cxx::bridge]
mod ffi {
    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

產生的 Rust：

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, PartialEq, Eq)]
#[repr(transparent)]
pub struct Suit {
    pub repr: u8,
}

#[allow(non_upper_case_globals)]
impl Suit {
    pub const Clubs: Self = Suit { repr: 0 };
    pub const Diamonds: Self = Suit { repr: 1 };
    pub const Hearts: Self = Suit { repr: 2 };
    pub const Spades: Self = Suit { repr: 3 };
}
}

產生的 C++：

enum class Suit : uint8_t {
  Clubs = 0,
  Diamonds = 1,
  Hearts = 2,
  Spades = 3,
};

錯誤處理

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn fallible(depth: usize) -> anyhow::Result<String> {
    if depth == 0 {
        return Err(anyhow::Error::msg("fallible1 requires depth > 0"));
    }

    Ok("Success!".into())
}

錯誤處理

#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        include!("example/include/example.h");
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn main() {
    if let Err(err) = ffi::fallible(99) {
        eprintln!("Error: {}", err);
        process::exit(1);
    }
}

其他型別

在 Android 中建構

建立 cc_library_static 來建構 C++ 程式庫，包括 CXX 產生的標頭檔案和來源檔案。

cc_library_static {
    name: "libcxx_test_cpp",
    srcs: ["cxx_test.cpp"],
    generated_headers: [
        "cxx-bridge-header",
        "libcxx_test_bridge_header"
    ],
    generated_sources: ["libcxx_test_bridge_code"],
}

在 Android 中建構

建立兩項 genrule，分別用來產生 CXX 標頭和 CXX 來源檔案。這些項目之後會用做 cc_library_static 的輸入內容。

// Generate a C++ header containing the C++ bindings
// to the Rust exported functions in lib.rs.
genrule {
    name: "libcxx_test_bridge_header",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) --header > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.h"],
}

// Generate the C++ code that Rust calls into.
genrule {
    name: "libcxx_test_bridge_code",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.cc"],
}

在 Android 中建構

建立依附於 libcxx 和 cc_library_static 的 rust_binary`。

rust_binary {
    name: "cxx_test",
    srcs: ["lib.rs"],
    rustlibs: ["libcxx"],
    static_libs: ["libcxx_test_cpp"],
}

與 Java 的互通性

Java 可透過 Java 原生介面 (JNI) 載入共用物件。jni Crate 可用來建立相容的程式庫。

首先，要建立用來匯出至 Java 的 Rust 函式：

__interoperability/java/src/lib.rs：

#![allow(unused)]
fn main() {
//! Rust <-> Java FFI demo.

use jni::objects::{JClass, JString};
use jni::sys::jstring;
use jni::JNIEnv;

/// HelloWorld::hello method implementation.
#[no_mangle]
pub extern "system" fn Java_HelloWorld_hello(
    env: JNIEnv,
    _class: JClass,
    name: JString,
) -> jstring {
    let input: String = env.get_string(name).unwrap().into();
    let greeting = format!("Hello, {input}!");
    let output = env.new_string(greeting).unwrap();
    output.into_inner()
}
}

__interoperability/java/Android.bp：

rust_ffi_shared {
    name: "libhello_jni",
    crate_name: "hello_jni",
    srcs: ["src/lib.rs"],
    rustlibs: ["libjni"],
}

接著，我們會從 Java 呼叫這個函式：

__interoperability/java/HelloWorld.java：

class HelloWorld {
    private static native String hello(String name);

    static {
        System.loadLibrary("hello_jni");
    }

    public static void main(String[] args) {
        String output = HelloWorld.hello("Alice");
        System.out.println(output);
    }
}

__interoperability/java/Android.bp：

java_binary {
    name: "helloworld_jni",
    srcs: ["HelloWorld.java"],
    main_class: "HelloWorld",
    required: ["libhello_jni"],
}

最後，您可以建構、同步處理及執行二進位檔：

m helloworld_jni
adb sync  # requires adb root && adb remount
adb shell /system/bin/helloworld_jni

練習

這是小組練習：我們會查看您的其中一項專案，嘗試將一些 Rust 整合至該專案。建議事項：

• 使用以 Rust 編寫的用戶端呼叫 AIDL 服務。

• 將函式從專案移至 Rust，並呼叫該函式。

歡迎瞭解 Chromium 中的 Rust

Chromium 中的第三方程式庫支援 Rust，且有第一方黏合程式碼可連結 Rust 和現有的 Chromium C++ 程式碼。

今天我們會在 Rust 中用字串做些小事。如果您有一小部份的程式碼要向使用者顯示 UTF8 字串，您可以在自己的程式碼集內採用這個方案，不必採用我們所介紹的該部分程式碼集。

設定

請確認您可以建構並執行 Chromium。任何平台和建構標記組合都可以，只要程式碼相對較新即可 (提交位置在 1223636 之後，日期對應到 2023 年 11 月)：

gn gen out/Debug
autoninja -C out/Debug chrome
out/Debug/chrome # or on Mac, out/Debug/Chromium.app/Contents/MacOS/Chromium

(如要達到最快的疊代速度，建議使用元件式及偵錯版本。這是預設情形！)

如果尚未這麼做，請查看建構 Chromium 的方法。提醒您，設定 Chromium 建構作業需要一段時間。

此外，也建議您安裝 Visual Studio Code。

關於練習

這部分的課程包含一系列連貫的練習。我們會在課程中穿插練習，而不是放到最後。如果沒時間完成某個部分也不必擔心，下次補上即可。

比較 Chromium 和 Cargo 的生態系統

Rust 社群一般使用 cargo 和 crates.io 的程式庫。Chromium 是以 gn 和 ninja 技術和一組精選的依附元件建構而成。

在 Rust 中編寫程式碼時，您有以下選擇：

• 藉助 //build/rust/*.gni 中的範本 (例如 rust_static_library，稍後會介紹)，使用 gn 和 ninja。這麼做會使用 Chromium 經稽核的工具鏈和 Crate。
• 使用 cargo，但限制自己使用 Chromium 經稽核的工具鏈和 Crate
• 使用 cargo，信任工具鏈和/或從網際網路下載的 Crate

接下來的重點將放在 gn 和 ninja，因為這就是將 Rust 程式碼建構至 Chromium 瀏覽器中的方式。同時，Cargo 是 Rust 生態系統中重要的一環，因此您應該學會使用這項工具。

Mini exercise

請分成小組，按照下列指示開始練習：

• 發想各種 cargo 可帶來優勢的情境，然後評估這些情境的風險狀況。
• 討論使用 gn 和 ninja、離線 cargo 等技術時，需要信任哪些工具、程式庫和人員。

Chromium Rust 政策

Chromium 目前不支援第一方 Rust，除非是 Chromium 領域技術主管核准的少數情況。

Chromium 的第三方程式庫政策列載於這個頁面 - 第三方程式庫可在各種情況下使用 Rust，包括這些程式庫是效能或安全方面的最佳選擇時。

只有極少數的 Rust 程式庫會直接公開 C/C++ API，這表示幾乎所有這類程式庫都需要少量的第一方黏合程式碼。

特定第三方 Crate 的第一方 Rust 黏合程式碼通常應儲存在 third_party/rust/<crate>/<version>/wrapper。

因此，今天的課程會著重在以下層面：

• 導入第三方 Rust 程式庫 (「Crates」)
• 編寫黏合程式碼，以使用 Chromium C++ 中的 Crate。

如果本政策有所異動，課程內容也會隨之更新。

Build rules

Rust 程式碼通常是以 cargo 建構。為提升建構效率，Chromium 會使用 gn 和 ninja，因為 Chromium 的靜態規則允許最大程度的平行處理。Rust 也不例外。

將 Rust 程式碼新增至 Chromium

在某個現有的 Chromium BUILD.gn 檔案中，宣告 rust_static_library：

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

您也可以在其他 Rust 目標中新增 deps。稍後我們會使用此程式碼，依附於第三方程式碼。

包含 unsafe Rust 程式碼

根據預設，rust_static_library 中禁止使用不安全的 Rust 程式碼，系統也不會編譯這類程式碼。如果需要不安全的 Rust 程式碼，請在 gn 目標中加入 allow_unsafe = true (本課程稍後會說明必須這麼做的情況)。

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [
    "lib.rs",
    "hippopotamus.rs"
  ]
  allow_unsafe = true
}

在 Chromium C++ 中使用 Rust 程式碼

將上述目標新增至某個 Chromium C++ 目標的 deps 即可。

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

# 或 source_set， static_library 等等。
component("preexisting_cpp") {
  deps = [ ":my_rust_lib" ]
}

Visual Studio Code

Rust 程式碼中省略了型別，因此相較於 C++ 而言，使用優質的 IDE 會更加有效。Visual Studio Code 很適合 Chromium 中的 Rust。使用方法：

• 確認 VSCode 具有 rust-analyzer 擴充功能，而非舊版 Rust 支援功能
• gn gen out/Debug --export-rust-project (或換成您的輸出目錄)
• ln -s out/Debug/rust-project.json rust-project.json

Build rules exercise

在您的 Chromium 版本中，將新的 Rust 目標加至 //ui/base/BUILD.gn，其中包含以下內容：

#![allow(unused)]
fn main() {
#[no_mangle]
pub extern "C" fn hello_from_rust() {
    println!("Hello from Rust!")
}
}

Important: note that no_mangle here is considered a type of unsafety by the Rust compiler, so you'll need to allow unsafe code in your gn target.

將這個新的 Rust 目標新增為 //ui/base:base 的依附元件。在 ui/base/resource/resource_bundle.cc 頂端宣告此函式 (稍後會說明如何使用繫結產生工具自動執行此操作)：

extern "C" void hello_from_rust();

從 ui/base/resource/resource_bundle.cc 的某處呼叫此函式，建議位置是 ResourceBundle::MaybeMangleLocalizedString 的頂端。建構及執行 Chromium，確認系統多次顯示「Hello from Rust!」。

如果使用 VSCode，現在請設定 Rust，讓 Rust 在 VSCode 中順利運作。這在後續練習中會很實用。如果您成功完成，就能在 println! 中以滑鼠右鍵按一下「Go to definition」。

如何找到說明

• rust_static_library gn 範本提供的選項
• #[no_mangle] 相關資訊
• extern "C" 相關資訊
• gn 的 --export-rust-project switch 相關資訊
• 如何在 VSCode 中安裝 rust-analyzer

測試

Rust 社群撰寫單元測試的模組，通常會位在與所測試程式碼相同的來源檔案中。這種做法已在先前課程中介紹，如下所示：

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    #[test]
    fn my_test() {
        todo!()
    }
}
}

在 Chromium 中，我們將單元測試放在獨立的來源檔案中，而對 Rust 也繼續採取這項做法，這樣不僅能較一致地找到測試，也有助於避免在 test 設定中再次重新建構 .rs 檔案。

因此 Chromium 中有以下 Rust 程式碼測試選項：

• 原生 Rust 測試 (即 #[test])。不建議在 //third_party/rust 之外使用。
• 在 C++ 中編寫的 gtest 測試，並透過 FFI 呼叫並執行 Rust。如果 Rust 程式碼只是精簡的 FFI 層，這麼做就夠充分，而現有的單元測試可為這項功能提供足夠的涵蓋率。
• 在 Rust 中編寫的 gtest 測試，並透過公用 API 使用受測試的 Crate (視需要使用 pub mod for_testing { ... })。這是接下來幾張投影片的主題。

rust_gtest_interop 程式庫

rust_gtest_interop 程式庫提供以下功能：

• 使用 Rust 函式做為 gtest 測試案例 (使用 #[gtest(...)] 屬性)
• 使用 expect_eq! 和類似的巨集 (類似於 assert_eq!，但不會導致恐慌，斷言失敗時也不會終止測試)。

Example:

use rust_gtest_interop::prelude::*;

#[gtest(MyRustTestSuite, MyAdditionTest)]
fn test_addition() {
    expect_eq!(2 + 2, 4);
}

Rust 測試適用的 GN 規則

如要建構 Rust gtest 測試，最簡單的方法就是將這些測試新增至已包含 C++ 測試的現有測試二進位檔，例如：

test("ui_base_unittests") {
  ...
  sources += [ "my_rust_lib_unittest.rs" ]
  deps += [ ":my_rust_lib" ]
}

也可以在單獨的 static_library 中編寫 Rust 測試，但必須手動宣告支援程式庫的依附元件：

rust_static_library("my_rust_lib_unittests") {
  testonly = true
  is_gtest_unittests = true
  crate_root = "my_rust_lib_unittest.rs"
  sources = [ "my_rust_lib_unittest.rs" ]
  deps = [
    ":my_rust_lib",
    "//testing/rust_gtest_interop",
  ]
}

test("ui_base_unittests") {
  ...
  deps += [ ":my_rust_lib_unittests" ]
}

chromium::import! 巨集

將 :my_rust_lib 新增至 GN deps 之後，我們仍需瞭解如何從 my_rust_lib_unittest.rs 匯入及使用 my_rust_lib。我們尚未為 my_rust_lib 提供明確的 crate_name，因此系統會依據完整目標路徑和名稱來運算出 Crate 名稱。幸好，我們可從自動匯入的 chromium Crate 中使用 chromium::import! 巨集，避免採用這類不方便的名稱：

chromium::import! {
    "//ui/base:my_rust_lib";
}

use my_rust_lib::my_function_under_test;

在掩蓋之下，巨集會展開為類似如下的內容：

extern crate ui_sbase_cmy_urust_ulib as my_rust_lib;

use my_rust_lib::my_function_under_test;

詳情請參閱 chromium::import 巨集的文件註解。

測試練習

又到了練習時間！

在您的 Chromium 版本中：

• 在 hello_from_rust 旁邊新增可測試的函式。建議措施：新增兩個以引數形式接收的整數、計算第 n 個費波那契數、加總切片中的整數等。
• 新增獨立的 ..._unittest.rs 檔案，內含新函式的測試。
• 將新測試新增至 BUILD.gn。
• 建構並執行測試，確認新測試能正常運作。

互通性

Rust 社群提供多個 C++/Rust 互通性選項，並且會持續開發新工具。目前 Chromium 使用的工具稱為 CXX。

您可以透過介面定義語言 (很類似 Rust) 描述整個語言邊界，然後 CXX 工具會為 Rust 和 C++ 中的函式和型別產生宣告。

如需完整的使用範例，請參閱 CXX 教學課程。

範例

CXX 要求在 .rs 原始碼的 cxx::bridge 模組中宣告整個 C++/Rust 邊界。

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    unsafe extern "C++" {
        include!("example/include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: &BlobstoreClient, buf: &mut MultiBuf) -> Result<u64>;
    }
}

// 這裡放 Rust 型別和函式的定義

CXX 的限制

使用 CXX 時，最實用的頁面是型別參照。

CXX 基本上適用下列情況：

• 您的 Rust-C++ 介面非常簡單，您可以宣告其中所有項目。
• 您只使用 CXX 已原生支援的型別，例如 std::unique_ptr、std::string、&[u8] 等。

它有許多限制，例如不支援 Rust 的 Option 型別。

這些限制會導致我們只能在 Chromium 中將 Rust 用於妥善隔離的「葉節點」，而非用於任意 Rust-C++ 互通情形。考慮 Chromium 中 Rust 的用途時，建議先草擬語言邊界的 CXX 繫結，瞭解是否足夠簡單。

錯誤處理

CXX 的 Result<T,E> 支援功能依賴 C++ 例外狀況，因此無法用於 Chromium。替代方案：

• Result<T, E> 的 T 部分可以是以下情形之一：

  • 可透過傳出參數傳回，例如透過 &mut T。也就是說，T 必須能跨越 FFI 界線傳遞，例如 T 必須符合下列條件：
    • 是基本型別 (例如 u32 或 usize)
    • 是 cxx 原生支援的型別 (就像 UniquePtr<T>)，具有可在失敗情況下使用的適當預設值 (「不像」Box<T>)。
  • 在 Rust 端保留，並透過參照公開。當 T 是 Rust 型別，無法跨越 FFI 邊界傳遞，且無法儲存在 UniquePtr<T> 時，這就可能有必要。

• Result<T, E> 的 E 部分可以是以下情形之一：

  • 傳回為布林值 (例如 true 代表成功，false 代表失敗)
  • 理論上可保留錯誤詳細資料，但目前在實際情況中並不需要。

CXX 錯誤處理：QR Code 範例

在 QR code 產生器這個範例中，布林值是用來表示成功與失敗，且成功結果可跨越 FFI 邊界傳遞：

#[cxx::bridge(namespace = "qr_code_generator")]
mod ffi {
    extern "Rust" {
        fn generate_qr_code_using_rust(
            data: &[u8],
            min_version: i16,
            out_pixels: Pin<&mut CxxVector<u8>>,
            out_qr_size: &mut usize,
        ) -> bool;
    }
}

CXX 錯誤處理：PNG 範例

PNG 解碼器的原型可說明當成功的結果無法跨越 FFI 邊界時，可以執行哪些操作：

#[cxx::bridge(namespace = "gfx::rust_bindings")]
mod ffi {
    extern "Rust" {
        /// 這回傳一個 FFI 友好的型別，等同於 `Result<PngReader<'a>, ()>`.
        fn new_png_reader<'a>(input: &'a [u8]) -> Box<ResultOfPngReader<'a>>;

        /// `crate::png::ResultOfPngReader` 型別的 C++ 繫結：
        type ResultOfPngReader<'a>;
        fn is_err(self: &ResultOfPngReader) -> bool;
        fn unwrap_as_mut<'a, 'b>(
            self: &'b mut ResultOfPngReader<'a>,
        ) -> &'b mut PngReader<'a>;

        /// `crate::png::PngReader` 型別的 C++ 繫結：
        type PngReader<'a>;
        fn height(self: &PngReader) -> u32;
        fn width(self: &PngReader) -> u32;
        fn read_rgba8(self: &mut PngReader, output: &mut [u8]) -> bool;
    }
}

在 Chromium 中使用 CXX

在 Chromium 中，我們會為每個要使用 Rust 的葉節點定義獨立的 #[cxx::bridge] mod。每個 rust_static_library 通常都需要一個值。只要將下列項目

cxx_bindings = [ "my_rust_file.rs" ]
   # 含有 #[cxx::bridge] 的檔案列表，而非所有原始碼檔案
allow_unsafe = true

新增至現有的 rust_static_library 目標，並搭配 crate_root 和 sources。

C++ 標頭會在合理位置產生，因此您只需採用下列程式碼：

#include "ui/base/my_rust_file.rs.h"

您會在 //base 中發現一些公用函式，可將 Chromium C++ 型別轉換成 CXX Rust 型別，逆向轉換也可以，例如 SpanToRustSlice。

練習：與 C++ 的互通性

第一部分

• 在您先前建立的 Rust 檔案中新增 #[cxx::bridge]，指定要從 C++ 呼叫的單一函式 (名為 hello_from_rust)，但不採用任何參數，也不會傳回值。
• 修改先前的 hello_from_rust 函式，移除 extern "C" 和 #[no_mangle]。現在這樣就只是標準的 Rust 函式。
• 修改 gn 目標，建構這些繫結。
• 在 C++ 程式碼中，移除 hello_from_rust 的前向宣告，改為納入產生的標頭檔案。
• 建構並執行！

第二部分

您可以試著玩玩 CXX，這有助於瞭解 Chromium 中的 Rust 有多靈活。

可嘗試的事項：

• 從 Rust 呼叫 C++。您會需要以下項目：
  • 額外的標頭檔案，可從 cxx::bridge 中 include!。您會需要在新標頭檔案中宣告 C++ 函式。
  • 用於呼叫這類函式的 unsafe 區塊，或者可在 #[cxx::bridge] 中指定 unsafe 關鍵字，如這個頁面所述。
  • 您可能也需要 #include "third_party/rust/cxx/v1/crate/include/cxx.h"
• 將 C++ 字串從 C++ 傳遞至 Rust。
• 將 C++ 物件的參照傳遞至 Rust。
• 刻意從 #[cxx::bridge] 中，取得不相符的 Rust 函式簽章，並熟悉看到的錯誤。
• 刻意從 #[cxx::bridge] 中取得不相符的 C++ 函式簽章，並熟悉看到的錯誤。
• 將某些型別的 std::unique_ptr 從 C++ 傳遞至 Rust，這樣 Rust 就能擁有某些 C++ 物件。
• 建立 Rust 物件並傳遞至 C++ 中，讓 C++ 擁有該物件 (提示：您需要 Box)。
• 在 C++ 型別上宣告一些方法，然後從 Rust 呼叫。
• 在 Rust 型別上宣告一些方法，然後從 C++ 呼叫。

第三部分

現在您已瞭解 CXX 互通性的優勢和限制，不妨思考一些 Chromium 中介面相當簡單的 Rust 用途。草擬定義該介面的方式。

如何找到說明

• cxx 繫結參照
• rust_static_library gn 範本

新增第三方 Crate

Rust 程式庫稱為「Crate」，位於 crates.io。Rust Crate「非常容易」互相依附，所以它們也確實常常這麼做！

對 Chromium 工程師來說，這有以下優缺點：

• 所有 Crate 都使用通用的建構系統，因此我們可以自動將其納入 Chromium...
• ...但 Crate 通常具有遞移依附元件，因此可能需要導入多個程式庫。

我們將探討以下內容：

• 如何在 Chromium 原始碼樹中加入 Crate
• 如何為其建立 gn 建構規則
• 如何稽核原始碼，確保足夠安全

設定 Cargo.toml 檔案以新增 Crate

Chromium 有一組集中管理的直接 Crate 依附元件。這些元件可透過單一 Cargo.toml 管理：

[dependencies]
bitflags = "1"
cfg-if = "1"
cxx = "1"
# 還有更多...

與任何其他 Cargo.toml 一樣，您可以指定依附元件的更多詳細資料。以最常見的情況來說，您會想在 Crate 中指定要啟用的 features。

將 Crate 新增至 Chromium 時，您通常需要在 gnrt_config.toml 這個額外檔案中提供額外資訊，這接下來會介紹。

設定 gnrt_config.toml

除了 Cargo.toml，還有 gnrt_config.toml。這包含用來處理 Crate 的 Chromium 專屬擴充功能。

新增 Crate 時，應至少指定 group，可以是以下其中一個：

#   'safe': The library satisfies the rule-of-2 and can be used in any process.
#   'sandbox': The library does not satisfy the rule-of-2 and must be used in
#              a sandboxed process such as the renderer or a utility process.
#   'test': The library is only used in tests.

舉例來說：

[crate.my-new-crate]
group = 'test' # only used in test code

視 Crate 原始碼布局而定，您可能也需要使用這個檔案指定其 `LICENSE 檔案的位置。

稍後我們會看到一些其他您需在這個檔案中設定的項目，才能解決問題。

下載 Crate

gnrt 這項工具瞭解如何下載 Crate，以及如何產生 BUILD.gn 規則。

首先，請按照以下方式下載任何你想要的 Crate：

cd chromium/src
vpython3 tools/crates/run_gnrt.py -- vendor

雖然 gnrt 工具屬於 Chromium 原始碼的一部分，但透過執行這項指令，您可以從 crates.io 下載並執行其依附元件。請參閱前面的章節中有關這項安全性決策的討論。

這項 vendor 指令可能會下載以下項目：

• 您的 Crate
• 直接依附元件和遞移依附元件
• 其他 Crate 的新版本。這是 cargo 的要求，以便解析 Chromium 所需的完整 Crate 組合。

Chromium 會維護部分 Crate 的修補程式，保留在 //third_party/rust/chromium_crates_io/patches 中。系統會自動重新套用這些設定，但如果修補失敗，就可能需要手動操作。

產生 gn 建構規則

下載 Crate 後，請如下產生 BUILD.gn 檔案：

vpython3 tools/crates/run_gnrt.py -- gen

現在請執行 git status，您應會看到以下情形：

• 在 third_party/rust/chromium_crates_io/vendor 中，至少有一個新的 Crate 原始碼
• 在 third_party/rust/<crate name>/v<major semver version> 中，至少有一個新的 BUILD.gn
• 適當的 README.chromium

「major semver version」是 Rust「Semver」版本號碼.

請仔細查看，尤其是 third_party/rust 中產生的內容。

[crate.unicode-linebreak]
allow-first-party-usage = false
build-script-outputs = ["tables.rs"]