Rust 程式設計語言

由 Steve Klabnik 與 Carol Nichols，以及 Rust 社群的貢獻撰寫而成

此版本假設你使用的是 Rust 1.65（於 2022-11-03 發布）或更高的版本，並在所有專案中的 Cargo.toml 都有 edition="2021" 來使用 Rust 2021 版號。請查看第一章的「安裝」段落來安裝或更新 Rust。

本書的 HTML 格式可以在線上閱讀：https://doc.rust-lang.org/stable/book/（正體中文版）。而離線版則包含在 rustup 安裝的 Rust 中，輸入 rustup docs --book 就能開啟。

社群中也有提供本書的各種[譯本]。

本書也有由 No Starch Press 出版平裝與電子版格式。

🚨 想要更有互動的學習體驗？來嘗試不同的 Rust Book，賣點有：隨堂測驗、重點提示、視覺化呈現，更多都在 https://rust-book.cs.brown.edu

• commit: 3f64052

前言

雖然不是那麼明確，但 Rust 程式設計語言旨在賦權（empowerment）：無論你現在寫的是何種程式碼，Rust 都能賦予你更多能力，在更廣泛的領域中帶有自信地向前邁進。

比方說，「系統層級」的工作會需要處理低階的記憶體管理、資料呈現與程序並行的細節。對以往來說，這塊程式領域被視為巫術般的存在，只有投入好幾年時間學習的選中之人才有辦法駕馭，也才能懂得如何避開其惡名昭彰的陷阱。而且就算是這個領域的實作者也謹慎行事，也生怕他們的程式碼會出現漏洞、崩潰或損壞。

Rust 破除了這些障礙，消除了以往的陷阱並提供友善全面的工具來協助你。想要「深入」底層控制的程式設計師可以使用 Rust，無需冒著常見的崩潰或安全漏洞風險，也無需學習得經常改變的工具鏈其中的細節。更好地是，這個語言本身就是設計成能引導你自然而然地寫出可靠且在速度與記憶體使用都十分高效的程式碼。

已經在處理底層程式碼的程式設計師可以使用 Rust 來擴展他們的野心。舉例來說，在 Rust 中進行平行化是相對低風險的動作，編譯器會幫你抓到典型的錯誤。而且你也能更有自信且更積極地進行最佳化，不必擔心會意外造成崩潰或漏洞。

但 Rust 並不只限於底層的系統程式設計。其表現力與易用易讀的程度能令人愉快地寫出 CLI 應用程式、網頁伺服器與許多其他種程式碼。你會在本書中看到這兩種簡單的範例。使用 Rust 能這讓你將一個領域所學到的技能延伸到另一個領域，你可以透過寫網頁應用程式來學習 Rust，然後應用同樣的技能到你的樹莓派（Raspberry Pi）上。

本書充分體現了 Rust 賦予其使用者更多能力的潛力。其內容平易近人，不止致力於協助你提升 Rust 的知識，還能提升讓你身為程式設計師的整體信心。所以讓我們準備開始學習吧，歡迎加入 Rust 的社群！

— Nicholas Matsakis 與 Aaron Turon

介紹

注意：本書的（英文）版本與出版的 The Rust Programming Language 以及電子書版本的 No Starch Press 一致。

歡迎閱讀 Rust 程式設計語言，這是一本 Rust 的入門書籍。Rust 程式設計語言能幫助你寫出更快更可靠的軟體。在設計程式語言時，「上層的易讀易用性」與「底層的掌控性」經常難以取捨。Rust 直接挑戰這個矛盾。Rust 在強大的技術能力與良好的開發者體驗之間取得平衡，讓你能控制底層的實作細節（比如記憶體使用），但免於以往這樣的控制所帶來的相關麻煩。

Rust 適用於誰

Rust 的各種特長讓它適用於很多人，我們來討論一些最重要的客群。

開發團隊

Rust 被認定是一個有生產力的工具，讓能力不均的大型系統程式設計團隊能夠協同開發。底層程式碼容易產生難以察覺的錯誤，在多數其他語言中，只能靠大量的測試、以及經驗豐富的開發者小心翼翼地審核程式碼，才能找出它們。而在 Rust 中，編譯器扮演著守門員的角色阻擋這些難以捉摸的程式錯誤，包含並行（concurrency）的錯誤。透過與編譯器一同合作，開發團隊可以將他們的時間專注在程式邏輯，而不是成天追著錯誤跑。

Rust 也將一些現代化的開發工具帶入系統程式設計的世界中：

• Cargo 是個管理依賴函式庫與建構的工具，讓新增、編譯與管理依賴函式庫變得十分輕鬆，並在 Rust 生態系統維持一致性。
• Rustfmt 工具確保開發者遵循統一的程式碼風格。
• Rust Language Server 為整合開發環境（IDE）提供了程式碼補全與行內錯誤訊息。

透過使用這些工具、以及其他 Rust 生態系統中的工具，開發者在寫系統層級的程式時更有生產力。

學生

Rust 適合學生以及那些對學習系統概念有興趣的人。許多人透過 Rust 學會相關主題，例如作業系統開發。社群的人都非常友善，且樂於解答學習者的問題。如同對本書的投入，Rust 團隊致力於讓系統概念深入人心，尤其是剛開始學習程式設計的人。

公司

已有大大小小數以百計的公司，在正式生產環境中使用 Rust 來處理各種任務，包含命令列工具、網路服務、DevOps 工具、嵌入式裝置、影音分析與轉碼、加密貨幣、生物資訊、搜尋引擎、物聯網應用、機器學習，甚至是 Firefox 瀏覽器的主要部分。

開源開發者

Rust 適用於想要建構 Rust 程式設計語言、社群、開發工具與函式庫的開發者。我們很樂於看到你願意對 Rust 語言貢獻。

重視速度與穩定性的開發者

Rust 適用於追求語言速度與穩定性的開發者。所謂的速度，我們指的是 Rust 程式碼的執行速度以及 Rust 讓你能開始撰寫程式碼的速度。Rust 編譯器的檢查能確保新增功能與重構時的穩定性。這與沒有這些檢查的語言形成對比，開發者通常不敢修改其脆弱的遺留程式碼。Rust 還力求無成本抽象化（zero-cost abstractions），高階的特性編譯成底層程式碼後，執行的速度能像手刻一樣快。Rust 致力於讓安全的程式碼同時也能是執行迅速的程式碼。

這裡提及的僅是一部分的最大受益者，Rust 語言期許能支援更多其他使用者。總體來說，Rust 最大的野心是消除數十年來開發者不得不作出的取捨，像是提供安全性與生產力、具有速度又易讀易用。歡迎嘗試 Rust，看看這門語言適不適合你。

本書寫給誰看

本書假設你已經使用其他程式語言寫過程式碼，無論哪種語言。我們會試著讓不同背景的開發者能理解內容，但我們不會花費很多篇幅談論什麼是程式設計或教你怎麼寫程式。如果你剛開始學習程式語言，一本專門介紹程式設計的書籍會更適合你。

如何閱讀本書

一般來說，本書預設你會從前往後依序閱讀。後面的章節建立在前面提到的概念上，並且前面的章節不會深入某特定主題，而於後面的章節再議。

你會發現本書有兩種類型的章節：概念章節與專案章節。在概念章節中，你會學到 Rust 的某些概念。在專案章節中，我們會一起應用當前所學來做小專案。第二、十二和二十章是專案章節，其餘是概念章節。

第一章會解釋如何安裝 Rust、如何寫支「Hello, world!」程式以及如何使用 Cargo－－Rust 的套件管理與建構工具。第二章透過實作一款猜數字遊戲的程式來介紹 Rust。我們在此提及大概的觀念，並在之後的章節提供更詳細的介紹。如果你想馬上動手實作看看的話，第二章會很適合你。第三章會涵蓋 Rust 與其他程式設計語言類似的功能。第四章則會學習 Rust 的所有權系統。如果你是嚴謹派的讀者、傾向先學習所有細節再進入實作，你可能會想跳過第二章直接前往第三章。當你想要應用學到的細節時，再回到第二章練習。

第五章討論結構體與方法，而第六章涵蓋列舉、match 表達式與 if let 控制流程的語法。你會在 Rust 中用結構體與列舉來自訂型別。

在第七章中，你會學到 Rust 的模組系統與隱私規則，讓你可以組織程式碼以及其公開應用程式介面（Application Programming Interface, API）。第八章會討論標準函式庫提供的一些常見集合資料結構，像是向量、字串與雜湊映射。第九章會探討 Rust 的錯誤處理哲學與技巧。

第十章將深入探討泛型、特徵（traits）與生命週期，讓你能定義出能套用多種型別的程式碼。第十一章都在討論測試，就算有 Rust 的安全性保障，還是必須透過測試來確保你的程式邏輯正確。在第十二章中，我們會動手實作 grep 命令列工具的部分功能，可以搜尋檔案中的文字。我們將會應用前幾章討論過的許多概念。

第十三章會探索閉包與疊代器，這是 Rust 借鑒函式程式設計語言的功能。在第十四章中，我們要更深入研究 Cargo 並討論分享函式庫給其他人的最佳方式。第十五章會討論標準函式庫提供的智慧指標以及能啟用它們功能的特徵（traits）。

在第十六章中，我們會介紹各種不同的並行程式設計模型，並談論 Rust 如何幫助你無懼地開發多執行緒的程式。第十七章會拿 Rust 的慣用風格與你可能較熟悉的物件導向程式設計原則作比較。

第十八章涉及模式與模式配對，它們的強大力量讓你能用 Rust 表達更多概念。第十九章是進階主題的大雜燴，其中包含：不安全（unsafe）的 Rust、巨集、以及更多關於生命週期、特徵、型別、函式與閉包的介紹。

在第二十章中，我們會完整實作一個底層跑多執行緒的網頁伺服器！

最後，以參照的方式收錄本語言的一些實用資訊。附錄 A 涵蓋 Rust 的關鍵字、附錄 B 涵蓋 Rust 的運算子與符號、附錄 C 涵蓋標準函式庫提供的可推導的特徵（derivable traits）、附錄 D 涵蓋一些實用開發工具，然後附錄 E 會解釋 Rust 的版號。在附錄 F 中你可以找到本書籍的各種翻譯版本，然後在附錄 G 我們會講解 Rust 的開發流程以及什麼是每夜版（Nightly）Rust。

本書沒有錯誤的閱讀方式－－如果你想要跳過一些章節，儘管跳過吧！後面也許會遇到不懂的地方而需要回頭去看。總之用最適合自己的方式閱讀。

學習 Rust 的過程中有個重要的部分－－學習如何閱讀編譯器顯示的錯誤訊息，讓訊息引導你寫出正確的程式碼。因此，我們特意提供很多無法編譯的範例，以及編譯器對應顯示的錯誤訊息。如果你隨意挑一則範例執行的話，它可能無法編譯喔！請務必看看範例旁的文字來瞭解該範例是不是故意出錯。可愛的吉祥物 Ferris 也能幫助你分辨哪些程式碼本來就無法運作：

Ferris	意思
	此程式碼無法編譯！
	此程式碼會恐慌！
	此程式碼不會產生預期的行為。

在大多數的情況下，我們會引導你將無法編譯的程式碼寫成正確的版本。

原始碼

產生本書的原始檔案可以在 GitHub 上找到。

開始入門

讓我們開始你的 Rust 旅途吧！千里之行始於足下，在此章節我們將討論：

• 在 Linux、macOS 和 Windows 上安裝 Rust
• 寫一支印出 Hello, world! 的程式
• 使用 Rust 的套件管理工具暨建構系統 cargo

安裝教學

第一步是安裝 Rust，我們將會透過 rustup 安裝 Rust，這是個管理 Rust 版本及相關工具的命令列工具。你將會需要網路連線才能下載。

注意：如果你基於某些原因不想使用 rustup 的話，請前往 Rust 其他安裝方法的頁面尋求其他選項。

以下步驟將會安裝最新的穩定版 Rust 編譯器。Rust 的穩定性能確保本書的所有範例在更新的 Rust 版本仍然能繼續編譯出來。輸出的結果可能會在不同版本間而有些微的差異，因為 Rust 時常會改善錯誤與警告訊息。換句話說，任何你所安裝的最新穩定版 Rust 都應該能夠正常運行本書的內容。

命令列標記

在本章節到整本書為止，我們將會顯示一些終端機會用到的命令。任一你會用到的命令都會始於 $。但你不需要去輸入 $，因為這通常代表每一命令列的起始位置。而沒有出現 $ 的行數，通常則代表前一行命列輸出的結果。除此之外，針對 PowerShell 的範例則將會使用 > 而不是 $。

在 Linux 或 macOS 上安裝 rustup

如果你使用的是 Linux 或 macOS，請開啟終端機然後輸入以下命令：

$ curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh

這道命令會下載一支腳本然後開始安裝 rustup 工具，接著安裝最新的穩定版 Rust。下載過程中可能會要求你輸入你的密碼。如果下載成功的話，將會出現以下內容：

Rust is installed now. Great!

你還會需要一個連結器（linker） 來讓 Rust 將編譯好的輸出資料整理到一個檔案內。通常你很可能已經有安裝了，但如果你遇到連結器相關的錯誤時，這代表你需要安裝一個 C 編譯器，因爲它通常都會帶有一個的連結器。有個 C 編譯器通常也很實用，因爲一些常見的 Rust 套件也會依賴於 C 而需要一個 C 編譯器。

在 macOS 上，你可以輸入以下命令來安裝 C 編譯器：

$ xcode-select --install

Linux 使用者的話則需要依據他們的發行版文件來安裝 GCC 或 Clang。舉例來說，如果你使用 Ubuntu 的話，你可以安裝 build-essential 套件。

在 Windows 上安裝 rustup

在 Windows 上請前往下載頁面並依照指示安裝 Rust。在安裝的某個過程中，你將會看到一個訊息要求說你還需要 C++ build tools for Visual Studio 2013 或更新的版本。

要取得 build tools 的話，你需要安裝 Visual Studio 2022。當你被問到要安裝哪些時，請記得包含：

• “Desktop Development with C++”
• The Windows 10 or 11 SDK
• The English language pack component（以及其他你想選擇的語言包）

本書接下來使用的命令都相容於 cmd.exe 和 PowerShell。如果有特別不同的地方，我們會解釋該怎麼使用。

疑難排除

想簡單確認你是否有正確安裝 Rust 的話，請開啟 shell 然後輸入此命令：

$ rustc --version

你應該會看到已發佈的最新穩定版本號、提交雜湊（hash）以及提交日期如以下格式所示：

rustc x.y.z (abcabcabc yyyy-mm-dd)

如果你看到這則訊息代表你成功安裝 Rust 了！如果你沒有看到的話，請如下檢查 Rust 是否在你的 %PATH% 系統變數裡。

在 Windows CMD 中請使用：

> echo %PATH%

在 PowerShell 中請使用：

> echo $env:Path

在 Linux 和 macOS 的話請使用：

$ echo $PATH

如果以上步驟皆正確無誤，但還是無法執行 Rust 的話，你可以前往一些地方尋求協助。例如您可以前往社群頁面聯絡其他 Rustaceans（這是我們常用稱呼自己取的暱稱）交談並取得協助。

更新與解除安裝

當你透過 rustup 安裝完 Rust 後，要更新到最新版本的方法非常簡單。在你的 shell 中執行以下更新腳本即可：

$ rustup update

要解除安裝 Rust 與 rustup 的話，則在 shell 輸入以下解除安裝腳本：

$ rustup self uninstall

本地端技術文件

安裝 Rust 的同時也會包含一份本地的技術文件副本，讓你可以離線閱讀。執行 rustup doc 就可以用你的瀏覽器開啟本地文件。

每當有任何型別或函式出現而你卻不清楚如何使用時，你就可以閱讀應用程式介面（API）技術文件來理解！

Hello, World!

現在你已經安裝好 Rust，是時候開始寫你的第一支 Rust 程式。當我們學習一門新的語言時，有一個習慣是寫一支印出「Hello, world!」到螢幕上的小程式，此章節將教你做一樣的事！

注意：本書將假設你已經知道命令列最基本的使用方法。Rust 對於你的編輯器、工具以及程式碼位於何處沒有特殊的要求，所以如果你更傾向於使用整合開發環境（IDE）的話，請儘管使用你最愛的 IDE。許多 IDE 都已經針對 Rust 提供某種程度的支援，請查看你所使用的 IDE 技術文件以瞭解詳情。Rust 團隊正透過 rust-analyzer 積極提升 IDE 的支援，請查 附錄 D 來了解更多細節。

建立專案目錄

你將先建立一個目錄來儲存你的 Rust 程式碼。程式碼位於何處並不重要，但為了能好好練習書中的範例和專案，我們建議你可以在你的 home 目錄建立一個 projects 目錄然後將你所有的專案保存在此。

請開啟終端機然後輸入以下命令來建立 projects 目錄和另一個在 projects 目錄底下的真正要寫「Hello, world!」專案的目錄。

對於 Linux、macOS 和 Windows 的 PowerShell，請輸入：

$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world

對於 Windows CMD，請輸入：

> mkdir "%USERPROFILE%\projects"
> cd /d "%USERPROFILE%\projects"
> mkdir hello_world
> cd hello_world

編寫並執行 Rust 程式

接著，請產生一個全新原始碼檔案並命名為 main.rs。Rust 的文件檔案都會以 .rs 副檔名稱作為結尾。如果你用到不只一個單字的話，慣例上是用底線區隔開來。比方說，請使用 hello_world.rs 而不是 helloworld.rs。

現在請開啟 main.rs 檔案然而後輸入範例 1-1 中的程式碼。

檔案名稱：main.rs

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

範例 1-1：印出「Hello, world!」的程式

儲存檔案然後回到你的專案目錄底下 ~/projects/hello_world。在 Linux 或 macOS 上，請輸入以下命令來編譯並執行檔案：

$ rustc main.rs
$ ./main
Hello, world!

在 Windows 上則輸入 .\main.exe 而非 ./main：

> rustc main.rs
> .\main.exe
Hello, world!

不管你的作業系統為何，終端機上應該都會出現 Hello, world!。如果你沒有看到，可以回到安裝章節中的「疑難排除」尋求協助。

如果 Hello, world! 有印出來，那麼恭喜你！你正式寫了一支 Rust 程式，所以你也正式成為 Rust 開發者了——歡迎加入！

分析這支 Rust 程式

讓我們來仔細瞧瞧你的「Hello, world!」程式。這是第一塊拼圖：

fn main() {

}

這幾行定義了一個 main 函式。main 是一個特別的函式：它是每個可執行的 Rust 程式永遠第一個執行的程式碼。第一行宣告了一個函式 main，它沒有參數也不回傳任何東西。如果有參數的話，它們會被加進括號 () 內。

函式本體被囊括在大括號 {} 內，Rust 要求所有函式都用大括號包起來。一般來說，良好的程式碼風格會要求將前大括號置於宣告函式的同一行，並用一個空格區隔開來。

如果你想要在不同 Rust 專案之間統一標準風格的話，rustfmt 可以格式化你的程式成特定的風格（更多 rustfmt 資訊請詳見附錄 D）。Rust 團隊已經將此工具納入標準 Rust 發行版中，就像 rustc 一樣，它應該已經安裝到你的電腦上了！

在 main 函式本體中有以下程式碼：

#![allow(unused)]
fn main() {
    println!("Hello, world!");
}

此行負責了整支程式要做的事：它將文字顯示在螢幕上。這邊有四個細節要注意。

首先，Rust 的排版風格是 4 個空格而非一個 tab。

第二，println! 會呼叫一支 Rust 巨集（macro）。如果是呼叫函式的話，那則會是 println（去掉 !）。我們會在第十九章討論更多巨集的細節。現在你只需要知道使用 ! 代表呼叫一支巨集而非一個正常的函式，且該巨集遵守的規則不全都和函式一樣。

第三，"Hello, world!" 是一個字串，我們將此字串作為引數傳遞給 println!，然後該字串就會被顯示到螢幕上。

第四，我們用分號（;）作為該行結尾，代表此表達式的結束和下一個表達式的開始。多數的 Rust 程式碼都以分號做結尾。

編譯和執行是不同的步驟

你剛剛執行了一個新建立的程式，讓我們來檢查過程中的每一個步驟吧。

在你執行一支 Rust 程式前，你必須用 Rust 編譯器來編譯它，也就是輸入 rustc 命令然後加上你的原始檔案，像這樣子：

$ rustc main.rs

如果你已經有 C 或 C++ 的背景，你應該就會發現這和 gcc 或 clang 非常相似。編譯成功後，Rust 編譯器會輸出一個二進制執行檔（binary executable）。

在 Linux、macOS 和 Windows 上的 PowerShell，你可以在你的 shell 輸入 ls 來查看你的執行檔：

$ ls
main  main.rs

在 Linux 和 macOS，你會看到兩個檔案。而在 Windows 上的 PowerShell，你會和使用 CMD 一樣看到三個檔案。在 Windows 上的 CMD，你需要輸入：

> dir /B %= /B 選項代表只顯示檔案名稱 =%
main.exe
main.pdb
main.rs

這顯示了副檔名為 .rs 的原始碼檔案、執行檔（在 Windows 上為 main.exe；其他則為 main），然後在 Windows 上會再出現一個副檔名為 .pdb 的除錯資訊文件。在這裡，你就可以像這樣執行 main 或 main.exe 檔案：

$ ./main # 在 Windows 上則是 .\main.exe

如果你的 main.rs 正是你的「Hello, world!」程式，這命令就會顯示 Hello, world! 到你的終端機。

如果你比較熟悉動態語言，像是 Ruby、Python 或 JavaScript，你可能會比較不習慣將編譯與執行程式分為兩個不同的步驟。Rust 是一門預先編譯（ahead-of-time compiled）的語言，代表你可以編譯完成後將執行檔送到其他地方，然後他們就算沒有安裝 Rust 一樣可以執行起來。但如果你給某個人 .rb、.py 或 .js 檔案，他們就需要 Ruby、Python 或 Javascript 分別都有安裝好。當然你在這些語言只需要一行命令就可以執行，在語言設計中這一切都只是取捨。

在簡單的程式使用 rustc 來編譯不會有什麼問題，但當你的專案成長時，你將會需要管理所有選擇並讓程式碼易於分享。接下來我們將介紹 Cargo 這項工具給你，它將協助你寫出真正的 Rust 程式。

Hello, Cargo!

Cargo 是 Rust 的建構系統與套件管理工具。大部分的 Rustaceans 都會用此工具來管理他們的專案，因為 Cargo 能幫你處理很多任務，像是建構你的程式碼、下載你程式碼所需要的依賴函式庫並建構它們。我們常簡稱程式碼所需要用到的函式庫為依賴（dependencies）。

簡單的 Rust 程式像是我們目前所寫的不會有任何依賴。當我們用 Cargo 建構「Hello, world!」專案時，Cargo 只會用到建構程式碼的那部分。隨著你寫的 Rust 程式越來越複雜，你將會加入一些依賴函式庫來幫助你。而如果你使用 Cargo 的話，加入這些依賴就會簡單很多。

既然大多數的 Rust 專案都是用 Cargo，所以接下來本書也將假設你也使用 Cargo。Cargo 在你使用「安裝教學」的官方安裝連結來安裝 Rust 時就已經連同安裝好了。如果你是用其他方式下載 Rust 的話，想要檢查 Cargo 有沒有下載好可以透過你的終端機輸入：

$ cargo --version

如果你有看到版本號，那就代表你有安裝了！如果你看到錯誤訊息，像是 command not found，請查看你的安裝辦法的技術文件，尋找如何額外下載 Cargo。

使用 Cargo 建立專案

讓我們來用 Cargo 建立一個專案，並來比較它和我們原本的「Hello, world!」專案有什麼差別。請回到你的 projects 目錄（或者任何你決定存放程式碼的地方），然後在任何作業系統上輸入：

$ cargo new hello_cargo
$ cd hello_cargo

第一道命令會建立一個新的目錄與專案叫做 hello_cargo。我們將我們的專案命名為 hello_cargo，然後 Cargo 就會產生相同名稱的目錄並產生所需的檔案。

進入 hello_cargo 然後顯示檔案的話，你會看到 Cargo 產生了兩個檔案和一個目錄： Cargo.toml 檔案以及一個 src 目錄，其內包含一個 main.rs 檔案。

它還會初始化成一個新的 Git repository 並附上 .gitignore 檔案。如果已經在 Git repository 內的話，執行 cargo new 則不會產生 Git 的檔案。你可以用 cargo new --vcs=git 覆寫這項行為。

注意：Git 是一個常見的版本控制系統。你可以加上 --vcs 來變更 cargo new 去使用不同的版本控制系統，或是不用任何版本控制系統。請執行 cargo new --help 來查看更多可使用的選項。

請用任何你喜歡的編輯器開啟 Cargo.toml，它應該會看起來和範例 1-2 差不多。

檔案名稱：Cargo.toml

[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2021"

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

[dependencies]

範例 1-2：用 cargo new 產生的 Cargo.toml

此檔案用的是 TOML（Tom’s Obvious, Minimal Language）格式，這是 Cargo 配置文件的格式。

第一行的 [package] 是一個段落（section）標題，說明以下的陳述式（statement）會配置這個套件。隨著我們加入更多資訊到此文件，我們也會加上更多段落。

接下來三行就是 Cargo 編譯你的程式所需的配置資訊：名稱、版本、誰寫的以及哪個 Rust edition 會用到。我們會在附錄 E 介紹什麼是 edition。

最後一行 [dependencies] 是用來列出你的專案會用到哪些依賴的段落。在 Rust 中，程式碼套件會被稱為 crates。我們在此專案還不需要任何其他 crate。但是我們會在第二章開始用到，屆時我們會再來介紹。

現在請開啟 src/main.rs 來看看：

檔案名稱：src/main.rs

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

Cargo 預設會為你產生一個「Hello, world!」程式，就像我們範例 1-1 寫的一樣！目前我們寫的專案與 Cargo 產生的程式碼不同的地方在於 Cargo 將程式碼放在 src 目錄底下，而且我們還有一個 Cargo.toml 配置文件在根目錄。

Cargo 預期你的原始檔案都會放在 src 目錄底下。專案的根目錄是用來放 README 檔案、授權條款、配置檔案以及其他與你的程式碼不相關的檔案。使用 Cargo 能夠幫助你組織你的專案，讓一切井然有序。

如果你的專案還沒開始使用 Cargo 的話，像是我們剛剛寫的「Hello, world!」專案，你只要將程式碼移入 src 然後產生正確的 Cargo.toml 檔案，就可以將它轉換成能夠使用 Cargo 的專案。

建構並執行 Cargo 專案

現在讓我們看看用 Cargo 產生的「Hello, world!」程式在建構和執行時有什麼差別！請在你的 hello_cargo 目錄下輸入以下命令來建構專案：

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

此命令會產生一個執行檔 target/debug/hello_cargo（在 Windows 上則是 target\debug\hello_cargo.exe），而不是在你目前的目錄。因為預設的建構會是 debug build，Cargo 會將執行檔放進名為 debug 的目錄。你可以用以下命令運行執行檔：

$ ./target/debug/hello_cargo # 在 Windows 上的話則是 .\target\debug\hello_cargo.exe
Hello, world!

如果一切順利，Hello, world! 就會顯示在終端機上。第一次執行 cargo build 的話，還會在根目錄產生另一個新檔案：Cargo.lock。此檔案是用來追蹤依賴函式庫的確切版本。不過此專案沒有任何依賴，所以目前這個檔案看起來內容會有點少。你不會需要去手動更改此檔案，Cargo 會幫你管理這個檔案的內容。

我們剛用 cargo build 建構完專案並用 ./target/debug/hello_cargo 執行它。不過我們其實也可以只用一道命令 cargo run 來編譯程式碼並接著運行產生的執行檔：

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_cargo`
Hello, world!

使用 cargo run 通常比執行 cargo build 然後使用執行檔的完整路徑還要方便，所以多數開發者通常都直接使用 cargo run。

請注意到這次輸出的結果我們沒有看到 Cargo 有在編譯 hello_cargo 的跡象，這是因為 Cargo 可以知道檔案完全沒被更改過，所以它不用重新建構可以選擇直接執行執行檔。如果你有變更你的原始碼的話，Cargo 才會在執行前重新建構專案，你才會看到這樣的輸出結果：

$ cargo run
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs
     Running `target/debug/hello_cargo`
Hello, world!

Cargo 還提供一道命令 cargo check，此命令會快速檢查你的程式碼，確保它能編譯通過但不會產生執行檔：

$ cargo check
   Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

為何你會不想要產生執行檔呢？這是因為 cargo check 省略了產生執行檔的步驟，所以它執行的速度比 cargo build 還來的快。如果你在寫程式時需要持續檢查的話，使用 cargo check 可以加快整體過程，讓你知道你的專案是否能編譯！所以許多 Rustaceans 都會在寫程式的過程中時不時執行 cargo check 來確保它能編譯。最後當他們準備好要使用執行檔時，才會用 cargo build。

讓我們來回顧我們目前學到的 Cargo 內容：

• 我們可以用 cargo new 產生專案。
• 我們可以用 cargo build 建構專案。
• 我們可以用 cargo run 同時建構並執行專案。
• 我們可以用 cargo check 建構專案來檢查錯誤，但不會產生執行檔。
• Cargo 會儲存建構結果在 target/debug 目錄底下，而不是放在與我們程式碼相同的目錄。

使用 Cargo 還有一項好處是在任何作業系統所使用的命令都是相同的，所以到這邊開始我們不再需要特別提供 Linux 和 macOS 相對於 Windows 不同的特殊命令。

建構發佈版本（Release）

當你的專案正式準備好要發佈的話，你可以使用 cargo build --release 來最佳化編譯結果。此命令會產生執行檔到 target/release 而不是 target/debug。最佳化可以讓你的 Rust 程式碼跑得更快，不過也會讓編譯的時間變得更久。這也是為何 Cargo 提供兩種不同的設定檔（profile）：一個用來作為開發使用，讓你可以快速並經常重新建構；另一個用來最終產生你要給使用者運行的程式用，它通常不會需要重新建構且能盡所能地跑得越快越好。如果你要做基準化分析（benchmarking）來檢測程式運行時間的話，請確認執行的是 cargo build --release 並使用 target/release 底下的執行檔做檢測。

將 Cargo 視為常規

雖然在簡單的專案下，Cargo 比起只使用 rustc 的確沒辦法突顯出什麼價值。但是當你的程式變得越來越複雜時，它將證明它的用途。當程式成長到好幾個檔案或需要依賴項目時，讓 Cargo 來協調你的專案會來的簡單許多。

儘管 hello_cargo 是個小專案，但它使用了你未來的 Rust 生涯中真實情況下會用到的工具。事實上，所有存在的專案，你幾乎都可以用以下命令完成：使用 Git 下載專案、移至專案目錄然後建構完成。

$ git clone example.org/someproject
$ cd someproject
$ cargo build

有關 Cargo 的更多資訊，請查看它的技術文件。

總結

你已經完成你的 Rust 旅途的第一步了！在本章節你學到了：

• 使用 rustup 安裝最新穩定版 Rust
• 更新到最新 Rust 版本
• 開啟本地端安裝的技術文件
• 直接使用 rustup 編寫並執行一支「Hello, world!」程式
• 使用 Cargo 建立並執行一個新專案

接下來是時候來建立一個更實際的程式來熟悉 Rust 程式碼的讀寫了。所以在第二章我們將寫出一支猜謎遊戲的程式。如果你想直接學習 Rust 的常見程式設計概念的話，你可直接閱讀第三章，之後再回來看第二章。

設計猜謎遊戲程式

讓我們親自動手一同完成一項專案來開始上手 Rust 吧！本章節會介紹一些常見 Rust 概念，展示如何在實際程式中使用它們。你會學到 let、match、方法、關聯函式、外部 crate 以及更多等等！我們會在之後的章節更詳細地探討這些概念。在本章中，你會練習到基礎概念。

我們會實作個經典新手程式問題：猜謎遊戲。它的運作方式如下：程式會產生 1 到 100 之間的隨機整數。接著它會通知玩家猜一個數字。在輸入猜測數字之後，程式會回應猜測的數字太低或太高。如果猜對的話，遊戲就會顯示祝賀訊息並關閉。

設置新專案

要設置新專案的話，前往你在第一章建立的 projects 目錄並使用 Cargo 建立一個新的專案，如下所示：

$ cargo new guessing_game
$ cd guessing_game

第一道命令 cargo new 會接收專案名稱（guessing_game）作為引數（argument）。第二道命令會將目錄移至新專案中。

檢查看看產生的 Cargo.toml 檔案：

檔案名稱：Cargo.toml

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"

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

[dependencies]

如同你在第一章看到的，cargo new 會產生一支「Hello, world!」程式。請檢查 src/main.rs 檔案：

檔案名稱：src/main.rs

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

現在讓我們用 cargo run 命令同時完成編譯與執行「Hello, world!」程式：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 1.50s
     Running `target/debug/guessing_game`
Hello, world!

run 命令在你需要對專案快速疊代時會很有用，我們要寫的遊戲也是如此，在繼續下一步之前可以快速測試每一步。

請重新開啟 src/main.rs 檔案。你要寫的程式碼全都會位於此檔案中。

處理猜測

猜謎遊戲的第一個部分會要求使用者輸入數字、處理該輸入，並檢查該輸入是否符合格式。所以我們要先讓玩家能夠輸入猜測數字，請輸入範例 2-1 的程式碼至 src/main.rs。

檔案名稱：src/main.rs

use std::io;

fn main() {
    println!("請猜測一個數字！");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

範例 2-1：取得使用者的猜測數字並顯示出來的程式

這段程式碼包含大量的資訊，所以讓我們一行一行來慢慢看吧。要取得使用者輸入並印出為輸出結果，我們需要將 io 輸入／輸出（input/output）函式庫引入作用域中。 io 函式庫來自標準函式庫（常稱為 std）：

use std::io;

fn main() {
    println!("請猜測一個數字！");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

在預設情況下，Rust 會將一些在標準函式庫定義的型別引入每個程式的作用域中。這樣的集合稱為 prelude，你可以在標準函式庫的技術文件中看到這包含了那些型別。

如果你想使用的型別不在 prelude 的話，你需要顯式（explicit）地使用 use 陳述式（statement）將該型別引入作用域。std::io 函式庫能提供一系列實用的功能，這包含接收使用者輸入的能力。

如同你在第一章所見的，main 函式是程式的入口點（entry point）：

use std::io;

fn main() {
    println!("請猜測一個數字！");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

fn 語法用來宣告新的函式（function），其中括號 () 說明此函式沒有任何參數，然後大括號 { 會作為函式本體的開頭。

同樣如第一章所學的，println! 是個能將字串顯示到螢幕上的巨集：

use std::io;

fn main() {
    println!("請猜測一個數字！");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

此程式碼會顯式提示訊息向使用者說明此遊戲該輸入什麼。

透過變數儲存數值

接著我們要建立一個變數來儲存使用者輸入，如以下所示：

use std::io;

fn main() {
    println!("請猜測一個數字！");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

現在程式變得越來越有趣了！在短短的這行當中有許多事情發生。先注意到我們使用了 let 陳述式建立了一個變數（variable）。以下是另一個例子：

let apples = 5;

這行建立了一個新的變數叫做 apple 並將數值 5 綁定給它。在 Rust 中，變數預設是不可變的（immutable），也就是一旦我們給予變數一個數值，該數值就不會被改變。我們會在第三章的「變數與可變性」段落討論此概念。要讓變數成為可變的話，我們可以在變數名稱前面加上 mut：

let apple = 5; // 不可變的
let mut banana = 5; // 可變的

注意：// 語法用來產生註解（comment）直到該行結束。Rust 會忽略註解中所有內容，我們會在第三章進一步討論到。

讓我們回到猜謎遊戲程式，你現在就知道 let mut guess 會產生一個可變變數叫做 guess。等號（=）告訴 Rust 我們現在想綁定某個值給變數，而等號的另一邊就是要綁定給 guess 的數值，也就是呼叫 String::new 的結果，這是一個回傳新的 String 實例（instance）的函式。String 是個標準函式庫提供的字串型別，這是可增長的 UTF-8 編碼文字。

::new 中的 :: 語法代表 new 是 String 型別的關聯函式。關聯函式（associated function） 是針對型別實作的函式，在此例中就是 String。此 new 函式建立一個新的空字串。你會在許多型別中找到 new 函式，因為這是函式建立某種新數值的常見名稱。

總結來說， let mut guess = String::new(); 這行會建立一個可變變數，且目前會得到一個新的空 String 實例。

取得使用者輸入

回想一下我們在程式第一行透過 use std::io; 來包含標準函式庫中的輸入／輸出功能。現在我們要從 io 模組（module）呼叫 stdin 函式，讓我們能處理使用者的輸入：

use std::io;

fn main() {
    println!("請猜測一個數字！");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

如果我們沒有匯入 io 函式庫，也就是將 use std::io 這行置於程式最一開始的位置的話，我們還是能直接寫出 std::io::stdin 來呼叫函式。stdin 函式會回傳一個 std::io::Stdin 實例，這是代表終端機標準輸入控制代碼（handle）的型別。

接下來 .read_line(&mut guess) 這行會對標準輸入控制代碼呼叫 read_line 方法（method）來取得使用者的輸入。我們還傳遞了 &mut guess 作為引數（argument）給 read_line，來告訴它使用者輸入時該儲存什麼字串。整個 read_line 的任務就是取得使用者在標準輸入寫入的任何內容，並加入到字串中（不會覆寫原有內容），使得我們可以傳遞該字串作為引數。字串引數需要是可變的，這樣該方法才能變更字串的內容。

& 說明此引數是個參考（reference），這讓程式中的多個部分可以取得此資料內容，但不需要每次都得複製資料到記憶體中。參考是個複雜的概念，而 Rust 其中一項主要優勢就是能夠輕鬆又安全地使用參考。你現在還不用知道一堆細節才能完成程式。現在你只需要知道參考和變數一樣，預設都是不可變的。因此你必須寫 &mut guess 而不是 &guess 才能讓它成為可變的。（第四章會再全面詳細解釋參考。）

使用 Result 處理可能的錯誤

我們要繼續處理這段程式碼。我們已經討論到第三行了，不過這仍然是這段單一邏輯程式碼中的一部分。接下來的部分是此方法：

use std::io;

fn main() {
    println!("請猜測一個數字！");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

我們可以將程式碼寫成這樣：

io::stdin().read_line(&mut guess).expect("讀取行數失敗");

但是這麼長通常會很難閱讀，最好還是能夠分段。當你透過 .method_name() 語法呼叫方法時，通常換行來寫並加上縮排，來拆開一串很長的程式碼會比較好閱讀。現在讓我們來討論這行在做什麼。

如稍早提過的，read_line 會將使用者任何輸入轉換至我們傳入的字串，但它還回傳了一個 Result 數值。Result 是種列舉（enumerations），常稱為 enums。列舉是種可能有數種狀態其中之一的型別，而每種可能的狀態我們稱之為列舉的變體（variants）。

第六章會更詳細地介紹列舉，這些 Result 型別的目的是要編碼錯誤處理資訊。

Result 的變體有 Ok 和 Err。Ok 變體指的是該動作成功完成，且 Ok 內部會包含成功產生的數值。而 Err 變體代表動作失敗，且 Err 會包含該動作如何與為何會失敗的資訊。

Result 型別的數值與任何型別的數值一樣，它們都有定義些方法。Result 的實例有 expect 方法 讓你能呼叫。如果此 Result 實例數值為 Err 的話，expect 會讓程式崩潰並顯示作為引數傳給 expect 的訊息。如果 read_line 回傳 Err 的話，這可能就是從底層作業系統傳來的錯誤結果。如果此 io::Result 實例數值為 Ok 的話，expect 會接收 Ok 的回傳值並只回傳該數值，讓你可以使用。在此例中，數值將為使用者輸入進標準輸入介面的位元組數字。

如果你沒有呼叫 expect，程式仍能編譯，但你會收到一個警告：

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

warning: `guessing_game` (bin "guessing_game") generated 1 warning
    Finished dev [unoptimized + debuginfo] target(s) in 0.59s

Rust 警告你沒有使用 read_line 回傳的 Result 數值，這意味著程式沒有處理可能發生的錯誤。

要解決此警告的正確方式是實際進行錯誤處理，但因為我們只想要當問題發生時直接讓程式當掉，所以你可以先使用 expect 就好。你會在第九章學到如何從錯誤中恢復。

透過 println! 佔位符印出數值

在結束大括號之前，目前程式碼中還有一行要來討論：

use std::io;

fn main() {
    println!("請猜測一個數字！");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

此行會印出存有使用者輸入的字串。其中的大括號 {} 是個佔位符（placeholder）：將 {} 想成是個小蟹鉗會夾住某個數值。當要印出變數的數值時，變數名稱可以放進括號內。當要印出表達式運算出的結果時，則先將空括號放進要格式化的字串，然後在字串後用逗號以相同的順序列出要印出的表達式列表。用 println! 同時印出變數與表達式結果的話會如以下所示：

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

println!("x = {x} 而且 y + 2 = {}", y + 2);
}

此程式碼會印出 x = 5 而且 y = 12。

測試第一個部分

讓我們來測試猜謎遊戲中的第一個部分。請使用 cargo run 來執行它：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 6.44s
     Running `target/debug/guessing_game`
請猜測一個數字！
請輸入你的猜測數字。
6
你的猜測數字：6

到目前為止，遊戲的第一個部分就完成了：我們取得了鍵盤的輸入然後顯示出來。

產生祕密數字

接下來，我們要產生一個能讓使用者猜看看的祕密數字。祕密數字每次都要不同，這樣遊戲才值得多玩幾次。讓我們使用 1 到 100 之間的隨機數字，這樣遊戲才不會太困難。Rust 的標準函式庫並不包含產生隨機數字的功能。然而，Rust 團隊有提供個 rand crate。

使用 Crate 來取得更多功能

所謂的 crate 是一個 Rust 原始碼檔案的集合。我們正在寫的專案屬於執行檔（binary）crate，也就會是個執行檔。而 rand crate 屬於函式庫（library）crate，這會包含讓其他程式能夠使用的程式碼。

Cargo 協調外部 crate 的功能正是它的亮點。在我們可以使用 rand 來寫程式碼前，我們需要修改 Cargo.toml 檔案來包含 rand crate 作為依賴函式庫（dependency）。開啟該檔案然後將以下行數加到 Cargo 自動產生的 [dependencies] 標頭（header）段落中最後一行下面。記得確認 rand 指定的版本數字與我們相同，不然此教學的範例程式碼可能不會運行成功：

檔案名稱：Cargo.toml

[dependencies]
rand = "0.8.5"

在 Cargo.toml 檔案中，標頭以下的所有內容都是該段落的一部分，一直到下個段落出現為止。[dependencies] 段落是告訴 Cargo 此專案要依賴哪些 crate，以及那些 crate 的版本為何。在此例中，我們透過語意化版本 0.8.5 來指定 rand crate。Cargo 能夠理解語意化版本（Semantic Versioning），有時也被稱之為 SemVer，這是一種定義版本數字的標準。數字 0.8.5 其實是 ^0.8.5 的縮寫，這代表任何至少爲 0.8.5 且低於 0.9.0 版本。

Cargo 將這些版本提供的公開 API 視爲是與版本 0.8.5 相容的，這樣的規格讓你能在本章節取得最新的 patch 發佈版本程式碼。任何 0.9.0 以上的版本就不會保證提供以下範例所使用的相同 API。

現在，在不改變任何程式碼的情況下，讓我們建構（build）專案吧，如範例 2-2 所示。

$ cargo build
    Updating crates.io index
  Downloaded rand v0.8.5
  Downloaded libc v0.2.127
  Downloaded getrandom v0.2.7
  Downloaded cfg-if v1.0.0
  Downloaded ppv-lite86 v0.2.16
  Downloaded rand_chacha v0.3.1
  Downloaded rand_core v0.6.3
   Compiling libc v0.2.127
   Compiling getrandom v0.2.7
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.16
   Compiling rand_core v0.6.3
   Compiling rand_chacha v0.3.1
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 2.53s

範例 2-2：在新增 rand crate 作為依賴後，執行 cargo build 的輸出

你可能會看到不同的版本數字（但多虧有 SemVer，它們都會與程式碼相容！）和不同的行數（依照作業系統可能會不同）以及每行順序可能會不相同。

當我們匯入了外部依賴，Cargo 會從 registry 取得所有 crate 的最新版本訊息，這是份 Crates.io 的資料副本。Crates.io 是個讓 Rust 生態系統中的每個人都能發佈它們的開源 Rust 專案並讓其他人使用的地方。

在更新 registry 之後，Cargo 會檢查 [dependencies] 段落並下載你還沒有的 crate。在此例中，雖然我們只有列出 rand 作為依賴，但 Cargo 還得下載 rand 所依賴的其他 crate 才能運作。在下載完 crates 之後，Rust 會編譯依賴函式庫以及使用到它們的專案。

如果你立即再次執行 cargo build 且沒有作出任何改變的話，你除了 Finished 這行以外不會在收到任何輸出。Cargo 知道它已經下載並編譯依賴函式庫了，而且你沒有在 Cargo.toml 檔案中再做任何改變。Cargo 也知道你沒有修改任何程式碼，所以也不會再重新編譯它。既然沒事可做，它就只好馬上結束。

如果你開啟 src/main.rs 檔案，加些瑣碎的修改，然後儲存並再次建構的話，你會只看到兩行輸出：

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

這幾行表示 Cargo 只更新你對 src/main.rs 檔案的瑣碎修改進行建構。你的依賴沒變，所以 Cargo 知道它可以重複使用已經下載並編譯過的程式碼。

透過 Cargo.lock 檔案確保建構可以重現

Cargo 有個機制能確保任何人或你在任何時候重新建構程式碼時，都能產生相同結果。舉例來說，要是下一週 rand crate 發佈了版本 0.8.6 且該版本包含重大程式錯誤更新，卻也有個會破壞你的程式碼的迴歸錯誤（regression），這時會發生什麼事呢？為了處理這樣的狀況，Rust 會在你第一次執行 cargo build 時建立個 Cargo.lock 檔案，它會位於 guessing_game 目錄中。

當你第一次建構專案時，Cargo 會決定出符合情境的依賴函式庫版本，然後將它們寫入 Cargo.lock 檔案中。當你在未來建構專案時，Cargo 會看到 Cargo.lock 的存在並使用其指定的版本，而非重新再次決定該用哪些版本。這讓你有個能自動重現的建構方案。換句話說，你的專案仍會繼續使用 0.8.5 直到你顯式升級為止，這都多虧了 Cargo.lock 檔案。由於 Cargo.lock 對於重現建構非常重要，所以通常它會和其他程式碼一同上傳到專案的版本控制源頭。

升級 Crate 來取得新版本

當你真的想升級 crate 時，Cargo 有提供個命令 update，這會忽略 Cargo.lock 檔案並依據 Cargo.toml 指定的規格決定所有合適的最新版本。如果成功的話，Cargo 會將這些版本寫入 Cargo.lock 檔案中。不然的話，Cargo 預設只會尋找大於 0.8.5 且小於 0.9.0 的版本。如果 rand 有發佈兩個新版本 0.8.6 和 0.9.0，當你輸入 cargo update 時，你會看到以下結果：

$ cargo update
    Updating crates.io index
    Updating rand v0.8.5 -> v0.8.6

Cargo 會忽略 0.9.0 的發布版本。此時你也會注意到 Cargo.lock 檔案中的變更，指出你現在使用的 rand crate 版本為 0.8.6。如果你想使用 rand 版本 0.9.0 或任何版本 0.9.x 系列更新 Cargo.toml 檔案，如以下所示：

[dependencies]
rand = "0.9.0"

下次你執行 cargo build 時，Cargo 將會更新 crate registry，並依據你指定的新版本來重新評估 rand 的確切版本。

Cargo 與其生態系統還有很多內容可以介紹，我們會在第十四章討論它們。但現在你只需要知道這些就好。Cargo 讓重複使用函式庫變得非常容易，讓 Rustaceans 可以組合許多套件寫出簡潔的專案。

產生隨機數字

讓我們開始使用 rand 產生數字來猜吧！下一步是更新 src/main.rs，如範例 2-3 所示。

檔案名稱：src/main.rs

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

fn main() {
    println!("請猜測一個數字！");

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

    println!("祕密數字為：{secret_number}");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

範例 2-3：新增程式碼來產生隨機數字

首先我們加上 use 這行：use rand::Rng;。Rng 特徵（trait）定義了隨機數字產生器實作的方法，所以此特徵必須引入作用域，我們才能使用這些方法。第十章會詳細解釋特徵。

接著，我們在中間加上兩行。我們在第一行呼叫的 rand::thread_rng 函式會回傳我們要使用的特定隨機數字產生器：這會位於目前執行緒（thread）並由作業系統提供種子（seed）。然後我們對隨機數字產生器呼叫 gen_range 方法。此方法由 Rng 特徵所定義，而我們則是用 use rand::Rng; 陳述式將此特徵引入作用域中。gen_range 方法接收一個範圍表達式作為引數並產生一個在此範圍之間的隨機數字。我們所使用的範圍表達式的格式爲 start..=end。這個範圍會包含下限和上限，所以我們需要指定 1..=100 來索取 1 到 100 之間的數字。

注意：你不可能憑空就知道該使用 crate 中的哪些特徵或是呼叫哪些方法與函式，所以每個 crate 都會提供技術文件解釋如何使用它。Cargo 另一大亮點就是執行 cargo doc --open 命令就能建構所有本地端依賴函式庫的技術文件，並在你的瀏覽器中開啟。舉例來說，如果你對 rand crate 的其他功能有興趣的話，你可以執行 cargo doc --open 然後點擊左側邊欄的 rand。

第二行會印出祕密數字，這在開發程式時能用來作測試，不過在最終版本我們會刪除它。如果在遊戲一開始程式就印出答案的話跟本就沒有玩的必要了！

請嘗試執行程式幾次：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 2.53s
     Running `target/debug/guessing_game`
請猜測一個數字！
祕密數字為：7
請輸入你的猜測數字。
4
你的猜測數字：4

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
請猜測一個數字！
祕密數字為：83
請輸入你的猜測數字。
5
你的猜測數字：5

你應該會得到不同的隨機數字，而且它們都應該要在 1 到 100 的範圍內。做得好！

將猜測的數字與祕密數字做比較

現在我們有使用者的輸入與隨機數字，我們可以來比較它們了。這步驟顯示在範例 2-4。注意此程式碼還無法編譯，我們會解釋為什麼。

檔案名稱：src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    // --省略--
    println!("請猜測一個數字！");

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

    println!("祕密數字為：{secret_number}");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("太小了！"),
        Ordering::Greater => println!("太大了！"),
        Ordering::Equal => println!("獲勝！"),
    }
}

範例 2-4：處理比較兩個數字後的可能數值

首先我們加上另一個 use 陳述式，這將 std::cmp::Ordering 型別從標準函式庫引入作用域中。Ordering 是另一個列舉，擁有的變體為 Less、Greater 與 Equal。這些是當你比較兩個數值時的三種可能結果。

然後我們在底下加上五行程式碼來使用 Ordering 型別。cmp 方法會比較兩個數值，並能在任何可以比較的數值中進行呼叫。其參考一個任何你想做比較的數值，在此例中就是將 guess 與 secret_number 做比較。然後它會回傳我們透過 use 陳述式引入作用域的 Ordering 列舉其中一個變體。我們使用 match 表達式來依據透過 guess 與 secret_number 呼叫 cmp 回傳的 Ordering 變體來決定下一步要做什麼。

match 表達式由分支（arms）所組成。分支包含一個能被配對的模式（pattern）以及對應的程式碼，這在當 match 的數值能與該分支的模式配對時就能執行。Rust 會用 match 得到的數值依序遍歷每個分支中的模式。match 結構與模式是 Rust 中非常強大的特色，能讓你表達各種程式碼可能會遇上的情形，並確保你有將它們全部處理完。這些特色功能會在第六章與第十八章分別討論其細節。

讓我們看看在此例中使用的 match 表達式。假設使用者猜測的數字是 50 而這次隨機產生的祕密數字是 38。

當程式碼比較 50 與 38 時，cmp 方法會回傳 Ordering::Greater，因為 50 大於 38。match 表達式會取得 Ordering::Greater 數值並開始檢查每個分支的模式。它會先查看第一個分支的模式 Ordering::Less 並看出數值 Ordering::Greater 無法與 Ordering::Less 配對，所以它忽略該分支的程式碼，並移到下一個分支。而下個分支的模式 Ordering::Greater 能配對到 Ordering::Greater！所以該分支對應的程式碼就會執行並印出 太大了！ 到螢幕上。最後 match 表達式就會在第一次成功配對就結束，所以在此情境中它不需要再查看最後一個分支。

然而範例 2-4 的程式碼還無法編譯，讓我們嘗試看看：

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
error[E0308]: mismatched types
   --> src/main.rs:26:21
    |
26  |     match guess.cmp(&secret_number) {
    |                 --- ^^^^^^^^^^^^^^ expected struct `String`, found integer
    |                 |
    |                 arguments to this function are incorrect
    |
    = note: expected reference `&String`
               found reference `&{integer}`
note: associated function defined here

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

錯誤的關鍵表示型別無法配對（mismatched types）。Rust 有個強力的靜態型別系統，但它也提供了型別推斷。當我們寫 let mut guess = String::new() 時，Rust 能夠推斷出 guess 應該要是 String 讓我們不必親自寫出型別。另一方面，secret_number 則是個數字型別。以下是一些在 Rust 中可以包含數字 1 到 100 的數字型別：32 位元數字 i32、非帶號（unsigned）32 位元數字 u32、64 位元數字 i64，以及更多等等。Rust 預設的數字型別為 i32，這就是 secret_number 的型別，除非你特地加上型別詮釋，Rust 才會推斷成不同的數字型別。此錯誤原因是因為 Rust 無法比較將字串與數字型別做比較。

所以我們要將程式從輸入讀取的 String 轉換成真正的數字型別，讓我們可以將其與祕密數字做比較。我們可以在 main 函式本體加上另一行程式碼：

檔案名稱：src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("請猜測一個數字！");

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

    println!("祕密數字為：{secret_number}");

    println!("請輸入你的猜測數字。");

    // --省略--

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    let guess: u32 = guess.trim().parse().expect("請輸入一個數字！");

    println!("你的猜測數字：{guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("太小了！"),
        Ordering::Greater => println!("太大了！"),
        Ordering::Equal => println!("獲勝！"),
    }
}

這行程式碼就是：

let guess: u32 = guess.trim().parse().expect("請輸入一個數字！");

我們建立了一個變數叫做 guess。小等一下，程式不是已經有個變數叫做 guess了嗎？的確是的，但 Rust 允許我們遮蔽之前的 guess 數值成新的數值。遮蔽（Shadowing）讓我們可以重複使用 guess 變數名稱，而不必強迫我們得建立兩個不同的變數，舉例來說像是 guess_str 和 guess。我們會在第三章更詳細地解釋此概念，現在這邊只需要知道這常拿來將一個數值的型別轉換成另一個型別。

我們將此新的變數綁定給 guess.trim().parse() 表達式。表達式中的 guess 指的是原本儲存字串輸入的 guess。String 中的 trim 方法會去除開頭與結尾的任何空白字元，我們一定要這樣做才能將字串與 u32 作比較，因為它只會包含數字字元。使用者一定得按下 enter 才能滿足 read_line 並輸入他們的猜測數字，這樣會加上一個換行字元。當使用者按下 enter 時，字串結尾就會加上換行字元。舉例來說，如果使用者輸入 5 並按下 enter 的話，guess 看起來會像這樣：5\n。\n 指的是「換行（newline）」，這是按下 enter 的結果（在 Windows 按下 enter 的結果會是輸入和換行 \r\n）。trim 方法能去除 \n 或 \r\n，讓結果只會是 5。

而字串中的 parse 方法會轉換字串成其他型別。我們在此用它將字串轉換成數字，我們需要使用 let guess: u32 來告訴 Rust 我們想使用的確切數字型別。guess 後面的分號（:）告訴 Rust 我們會詮釋此變數的型別。Rust 有些內建的數字型別，這裡的 u32 是個非帶號（unsigned）的 32 位元整數。對於不大的正整數來說，這是不錯的預設選擇。你會在第三章學到其他數字型別。

除此之外，在此範例程式中的 u32 詮釋與 secret_number 的比較意味著 Rust 也會將 secret_number 推斷成 u32。所以現在會有兩個相同型別的數值能做比較了！

parse 的呼叫很容易造成錯誤，因為它只適用於邏輯上能轉換成數字的字元。舉例來說，如果字串包含 A👍% 的話，就不可能轉換成數字。因為它可能會失敗，parse 方法回傳的是 Result 型別，就和 read_line 方法一樣（在之前的「使用 Result 處理可能的錯誤」段落提及）。我們也會用相同的方式來處理此 Result，也就是呼叫 expect 方法。如果 parse 回傳 Result 的 Err 變體的話，由於它無法從字串建立數字，expect 的呼叫會讓遊戲當掉並顯示我們給予的訊息。如果 parse 能成功將字串轉成數字，它將會回傳 Result 的 Ok 變體，而 expect 將會回傳 Ok 的內部數值。

現在讓我們執行程式：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 0.43s
     Running `target/debug/guessing_game`
請猜測一個數字！
祕密數字為：58
請輸入你的猜測數字。
  76
你的猜測數字：76
太大了！

不錯！儘管我們在猜測數字前加了一些空格，但程式仍能推斷出使用者猜測的是 76。多執行程式幾次來驗證不同種輸入產生的不同行為：像是正確猜出數字、猜測的數字太高或猜測的數字太低。

我們已經大致上將遊戲完成了，但使用者只能猜測一次。讓我們用迴圈來修改吧！

透過迴圈來允許多次猜測

loop 關鍵字會產生無限迴圈。我們加入此迴圈讓使用者可能有更多機會可以猜測：

檔案名稱：src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("請猜測一個數字！");

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

    // --省略--

    println!("祕密數字為：{secret_number}");

    loop {
        println!("請輸入你的猜測數字。");

        // --省略--


        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("讀取該行失敗");

        let guess: u32 = guess.trim().parse().expect("請輸入一個數字！");

        println!("你的猜測數字：{guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("太小了！"),
            Ordering::Greater => println!("太大了！"),
            Ordering::Equal => println!("獲勝！"),
        }
    }
}

如同你所見，我們將輸入猜測提示以下的程式碼都移入迴圈中。請確保迴圈中的每一行有用四個空格來做縮排，然後再次執行程式。現在程式會不停地尋問要猜測的數字了！但這樣帶來了新的問題，看來使用者無法離開遊戲！

使用者的確永遠可以使用快捷鍵 ctrl-c 來中斷程式。但還有其他辦法能逃離這個無限循環，如同在「將猜測的數字與祕密數字做比較」中討論 parse 時提到的，如果使用者輸入非數字答案的話，程式就會當掉。我們可以利用此特性來讓使用者離開，如以下所示：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 1.50s
     Running `target/debug/guessing_game`
請猜測一個數字！
祕密數字為：59
請輸入你的猜測數字。
45
你的猜測數字：45
太小了！
請輸入你的猜測數字。
60
你的猜測數字：60
太大了！
請輸入你的猜測數字。
59
你的猜測數字：59
獲勝！
請輸入你的猜測數字。
quit
thread 'main' panicked at '請輸入一個數字！: ParseIntError { kind: InvalidDigit }', src/main.rs:28:47
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

輸入 quit 就能離開遊戲，但是你會看到其他非數字輸入也是如此。這並不是最理想的方案，我們想要在猜對數字時自動停止。

猜對後離開

讓我們加上 break 陳述式來在使用者獲勝時離開遊戲：

檔案名稱：src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("請猜測一個數字！");

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

    println!("祕密數字為：{secret_number}");

    loop {
        println!("請輸入你的猜測數字。");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("讀取該行失敗");

        let guess: u32 = guess.trim().parse().expect("請輸入一個數字！");

        println!("你的猜測數字：{guess}");

        // --省略--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("太小了！"),
            Ordering::Greater => println!("太大了！"),
            Ordering::Equal => {
                println!("獲勝！");
                break;
            }
        }
    }
}

在 獲勝！ 之後加上 break 這行讓程式在使用者猜對祕密數字時可以離開迴圈。離開迴圈也意味著離開程式，因為此迴圈是 main 中的最後一個部分。

處理無效輸入

為了進一步改善遊戲體驗，當使用者的輸入不是數字時，我們不該讓程式直接當掉。遊戲程式可以忽略非數字來讓使用者繼續猜測。我們可以修改 guess 這段將 String 轉換成 u32 的程式碼，如範例 2-5 所示。

檔案名稱：src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("請猜測一個數字！");

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

    println!("祕密數字為：{secret_number}");

    loop {
        println!("請輸入你的猜測數字。");

        let mut guess = String::new();

        // --省略--

        io::stdin()
            .read_line(&mut guess)
            .expect("讀取該行失敗");

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

        println!("你的猜測數字：{guess}");

        // --省略--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("太小了！"),
            Ordering::Greater => println!("太大了！"),
            Ordering::Equal => {
                println!("獲勝！");
                break;
            }
        }
    }
}

範例 2-5：忽略非數字的猜測並要求下一個猜測數字，而不是讓程式當掉

我們將 expect 的呼叫換成 match 表達式，從錯誤中當掉改成實際處理錯誤。你應該還記得 parse 回傳的是 Result 型別，且 Result 是個列舉，其變體為 Ok 與 Err。我們在此使用 match 表達式，如同我們對 cmp 方法回傳的 Ordering 處理方式一樣。

如果 parse 能成功將字串轉換成數字，它會回傳 Ok 數值內包含的結果數字。該 Ok 數值就會配對到第一個分支的模式，然後 match 表達式就會回傳 parse 產生並填入 Ok 內的 num 數值。該數字最後就會如我們所願變成我們建立的 guess 變數。

如果 parse 無法將字串轉換成數值的話，它會回傳包含與錯誤相關資訊的 Err 數值。該 Err 數值並不符合 match 的第一個分支模式 Ok(num)，但它能配對到第二個分支。底線 _ 是個捕獲數值，在此例中，我們說我們想要配對到所有的 Err 數值，無論其中有什麼資訊在裡面。所以程式會執行第二條分支 continue，這告訴程式繼續 loop 下一個疊代並要求其他猜測數字。如此一來程式就能忽略所有 parse 可能會遇到的所有錯誤！

現在程式的每個部分都如我們所預期的了，讓我們試試看：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
   Finished dev [unoptimized + debuginfo] target(s) in 4.45s
     Running `target/debug/guessing_game`
請猜測一個數字！
祕密數字為：61
請輸入你的猜測數字。
10
你的猜測數字：10
太小了！
請輸入你的猜測數字。
99
你的猜測數字：99
太大了！
請輸入你的猜測數字。
foo
請輸入你的猜測數字。
61
你的猜測數字：61
獲勝！

太棒了！有了最後一項小修改，我們終於完成了猜謎遊戲。回想一下程式仍然會印出祕密數字。這在測試很有用，但在實際遊戲時就毀了樂趣了。讓我們刪除會印出祕密數字的 println!。範例 2-6 就是最終的程式碼。

檔案名稱：src/main.rs

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("請猜測一個數字！");

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

    loop {
        println!("請輸入你的猜測數字。");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("讀取該行失敗");

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

        println!("你的猜測數字：{guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("太小了！"),
            Ordering::Greater => println!("太大了！"),
            Ordering::Equal => {
                println!("獲勝！");
                break;
            }
        }
    }
}

範例 2-6：完整的猜謎遊戲程式碼

此時此刻，你已經完成了猜謎遊戲。恭喜你！

總結

此專案讓你能動手實踐並親自體驗許多 Rust 的新概念：let、match、函式、外部 crate 的使用以及更多等等。在接下來陸續的章節，你將深入學習這些概念。第三章會涵蓋多數程式設計語言都有的概念，像是變數、資料型別與函式，以及如何在 Rust 中使用它們。第四章會探索所有權（ownership），這是 Rust 與其他語言最不同的特色。第五章會討論結構體（structs）與方法語法，而第六章會解釋列舉。

常見程式設計概念

此章節涵蓋了幾乎所有程式語言都會出現的概念，以及如何在 Rust 使用。許多程式語言的核心概念都是相同的，所以此章節所介紹的概念也不是 Rust 所特有的。不過我們會用 Rust 的程式碼來討論它們，並解釋使用這些概念的慣例。

更明確來說，你將會學習到變數、基本型別、註解以及控制流程。這些基本概念會出現在每個 Rust 程式中，所以提早學習這些概念可以為你打下穩健的基礎。

關鍵字（Keywords）

Rust 程式語言和其他語言一樣會保留一系列的關鍵字（keywords）。請注意你將無法用這些字作為變數或函式名稱。大多數關鍵字都有特別意義，而你將會在你的 Rust 程式使用它們來處理不同的任務；而有一些目前則還沒有任何用途，但是在未來可能會被 Rust 加入所以作為保留。你可以在附錄 A 查看關鍵字列表。

變數與可變性

如同「透過變數儲存數值」提到的，變數預設是不可變的。這是 Rust 推動你能充分利用 Rust 提供的安全性和簡易並行性來寫程式的許多方法之一。不過，你還是有辦法能讓你的變數成為可變的。讓我們來探討為何 Rust 鼓勵你多多使用不可變，以及何時你會想要改為可變的。

當一個變數是不可變的，只要有數值綁定在一個名字上，你就無法改變其值。為了方便說明，讓我們使用 cargo new variables 在 projects 目錄下產生一個新專案叫做 variables。

再來在你的 variables 目錄下開啟 src/main.rs 然後覆蓋程式碼為以下內容。這是段還無法編譯的程式碼：

檔案名稱：src/main.rs

fn main() {
    let x = 5;
    println!("x 的數值為：{x}");
    x = 6;
    println!("x 的數值為：{x}");
}

儲存然後使用 cargo run 執行程式。你應該會收到一則有關於不可變的錯誤訊息，如下所示：

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0384]: cannot assign twice to immutable variable `x`
 --> src/main.rs:4:5
  |
2 |     let x = 5;
  |         -
  |         |
  |         first assignment to `x`
  |         help: consider making this binding mutable: `mut x`
3 |     println!("x 的數值為：{x}");
4 |     x = 6;
  |     ^^^^^ cannot assign twice to immutable variable

For more information about this error, try `rustc --explain E0384`.
error: could not compile `variables` due to previous error

此範例顯示了編譯器如何協助你找到你程式碼的錯誤。雖然看到編譯器錯誤訊息總是令人感到沮喪，但這通常是為了讓你知道你的程式無法安全地完成你想讓它完成的任務。它們不代表你不是個優秀的程式設計師！有經驗的 Rustaceans 時常會與編譯器錯誤訊息打交道。

你得到的錯誤訊息說明「cannot assign twice to immutable variable x」，因為你嘗試第二次賦值給 x 變數。

當我們嘗試改變一個原先設計為不可變的變數時，能夠產生編譯時錯誤是很重要的。因為這樣的情況很容易導致程式錯誤。如果我們有一部分的程式碼在執行時認為某個數值絕對不會改變，但另一部分的程式碼卻更改了其值，那麼這就有可能讓前一部分的程式碼就可能以無法預測的方式運行。這樣的程式錯誤的起因是很難追蹤的，尤其是當第二部分的程式碼偶而才會改變其值。Rust 編譯器會保證當你宣告一個數值不會被改變時，它就絕對不會被改變。這樣你就不需要去追蹤該值可能會被改變，讓你的程式碼更容易推導。

但同時可變性也是非常有用的，能讓程式碼變得更好寫。雖然變數預設是不可變的，但就如同第二章一樣你可以在變數名稱前面加上 mut 讓它們可以成為可變的。加上 mut 也向未來的讀取者表明了其他部分的程式碼將會改變此變數的數值。

舉例來說，讓我們改變 src/main.rs 成以下程式碼：

檔案內容：src/main.rs

fn main() {
    let mut x = 5;
    println!("x 的數值為：{x}");
    x = 6;
    println!("x 的數值為：{x}");
}

當你執行程式的話，我們會得到：

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished dev [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/variables`
x 的數值為：5
x 的數值為：6

當使用 mut 時，我們可以將 x 的數值從 5 改變為 6。何時使用可變性的決定權在你手上，你可以依照特定場合做出你認為最佳的選擇。

常數

常數（constants）。和不可變變數一樣，常數會讓數值與名稱綁定且不允許被改變，但是不可變變數與常數還是有些差異。

首先，你無法在使用常數使用 mut，常數不是預設不可變，它們永遠都不可變。如果你使用 const 宣告而非 let 的話，你必須指明型別。我們會在下一章「資料型別」詳細解釋型別與型別詮釋，所以現在先別擔心細節。你只需要先知道你永遠必須先詮釋常數的型別。

常數可以被定義在任一有效範圍，包含全域有效範圍。這讓它們非常有用，讓許多部分的程式碼都能夠知道它們。

最後一個差別是常數只能被常數表達式設置，而不能用任一在運行時產生的其他數值設置。

以下為一個常數名稱的範例：

#![allow(unused)]
fn main() {
const THREE_HOURS_IN_SECONDS: u32 = 60 * 60 * 3;
}

變數的名稱為 THREE_HOURS_IN_SECONDS ，且它的數值被設為 60（一分鐘有多少秒）乘上 60（一小時有多少分鐘）乘上 3（此程式想要計算的小時數量）。Rust 的常數命名規則為使用全部英文大寫並用底寫區隔每個單字。編譯器能夠在編譯時用特定限制集合內的操作進行運算，讓我們能用易於理解且驗證的方式寫出此數值，而不用將常數設爲 10,800。你可以查閱 Rust Reference 的 constant evaluation 段落來瞭解哪些操作可以在宣告常數時使用。

在整支程式運行時，常數在它們的範圍內都是有效的。這樣的性質讓常數在處理應用程式中需要被許多程式碼部份所知道的數值的情況下是非常好的選擇，像是一款遊戲中玩家能夠得到的最高分數或者光速的數值。

將會擴散到所有程式碼的數值定義為常數，對於幫助未來程式碼的維護者理解是非常好的選擇。這也讓未來需要更新數值的話，你知道需要修改寫死的地方就好。

遮蔽（Shadowing）

如同你在猜謎遊戲教學所看到的，在第二章你可以用之前的變數再次宣告新的變數。Rustaceans 會說第一個變數被第二個變數所遮蔽了，這代表當你使用該變數名稱時，編譯器會看到的是第二個變數的數值。第二個變數會遮蔽第一個變數，佔據變數名稱的使用權，直到它自己也被遮蔽或是離開作用域。我們可以用 let 關鍵字來重複宣告相同的變數名稱來遮蔽一個變數：

檔案名稱：src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

    {
        let x = x * 2;
        println!("x 在內部範圍的數值為：{x}");
    }

    println!("x 的數值為：{x}");
}

此程式首先將 x 給予 5，然後它重複用 let x = 建立一個新變數 x，取代了原本的數值並加上 1，所以 x 的數值變為 6。然後在接下來括號的內部範圍內，第三次的 let 陳述式一樣遮蔽了 x 讓它將原本的值乘與 2，讓 x 數值為 12。當該範圍結束時，內部的遮蔽也結束，所以 x 就回到原本的 6。當我們運行此程式時，就會輸出以下結果：

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished dev [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/variables`
x 在內部範圍的數值為：12
x 的數值為：6

遮蔽與標記變數為 mut 是不一樣的，因為如果我們不小心重新賦值而沒有加上 let 關鍵字的話，是會產生編譯期錯誤的。使用 let 的話，我們可以作出一些改變，然後在這之後該變數仍然是不可變的。

另一個 mut 與遮蔽不同的地方是，我們能有效地再次運用 let 產生新的變數，可以在重新運用相同名稱時改變它的型別。舉例來說，當我們希望程式要求使用者顯示出字串間應該顯示多少空格，同時我們又希望它被存為一個數字時，我們可以這樣做：

fn main() {
    let spaces = "   ";
    let spaces = spaces.len();
}

第一次宣告 spaces 的變數是一個字串型別，而第二次宣告 spaces 則成了數字型別。遮蔽這項功能讓我們不必去宣告像是 spaces_str 與 spaces_num，我們可以重複使用 spaces 這個變數名稱。不過，可變變數仍然是無法變更變數型別的，如果這樣做的話我們就會拿到編譯期錯誤：

fn main() {
    let mut spaces = "   ";
    spaces = spaces.len();
}

此錯誤訊息告訴我們我們不允許改變變數的型別：

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0308]: mismatched types
 --> src/main.rs:3:14
  |
2 |     let mut spaces = "   ";
  |                      ----- expected due to this value
3 |     spaces = spaces.len();
  |              ^^^^^^^^^^^^ expected `&str`, found `usize`

For more information about this error, try `rustc --explain E0308`.
error: could not compile `variables` due to previous error

現在我們講完變數了，讓我們看看它們可以擁有的資料型別吧。

資料型別

每個數值在 Rust 中都屬於某種資料型別，這告訴 Rust 何種資料被指定，好讓它能妥善處理資料。我們將討論兩種資料型別子集：純量（scalar）與複合（compound）。

請記住 Rust 是一門靜態型別語言，這代表它必須在編譯時知道所有變數的型別。編譯器通常能依據數值與我們使用的方式推導出我們想使用的型別。但有時候如果多種型別都有可能時，像是第二章的「將猜測的數字與祕密數字做比較」用到的 parse 將 String 轉換成數字時，我們就需要像這樣加上型別詮釋：

#![allow(unused)]
fn main() {
let guess: u32 = "42".parse().expect("這不是數字！");
}

如果我們沒有像上列程式碼這樣加上型別詮釋 : u32 的話，Rust 將會顯示以下錯誤訊息。這表示編譯器需要我們給予更多資訊才能夠知道我們想用何種型別：

$ cargo build
   Compiling no_type_annotations v0.1.0 (file:///projects/no_type_annotations)
error[E0282]: type annotations needed
 --> src/main.rs:2:9
  |
2 |     let guess = "42".parse().expect("這不是數字！");
  |         ^^^^^
  |
help: consider giving `guess` an explicit type
  |
2 |     let guess: _ = "42".parse().expect("這不是數字！");
  |              +++

For more information about this error, try `rustc --explain E0282`.
error: could not compile `no_type_annotations` due to previous error

你將會看到其他資料型別的各種型別詮釋。

純量型別

純量型別代表單一數值。Rust 有四種主要純量型別：整數、浮點數、布林以及字元。你應該在其他程式語言就看過它們了，讓我們來看看它們在 Rust 是怎麼使用的：

整數型別

整數是沒有小數點的數字。我們在第二章用到了一個整數型別 u32，此型別表示其擁有的數值應該是一個佔 32 位元大小的非帶號整數（帶號整數的話則是用 i 起頭而非 u）。表格 3-1 展示了 Rust 中內建的整數型別。我們可以使用以下任何一種型別來宣告一個整數數值。

表格 3-1：Rust 中的整數型別

每個變體都可以是帶號或非帶號的，並且都有明確的大小。帶號與非帶號的區別是數字能不能有負數，換句話說就是數字能否帶有正負符號，如果沒有的話那就只會出現正整數而已。就像在紙上寫數字一樣：當我們需要考慮符號時，我們就會在數字前面加上正負號；但如果我們只在意正整數的話，那它可以不帶符號。帶號數字是以二補數的方式儲存。

每一帶號變體可以儲存的數字範圍包含從 -(2^{n - 1}) 到 2^{n - 1} - 1 以內的數字，n 就是該變體佔用的位元大小。所以一個 i8 可以儲存的數字範圍就是從 -(2⁷) 到 2⁷ - 1，也就是 -128 到 127。而非帶號可以儲存的數字範圍則是從 0 到 2ⁿ - 1，所以 u8 可以儲存的範圍是從 0 到 2⁸ - 1，也就是 0 到 255。

另外，isize 與 usize 型別則是依據你程式運行的電腦架構來決定大小，所以上方表格才用「系統架構」來表示長度：如果你在 64 位元架構上的話就是 64 位元；如果你是 32 位元架構的話就是 32 位元。

你可以用表格 3-2 列的格式來寫出整數字面值（literals）。能適用於數種數字型別的數字字面值都允許在最後面加上型別，比如說用 57u8 來指定型別。數字字面值也可以加上底線 _ 分隔方便閱讀，比如說 1_000 其實就和指定 1000 的數值一樣。

表格 3-2：Rust 中的整數字面值

所以你該用哪些整數型別呢？如果你不確定的話，Rust 預設的型別是很好的起始點：整數型別預設是 i32。而你會用到 isize 或 usize 的主要時機是作為某些集合的索引。

整數溢位

假設你有個變數型別是 u8 可以儲存 0 到 255 的數值。如果你想要改變變數的值超出這個範圍的話，比方說像是 256，那麼就會發生整數溢位，這會產生兩種不同的結果。如果你是在除錯模式編譯的話，Rust 會包含整數溢位的檢查，造成你的程式在執行時恐慌（panic）。Rust 使用恐慌來表示程式因錯誤而結束，我們會在第九章的「對無法復原的錯誤使用 panic!」段落討論更多造成恐慌的細節。

當你是在發佈模式下用 --release 來編譯的話，Rust 則不會加上整數溢位的檢查而造成恐慌。相反地，如果發生整數溢位的話，Rust 會作出二補數包裝的動作。簡單來說，超出最大值的數值可以被包裝成該型別的最低數值。以 u8 為例的話，256 會變成 0、257 會變成 1，以此類推。程式不會恐慌，但是該變數可能會得到一個不是你原本預期的數值。通常依靠整數溢位的行為仍然會被視為邏輯錯誤。

要顯式處理可能的溢位的話，你可以使用以下標準函式庫中基本型別提供的一系列方法：

• 將所有操作用 wrapping_* 方法包裝，像是 wrapping_add。
• 使用 checked_* 方法，如果有溢位的話其會回傳 None 數值。
• 使用 overflowing_* 方法，其會回傳數值與一個布林值來顯示是否有溢位發生。
• 屬於 saturating_* ，讓數值溢位時保持在最小或最大值。

浮點數型別

Rust 還有針對有小數點的浮點數提供兩種基本型別：f32 和 f64，分別佔有 32 位元與 64 位元的大小。而預設的型別為 f64，因為現代的電腦處理的速度幾乎和 f32 一樣卻還能擁有更高的精準度。所有的浮點數型別都是帶號的（signed）。

以下為展示浮點數的範例：

檔案名稱：src/main.rs

fn main() {
    let x = 2.0; // f64

    let y: f32 = 3.0; // f32
}

浮點數是依照 IEEE-754 所定義的，f32 型別是單精度浮點數，而 f64 是倍精度浮點數。

數值運算

Rust 支援你所有想得到的數值型別基本運算：加法、減法、乘法、除法和取餘。整數除法會取最接近零的下界數值。以下程式碼展示出如何在 let 陳述式使用這些運算：

檔案名稱：src/main.rs

fn main() {
    // 加法
    let sum = 5 + 10;

    // 減法
    let difference = 95.5 - 4.3;

    // 乘法
    let product = 4 * 30;

    // 除法
    let quotient = 56.7 / 32.2;
    let truncated = -5 / 3; // 結果爲 -1

    // 取餘
    let remainder = 43 % 5;
}

每一個陳述式中的表達式都使用了一個數學運算符號並計算出一個數值出來，賦值給該變數。附錄 B 有提供列表列出 Rust 所提供的所有運算子。

布林型別

如同其他多數程式語言一樣，Rust 中的布林型別有兩個可能的值：true 和 false。布林值的大小為一個位元組。要在 Rust 中定義布林型別的話用 bool，如範例所示：

檔案名稱：src/main.rs

fn main() {
    let t = true;

    let f: bool = false; // 型別詮釋的方式
}

布林值最常使用的方式之一是作為條件判斷，像是在 if 表達式中使用。我們將會在「控制流程」段落介紹如何在 Rust 使用 if 表達式。

字元型別

Rust 的 char 型別是最基本的字母型別，以下程式碼顯示了使用它的方法：

檔案名稱：src/main.rs

fn main() {
    let c = 'z';
    let z: char = 'ℤ'; // 明確標註型別的寫法
    let heart_eyed_cat = '😻';
}

注意到 char 字面值是用單引號賦值，宣告字串字面值時才是用雙引號。Rust 的 char 型別大小為四個位元組並表示為一個 Unicode 純量數值，這代表它能擁有的字元比 ASCII 還來的多。舉凡標音字母（Accented letters）、中文、日文、韓文、表情符號以及零長度空格都是 Rust char 的有效字元。Unicode 純量數值的範圍包含從 U+0000 到 U+D7FF 以及 U+E000 到 U+10FFFF。但是一個「字元」並不是真正的 Unicode 概念，所以你對於什麼是一個「字元」的看法可能會和 Rust 的 char 不一樣。我們將會在第八章的「透過字串儲存 UTF-8 編碼的文字」來討論此議題。

複合型別

複合型別可以組合數個數值為一個型別，Rust 有兩個基本複合型別：元組（tuples）和陣列（arrays）。

元組（Tuple）型別

元組是個將許多不同型別的數值合成一個複合型別的常見方法。元組擁有固定長度：一旦宣告好後，它們就無法增長或縮減。

我們建立一個元組的方法是寫一個用括號囊括起來的數值列表，每個值再用逗號分隔開來。元組的每一格都是一個獨立型別，不同數值不必是相同型別。以下範例我們也加上了型別詮釋，平時不一定要加上：

檔案名稱：src/main.rs

fn main() {
    let tup: (i32, f64, u8) = (500, 6.4, 1);
}

此變數 tup 就是整個元組，因為一個元組就被視為單一複合元素。要拿到元組中的每個獨立數值的話，我們可以用模式配對（pattern matching）來解構一個元組的數值，如以下所示：

檔案名稱：src/main.rs

fn main() {
    let tup = (500, 6.4, 1);

    let (x, y, z) = tup;

    println!("y 的數值為：{y}");
}

此程式先是建立了一個元組然後賦值給 tup，接著它用模式配對和 let 將 tup 拆成三個個別的變數 x、y 和 z。這就叫做解構（destructuring），因為它將單一元組拆成了三個部分。最後程式將 y 的值印出來，也就是 6.4。

我們也可以直接用句號（.）再加上數值的索引來取得元組內的元素。舉例來說：

檔案名稱：src/main.rs

fn main() {
    let x: (i32, f64, u8) = (500, 6.4, 1);

    let five_hundred = x.0;

    let six_point_four = x.1;

    let one = x.2;
}

此程式建立了元組 x，然後用它們個別的索引來存取元組的元素。和多數程式語言一樣，元組的第一個索引是 0。

沒有任何數值的元組有一種特殊的名稱叫做單元型別（Unit），其數值與型別都寫作 ()，通常代表一個空的數值或空的回傳型別。表達式要是沒有回傳任何數值的話，它們就會隱式回傳單元型別。

陣列型別

另一種取得數個數值集合的方法是使用陣列。和元組不一樣的是，陣列中的每個型別必須是一樣的。和其他語言的陣列不同，Rust 的陣列是固定長度的。

我們將數值寫在陣列中的括號內，每個數值再用逗號區隔開來：

檔案名稱：src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];
}

當你想要你的資料被配置在堆疊（stack）而不是堆積（heap）的話，使用陣列是很好的選擇（我們會在第四章討論堆疊與堆積的內容）。或者當你想確定你永遠會取得固定長度的元素時也是。所以陣列不像向量（vector）型別那麼有彈性，向量是標準函式庫提供的集合型別，類似於陣列但允許變更長度大小。如果你不確定該用陣列或向量的話，通常你應該用向量就好。第八章將會討論更多向量的細節。

不過如果你知道元素的多寡不會變的話，陣列就是個不錯的選擇。舉例來說，如果你想在程式中使用月份的話，你可能就會選擇用陣列宣告，因為永遠只會有 12 個月份：

#![allow(unused)]
fn main() {
let months = ["一月", "二月", "三月", "四月", "五月", "六月", "七月",
              "八月", "九月", "十月", "十一月", "十二月"];
}

要詮釋陣列型別的話，你可以在中括號寫出型別和元素個數，並用分號區隔開來，如以下所示：

#![allow(unused)]
fn main() {
let a: [i32; 5] = [1, 2, 3, 4, 5];
}

i32 在此是每個元素的型別，在分號後面的數字 5 指的是此陣列有五個元素。

如果你想建立的陣列中每個元素數值都一樣的話，你可以指定一個數值後加上分號，最後寫出元素個數。如以下所示：

#![allow(unused)]
fn main() {
let a = [3; 5];
}

陣列 a 會包含 5 個元素，然後每個元素的初始化數值均為 3。這樣寫與 let a = [3, 3, 3, 3, 3]; 的寫法一樣，但比較簡潔。

獲取陣列元素

一個陣列是被配置在堆疊上且已知固定大小的一整塊記憶體，你可以用索引來取得陣列的元素，比如：

檔案名稱：src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];

    let first = a[0];
    let second = a[1];
}

在此範例中，變數 first 會得到數值 1，因為這是陣列索引 [0] 的數值。變數 second 則會從陣列索引 [1] 得到數值 2。

無效的陣列元素存取

讓我們看看如果我們存取陣列之後的元素會發生什麼事呢？假設你修改成以下範例，這是改寫自第二章猜謎遊戲要從使用者取得陣列索引的程式碼：

檔案名稱：src/main.rs

use std::io;

fn main() {
    let a = [1, 2, 3, 4, 5];

    println!("請輸入陣列索引");

    let mut index = String::new();

    io::stdin()
        .read_line(&mut index)
        .expect("讀行失敗");

    let index: usize = index
        .trim()
        .parse()
        .expect("輸入的索引並非數字");

    let element = a[index];

    println!(
        "索引 {index} 元素的數值爲：{element}"
    );
}

此程式碼能編譯成功。如果你透過 cargo run 執行此程式碼並輸入 0、1、2、3 或 4 的話，程式將會印出陣列索引對應的數值。但如果你輸入超出陣列長度的數值，像是 10 的話，你會看到像是這樣的輸出結果：

thread 'main' panicked at 'index out of bounds: the len is 5 but the index is 10', src/main.rs:19:19
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

此程式會在使用無效數值進行索引操作時產生執行時（runtime）錯誤。程式會退出並回傳錯誤訊息，且不會執行最後的 println!。當你嘗試使用索引存取元素時，Rust 會檢查你的索引是否小於陣列長度，如果索引大於或等於陣列長度的話，Rust 就會恐慌。這樣的檢查必須發生在執行時，尤其是在此例，因爲編譯器無法知道之後的使用者將會輸入哪些數值。

這是 Rust 記憶體安全原則給予的保障。在許多低階語言並不會提供這樣的檢查，所以當你提供不正確的索引時，無效的記憶體可能會被存取。Rust 會保護你免於這樣的錯誤風險，並立即離開程式，而不是允許記憶體存取並繼續。第九章將會討論更多有關 Rust 的錯誤處理方式以及如何讓你寫出易讀且安全的程式碼，而不會恐慌或造成無效的記憶體存取。

函式

函式在 Rust 程式碼中無所不在。你已經見過一個語言最重要的函式了：main 函式是許多程式的入口點。此外你也看到了 fn 關鍵字能讓你宣告新的函式。

Rust 程式碼使用 snake case 式作為函式與變數名稱的慣例風格。所有的字母都是小寫，並用底線區隔單字。以下是一支包含函式定義範例的程式：

檔案名稱：src/main.rs

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

    another_function();
}

fn another_function() {
    println!("另一支函式。");
}

我們在 Rust 中定義函式是先從 fn 開始，再加上函式名稱和一組括號，大括號告訴編譯器函式本體的開始與結束位置。

我們可以輸入函式的名稱並加上括號來呼叫任何我們定義過的函式。因為 another_function 已經在程式中定義了，他就可以在 main 函式中呼叫。注意到我們是在原始碼中的 main 函式之後定義 another_function 的，我們當然也可以把它定義在前面。Rust 不在乎你的函式是在哪裡定義的，只需要知道它定義在作用域的某處，且能被呼叫者看到就好。

讓我們開啟一個新的專案叫做 functions 來進一步探索。請將 another_function 範例放入 src/main.rs 然後執行它。你應該會看到以下輸出：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished dev [unoptimized + debuginfo] target(s) in 0.28s
     Running `target/debug/functions`
Hello, world!
另一支函式。

程式碼會按照 main 函式中的順序執行。首先，「Hello, world!」的訊息會先顯示出來，再來才會呼叫 another_function 並印出它的訊息。

參數

我們也可以定義函式成擁有參數（parameters）的，這是函式簽名（signatures）中特殊的變數。當函式有參數時，你可以提供那些參數的確切數值。嚴格上來說，我們傳遞的數值會叫做引數（arguments）。但為了方便起見，通常大家不太會去在意兩者的區別。雖然函式定義時才叫參數，傳遞數值時叫做引數，但很多情況下都能被交換使用。

以下的 another_function 是加上參數後的版本：

檔案名稱：src/main.rs

fn main() {
    another_function(5);
}

fn another_function(x: i32) {
    println!("x 的數值為：{x}");
}

嘗試執行程式的話，你應該會看到以下輸出結果：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished dev [unoptimized + debuginfo] target(s) in 1.21s
     Running `target/debug/functions`
x 的數值為：5

宣告 another_function 時有一個參數叫做 x，而 x 的型別被指定為 i32。當我們傳遞 5 給 another_function 時，println! 巨集會將 5 置於格式化字串中的大括號內 x 的位置。

在函式簽名中，你必須宣告每個參數的型別，這是 Rust 刻意做下的設計決定：在函式定義中要求型別詮釋，代表編譯器幾乎不需要你在其他地方再提供資訊才能知道你要使用什麼型別。而且如果編譯器能知道函式預期的型別的話，它還能夠給予更有幫助的錯誤訊息。

如果要定義函式擁有數個參數時，會用逗號區隔開來，像這樣：

檔案名稱：src/main.rs

fn main() {
    print_labeled_measurement(5, 'h');
}

fn print_labeled_measurement(value: i32, unit_label: char) {
    println!("測量值爲：{value}{unit_label}");
}

此範例建立了一個有兩個參數的函式 print_labeled_measurement，第一個參數叫做 value 而型別爲 i32，第二個參數叫做 unit_label 而型別爲 char。接著函式會印出包含 value 與 unit_label 的文字。

讓我們試著執行此程式碼，請覆蓋你的專案 functions 內的 src/main.rs 檔案內容為以上範例，然後用 cargo run 執行程式：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished dev [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/functions`
測量值爲：5h

因為我們呼叫函式時，將 5 給了 value 且將 'h' 給了 unit_label，程式輸出就會包含這些數值。

陳述式與表達式

函式本體是由一系列的陳述式（statements）並在最後可以選擇加上表達式（expression）來組成。目前我們只講了沒有用到表達式做結尾的函式。由於 Rust 是門基於表達式（expression-based）的語言，知道這樣的區別是很重要的。其他語言通常沒有這樣的區別，所以現在讓我們來看看陳述式和表達式有什麼不同，以及它們怎麼影響函式本體。

• 陳述式（Statements）是進行一些動作的指令，且不回傳任何數值。
• 表達式（Expressions）則是計算並產生數值。讓我們來看一些範例：

我們其實已經使用了很多次陳述式與表達式。建立一個變數然後用 let 關鍵字賦值給它就是一道陳述式。在範例 3-1 中的 let y = 6; 就是個陳述式。

檔案名稱：src/main.rs

fn main() {
    let y = 6;
}

範例 3-1：包含一道陳述式的 main 函式宣告

此函式定義也是陳述式，整個範例本身就是一個陳述式。

陳述式不會回傳數值，因此你無法將 let 陳述式賦值給其他變數。如同以下程式碼所做的，你將會得到一個錯誤：

檔案名稱：src/main.rs

fn main() {
    let x = (let y = 6);
}

當你執行此程式時，你就會看到這樣的錯誤訊息：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error: expected expression, found `let` statement
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^

error: expected expression, found statement (`let`)
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^^^^^^^
  |
  = note: variable declaration using `let` is a statement

error[E0658]: `let` expressions in this position are unstable
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^^^^^^^
  |
  = note: see issue #53667 <https://github.com/rust-lang/rust/issues/53667> for more information

warning: unnecessary parentheses around assigned value
 --> src/main.rs:2:13
  |
2 |     let x = (let y = 6);
  |             ^         ^
  |
  = note: `#[warn(unused_parens)]` on by default
help: remove these parentheses
  |
2 -     let x = (let y = 6);
2 +     let x = let y = 6;
  |

For more information about this error, try `rustc --explain E0658`.
warning: `functions` (bin "functions") generated 1 warning
error: could not compile `functions` due to 3 previous errors; 1 warning emitted

let y = 6 陳述式不回傳數值，所以 x 得不到任何數值。這就和其他語言有所不同，像是 C 或 Ruby，通常它們的賦值仍能回傳所得到的值。在那些語言，你可以寫 x = y = 6 同時讓 x 與 y 都取得 6，但在 Rust 就不行。

表達式則會運算出一個數值，並組合成你大部分所寫的 Rust 程式。先想想看一個數學運算比如 5 + 6，這就是個會算出 11 的表達式。表達式可以是陳述式的一部分：在範例 3-1 中 let y = 6; 的 6 其實就是個算出 6 的表達式。呼叫函式也可以是表達式、呼叫巨集也是表達式、我們用 {} 產生的作用域也是表達式。舉例來說：

檔案名稱：src/main.rs

fn main() {
    let x = 5;

    let y = {
        let x = 3;
        x + 1
    };

    println!("y 的數值為：{y}");
}

此表達式：

{
    let x = 3;
    x + 1
}

就是一個會回傳 4 的區塊，此值再用 let 陳述式賦值給 y。請注意到 x + 1 這行沒有加上分號，它和你目前看到的寫法有點不同，因為表達式結尾不會加上分號。如果你在此表達式加上分號的話，它就不會回傳數值。在我們繼續探討函式回傳值與表達式的同時請記住這一點。

函式回傳值

函式可以回傳數值給呼叫它們的程式碼，我們不會為回傳值命名，但我們必須用箭頭（->）來宣告它們的型別。在 Rust 中，回傳值其實就是函式本體最後一行的表達式。你可以用 return 關鍵字加上一個數值來提早回傳函式，但多數函式都能用最後一行的表達式作為數值回傳。以下是一個有回傳數值的函式範例：

檔案名稱：src/main.rs

fn five() -> i32 {
    5
}

fn main() {
    let x = five();

    println!("x 的數值為：{x}");
}

在 five 函式中沒有任何函式呼叫、巨集甚至是 let 陳述式，只有一個 5。這在 Rust 中完全是合理的函式。請注意到函式的回傳型別也有指明，就是 -> i32。嘗試執行此程式的話，輸出結果就會像是這樣：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished dev [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/functions`
x 的數值為：5

five 中的 5 就是函式的回傳值，這就是為何回傳型別是 i32。讓我們進一步研究細節，這邊有兩個重要的地方：首先這行 let x = five(); 顯示了我們用函式的回傳值作為變數的初始值。因為函式 five 回傳 5，所以這行和以下程式碼相同：

#![allow(unused)]
fn main() {
let x = 5;
}

再來，five 函式沒有參數但有定義回傳值的型別。所以函式本體只需有一個 5 就好，不需加上分號，這樣就能當做表達式回傳我們想要的數值。

讓我們再看另一個例子：

檔案名稱：src/main.rs

fn main() {
    let x = plus_one(5);

    println!("x 的數值為：{x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1
}

執行此程式會顯示 x 的數值為：6，但如果我們在最後一行 x + 1 加上分號的話，就會將它從表達式變為陳述式。我們就會得到錯誤：

檔案名稱：src/main.rs

fn main() {
    let x = plus_one(5);

    println!("x 的數值為：{x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1;
}

編譯此程式就會產生以下錯誤：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error[E0308]: mismatched types
 --> src/main.rs:7:24
  |
7 | fn plus_one(x: i32) -> i32 {
  |    --------            ^^^ expected `i32`, found `()`
  |    |
  |    implicitly returns `()` as its body has no tail or `return` expression
8 |     x + 1;
  |          - help: removing this semicolon

For more information about this error, try `rustc --explain E0308`.
error: could not compile `functions` due to previous error

錯誤訊息 mismatched types 就告訴了我們此程式碼的核心問題。plus_one 的函式定義說它會回傳 i32 但是陳述式不會回傳任何數值。我們用單元型別 () 表示不會回傳任何值。因此沒有任何值被回傳，這和函式定義相牴觸，最後產生錯誤。在此輸出結果，Rust 提供了一道訊息來協助解決問題：它建議移除分號，這樣就能修正錯誤。

註解

所有程式設計師均致力於讓他們的程式碼易於閱讀，不過有時候額外的解釋還是需要的。這種情況下，開發者會在他們的程式碼留下一些註解（comments），編譯器會忽略這些字，但其他人在閱讀程式碼時可能就會覺得很有幫助。

這是一個簡單地註解：

#![allow(unused)]
fn main() {
// 安安，你好
}

在 Rust 中，慣用的註解風格是用兩行斜線再加上一個空格起頭，然後註解就能一直寫到該行結束為止。如果註解會超過一行的話，你需要在每一行都加上 //，如下所示：

#![allow(unused)]
fn main() {
// 這邊處理的事情很複雜，長到
// 我們需要多行註解來能解釋！
// 希望此註解能幫助你理解。
}

註解也可以加在程式碼之後：

檔案名稱：src/main.rs

fn main() {
    let lucky_number = 7; // 幸運 777！
}

不過你會更常看到它們用用以下格式，註解會位於要說明的程式碼上一行：

檔案名稱：src/main.rs

fn main() {
    // 幸運 777！
    let lucky_number = 7;
}

Rust 還有另一種註解：技術文件註解。我們會在第十四章的「發佈 Crate 到 Crates.io」段落提到它。

控制流程

在大多數程式語言中，能夠決定依據某項條件是否為 true 來執行些程式碼，以及依據某項條件是否為 true 來重複執行些程式碼是非常基本的組成元件。在 Rust 程式碼中能讓你控制執行流程的常見方法有 if 表達式以及迴圈。

if 表達式

if 能讓你依照條件判斷對你的程式碼產生分支。基本上你提供一個條件然後就像是在說：「如果此條件符合的話，就執行這個程式碼區塊；如果沒有的話，就不要執行這段程式碼。」

請在你的 projects 目錄下建立一個新的專案叫做 branches 好讓我們來探討 if 表達式。接著請在 src/main.rs 檔案內輸入以下內容：

檔案名稱：src/main.rs

fn main() {
    let number = 3;

    if number < 5 {
        println!("條件為真");
    } else {
        println!("條件為否");
    }
}

所有的 if 表達式都由 if 關鍵字開始再加上一個條件。在此例中的條件是判斷變數 number 是否小於 5。條件符合時所要執行的程式碼區塊被放在條件之後的大括號裡。與 if 表達式條件相關的程式碼段落有時也被稱為分支（arms），就像我們在第二章「將猜測的數字與祕密數字做比較」段落提到的 match 表達式的分支一樣。

另外，我們還可以選擇性地加上 else 表達式（就像範例寫的），讓條件不符時可以去執行另外一段程式碼。如果你沒有提供 else 表達式且條件為否的話，程式會直接略過 if 的程式碼區塊，接著執行後續的程式碼。

請嘗試執行此程式碼，你應該會看到以下輸出結果：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished dev [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
條件為真

讓我們來變更 number 的值使條件變成 false，再來看看會發生什麼事：

fn main() {
    let number = 7;

    if number < 5 {
        println!("條件為真");
    } else {
        println!("條件為否");
    }
}

再跑一次程式，然後看看輸出：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished dev [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
條件為否

還有一件值得注意的是程式碼的條件判斷必須是 bool。如果條件不是 bool 的話，我們就會遇到錯誤。比方說，試試以下程式碼：

檔案名稱：src/main.rs

fn main() {
    let number = 3;

    if number {
        println!("數字為三");
    }
}

這次 if 條件計算出數值 3，然後 Rust 丟出錯誤給我們：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: mismatched types
 --> src/main.rs:4:8
  |
4 |     if number {
  |        ^^^^^^ expected `bool`, found integer

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` due to previous error

錯誤訊息告訴我們 Rust 預期收到 bool 但是卻拿到整數。這和 Ruby 和 JavaScript 就不同，Rust 不會自動將非布林值型別轉換成布林值。你永遠必須顯式提供布林值給 if 作為它的條件判斷。舉例來說，如果我們希望 if 只會在數值不為 0 才執行，我們可以將 if 表達式改成以下範例：

檔案名稱：src/main.rs

fn main() {
    let number = 3;

    if number != 0 {
        println!("數字不為零");
    }
}

執行此程式碼就會印出「數字不為零」。

使用 else if 處理多重條件

想要實現多重條件的話，你可以將 if 和 else 組合成 else if 表達式。舉例來說：

檔案名稱：src/main.rs

fn main() {
    let number = 6;

    if number % 4 == 0 {
        println!("數字可以被 4 整除");
    } else if number % 3 == 0 {
        println!("數字可以被 3 整除");
    } else if number % 2 == 0 {
        println!("數字可以被 2 整除");
    } else {
        println!("數字無法被 4、3、2 整除");
    }
}

程式有四種可能的分支，當你執行它時你應該會看到以下輸出結果：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished dev [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
數字可以被 3 整除

當此程式執行時，他會依序檢查每一個 if 表達式，並執行第一個條件為 true 的程式碼段落。注意到雖然 6 的確可以除以 2，但我們沒有看到 數字可以被 2 整除，也沒有看到來自 else 那段的 數字無法被 4、3、2 整除。這是因為 Rust 只會執行第一個條件為 true 的區塊，而當它遇到時它就不會再檢查其他條件。

使用太多的 else if 表達式很容易讓你的程式碼變得凌亂，所以當你需要用到一個以上時，你可能會想要先重構程式碼看看。為此我們在第六章會介紹一個功能強大的 Rust 條件判斷結構叫做 match。

在 let 陳述式中使用 if

因為 if 是表達式，所以我們可以像範例 3-2 這樣放在 let 陳述式的右邊，將結果賦值給變數。

檔案名稱：src/main.rs

fn main() {
    let condition = true;
    let number = if condition { 5 } else { 6 };

    println!("數字結果為：{number}");
}

範例 3-2：將 if 表達式的結果賦值給變數

變數 number 會得到 if 表達式運算出的數值。執行此程式看看會發生什麼事：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished dev [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/branches`
數字結果為：5

你應該還記得程式碼區塊也可以是表達式且會回傳最後一行的數值，而且數字本身也是表達式。在此例中，if 表達式的值取決於哪段程式碼被執行。這代表可能成為最終結果的每一個 if 分支必須要是相同型別。在範例 3-2 中，各分支的型別都是 i32。如果型別不一致的話，如以下範例所示，我們會得到錯誤：

檔案名稱：src/main.rs

fn main() {
    let condition = true;

    let number = if condition { 5 } else { "六" };

    println!("數字結果為：{number}");
}

當我們嘗試編譯程式碼時，我們會得到錯誤。if 和 else 分支的型別並不一致，而且 Rust 還確切指出程式出錯的地方在哪：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: `if` and `else` have incompatible types
 --> src/main.rs:4:44
  |
4 |     let number = if condition { 5 } else { "六" };
  |                                 -          ^^^^^ expected integer, found `&str`
  |                                 |
  |                                 expected because of this

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` due to previous error

if 段落的表達式運算出整數，但 else 的區塊卻運算出字串。這樣行不通的原因是變數只能有一個型別。Rust 必須在編譯期間確切知道變數 number 的型別，這樣才能驗證它的型別在任何有使用到 number 的地方都是有效的。要是 number 只能在執行時知道的話，Rust 就沒辦法這樣做了。如果編譯器必須追蹤所有變數多種可能存在的型別，那就會變得非常複雜並無法為程式碼提供足夠的保障。

使用迴圈重複執行

重複執行同一段程式碼區塊時常是很有用的。針對這樣的任務，Rust 提供了多種產生迴圈（loops）的方式。一個迴圈會執行一段程式碼區塊，然後在結束時馬上回到區塊起始位置繼續執行。為了繼續探討迴圈，讓我們再開一個新專案 loops。

Rust 提供三種迴圈：loop、while 和 for。讓我們每個都嘗試看看吧。

使用 loop 重複執行程式碼

loop 關鍵字告訴 Rust 去反覆不停地執行一段程式碼直到你親自告訴它要停下來。

我們用以下範例示範，請修改你 loops 目錄下的 src/main.rs 檔案成以下程式碼：

檔案名稱：src/main.rs

fn main() {
    loop {
        println!("再一次！");
    }
}

當我們執行此程式時，我們會看到 再一次！ 一直不停地重複顯示出來，直到我們手動停下程式為止。大多數的終端機都支援 ctrl-c 這個快捷鍵來中斷一支卡在無限迴圈的程式，你可以自己試試看：

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished dev [unoptimized + debuginfo] target(s) in 0.29s
     Running `target/debug/loops`
再一次！
再一次！
再一次！
再一次！
^C再一次！

^C 這個符號表示你按下了 ctrl-c。按照程式收到中斷訊號的時間點，你可能不會看到 再一次！ 出現在 ^C 之後。

幸運的是 Rust 有提供一個從程式中打破迴圈的方法。你可以在迴圈內加上 break 關鍵字告訴程式何時停止執行迴圈。回想一下我們在第二章「猜對後離開」段落就做過這樣的事，當使用者猜對正確數字而獲勝時就會離開程式。

我們在猜謎遊戲中也用到了 continue。這在迴圈中會告訴程式跳過這次疊代中剩餘的程式碼，然後進行下一次疊代。

從迴圈回傳數值

其中一種使用 loop 的用途是重試某些你覺得會失敗的動作，像是檢查一個執行緒是否已經完成其任務。這樣你可能就會想傳遞任務結果給之後的程式碼。要做到這樣的事，你可以在你要用來停下迴圈的 break 表達式內加上一個你想回傳數值，該值就會被停止的迴圈回傳，如以下所示：

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

        if counter == 10 {
            break counter * 2;
        }
    };

    println!("結果為：{result}");
}

在迴圈之前，我們宣告了一個變數 counter 並初始化為 0，然後我們宣告了另一個變數 result 來取得迴圈回傳的值。在迴圈每一次的疊代中，我們將變數 counter 加上 1 並檢查它是否等於 10。如果是的話就用 break 關鍵字回傳 counter * 2。在迴圈結束後，我們用分號才結束這個賦值給 result 的陳述式。最後我們印出 result，而結果為 20。

用迴圈標籤辨別多重迴圈

如果你有迴圈在迴圈之內的話，break 和 continue 會用在該位置最內層的迴圈中。你可以選擇在迴圈使用迴圈標籤（loop label），然後使用 break 和 continue 加上那些迴圈標籤定義的關鍵字，而不是作用在最內層迴圈而已。以下是使用雙層巢狀迴圈的範例：

fn main() {
    let mut count = 0;
    'counting_up: loop {
        println!("count = {count}");
        let mut remaining = 10;

        loop {
            println!("remaining = {remaining}");
            if remaining == 9 {
                break;
            }
            if count == 2 {
                break 'counting_up;
            }
            remaining -= 1;
        }

        count += 1;
    }
    println!("End count = {count}");
}

外層迴圈有個 'counting_up 的標籤，而且其會從 0 數到 2。而內層沒有迴圈標籤的迴圈則會從 10 數到 9。第一個 break 沒有指定任何標籤只會離開內層迴圈。而陳述式 break 'counting_up; 則會離開外層迴圈。此程式碼會印出：

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished dev [unoptimized + debuginfo] target(s) in 0.58s
     Running `target/debug/loops`
count = 0
remaining = 10
remaining = 9
count = 1
remaining = 10
remaining = 9
count = 2
remaining = 10
End count = 2

使用 while 做條件迴圈

在程式中用條件判斷迴圈的執行通常是很有用的。當條件為 true 時，迴圈就繼續執行。當條件不再是 true 時，程式就用 break 停止迴圈。這樣的循環行為可以用 loop、if、else 和 break 組合出來。如果你想嘗試的話，你現在就可以自己寫寫看看。但是這種模式非常常見，所以 Rust 有提供內建的結構稱為 while 迴圈。在範例 3-3 我們就是使用 while 讓該程式會循環三次，每次計數都減一，然後在迴圈之後印出訊息並離開。

檔案名稱：src/main.rs

fn main() {
    let mut number = 3;

    while number != 0 {
        println!("{number}!");

        number -= 1;
    }

    println!("升空！！！");
}

範例 3-3：使用 while 迴圈，當條件符合就持續執行程式碼

這樣消除了很多使用 loop、if、else 與 break 會有的巢狀結構，這樣可以更易閱讀。當條件為 true 的，程式碼就執行；不然的話，它就離開迴圈。

使用 for 遍歷集合

你可以用 while 來遍歷一個集合的元素，像是陣列等等。舉例來說，範例 3-4 的迴圈就會印出陣列 a 的每個元素。

檔案名稱：src/main.rs

fn main() {
    let a = [10, 20, 30, 40, 50];
    let mut index = 0;

    while index < 5 {
        println!("數值為：{}", a[index]);

        index += 1;
    }
}

範例 3-4：使用 while 遍歷集合的每個元素

程式在此對陣列的每個元素計數，它先從索引 0 開始，然後持續循環直到它抵達最後一個陣列索引為止（也就是 index < 5 不再為 true）。執行此程式會印出陣列裡的每個元素：

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32s
     Running `target/debug/loops`
數值為：10
數值為：20
數值為：30
數值為：40
數值為：50

所有五個元素都如預期顯示在終端機上。儘管 index 會在某一刻達到 5，但是迴圈會在嘗試取得陣列第六個元素前就停止執行。

但這樣的方式是容易出錯的，我們可能取得錯誤的索引數值或測試條件而造成程式恐慌。這同時也使程式變慢，因為編譯器得在執行時的程式碼對迴圈中每次疊代中進行索引是否在陣列範圍內的條件檢查。

所以更簡潔的替代方案是，你可以使用 for 迴圈來對集合的每個元素執行一些程式碼。for 迴圈的樣子就像範例 3-5 寫的這一樣。

檔案名稱：src/main.rs

fn main() {
    let a = [10, 20, 30, 40, 50];

    for element in a {
        println!("數值為：{element}");
    }
}

範例 3-5：使用 for 迴圈遍歷集合的每個元素

當我們執行此程式時，我們會看到和範例 3-4 一樣的結果。最重要的是，我們增加了程式的安全性，去除了造成程式錯誤的可能性。不會出現超出陣列大小或是讀取長度不足的風險。

比方說在範例 3-4 的程式碼，如果你變更陣列 a 的元素為只有 4 個，但忘記更新條件判斷為 while index < 4 的話，程式就會恐慌。使用 for 迴圈的話，我們變更陣列長度時，就不需要去記得更新其他程式碼。

for 迴圈的安全性與簡潔程度讓它成為 Rust 最常被使用的迴圈結構。就算你想執行的是依照次數循環的程式碼，像是範例 3-3 的 while 迴圈範例，多數 Rustaceans 還是會選擇 for 迴圈。要這麼做的方法是使用 Range，這是標準函式庫提供的型別，用來產生一連串的數字序列，從指定一個數字開始一直到另一個數字之前結束。

以下是我們用 for 迴圈來計數的另一種方式，它用了一個我們還沒講過的方法 rev，這可以用來反轉這個範圍：

檔案名稱：src/main.rs

fn main() {
    for number in (1..4).rev() {
        println!("{number}!");
    }
    println!("升空！！！");
}

這樣是不是看起來好讀許多？

總結

你做到了！這的確是篇大章節：你學到了變數、純量與複合資料型別、函式、註解、if 表達式以及迴圈！如果你想練習此章的概念，你可以試著打造以下程式：

• 轉換攝氏與華氏溫度。
• 產生第 n 個斐波那契數字。
• 試著用重複的歌詞印出 Christmas carol 的 The Twelve Days of Christmas。

當你準備好後，我們就來探討一個其他語言不常見的概念：所有權。

理解所有權

所有權可以說是 Rust 最與眾不同的特色，並深深影響著整個語言。這讓 Rust 不需要垃圾回收（garbage collector）就可以保障記憶體安全，因此理解 Rust 中的所有權如何運作至關重要。在本章節，我們將討論所有權以及一些相關的功能：借用、切片與 Rust 如何在記憶體配置資料。

什麼是所有權？

所有權在 Rust 中用來管理程式記憶體的一系列規則。

所有程式都需要在執行時管理它們使用記憶體的方式。有些語言會用垃圾回收機制，在程式執行時不斷尋找不再使用的記憶體；而有些程式，開發者必須親自配置和釋放記憶體。Rust 選擇了第三種方式：記憶體由所有權系統管理，且編譯器會在編譯時加上一些規則檢查。如果有地方違規的話，程式就無法編譯。這些所有權的規則完全不會降低執行程式的速度。

因為所有權對許多程式設計師來說是個全新的觀念，所以的確需要花一點時間消化。好消息是隨著你越熟悉 Rust 與所有權系統的規則，你越能輕鬆地開發出安全又高效的程式碼。加油，堅持下去！

當你理解所有權時，你就有一個穩健的基礎能夠理解那些使 Rust 獨特的功能。在本章節中，你將透過一些範例來學習所有權，我們會專注在一個非常常見的資料結構：字串。

堆疊（Stack）與堆積（Heap）

在許多程式語言中，你通常不需要去想到堆疊與堆積。但在像是 Rust 這樣的系統程式語言，資料是位於堆疊還是堆積就會有差，這會影響語言的行為也是你得作出某些特定決策的理由。在本章稍後討論所有權時，都會談到堆疊與堆積的關聯，所以這裡預先稍作解釋。

堆疊與堆積都是提供程式碼在執行時能夠使用的記憶體部分，但他們組成的方式卻不一樣。堆疊會按照它取得數值的順序依序存放它們，並以相反的順序移除數值。這通常稱為後進先出（last in, first out）。你可以把堆疊想成是盤子，當你要加入更多盤子，你會將它們疊在最上面。如果你要取走盤子的話，你也是從最上方拿走。想要從底部或中間，插入或拿走盤子都是不可行的！當我們要新增資料時，我們會稱呼為推入堆疊（pushing onto the stack），而移除資料則是叫做彈出堆疊（popping off the stack）。所有在堆疊上的資料都必須是已知固定大小。在編譯時屬於未知或可能變更大小的資料必須儲存在堆積。

堆積就比較沒有組織，當你要將資料放入堆積，你得要求一定大小的空間。記憶體配置器（memory allocator）會找到一塊夠大的空位，標記為已佔用，然後回傳一個指標（pointer），指著該位置的位址。這樣的過程稱為在堆積上配置（allocating on the heap），或者有時直接簡稱為配置（allocating）就好（將數值放入堆疊不會被視為是在配置）。因為指標是固定已知的大小，所以你可以存在堆疊上。但當你要存取實際資料時，你就得去透過指標取得資料。你可以想像成是一個餐廳。當你進入餐廳時，你會告訴服務員你的團體有多少人，他就會將你們帶到足夠人數的餐桌。如果你的團體有人晚到的話，他們可以直接詢問你坐在哪而找到你。

將資料推入堆疊會比在堆積上配置還來的快，因為配置器不需要去搜尋哪邊才能存入新資料，其位置永遠在堆疊最上方。相對的，堆積就需要比較多步驟，配置器必須先找到一個夠大的空位來儲存資料，然後作下紀錄為下次配置做準備。

在堆積上取得資料也比在堆疊上取得來得慢，因為你需要用追蹤指標才找的到。現代的處理器如果在記憶體間跳轉越少的話速度就越快。讓我們繼續用餐廳做比喻，想像伺服器就是在餐廳為數個餐桌點餐。最有效率的點餐方式就是依照餐桌順序輪流點餐。如果幫餐桌 A 點了餐之後跑到餐桌 B 點，又跑回到 A 然後又跑到 B 的話，可以想像這是個浪費時間的過程。同樣的道理，處理器在處理任務時，如果處理的資料相鄰很近（就如同存在堆疊）的話，當然比相鄰很遠（如同存在堆積）來得快。

當你的程式碼呼叫函式時，傳遞給函式的數值（可能包含指向堆積上資料的指標）與函式區域變數會被推入堆疊。當函式結束時，這些數值就會被彈出。

追蹤哪部分的程式碼用到了堆積上的哪些資料、最小化堆積上的重複資料、以及清除堆積上沒在使用的資料確保你不會耗盡空間，這些問題都是所有權系統要處理的。一旦你理解所有權後，你通常就不再需要經常考慮堆疊與堆積的問題，不過能理解所有權主要就是為了管理堆積有助於解釋為何它要這樣運作。

所有權規則

首先，讓我們先看看所有權規則。當我們在解釋說明時，請記得這些規則：

• Rust 中每個數值都有個擁有者（owner）。
• 同時間只能有一個擁有者。
• 當擁有者離開作用域時，數值就會被丟棄。

變數作用域

現在既然我們已經知道了基本語法，我們接下來就不再將 fn main() { 寫進程式碼範例範例中。所以你在參考時，請記得親自寫在 main 函式內。這樣一來，我們的範例可以更加簡潔，讓我們更加專注在細節而非樣板程式。

作為所有權的第一個範例，我們先來看變數的作用域（scope）。作用域是一些項目在程式內的有效範圍。假設我們有以下變數：

#![allow(unused)]
fn main() {
let s = "hello";
}

變數 s 是一個字串字面值（string literal），而字串數值是寫死在我們程式內。此變數的有效範圍是從它宣告開始一直到當前作用域結束為止。範例 4-1 註解了 s 在哪裡是有效的。

fn main() {
    {                      // s 在此處無效，因為它還沒宣告
        let s = "hello";   // s 在此開始視為有效

        // 使用 s
    }                      // 此作用域結束， s 不再有效
}

範例 4-1：變數與它在作用域的有效範圍

換句話說，這裡有兩個重要的時間點：

• 當 s 進入作用域時，它是有效的。
• 它持續被視為有效直到它離開作用域為止。

目前為止，變數何時有效與作用域的關係都還跟其他程式語言相似。現在我們要以此基礎來介紹 String 型別

String 型別

要能夠解釋所有權規則，我們需要使用比第三章的「資料型別」介紹過的還複雜的型別才行。之前我們提到的型別都是已知固定大小且儲存在堆疊上的，在作用域結束時就會從堆疊中彈出。而且如果其它部分的程式碼需要在不同作用域使用相同數值的話，它們都能迅速簡單地透過複製產生新的單獨實例。但是我們想要觀察的是儲存在堆積上的資料，並研究 Rust 是如何知道要清理資料的。而 String 型別正是個絕佳範例。

我們專注在 String 與所有權有關的部分。這些部分也適用於其他基本函式庫或你自己定義的複雜資料型別。我們會在第八章更深入探討 String。

我們已經看過字串字面值（string literals），字串的數值是寫死在我們的程式內的。字串字面值的確很方便，但它不可能完全適用於我們使用文字時的所有狀況。其中一個原因是因為它是不可變的，另一個原因是並非所有字串值在我們編寫程式時就會知道。舉例來說，要是我們想要收集使用者的輸入並儲存它呢？對於這些情形，Rust 提供第二種字串型別 String。此型別管理配置在堆積上的資料，所以可以儲存我們在編譯期間未知的一些文字。你可以從字串字面值使用 from 函式來建立一個 String，如以下所示：

#![allow(unused)]
fn main() {
let s = String::from("hello");
}

雙冒號 :: 讓我們可以將 from 函式置於 String 型別的命名空間（namespace）底下，而不是取像是 string_from 這樣的名稱。我們將會在第五章的「方法語法」討論這個語法，並在第七章的「參考模組項目的路徑」討論模組（modules）與命名空間。

這種類型的字串是可以被改變的：

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

    s.push_str(", world!"); // push_str() 將字面值加到字串後面

    println!("{}", s); // 這會印出 `hello, world!`
}

所以這邊有何差別呢？為何 String 是可變的，但字面值卻不行？兩者最主要的差別在於它們對待記憶體的方式。

記憶體與配置

以字串字面值來說，我們在編譯時就知道它的內容，所以可以寫死在最終執行檔內。這就是為何字串字面值非常迅速且高效。但這些特性均來自於字串字面值的不可變性。不幸的是我們無法將編譯時未知大小的文字，或是執行程式時大小可能會改變的文字等對應記憶體塞進執行檔中。

而對於 String 型別來說，為了要能夠支援可變性、改變文字長度大小，我們需要在堆積上配置一塊編譯時未知大小的記憶體來儲存這樣的內容，這代表：

• 記憶體配置器必須在執行時請求記憶體。
• 我們不再需要這個 String 時，我們需要以某種方法將此記憶體還給配置器。

當我們呼叫 String::from 時就等於完成第一個部分，它的實作會請求配置一塊它需要的記憶體。這邊大概和其他程式語言都一樣。

不過第二部分就不同了。在擁有垃圾回收機制（garbage collector, GC）的語言中，GC 會追蹤並清理不再使用的記憶體，所以我們不用去擔心這件事。沒有 GC 的話，識別哪些記憶體不再使用並明確的呼叫程式碼釋放它們就是我們的責任了，就像我們請求取得它一樣。在以往的歷史我們可以看到要完成這件事是一項艱鉅的任務，如果我們忘了，那麼就等於在浪費記憶體。如果我們釋放的太早的話，我們則有可能會拿到無效的變數。要是我們釋放了兩次，那也會造成程式錯誤。我們必須準確無誤地配對一個 allocate 給剛好一個 free。

Rust 選擇了一條不同的道路：當記憶體在擁有它的變數離開作用域時就會自動釋放。以下是我們解釋作用域的範例 4-1，但使用的是 String 而不是原本的字串字面值：

fn main() {
    {
        let s = String::from("hello"); // s 在此開始視為有效

        // 使用 s
    }                                  // 此作用域結束
                                       // s 不再有效
}

當 s 離開作用域時，我們就可以很自然地將 String 所需要的記憶體釋放回配置器。當變數離開作用域時，Rust 會幫我們呼叫一個特殊函式。此函式叫做 drop，在這裡當時 String 的作者就可以寫入釋放記憶體的程式碼。Rust 會在大括號結束時自動呼叫 drop。

注意：在 C++，這樣在項目生命週期結束時釋放資源的模式，有時被稱為資源取得即初始化（Resource Acquisition Is Initialization, RAII）。如果你已經用過 RAII 的模式，那麼你應該就會很熟悉 Rust 的 drop 函式。

這樣的模式對於 Rust 程式碼的編寫有很深遠的影響。雖然現在這樣看起來很簡單，但在更多複雜的情況下程式碼的行為可能會變得很難預測。像是當我們需要許多變數，所以得在堆積上配置它們的情況。現在就讓我們開始來探討這些情形。

變數與資料互動的方式：移動（Move）

數個變數在 Rust 中可以有許多不同方式來與相同資料進行互動。讓我們看看使用整數的範例 4-2。

fn main() {
    let x = 5;
    let y = x;
}

範例 4-2：將變數 x 的數值賦值給 y

我們大概可以猜到這做了啥：「x 取得數值 5，然後拷貝（copy）了一份 x 的值給 y。」所以我們有兩個變數 x 與 y，而且都等於 5。這的確是我們所想的這樣，因為整數是已知且固定大小的簡單數值，所以這兩個數值 5 都會推入堆疊中。

現在讓我們看看 String 的版本：

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

這和之前的程式碼非常相近，所以我們可能會認為它做的事也是一樣的：也就是第二行也會拿到一份 s1 拷貝的值給 s2。但事實上卻不是這樣。

請看看圖示 4-1 來瞭解 String 底下的架構到底長什麼樣子。一個 String 由三個部分組成，如圖中左側所示：一個指向儲存字串內容記憶體的指標、它的長度和它的容量。這些資料是儲存在堆疊上的，但圖右的內容則是儲存在堆積上。

圖示 4-1：將數值 "hello" 賦值給 s1 的 String 記憶體結構

長度指的是目前所使用的 String 內容在記憶體以位元組為單位所佔用的大小。而容量則是 String 從配置器以位元組為單位取得的總記憶體量。長度和容量的確是有差別的，但現在對我們來說還不太重要，你現在可以先忽略容量的問題。

當我們將 s1 賦值給 s2，String 的資料會被拷貝，不過我們拷貝的是堆疊上的指標、長度和容量。我們不會拷貝指標指向的堆積資料。資料以記憶體結構表示的方式會如圖示 4-2 表示。

圖示 4-2：s2 擁有一份 s1 的指標、長度和容量的記憶體結構

所以實際上的結構不會長的像圖示 4-3 這樣，如果 Rust 也會拷貝堆積資料的話，才會看起來像這樣。如果 Rust 這麼做的話，s2 = s1 的動作花費會變得非常昂貴。當堆積上的資料非常龐大時，對執行時的性能影響是非常顯著的。

圖示 4-3：如果 Rust 也會拷貝堆積資料，s2 = s1 可能會長得樣子

稍早我們提到當變數離開作用域時，Rust 會自動呼叫 drop 函式並清理該變數在堆積上的資料。但圖示 4-2 顯示兩個資料指標都指向相同位置，這會造成一個問題。當 s2 與 s1 都離開作用域時，它們都會嘗試釋放相同的記憶體。這被稱呼為雙重釋放（double free）錯誤，也是我們之前提過的錯誤之一。釋放記憶體兩次可能會導致記憶體損壞，進而造成安全漏洞。

為了保障記憶體安全，在此情況中 Rust 還會再做一件重要的事。在 let s2 = s1; 之後，Rust 就不再將 s1 視爲有效。因此當 s1 離開作用域時，Rust 不需要釋放任何東西。請看看如果在 s2 建立之後繼續使用 s1 會發生什麼事，以下程式就執行不了：

fn main() {
    let s1 = String::from("hello");
    let s2 = s1;

    println!("{}, world!", s1);
}

你會得到像這樣的錯誤，因為 Rust 會防止你使用無效的參考：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0382]: borrow of moved value: `s1`
 --> src/main.rs:5:28
  |
2 |     let s1 = String::from("hello");
  |         -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait
3 |     let s2 = s1;
  |              -- value moved here
4 |
5 |     println!("{}, world!", s1);
  |                            ^^ value borrowed here after move
  |
  = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info)

For more information about this error, try `rustc --explain E0382`.
error: could not compile `ownership` due to previous error

如果你在其他語言聽過淺拷貝（shallow copy）和深拷貝（deep copy）這樣的詞，拷貝指標、長度和容量而沒有拷貝實際內容這樣的概念應該就相近於淺拷貝。但因為 Rust 同時又無效化第一個變數，我們不會叫此為淺拷貝，而是稱此動作為移動（move）。在此範例我們會稱 s1 被移動到 s2，所以實際上發生的事長得像圖示 4-4 這樣。

圖示 4-4：s1 無效後的記憶體結構

這樣就解決了問題！只有 s2 有效的話，當它離開作用域，就只有它會釋放記憶體，我們就完成所有動作了。

除此之外，這邊還表達了另一個設計決策：Rust 永遠不會自動將你的資料建立「深拷貝」。因此任何自動的拷貝動作都可以被視為是對執行效能影響很小的。

變數與資料互動的方式：克隆（Clone）

要是我們真的想深拷貝 String 在堆積上的資料而非僅是堆疊資料的話，我們可以使用一個常見的方法（method）叫做 clone。我們會在第五章講解方法語法，不過既然方法是很常見的程式語言功能，你很可能已經有些概念了。

以下是 clone 方法運作的範例：

fn main() {
    let s1 = String::from("hello");
    let s2 = s1.clone();

    println!("s1 = {}, s2 = {}", s1, s2);
}

此程式碼能執行無誤，並明確作出了像圖示 4-3 這樣的行為，也就是堆積資料的確被複製了一份。

當你看到 clone 的呼叫，你就會知道有一些特定的程式碼被執行且消費可能是相對昂貴的。你可以很清楚地知道有些不同的行為正在發生。

只在堆疊上的資料：拷貝（Copy）

還有一個小細節我們還沒提到，也就是我們在使用整數時的程式碼。回想一下範例 4-2 是這樣寫的，它能執行而且是有效的：

fn main() {
    let x = 5;
    let y = x;

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

但這段程式碼似乎和我們剛學的互相矛盾：我們沒有呼叫 clone，但 x 卻仍是有效的，沒有移動到 y。

原因是因為像整數這樣的型別在編譯時是已知大小，所以只會存在在堆疊上。所以要拷貝一份實際數值的話是很快的。這也讓我們沒有任何理由要讓 x 在 y 建立後被無效化。換句話說，這邊沒有所謂淺拷貝與深拷貝的差別。所以這邊呼叫 clone 的話不會與平常的淺拷貝有啥不一樣，我們可以保持這樣就好。

Rust 有個特別的標記叫做 Copy 特徵（trait）可以用在標記像整數這樣存在堆疊上的型別（我們會在第十章討論什麼是特徵）。如果一個型別有 Copy 特徵的話，一個變數在賦值給其他變數後仍然會是有效的。

如果一個型別有實作（implement）Drop 特徵的話，Rust 不會允許我們讓此型別擁有 Copy 特徵。如果我們對某個型別在數值離開作用域時，需要再做特別處理的話，我們對此型別標註 Copy 特徵會在編譯時期產生錯誤。想要瞭解如何為你的型別實作 Copy 特徵的話，請參考附錄 C 「可推導的特徵」。

所以哪些型別有實作 Copy 特徵呢？你可以閱讀技術文件來知道哪些型別有，但基本原則是任何簡單地純量數值都可以實作 Copy，且不需要配置記憶體或任何形式資源的型別也有實作 Copy。以下是一些有實作 Copy 的型別：

• 所有整數型別像是 u32。
• 布林型別 bool，它只有數值 true 與 false。
• 所有浮點數型別像是 f64。
• 字元型別 char。
• 元組，不過包含的型別也都要有實作 Copy 才行。比如 (i32, i32) 就有實作 Copy，但 (i32, String) 則無。

所有權與函式

傳遞數值給函式的方式和賦值給變數是類似的。傳遞變數給函式會是移動或拷貝，就像賦值一樣。範例 4-3 說明了變數如何進入且離開作用域。

檔案名稱：src/main.rs

fn main() {
    let s = String::from("hello");  // s 進入作用域

    takes_ownership(s);             // s 的值進入函式
                                    // 所以 s 也在此無效

    let x = 5;                      // x 進入作用域

    makes_copy(x);                  // x 本該移動進函式裡
                                    // 但 i32 有 Copy，所以 x 可繼續使用

} // x 在此離開作用域，接著是 s。但因為 s 的值已經被移動了
  // 它不會有任何動作

fn takes_ownership(some_string: String) { // some_string 進入作用域
    println!("{}", some_string);
} // some_string 在此離開作用域並呼叫 `drop`
  // 佔用的記憶體被釋放

fn makes_copy(some_integer: i32) { // some_integer 進入作用域
    println!("{}", some_integer);
} // some_integer 在此離開作用域，沒有任何動作發生

範例 4-3：具有所有權的函式

如果我們嘗試在呼叫 takes_ownership 後使用 s，Rust 會拋出編譯時期錯誤。這樣的靜態檢查可以免於我們犯錯。你可以試試看在 main 裡哪裡可以使用 s 和 x，以及所有權規則如何防止你寫錯。

回傳值與作用域

回傳值一樣能轉移所有權，範例 4-4 和範例 4-3 一樣加上了註解說明一個函式如何回傳些數值。

檔案名稱：src/main.rs

fn main() {
    let s1 = gives_ownership();         // gives_ownership 移動它的回傳值給 s1

    let s2 = String::from("哈囉");     // s2 進入作用域

    let s3 = takes_and_gives_back(s2);  // s2 移入 takes_and_gives_back
                                        // 該函式又將其回傳值移到 s3
} // s3 在此離開作用域並釋放
  // s2 已被移走，所以沒有任何動作發生
  // s1 離開作用域並釋放

fn gives_ownership() -> String {             // gives_ownership 會將他的回傳值
                                             // 移動給呼叫它的函式

    let some_string = String::from("你的字串"); // some_string 進入作用域

    some_string                              // 回傳 some_string 並移動給
                                             // 呼叫它的函式
}

// 此函式會取得一個 String 然後回傳它
fn takes_and_gives_back(a_string: String) -> String { // a_string 進入作用域

    a_string  // 回傳 a_string 並移動給呼叫的函式
}

範例 4-4：轉移回傳值的所有權

變數的所有權每次都會遵從相同的模式：賦值給其他變數就會移動。當擁有堆積資料的變數離開作用域時，該數值就會被 drop 清除，除非該資料的所有權被移動到其他變數所擁有。

雖然這樣是正確的，但在每個函式取得所有權再回傳所有權的確有點囉唆。要是我們可以讓函式使用一個數值卻不取得所有權呢？要是我們想重複使用同個值，但每次都要傳入再傳出實在是很麻煩。而且我們有時也會想要讓函式回傳一些它們自己產生的值。

Rust 能讓我們使用元組回傳多個數值，如範例 4-5 所示。

檔案名稱：src/main.rs

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

    let (s2, len) = calculate_length(s1);

    println!("'{}' 的長度為 {}。", s2, len);
}

fn calculate_length(s: String) -> (String, usize) {
    let length = s.len(); // len() 回傳 String 的長度

    (s, length)
}

範例 4-5：回傳參數的所有權

但這實在太繁瑣，而且這樣的情況是很常見的。幸運的是 Rust 有提供一個概念能在不轉移所有權的狀況下使用數值，這叫做參考（references）。

參考與借用

我們在範例 4-5 使用元組的問題在於，我們必須回傳 String 給呼叫的函式，我們才能繼續在呼叫 calculate_length 之後繼續使用 String，因為 String 會被傳入 calculate_length。不過我們其實可以提供個 String 數值的參考。參考（references） 就像是指向某個地址的指標，我們可以追蹤存取到該處儲存的資訊，而該地址仍被其他變數所擁有。和指標不一樣的是，參考保證所指向的特定型別的數值一定是有效的。

以下是我們定義並使用 calculate_length 時，在參數改用參考物件而非取得所有權的程式碼：

檔案名稱：src/main.rs

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

    let len = calculate_length(&s1);

    println!("'{}' 的長度為 {}。", s1, len);
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

首先你會注意到原先變數宣告與函式回傳值會用到元組的地方都被更改了。再來注意到我們傳遞的是 &s1 給 calculate_length，然後在定義時我們是取 &String 而非 String。這些「&」符號就是參考，它們允許你不必獲取所有權來參考它。以下用圖示 4-5 示意。

圖示 4-5：顯示 &String s 指向 String s1 的示意圖

注意：使用 & 參考的反向動作是解參考（dereferencing），使用的是解參考運算符號 *。我們會在第八章看到一些解參考的範例並在第 15 章詳細解釋解參考。

讓我們進一步看看函式的呼叫：

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

    let len = calculate_length(&s1);

    println!("'{}' 的長度為 {}。", s1, len);
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

&s1 語法讓我們可以建立一個指向 s1 數值的參考，但不會擁有它。因為它並沒有所有權，它所指向的資料在不再使用參考後並不會被丟棄。

同樣地，函式簽名也是用 & 說明參數 s 是個參考。讓我們加一些註解在範例上：

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

    let len = calculate_length(&s1);

    println!("'{}' 的長度為 {}。", s1, len);
}

fn calculate_length(s: &String) -> usize { // s 是個 String 的參考
    s.len()
} // s 在此離開作用域，但因為它沒有它所指向的資料的所有權
  // 所以不會被釋放掉

變數 s 有效的作用域和任何函式參數的作用域一樣，但當不再使用參考時，參考所指向的數值不會被丟棄，因為我們沒有所有權。當函式使用參考作為參數而非實際數值時，我們不需要回傳數值來還所有權，因為我們不曾擁有過。

我們會稱呼建立參考這樣的動作叫做借用（borrowing）。就像現實世界一樣，如果有人擁有某項東西，他可以借用給你。當你使用完後，你就還給他。你並不擁有它。

所以要是我們嘗試修改我們借用的東西會如何呢？請試試範例 4-6 的程式碼。直接劇透你：它執行不了的！

檔案名稱：src/main.rs

fn main() {
    let s = String::from("hello");

    change(&s);
}

fn change(some_string: &String) {
    some_string.push_str(", world");
}

範例 4-6：嘗試修改借用的值

以下是錯誤訊息：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0596]: cannot borrow `*some_string` as mutable, as it is behind a `&` reference
 --> src/main.rs:8:5
  |
7 | fn change(some_string: &String) {
  |                        ------- help: consider changing this to be a mutable reference: `&mut String`
8 |     some_string.push_str(", world");
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `some_string` is a `&` reference, so the data it refers to cannot be borrowed as mutable

For more information about this error, try `rustc --explain E0596`.
error: could not compile `ownership` due to previous error

如同變數預設是不可變，參考也是一樣的。我們不被允許修改我們參考的值。

可變參考

我們可以修正範例 4-6 的程式碼，讓我們可以變更借用的數值。我們可以加一點小修改，改用可變參考就好：

檔案名稱：src/main.rs

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

    change(&mut s);
}

fn change(some_string: &mut String) {
    some_string.push_str(", world");
}

首先我們將 s 加上了 mut，然後我們在呼叫 change 函式的地方建立了一個可變參考 &mut s，然後更新函式的簽章成 some_string: &mut String 來接收這個可變參考。這樣能清楚表達 change 函式會改變它借用的參考。

可變參考有個很大的限制：如果你有一個數值的可變參考，你就無法再對該數值有其他任何參考。所以嘗試建立兩個 s 的可變參考的話就會失敗，如以下範例所示：

檔案名稱：src/main.rs

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

    let r1 = &mut s;
    let r2 = &mut s;

    println!("{}, {}", r1, r2);
}

以下是錯誤資訊：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0499]: cannot borrow `s` as mutable more than once at a time
 --> src/main.rs:5:14
  |
4 |     let r1 = &mut s;
  |              ------ first mutable borrow occurs here
5 |     let r2 = &mut s;
  |              ^^^^^^ second mutable borrow occurs here
6 |
7 |     println!("{}, {}", r1, r2);
  |                        -- first borrow later used here

For more information about this error, try `rustc --explain E0499`.
error: could not compile `ownership` due to previous error

此錯誤表示此程式碼是無效的，因爲我們無法同時可變借用 s 超過一次。第一次可變借用在 r1 且必須持續到它在 println! 用完爲止，但在其產生到使用之間，我們嘗試建立了另一個借用了與 r1 相同資料的可變借用 r2。

這項防止同時間對相同資料進行多重可變參考的限制允許了可變行為，但是同時也受到一定程度的約束。這通常是新 Rustaceans 遭受挫折的地方，因為多數語言都會任你去改變其值。這項限制的好處是 Rust 可以在編譯時期就防止資料競爭（data races）。資料競爭和競爭條件（race condition）類似，它會由以下三種行為引發：

• 同時有兩個以上的指標存取同個資料。
• 至少有一個指標在寫入資料。
• 沒有針對資料的同步存取機制。

資料競爭會造成未定義行為（undefined behavior），而且在執行時你通常是很難診斷並修正的。Rust 能夠阻止這樣的問題發生，不讓有資料競爭的程式碼編譯通過！

如往常一樣，我們可以用大括號來建立一個新的作用域來允許多個可變參考，只要不是同時擁有就好：

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

    {
        let r1 = &mut s;
    } // r1 離開作用域，所以建立新的參考也不會有問題

    let r2 = &mut s;
}

Rust 對於可變參考和不可變參考的組合中也實施著類似的規則，以下程式碼就會產生錯誤：

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

    let r1 = &s; // 沒問題
    let r2 = &s; // 沒問題
    let r3 = &mut s; // 很有問題！

    println!("{}, {}, and {}", r1, r2, r3);
}

以下是錯誤訊息：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:14
  |
4 |     let r1 = &s; // no problem
  |              -- immutable borrow occurs here
5 |     let r2 = &s; // no problem
6 |     let r3 = &mut s; // BIG PROBLEM
  |              ^^^^^^ mutable borrow occurs here
7 |
8 |     println!("{}, {}, and {}", r1, r2, r3);
  |                                -- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` due to previous error

哇！看來我們也不可以擁有不可變參考的同時擁有可變參考。

擁有不可變參考的使用者可不希望有人暗地裡突然改變了值！不過數個不可變參考是沒問題的，因為所有在讀取資料的人都無法影響其他人閱讀資料。

請注意參考的作用域始於它被宣告的地方，一直到它最後一次參考被使用為止。舉例來說以下程式就可以編譯，因為不可變參考最後一次的使用（println!）在可變參考宣告之前：

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

    let r1 = &s; // 沒問題
    let r2 = &s; // 沒問題
    println!("{} and {}", r1, r2);
    // 變數 r1 和 r2 將不再使用
    
    let r3 = &mut s; // 沒問題
    println!("{}", r3);
}

不可變參考 r1 和 r2 的作用域在 println! 之後結束。這是它們最後一次使用到的地方，也就是在宣告可變參考 r3 之前。它們的作用域沒有重疊，所以程式碼是允許的：編譯器能辨別出參考何時在作用域之前不再被使用。

雖然借用錯誤有時是令人沮喪的，但請記得這是 Rust 編譯器希望提前（在編譯時而非執行時）指出潛在程式錯誤並告訴你問題的源頭在哪。這樣你就不必親自追蹤為何你的資料跟你預期的不一樣。

迷途參考

在有指標的語言中，通常都很容易不小心產生迷途指標（dangling pointer）。當資源已經被釋放但指標卻還留著，這樣的指標指向的地方很可能就已經被別人所有了。相反地，在 Rust 中編譯器會保證參考絕不會是迷途參考：如果你有某些資料的參考，編譯器會確保資料不會在參考結束前離開作用域。

讓我們來嘗試產生迷途指標，看看 Rust 怎麼產生編譯期錯誤：

檔案名稱：src/main.rs

fn main() {
    let reference_to_nothing = dangle();
}

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

    &s
}

以下是錯誤訊息：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0106]: missing lifetime specifier
 --> src/main.rs:5:16
  |
5 | fn dangle() -> &String {
  |                ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from
help: consider using the `'static` lifetime
  |
5 | fn dangle() -> &'static String {
  |                 +++++++

For more information about this error, try `rustc --explain E0106`.
error: could not compile `ownership` due to previous error

此錯誤訊息包含了一個我們還沒介紹的功能：生命週期（lifetimes）。我們會在第十章詳細討論生命週期。就算我們先不管生命週期的部分，錯誤訊息仍然告訴了我們程式出錯的關鍵點：

this function's return type contains a borrowed value, but there is no value
for it to be borrowed from

讓我們進一步看看我們的 dangle 程式碼每一步發生了什麼：

檔案名稱：src/main.rs

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String { // 回傳 String 的迷途參考

    let s = String::from("hello"); // s 是個新 String

    &s // 我們回傳 String s 的參考
} // s 在此會離開作用域並釋放，它的記憶體就不見了。
  // 危險！

因為 s 是在 dangle 內產生的，當 dangle 程式碼結束時，s 會被釋放。但我們卻嘗試回傳參考。此參考會指向一個已經無效的 String。這看起來不太優！Rust 不允許我們這麼做。

解決的辦法是直接回傳 String 就好：

fn main() {
    let string = no_dangle();
}

fn no_dangle() -> String {
    let s = String::from("hello");

    s
}

這樣就沒問題了。所有權轉移了出去，沒有任何值被釋放。

參考規則

讓我們來回顧我們討論到的參考規則：

• 在任何時候，我們要嘛只能有一個可變參考，要嘛可以有任意數量的不可變參考。
• 參考必須永遠有效。

接下來我們要來看看一個不太一樣的參考型別：切片（slices）。

切片型別

切片（slice） 讓你可以參考一串集合中的元素序列，而並非參考整個集合。切片也算是某種類型的參考，所以它沒有所有權。

以下是個小小的程式問題：寫一支函式接收一串用空格分開單字的字串，並回傳第一個找到的單字，如果函式沒有在字串找到空格的話，就代表整個字串就是一個單字，所以就回傳整個字串。

我們先來想看看不使用切片的話，以下函式的簽名會長怎樣。這有助於我們理解切片想解決什麼問題：

fn first_word(s: &String) -> ?

此函式 first_word 有一個參數 &String。我們不需要取得所有權，所以這是合理的。但我們該回傳啥呢？我們目前還沒有方法能夠描述一個字串的其中一部分。不過我們可以回傳單字的最後一個索引，也就是和空格作比較。讓我們像範例 4-7 這樣試試看。

檔案名稱：src/main.rs

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

範例 4-7：函式 first_word 回傳參數 String 第一個單字最後的索引

因為我們需要遍歷 String 的每個元素並檢查該值是否為空格，我們要用 as_bytes 方法將 String 轉換成一個位元組陣列。

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

接下來我們使用 iter 方法對位元組陣列建立一個疊代器（iterator）：

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

我們會在第十三章討論疊代器的細節。現在我們只需要知道 iter 是個能夠回傳集合中每個元素的方法，然後 enumerate 會將 iter 的結果包裝起來回傳成元組。enumerate 回傳的元組中的第一個元素是索引，第二個才是元素的參考。這樣比我們自己計算索引還來的方便。

既然 enumerate 回傳的是元組，我們可以用模式配對來解構元組。我們會在第六章進一步解釋模式配對。所以在 for 迴圈中，我們指定了一個模式讓 i 取得索引然後 &item 取得元組中的位元組。因為我們從用 .iter().enumerate() 取得參考的，所以在模式中我們用的是 & 來獲取。

在 for 迴圈裡面我們使用字串字面值的語法搜尋位元組是不是空格。如果我們找到空格的話，我們就回傳該位置。不然我們就用 s.len() 回傳整個字串的長度。

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

我們現在有了一個能夠找到字串第一個單字結尾索引的辦法，但還有一個問題。我們回傳的是一個獨立的 usize，它套用在 &String 身上才有意義。換句話說，因為它是個與 String 沒有直接關係的數值，我們無法保證它在未來還是有效的。參考一下使用了範例 4-7 中函式 first_word 的範例 4-8：

檔案名稱：src/main.rs

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s); // word 取得數值 5

    s.clear(); // 這會清空 String，這就等於 ""

    // word 仍然是數值 5 ，但是我們已經沒有相等意義的字串了
    // 擁有 5 的變數 word 現在完全沒意義！
}

範例 4-8：先儲存呼叫函式 first_word的結果再變更 String 的內容

此程式可以成功編譯沒有任何錯誤，而且我們在呼叫 s.clear() 後仍然能使用 word。因為 word 和 s 並沒有直接的關係，word 在之後仍能繼續保留 5。我們可以用 s 取得 5 並嘗試取得第一個單字。但這樣就會是程式錯誤了，因為 s 的內容自從我們賦值 5 給 word 之後的內容已經被改變了。

要隨時留意 word 會不會與 s 的資料脫鉤是很煩瑣的且容易出錯！要是我們又寫了個函式 second_word，管理這些索引會變得非常難以管控！我們會不得不將函式簽名改成這樣：

fn second_word(s: &String) -> (usize, usize) {

現在我們得同時紀錄起始與結束的索引，而且我們還產生了更多與原本數值沒辦法直接相關的計算結果。我們現在有三個非直接相關的變數需要保持同步。

幸運的是 Rust 為此提供了一個解決辦法：字串切片（String slice）。

字串切片

字串切片是 String 其中一部分的參考，它長得像這樣：

fn main() {
    let s = String::from("hello world");

    let hello = &s[0..5];
    let world = &s[6..11];
}

與其參考整個 String，hello 只參考了一部分的String，透過 [0..5] 來指示。我們可以像這樣 [起始索引..結束索引] 用中括號加上一個範圍來建立切片。起始索引 是切片的第一個位置，而 結束索引 在索引結尾之後的位置（所以不包含此值）。在內部的切片資料結構會儲存起始位置，以及 結束索引 與 起始索引 相減後的長度。所以用 let world = &s[6..11]; 作為例子的話， world 就會是個切片，包含一個指標指向索引爲 6 的位元組 s 和一個長度數值 5。

圖示 4-6 就是此例的示意圖。

圖示 4-6：指向部分 String 的字串切片

要是你想用 Rust 指定範圍的語法 .. 從索引 0 開始的話，你可以省略兩個句點之前的值。換句話說，以下兩個是相等的：

#![allow(unused)]
fn main() {
let s = String::from("hello");

let slice = &s[0..2];
let slice = &s[..2];
}

同樣地，如果你的切片包含 String 的最後一個位元組的話，你同樣能省略最後一個數值。這代表以下都是相等的：

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[3..len];
let slice = &s[3..];
}

如果你要獲取整個字串的切片，你甚至能省略兩者的數值，以下都是相等的：

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[0..len];
let slice = &s[..];
}

注意：字串切片的索引範圍必須是有效的 UTF-8 字元界限。如果你嘗試從一個多位元組字元（multibyte character）中產生字串切片，你的程式就會回傳錯誤。為了方便介紹字串切片，本章只使用了 ASCII 字元而已。 我們會在第八章的「使用 String 儲存 UTF-8 編碼的文字」做更詳盡的討論。

有了這些資訊，讓我們用切片來重寫 first_word 吧。對於「字串切片」的回傳型別我們會寫 &str：

檔案名稱：src/main.rs

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {}

我們如同範例 4-7 一樣用判斷第一個空格取得了單字結尾的索引。當我們找到第一個空格，我們用字串的初始索引與當前空格的索引作為初始與結束索引來回傳字串切片。

現在當我們呼叫 first_word，我們就會取得一個與原本資料有直接相關的數值。此數值是由切片的起始位置即切片中的元素個數組成。

這樣函式 second_word 一樣也可以回傳切片：

fn second_word(s: &String) -> &str {

我們現在有個不可能出錯且更直觀的 API，因為編譯器會確保 String 的參考會是有效的。還記得我們在範例 4-8 的錯誤嗎？就是那個當我們取得單字結尾索引，但字串卻已清空變成無效的錯誤。那段程式碼邏輯是錯誤的，卻不會馬上顯示錯誤。要是我們持續嘗試用該索引存取空字串的話，問題才會浮現。切片可以讓這樣的程式錯誤無所遁形，並及早讓我們知道我們程式碼有問題。使用切片版本 first_word 的程式碼的話就會出現編譯期錯誤：

檔案名稱：src/main.rs

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s);

    s.clear(); // 錯誤！

    println!("第一個單字為：{}", word);
}

以下是錯誤訊息：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> src/main.rs:18:5
   |
16 |     let word = first_word(&s);
   |                           -- immutable borrow occurs here
17 |
18 |     s.clear(); // 錯誤！
   |     ^^^^^^^^^ mutable borrow occurs here
19 |
20 |     println!("第一個單字為：{}", word);
   |                                ---- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` due to previous error

回憶一下借用規則，要是我們有不可變參考的話，我們就不能取得可變參考。因為 clear 會縮減 String，它必須是可變參考。在呼叫 clear 之後的 println! 用到了 word 的參考，所以不可變參考在該處仍必須保持有效。Rust 不允許同時存在 clear 的可變參考與 word 的不可變參考，所以編譯會失敗。Rust 不僅讓我們的 API 更容易使用，還想辦法讓所有錯誤在編譯期就消除！

字串字面值作為切片

回想一下我們講說字串字面值是怎麼存在執行檔的。現在既然我們已經知道切片，我們就能知道更清楚理解字串字面值：

#![allow(unused)]
fn main() {
let s = "Hello, world!";
}

此處 s 的型別是 &str：它是指向執行檔某部份的切片。這也是為何字串字面值是不可變的，&str 是個不可變參考。

字串切片作為參數

知道你可以取得字面值的切片與 String 數值後，我們可以再改善一次 first_word。也就是它的簽名表現：

fn first_word(s: &String) -> &str {

較富有經驗的 Rustacean 會用範例 4-9 的方式編寫函式簽名，因為這讓該函式可以同時接受 &String 和 &str 的數值。

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // first_word 適用於 `String` 的切片，無論是部分或整體
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);

    let my_string_literal = "hello world";

    // first_word 適用於字串字面值，無論是部分或整體
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // 因為字串字面值本來就是切片
    // 沒有切片語法也是可行的！
    let word = first_word(my_string_literal);
}

範例 4-9：使用字串切片作為參數 s 來改善函式 first_word

如果我們有字串切片的話，我們可以直接傳遞。如果我們有 String 的話，我們可以傳遞此 String 的切片或參考。這樣的彈性用到了強制解參考（deref coercion），這個功能我們會在第十五章的「函式與方法的隱式強制解參考」段落做介紹。

定義函式的參數為字串切片而非 String 可以讓我們的 API 更通用且不會失去任何功能：

檔案名稱：src/main.rs

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // first_word 適用於 `String` 的切片，無論是部分或整體
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);

    let my_string_literal = "hello world";

    // first_word 適用於字串字面值，無論是部分或整體
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // 因為字串字面值本來就是切片
    // 沒有切片語法也是可行的！
    let word = first_word(my_string_literal);
}

其他切片

字串切片如你所想的一樣是特別針對字串的。但是我們還有更通用的切片型別。請考慮以下陣列：

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];
}

就像我們參考一部分的字串一樣，我們可以這樣參考一部分的陣列：

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];

let slice = &a[1..3];

assert_eq!(slice, &[2, 3]);
}

此切片的型別為 &[i32]，它和字串運作的方式一樣，儲存了切片的第一個元素以及總長度。你以後會對其他集合也使用這樣的切片。我們會在第八章討論這些集合的更多細節。

總結

所有權、借用與切片的概念讓 Rust 可以在編譯時期就確保記憶體安全。Rust 程式語言讓你和其他程式語言一樣控制你的記憶體使用方式，但是會在擁有者離開作用域時自動清除擁有的資料，讓你不必再編寫或除錯額外的程式碼。

所有權影響了 Rust 很多其它部分執行的方式，所以我們在書中之後討論這些概念。讓我們繼續到第五章，看看如何用 struct 將資料組合在一起。

透過結構體組織相關資料

struct 或結構體（structure）是個讓你封裝並命名數個相關數值為單一組合的自定型別。如果你熟悉物件導向語言的話，struct 就像是物件的資料屬性。在本章節，我們會比較元組與結構體的差別，介紹如何使用結構體，並討論何時使用結構體組織資料是比較好的選擇。

我們將會解釋如何定義並產生結構體實例，我們也會討論如何定義關聯函式，尤其是叫做方法（method） 的關聯函式，這能指定結構體型別特定的相關型別。結構體與將會在第六章提到的列舉（enum）是 Rust 產生新型別的基本元件，它們能充分利用 Rust 的編譯時型別檢查。

定義與實例化結構體

結構體（Structs）和我們在「元組型別」段落討論過的元組類似，兩者都能持有多種相關數值。和元組一樣，結構體的每個部分可以是不同的型別。但與元組不同的地方是，在結構體中你必須為每個資料部分命名以便表達每個數值的意義。因為有了這些名稱，結構體通常比元組還來的有彈性：你不需要依賴資料的順序來指定或存取實例中的值。

欲定義結構體，我們輸入關鍵字 struct 並為整個結構體命名。結構體的名稱需要能夠描述其所組合出的資料意義。然後在大括號內，我們對每個資料部分定義名稱與型別，我們會稱為欄位（fields）。舉例來說，範例 5-1 定義了一個儲存使用者帳號的結構體。

檔案名稱：src/main.rs

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {}

範例 5-1：User 結構體定義

要在我們定義後使用該結構體，我們可以指定每個欄位的實際數值來建立結構體的實例（instance）。要建立實例的話，我們先寫出結構體的名稱再加上大括號，裡面會包含數個「key: value」的配對。key 是每個欄位的名稱，而 value 就是你想給予欄位的數值。欄位的順序可以不用和定義結構體時的順序一樣。換句話說，結構體的定義比較像是型別的通用樣板，然後實例會依據此樣板插入特定資料來將產生型別的數值。比如說，我們可以像範例 5-2 這樣宣告一個特定使用者。

檔案名稱：src/main.rs

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        email: String::from("[email protected]"),
        username: String::from("someusername123"),
        sign_in_count: 1,
    };
}

範例 5-2：產生一個 User 結構體的實例

要取得結構體中特定數值的話，我們使用句點。如果我們只是想要此使用者的電子郵件信箱，我們使用 user1.email。如果該實例可變的話，我們可以使用句點並賦值給該欄位來改變其值。範例 5-3 顯示了如何改變一個可變 User 實例中 email 欄位的值。

檔案名稱：src/main.rs

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let mut user1 = User {
        active: true,
        email: String::from("[email protected]"),
        username: String::from("someusername123"),
        sign_in_count: 1,
    };

    user1.email = String::from("[email protected]");
}

範例 5-3：改變 User 中 email 欄位的值

請注意整個實例必須是可變的，Rust 不允許我們只標記特定欄位是可變的。再來，就像任何表達式一樣，我們可以在函式本體最後的表達式中，建立一個新的結構體實例作為回傳值。

範例 5-4 展示了 build_user 函式會依據給予的電子郵件和使用者名稱來回傳 User 實例。而 active 欄位取得數值 true 且 sign_in_count 取得數值 1。

檔案名稱：src/main.rs

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        email: email,
        username: username,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("[email protected]"),
        String::from("someusername123"),
    );
}

範例 5-4：build_user 函式取得電子郵件與使用者名稱並回傳 User 實例

函式參數名稱與結構體欄位名稱相同是非常合理的，但是要重複寫 email 和 username 的欄位名稱與變數就有點冗長了。如果結構體有更多欄位的話，重複寫這些名稱就顯得有些煩人了。幸運的是，我們的確有更方便的語法！

用欄位初始化簡寫語法

由於範例 5-4 的參數名稱與結構體欄位名稱相同，我們可以使用欄位初始化簡寫（field init shorthand）語法來重寫 build_user，讓它的結果相同但不必重複寫出 email 和 username，如範例 5-5 所示。

檔案名稱：src/main.rs

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        email,
        username,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("[email protected]"),
        String::from("someusername123"),
    );
}

範例 5-5：build_user 函式使用欄位初始化簡寫，因為參數 username 與 email 結構體欄位相同

在此我們建立了 User 結構體的實例，它有一個欄位叫做 email。我們希望用 build_user 函式中的參數 email 賦值給 email 欄位。然後因為 email 欄位與 email 參數有相同的名稱，我們只要寫 email 就好，不必寫 email: email。

使用結構體更新語法從其他結構體建立實例

通常我們也會從其他的實例來產生新的實例，保留大部分欄位，不過修改一些欄位數值，這時你可以使用結構體更新語法（struct update syntax）。

首先範例 5-6 顯示了我們沒有使用更新語法來建立新的 User 實例 user2。我們設置了新的數值給 email，但其他欄位就使用我們在範例 5-2 建立的 user1 相同的值。

檔案名稱：src/main.rs

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --省略--
    
    let user1 = User {
        email: String::from("[email protected]"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };
    
    let user2 = User {
        active: user1.active,
        username: user1.username,
        email: String::from("[email protected]"),
        sign_in_count: user1.sign_in_count,
    };
}

範例 5-6：從 user1 中建立新的 User 實例

使用結構體更新語法，我們可以用較少的程式碼達到相同的效果，如範例 5-7 所示。.. 語法表示剩下沒指明的欄位都會取得與所提供的實例相同的值。

檔案名稱：src/main.rs

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --省略--

    let user1 = User {
        email: String::from("[email protected]"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        email: String::from("[email protected]"),
        ..user1
    };
}

範例 5-7：對新的 User 實例設置新的 email 數值，但剩下就都使用 user1

範例 5-7 的程式碼產生的 user2 實例有不同 email，但是有與 user1 相同的 username、active 和 sign_in_count。..user1 加在最後面表示任何剩餘的欄位都會與 user1 對應欄位的數值相同，不過我們可以用任意順序指定多少想指定的欄位，不需要與結構體定義欄位的順序一樣。

注意到結構體更新語法和賦值一樣使用 =，這是因為它也會轉移資料，就如同我們在「變數與資料互動的方式：移動」段落看到的一樣。在此範例中，我們在建立 user2 之後就無法再使用 user1，因為 user1 的 username 欄位的 String 被移到 user2 了。如果我們同時給 user2 的 email 與 username 新的 String，這樣 user1 會用到的數值只會有 active 和 sign_in_count，這樣 user1 在 user2 就仍會有效。因為 active 和 sign_in_count 都是有實作 Copy 特徵的型別，所以我們在「變數與資料互動的方式：克隆」段落討論到的行為會造成影響。

使用無名稱欄位的元組結構體來建立不同型別

Rust 還支援定義結構體讓它長得像是元組那樣，我們稱作元組結構體（tuple structs）。元組結構體仍然有定義整個結構的名稱，但是它們的欄位不會有名稱，它們只會有欄位型別而已。元組結構體的用途在於當你想要為元組命名，好讓它跟其他不同型別的元組作出區別，以及對常規結構體每個欄位命名是冗長且不必要的時候。

要定義一個元組結構體，一樣先從 struct 關鍵字開始，其後再接著要定義的元組。舉例來說，以下是兩個使用元組結構體定義的 Color 和 Point：

檔案名稱：src/main.rs

struct Color(i32, i32, i32);
struct Point(i32, i32, i32);

fn main() {
    let black = Color(0, 0, 0);
    let origin = Point(0, 0, 0);
}

注意 black 與 origin 屬於不同型別，因為它們是不同的元組結構體實例。每個你定義的結構體都是專屬於自己的型別，就算它們的欄位型別可能一模一樣。舉例來說，一個參數為 Color 的函式就無法接受 Point 引數，就算它們的型別都是三個 i32 的組合。除此之外，元組結構體實例和元組類似，你可以將它們解構為獨立部分，你也可以使用 . 加上索引來取得每個數值。

無任何欄位的類單元結構體

你也可以定義沒有任何欄位的結構體！這些叫做類單元結構體（unit-like structs），因為它們的行為就很像我們在「元組型別」段落討論過的單元型別（unit type）() 類似。類單元結構體很適合用在當你要實作一個特徵（trait）或某種型別，但你沒有任何需要儲存在型別中的資料。我們會在第十章討論特徵。以下的範例宣告並實例化一個類單元結構體叫做 AlwaysEqual：

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

我們使用 struct 關鍵字定義我們想要的名稱 AlwaysEqual，然後加上分號就好，不必再加任何括號！這樣我們就能一樣用 subject 變數取得一個 AlwaysEqual 的實例：直接使用我們定義的名稱，不用加任何括號。想像一下之後我們可以針對 AlwaysEqual 的實例實作與其他型別實例相同的行爲，像是爲了測試回傳已知的結果。我們不需要任何資料就能實作該行爲！你能在第十章看到如何定義特徵（trait）並對任何型別實作它們，這也包含類單元結構體。

結構體資料的所有權

在範例 5-1 的 User 結構體定義中，我們使用了擁有所有權的 String 型別，而不是 &str 字串切片型別。這邊是故意這樣選擇的，因為我們希望每個結構體的實例可以擁有它所有的資料，並在整個結構體都有效時資料也是有效的。

要在結構體中儲存別人擁有的資料參考是可行的，但這會用到生命週期（lifetimes），我們在第十章才會談到。生命週期能確保資料參考在結構體存在期間都是有效的。要是你沒有使用生命週期來用結構體儲存參考的話，會如以下出錯：

檔案名稱：src/main.rs

struct User {
    active: bool,
    username: &str,
    email: &str,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: "someusername123",
        email: "[email protected]",
        sign_in_count: 1,
    };
}

編譯器會抱怨它需要生命週期標記：

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,
  |

error[E0106]: missing lifetime specifier
 --> src/main.rs:4:12
  |
4 |     email: &str,
  |            ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 |     username: &str,
4 ~     email: &'a str,
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `structs` due to 2 previous errors

在第十章，我們將會討論如何修正這樣的錯誤，好讓你可以在結構體中儲存參考。但現在的話，我們先用有所有權的 String 而非 &str 參考來避免錯誤。

使用結構體的程式範例

為了瞭解我們何時會想要使用結構體，讓我們來寫一支計算長方形面積的程式。我們會先從單一變數開始，再慢慢重構成使用結構體。

讓我們用 Cargo 建立一個新的專案 rectangles ，它將接收長方形的長度與寬度，然後計算出長方形的面積。範例 5-8 展示了在我們專案底下 src/main.rs 用其中一種方式寫出來的小程式。

檔案名稱：src/main.rs

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "長方形的面積為 {} 平方像素。",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

範例 5-8：使用變數 width 和 height 計算長方形面積

現在使用 cargo run 執行程式：

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished dev [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/rectangles`
長方形的面積為 1500 平方像素。

雖然此程式碼成功呼叫 area 函式計算出長方形的面積，但我們可以做得更好，讓程式碼更簡潔且更易閱讀。

此程式碼的問題在 area 的函式簽名就能看出來：

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "長方形的面積為 {} 平方像素。",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

area 函式有寬度與長度兩個參數，可用以計算長方形的面積。但在我們的程式中，其參數相關性卻沒有表達出來。要是能將寬度與長度組合起來的話，會更容易閱讀與管理。我們可以使用我們在第三章提到的「元組型別」。

使用元組重構

範例 5-9 展示了我們的程式用元組的另一種寫法。

檔案名稱：src/main.rs

fn main() {
    let rect1 = (30, 50);

    println!(
        "長方形的面積為 {} 平方像素。",
        area(rect1)
    );
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

範例 5-9：使用元組指定長方形的寬度與長度

一方面來說，此程式的確比較好。元組讓我們增加了一些結構，而我們現在只需要傳遞一個引數。但另一方面來說，此版本的閱讀性反而更差。元組無法命名它的元素，所以我們需要索引部分元組，讓我們的計算變得比較不清晰。

我們在計算面積時，哪個值是寬度還是長度的確不重要。但如果我們要顯示出來的話，這就很重要了！我們會需要記住元組索引 0 是 width 然後元組索引 1 是 height。如果有其他人要維護這段程式碼的話，他就也記住這件事才能使用我們的程式碼。由於我們無法從程式碼表達出資料的意義，它就很容易產生錯誤。

使用結構體重構：賦予更多意義

我們可以用結構體來為資料命名以賦予其意義。我們可以將元組轉換成一個有整體名稱且內部資料也都有名稱的結構體，如範例 5-10 所示。

檔案名稱：src/main.rs

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "長方形的面積為 {} 平方像素。",
        area(&rect1)
    );
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

範例 5-10：定義 Rectangle 結構體

我們在此定義了一個結構體叫做 Rectangle。在大括號內，我們定義了 width 與 height 的欄位，兩者型別皆為 u32。然後在 main 中，我們建立了一個寬度為 30 長度為 50 的 Rectangle 實例。

現在我們的 area 函式使需要一個參數 rectangle，其型別為 Rectangle 結構體實例的不可變借用。如同第四章提到的，我們希望借用結構體而非取走其所有權。這樣一來，main 能保留它的所有權並讓 rect1 繼續使用，這也是為何我們要在要呼叫函式的簽名中使用 &。

area 函式能夠存取 Rectangle 中的 width 與 height 欄位（存取借用結構體實例的欄位不會移動欄位數值，這就是為何你常看到結構體的借用）。我們的 area 函式簽名可以表達出我們想要做的事情了：使用 width 與 height 欄位來計算 Rectangle 的面積。這能表達出寬度與長度之間的關係，並且給了它們容易讀懂的名稱，而不是像元組那樣用索引 0 和 1。這樣清楚多了。

使用推導特徵實現更多功能

現在要是能夠在我們除錯程式時能夠印出 Rectangle 的實例並看到它所有的欄位數值就更好了。範例 5-11 嘗試使用我們之前章節提到的 println! 巨集，但是卻無法執行。

檔案名稱：src/main.rs

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {}", rect1);
}

範例 5-11：嘗試印出 Rectangle 實例

當我們編譯此程式碼時，我們會得到以下錯誤訊息：

error[E0277]: `Rectangle` doesn't implement `std::fmt::Display`

println! 巨集預設可以做各式各樣的格式化，大括號告訴 println! 要使用 Display 特徵的格式化方式：其輸出結果是用來給最終使用者使用的。我們目前遇過的基本型別預設都會實作 Display，因為它們也只有一種顯示方式（像是 1）能夠給使用者。但是對結構體來說 println! 要怎麼格式化輸出結果就會有點不明確了，因為顯示的方式就很有多種。是要加上頓號嗎？是要印出大括號嗎？所有的欄位都要顯示出來嗎？基於這些不確定因素，Rust 不會去猜我們要的是什麼，所以結構體預設並沒有 Display 的實作，也就無法使用 println! 與 {} 佔位符。

如果我們繼續閱讀錯誤訊息，我們會得到一些有幫助的資訊：

   = help: the trait `std::fmt::Display` is not implemented for `Rectangle`
   = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead

讓我們來試試看吧！println! 巨集的呼叫方式現在看起來應該會像這樣 println!("rect1 is {:?}", rect1);。在 println! 內加上 :? 這樣的標記指的是我們想要使用 Debug 特徵來作為輸出格式方式。Debug 特徵讓我們能印出對開發者有幫助的資訊，好讓我們在除錯程式時可以看到它的數值。

但是要是編譯這樣的程式的話，哎呀！我們卻還是會得到錯誤：

error[E0277]: `Rectangle` doesn't implement `Debug`

不過同樣地，編譯器又給了我們有用的資訊：

   = help: the trait `Debug` is not implemented for `Rectangle`
   = note: add `#[derive(Debug)]` to `Rectangle` or manually `impl Debug for Rectangle`

Rust 的確有印出除錯資訊的功能，但是我們要針對我們的結構體顯式實作出來才會有對應的功能。為此我們可以在結構體前加上屬性（attribute） #[derive(Debug)]，如範例 5-12 所示。

檔案名稱：src/main.rs

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

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {:?}", rect1);
}

範例 5-12：加上屬性（attribute）來推導（derive） Debug 特徵的並印出 Rectangle 實例的格式化資訊

現在當我們執行程式，我們不會再得到錯誤了，而且我們可以看到格式化後的輸出結果：

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished dev [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle { width: 30, height: 50 }

漂亮！雖然這不是非常好看的輸出格式，但是它的確顯示了實例中所有的欄位數值，這對我們除錯時會非常有用。不過如果我們的結構體非常龐大的話，我們會希望輸出格式可以比較好閱讀。為此我們可以在 println! 的字串使用 {:#?} 而非 {:?}。在此例中使用 {:#?} 風格的話，輸出結果就會如下：

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished dev [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle {
    width: 30,
    height: 50,
}

另一種使用 Debug 格式印出數值的方式是使用 dbg! 巨集 。這會拿走一個表達式的所有權（相較於 println! 只會拿參考），印出該 dbg! 巨集在程式碼中呼叫的檔案與行數，以及該表達式的數值結果，最後回傳該數值的所有權。

呼叫 dbg! 巨集會顯示到標準錯誤終端串流（stderr），而不像 println! 是印到標準輸出終端串流（stdout）。我們會在第十二章的「將錯誤訊息寫入標準錯誤而非標準輸出」段落進一步討論 stderr 與 stdout。

以下的範例我們印出賦值給 width 的數值，以及整個 rect1 結構體的數值：

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

fn main() {
    let scale = 2;
    let rect1 = Rectangle {
        width: dbg!(30 * scale),
        height: 50,
    };

    dbg!(&rect1);
}

我們在表達式 30 * scale 加上 dbg!，因爲 dbg! 會回傳表達式的數值所有權， width 將能取得和不加上 dbg! 時相同的數值。而我們不希望 dbg! 取走 rect1 的所有權，所以我們在下一個 rect1 的呼叫使用參考。以下是此範例得到的輸出結果：

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished dev [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/rectangles`
[src/main.rs:10] 30 * scale = 60
[src/main.rs:14] &rect1 = Rectangle {
    width: 60,
    height: 50,
}

我們可以看見第一個輸出結果來自 src/main.rs 第十行，也就是我們除錯表達式 30 * scale 的地方，其結果數值爲 60 （整數實作的 Debug 格式只會印出它們的數值）。而在 src/main.rs 第十四行所呼叫的 dbg! 則輸出 &rect1 的數值，也就是 Rectangle 的結構體。此輸出就會使用 Rectangle 實作的 Debug 漂亮格式。當你需要嘗試理解程式碼怎麼運作時，dbg! 巨集可以變得相當實用！

除了 Debug 特徵之外，Rust 還提供了一些特徵能讓我們透過 derive 屬性來使用並爲我們的自訂型別擴增實用的行爲。這些特徵與它們的行爲有列在附錄 C。我們會在第十章介紹如何實作這些特徵的自訂行爲，以及如何建立你自己的特徵。除了 derive 以外也有其他很多屬性，想了解更多資訊的話，請參考 Rust Reference 的「Attributes」段落。

我們的函式 area 最後就非常清楚明白了，它只會計算長方形的面積。這樣的行為要是能夠緊貼著我們的 Rectangle 結構體，因為這樣一來它就不會相容於其他型別。讓我們看看我們如何繼續重構我們的程式碼，接下來我們可以將函式 area 轉換為 Rectangle 型別的方法（method）。

方法語法

方法（Methods）和函式類似，我們用 fn 關鍵字並加上它們名稱來宣告，它們都有參數與回傳值，然後它們包含一些程式碼能夠在其他地方呼叫方法。和函式不同的是，方法是針對結構體定義的（或是列舉和特徵物件，我們會在第六章與第十七章分別介紹它們），且它們第一個參數永遠是 self，這代表的是呼叫該方法的結構體實例。

定義方法

讓我們把 Rectangle 作為參數的 area 函式轉換成定義在 Rectangle 內的 area 方法，如範例 5-13 所示。

檔案名稱：src/main.rs

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "長方形的面積為 {} 平方像素。",
        rect1.area()
    );
}

範例 5-13：在 Rectangle 中定義 area 方法

要定義 Rectangle 中的方法，我們先為 Rectangle 加個 impl（implementation）區塊來開始。所有在此區塊的內容都跟 Rectangle 型別有關。再來將 area 移入 impl 的大括號中，並將簽名中的第一個參數（在此例中是唯一一個）與其本體中用到的地方改成 self。在 main 中我們原先使用 rect1 作為引數呼叫的 area，可以改成使用方法語法（method syntax）來呼叫 Rectangle 的 area 方法。方法語法在實例後面呼叫，我們在其之後加上句點、方法名稱、括號然後任何所需的引數。

在 area 的簽名中，我們使用 &self 而非 rectangle: &Rectangle。&self 是 self: &Self 的簡寫。在一個 impl 區塊內，Self 型別是該 impl 區塊要實作型別的別名。方法必須有個叫做 self 的 Self 型別作為它們的第一個參數，所以 Rust 讓你在寫第一個參數時能直接簡寫成 self。注意到我們在 self 縮寫的前面仍使用 &，已表示此方法是借用 Self 的實例，就像我們在 rectangle: &Rectangle 做的一樣。就和其他參數一樣，方法可以選擇拿走 self 的所有權、像我們這裡借用不可變的 self 或是借用可變的 self。

我們之所以選擇 &self 的原因和我們在之前函式版本的 &Rectangle 一樣，我們不想取得所有權，只想讀取結構體的資料，而非寫入它。如果我們想要透過方法改變實例的數值的話，我們會使用 &mut self 作為第一個參數。而只使用 self 取得所有權的方法更是非常少見，這種使用技巧通常是為了想改變 self 成你想要的樣子，並且希望能避免原本被改變的實例繼續被呼叫。

使用方法而非函式最大的原因是，除了可以使用方法語法而不必在方法簽名重複 self 的型別之外，其更具組織性。我們將所有一個型別所能做的事都放入 impl 區塊中了，而不必讓未來的使用者在茫茫函式庫中尋找 Rectangle 的功能。

另外我們還可以選擇將方法的名稱取作其結構體的其中一個欄位。舉例來說，我們也可以在 Rectangle 定義一個 width 方法：

Filename: src/main.rs

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

impl Rectangle {
    fn width(&self) -> bool {
        self.width > 0
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    if rect1.width() {
        println!("長方形的寬度不為零，而是 {}", rect1.width);
    }
}

這裡我們選擇讓 width 方法判斷實例的 width 是否大於 0：如果是的話回傳 true；如果為 0 的話就回傳 false。我們可以讓欄位與方法擁有相同的名稱，並作為任何用途使用。在 main 中，當我們在 rect1.width 後方加上括號，Rust 就會知道我們指的是 width 方法。當我們沒有使用括號時，Rust 會知道我們指的是 width 欄位。

雖然不是必定的做法，但通常我們將方法名稱與欄位設為一樣時，我們希望它只回傳該欄位的數值而已。像這樣的方法稱為 getter，Rust 並不會像其他語言那樣自動為結構體欄位實作它們。Getter 常用於將欄位隱藏起來，但提供個公開方法並只限讀取該欄位，來做為該型別的公開 API。我們會在第七章討論什麼是公開與私有，以及如何設計方法或欄位為公開或私有的。

-> 運算子跑去哪了？

在 C 與 C++ 中，我們有兩種呼叫方式的運算元：我們會用 . 來直接呼叫物件的方法；用 -> 來呼叫需要先解參考的物件。換句話說，如果 object 是指標的話，object->something() 就會像是(*object).something()。

Rust 沒有提供 -> 這樣的運算子。相反地 Rust 有個功能叫做自動參考與解參考（automatic referencing and dereferencing）。呼叫方法是 Rust 少數會有這樣行為的地方。

運作方式如下：當你呼叫方法像是 object.something() 時，Rust 會自動加上&、&mut 或 *，以便符合方法簽名。換句話說，以下範例是相同的：

#![allow(unused)]
fn main() {
#[derive(Debug,Copy,Clone)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
   fn distance(&self, other: &Point) -> f64 {
       let x_squared = f64::powi(other.x - self.x, 2);
       let y_squared = f64::powi(other.y - self.y, 2);

       f64::sqrt(x_squared + y_squared)
   }
}
let p1 = Point { x: 0.0, y: 0.0 };
let p2 = Point { x: 5.0, y: 6.5 };
p1.distance(&p2);
(&p1).distance(&p2);
}

第一個呼叫簡潔多了，這種自動參考的行為之所以可行是因為方法有明確的 self 參考型別。依據接收者的方法名稱，Rust 可以知道該方法是在讀取（&self）、可變的（&mut self）或是會消耗的（self）。而 Rust 之所以允許借用方法接收者成隱式的原因，是因為這可以讓所有權更易讀懂。

擁有更多參數的方法

讓我們來練習再實作另一個 Rectangle 的方法。這次我們要 Rectangle 的實例可以接收另一個 Rectangle 實例，要是 self 本身（第一個 Rectangle）可以包含另一個 Rectangle 的話我們就回傳 true，不然的話就回傳 false。也就是我們希望定一個方法 can_hold ，如範例 5-14 所示。

檔案名稱：src/main.rs

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("rect1 能容納 rect2 嗎？{}", rect1.can_hold(&rect2));
    println!("rect1 能容納 rect3 嗎？{}", rect1.can_hold(&rect3));
}

範例 5-14：使用一個還沒定義完的方法 can_hold

然後我們預期的輸出結果會如以下所示，因為 rect2 的兩個維度都比 rect1 小，但 rect3 比 rect1 寬：

rect1 能容納 rect2 嗎？true
rect1 能容納 rect3 嗎？false

我們知道我們要定義方法的話，它一定得在 impl Rectangle 區塊底下。方法的名稱會叫做 can_hold。它會取得另一個 Rectangle 的不可變參考作為參數。我們可以從程式碼呼叫方法的地方來知道參數的可能的型別：rect1.can_hold(&rect2) 傳遞了 &rect2，這是一個 rect2 的不可變參考，同時也是 Rectangle 的實例。這是合理的，因為我們只需要讀取 rect2（而不是寫入，寫入代表我們需要可變參考），且我們希望 main 能夠保持 rect2 的所有權，好讓我們之後能在繼續使用它來呼叫 can_hold 方法。can_hold 的回傳值會是布林值，然後實作細節會是檢查 self 的寬度與長度是否都大於其他 Rectangle 的寬度與長度。讓我們加入範例 5-13 的 can_hold 方法到 impl 區塊中，如範例 5-15 所示。

檔案名稱：src/main.rs

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("rect1 能容納 rect2 嗎？{}", rect1.can_hold(&rect2));
    println!("rect1 能容納 rect3 嗎？{}", rect1.can_hold(&rect3));
}

範例 5-15：在 Rectangle 中實作了取得其他 Rectangle 作為參數的 can_hold 方法

當我們用範例 5-14 的 main 函式執行此程式碼的話，我們會得到預期的輸出結果。方法可以在參數 self 之後接收更多參數，而那些參數就和函式中的參數用法一樣。

關聯函式

所有在 impl 區塊內的方法都屬於關聯函式（associated functions），因為它們都與 impl 實作的型別相關。要是有方法不需要自己的型別實例的話，我們可以定義個沒有 self 作為它們第一個參數的關聯函式（因此不會被稱作方法）。我們已經在 String 型別使用過 String::from 這種關聯函式了。

不屬於方法的關聯函式很常用作建構子，來產生新的結構體實例。這通常會叫做 new，但是 new 其實不是特殊名稱，也沒有內建在語言內。舉例來說，我們可以提供一個只接收一個維度作為參數的關聯函式，讓它賦值給寬度與長度，讓我們可以用 Rectangle 來產生正方形，而不必提供兩次相同的值：

檔案名稱：src/main.rs

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

impl Rectangle {
    fn square(size: u32) -> Self {
        Self {
            width: size,
            height: size,
        }
    }
}

fn main() {
    let sq = Rectangle::square(3);
}

回傳型別中與函式本體中的 Self 關鍵字是 impl 關鍵字接著出現的型別別名，在此例中就是 Rectangle。

要呼叫關聯函式的話，我們使用 :: 語法並加上結構體的名稱。比方說 let sq = Rectangle::square(3);。此函式用結構體名稱作為命名空間，:: 語法可以用在關聯函式以及模組的命名空間，我們會在第七章介紹模組。

多重 impl 區塊

每個結構體都允許有數個 impl 區塊。舉例來說，範例 5-15 與範例 5-16 展示的程式碼是一樣的，它讓每個方法都有自己的 impl 區塊。

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("rect1 能容納rect2？{}", rect1.can_hold(&rect2));
    println!("rect1 能容納rect3？{}", rect1.can_hold(&rect3));
}

範例 5-16：使用多重 impl 來重寫範例 5-15

這邊我們的確沒有將方法拆為 impl 區塊的理由，不過這樣的語法是合理的。我們會在第十章介紹泛型型別與特徵，看到多重 impl 區塊是非常實用的案例。

總結

結構體讓你可以自訂對你的領域有意義的型別。使用結構體的話，你可以讓每個資料部分與其他部分具有相關性，並為每個部分讓程式更好讀懂。在 impl 區塊中，你可以定義與你的型別有關的函式，而方法就是其中一種關聯函式，能讓你指定你的結構體能有何種行為。

但是結構體並不是自訂型別的唯一方法：讓我們看下去 Rust 的列舉功能，讓你的工具箱可以再多一項可以使用的工具。

列舉與模式配對

在本章節中，我們將討論列舉（enumerations），有時也被簡寫為 enums。列舉讓你定義一個能夠列舉其可能變體（variants）的型別。首先，我們會定義並使用列舉來展示列舉如何將其數據組織起來。再來，我們會來探討一個特定的實用列舉：Option，其代表該值為某些東西不然就是什麼都沒有。然後我們會看看 match 表達式的模式配對是怎麼運作的，讓它能夠針對列舉中不同數值執行不同的程式碼。最後，我們會介紹 if let 這個結構，來用簡潔又方便的方式處理列舉。

定義列舉

結構體讓你能將相關的欄位與資訊組織在一起，像是 Rectangle 中的 width 與 height，而列舉則是讓你能表達一個數值屬於一組特定數值的其中一種。舉例來說，我們可能想要表達 Rectangle 是其中一種可能的形狀，而這些形狀可能還包括 Circle 與 Triangle。Rust 讓我們能以列舉的形式表現這樣的可能性。

讓我們看一個程式碼表達的例子，來看看為何此時用列舉會比結構體更恰當且實用。假設我們要使用 IP 位址，而且現在有兩個主要的標準能使用 IP 位址：IPv4 與 IPv6。這些是我們的程式碼可能會遇到的 IP 位址，我們可以列舉（enumerate）出所有可能的變體，這正是列舉的由來。

任何 IP 位址可以是第四版或第六版，但不是同時存在。IP 位址這樣的特性非常適合使用列舉資料結構，因為列舉的值只能是其中一個變體。第四版與第六版同時都屬於 IP 位址，所以當有程式碼要處理任何類型的 IP 位址時，它們都應該被視為相同型別。

要表達這樣的概念，我們可以定義 IpAddrKind 列舉和列出 IP 位址可能的類型 V4 和 V6。這些稱為列舉的變體（variants）：

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

IpAddrKind 現在成了能在我們程式碼任何地方使用的自訂資料型別。

列舉數值

我們可以像這樣建立兩個不同變體的 IpAddrKind 實例：

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

注意變體會位於列舉命名空間底下，所以我們用兩個冒號來標示。這樣的好處在於 IpAddrKind::V4 和 IpAddrKind::V6 都是同型別 IpAddrKind。比方說，我們就可以定義一個接收任 IpAddrKind 的函式：

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

然後我們可以用任意變體呼叫此函式：

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

使用列舉還有更多好處。我們再進一步想一下我們的 IP 位址型別還沒有辦法儲存實際的 IP 位址資料，我們現在只知道它是哪種類型。考慮到你已經學會第五章的結構體，你應該會像範例 6-1 這樣嘗試用結構體解決問題。

fn main() {
    enum IpAddrKind {
        V4,
        V6,
    }

    struct IpAddr {
        kind: IpAddrKind,
        address: String,
    }

    let home = IpAddr {
        kind: IpAddrKind::V4,
        address: String::from("127.0.0.1"),
    };

    let loopback = IpAddr {
        kind: IpAddrKind::V6,
        address: String::from("::1"),
    };
}

範例 6-1：使用 struct 儲存 IP 位址的資料與 IpAddrKind 的變體

我們在這裡定義了一個有兩個欄位的結構體 IpAddr：欄位 kind 擁有 IpAddrKind（我們上面定義過的列舉）型別，address 欄位則是 String 型別。再來我們有兩個此結構體的實例。第一個 home 擁有 IpAddrKind::V4 作為 kind 的值，然後位址資料是 127.0.0.1。第二個實例 loopback 擁有 IpAddrKind 另一個變體 V6 作為 kind 的值，且有 ::1 作為位址資料。我們用結構體來組織 kind 和 address 的值在一起，讓變體可以與數值相關。

但是我們可以用另一種更簡潔的方式來定義列舉就好，而不必使用結構體加上列舉。列舉內的每個變體其實都能擁有數值。以下這樣新的定義方式讓 IpAddr 的 V4 與 V6 都能擁有與其相關的 String 數值：

fn main() {
    enum IpAddr {
        V4(String),
        V6(String),
    }

    let home = IpAddr::V4(String::from("127.0.0.1"));

    let loopback = IpAddr::V6(String::from("::1"));
}

我們將資料直接附加到列舉的每個變體上，這樣就不再用結構體。這裏我們還能看到另一項列舉的細節：我們定義的每一個列舉變體也會變成建構該列舉的函式。也就是說 IpAddr::V4() 是個函式，且接收 String 引數並回傳 IpAddr 的實例。我們在定義列舉時就會自動拿到這樣的建構函式。

改使用列舉而非結構體的話還有另一項好處：每個變體可以擁有不同型別與資料的數量。第四版的 IP 位址永遠只會有四個 0 到 255 的數字部分，如果我們想要讓 V4 儲存四個 u8，但 V6 位址仍保持 String 不變的話，我們在結構體是無法做到的。列舉可以輕鬆勝任：

fn main() {
    enum IpAddr {
        V4(u8, u8, u8, u8),
        V6(String),
    }

    let home = IpAddr::V4(127, 0, 0, 1);

    let loopback = IpAddr::V6(String::from("::1"));
}

我們展示了許多種定義儲存第四版與第六版 IP 位址資料結構的方式，不過需要儲存 IP 位址並編碼成不同類型的案例實在太常見了，所以標準函式庫已經幫我們定義好了！讓我們看看標準函式庫是怎麼定義 IpAddr 的：它有和我們一模一樣的列舉變體，不過變體各自儲存的資料是另外兩個不同的結構體，兩個定義的內容均不相同：

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --省略--
}

struct Ipv6Addr {
    // --省略--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

此程式碼展示了你可以將任何資料類型放入列舉的變體中：字串、數字型別、結構體都可以。你甚至可以再包含另一個列舉！另外標準函式庫內的型別常常沒有你想得那麼複雜。

請注意雖然標準函式庫已經有定義 IpAddr，但我們還是可以使用並建立我們自己定義的型別，而且不會產生衝突，因為我們還沒有將標準函式庫的定義匯入到我們的作用域中。我們會在第七章討論如何將型別匯入作用域內。

讓我們再看看範例 6-2 的另一個列舉範例，這次的變體有各式各樣的型別。

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

fn main() {}

範例 6-2：Message 列舉的變體各自擁有不同的型別與數值數量

此列舉有四個不同型別的變體：

• Quit 沒有包含任何資料。
• Move 包含了和結構體一樣的名稱欄位。
• Write 包含了一個 String。
• ChangeColor 包含了三個 i32。

如同範例 6-2 這樣定義列舉變體和定義不同類型的結構體很像，只不過列舉不使用 struct 關鍵字，而且所有的變體都會在 Message 型別底下。以下的結構體可以包含與上方列舉變體定義過的資料：

struct QuitMessage; // 類單元結構體
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // 元組結構體
struct ChangeColorMessage(i32, i32, i32); // 元組結構體

fn main() {}

但是如果我們使用不同結構體且各自都有自己的型別的話，我們就無法像範例 6-2 那樣將 Message 視為單一型別，輕鬆在定義函式時接收訊息所有可能的類型。

列舉和結構體還有一個地方很像：如同我們可以對結構體使用 impl 定義方法，我們也可以對列舉定義方法。以下範例顯示我們可以對 Message 列舉定義一個 call 方法：

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

    impl Message {
        fn call(&self) {
            // 在此定義方法本體
        }
    }

    let m = Message::Write(String::from("hello"));
    m.call();
}

方法本體使用 self 來取得我們呼叫方法的值。在此例中，我們建立了一個變數 m 並取得 Message::Write(String::from("hello"))，而這就會是當我們執行 m.call() 時 call 方法內會用到的 self。

讓我們再看看另一個標準函式庫內非常常見且實用的列舉：Option。

Option 列舉相對於空值的優勢

在此段落我們將來研究 Option，這是在標準函式庫中定義的另一種列舉。Option 廣泛運用在許多場合，它能表示一個數值可能有某個東西，或者什麼都沒有。

舉例來說，如果你向一串包含元素的列表索取第一個值，你會拿到數值，但如果你向空列表索取的話，你就什麼都拿不到。在型別系統中表達這樣的概念可以讓編譯器檢查我們是否都處理完我們該處理的情況了。這樣的功能可以防止其他程式語言中極度常見的程式錯誤。

程式語言設計通常要考慮哪些功能是你要的，但同時哪些功能是你不要的也很重要。Rust 沒有像其他許多語言都有空值。空值（Null）代表的是沒有任何數值。在有空值的語言，所有變數都有兩種可能：空值或非空值。

而其發明者 Tony Hoare 在他 2009 的演講「空參考：造成數十億損失的錯誤」（“Null References: The Billion Dollar Mistake”）中提到：

我稱它為我十億美元級的錯誤。當時我正在為一門物件導向語言設計第一個全方位的參考型別系統。我當時的目標是透過編譯器自動檢查來確保所有的參考都是安全的。但我無法抗拒去加入空參考的誘惑，因為實作的方式實在太簡單了。這導致了無數的錯誤、漏洞與系統崩潰，在接下來的四十年中造成了大概數十億美金的痛苦與傷害。

空值的問題在於，如果你想在非空值使用空值的話，你會得到某種錯誤。由於空值與非空值的特性無所不在，你會很容易犯下這類型的錯誤。

但有時候能夠表達「空（null）」的概念還是很有用的：空值代表目前的數值因為某些原因而無效或缺少。

所以問題不在於概念本身，而在於如何實作。所以 Rust 並沒有空值，但是它有一個列舉可以表達出這樣的概念，也就是一個值可能是存在或不存在的。此列舉就是 Option<T>，它是在標準函式庫中這樣定義的：

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

Option<T> 實在太實用了，所以它早已加進 prelude 中，你不需要特地匯入作用域中。它的變體一樣也被加進 prelude 中，你可以直接使用 Some 和 None 而不必加上 Option:: 的前綴。Option<T> 仍然就只是個列舉， Some(T) 與 None 仍然是Option<T> 型別的變體。

<T> 語法是我們還沒介紹到的 Rust 功能。它是個泛型型別參數，我們會在第十章正式介紹泛型（generics）。現在你只需要知道 <T> 指的是 Option 列舉中的 Some 變體可以是任意型別。而透過 Option 數值來持有數字型別和字串型別的話，它們最終會換掉 Option<T> 中的 T，成為不同的型別。以下是使用 Option 來包含數字與字串型別的範例：

fn main() {
    let some_number = Some(5);
    let some_char = Some('e');

    let absent_number: Option<i32> = None;
}

some_number 的型別是 Option<i32>，而 some_char 的型別是 Option<char>，兩者是不同的型別。Rust 可以推導出這些型別，因為我們已經在 Some 變體指定數值。至於 absent_number 的話，Rust 需要我們寫出完整的 Option 型別，因為編譯器無法從 None 推導出相對應的 Some 變體會持有哪種型別。我們在這裡告訴 Rust 我們 absent_number 所指的型別為 Option<i32>。

當我們有 Some 值時，我們會知道數值是存在的而且就位於 Some 內。當我們有 None 值時，在某種意義上它代表該值是空的，我們沒有有效的數值。所以為何 Option<T> 會比用空值來得好呢？

簡單來說因為 Option<T> 與 T（T 可以是任意型別）是不同的型別，編譯器不會允許我們像一般有效的值那樣來使用 Option<T>。舉例來說，以下範例是無法編譯的，因為這是將 i8 與 Option<i8> 相加：

fn main() {
    let x: i8 = 5;
    let y: Option<i8> = Some(5);

    let sum = x + y;
}

如果我們執行此程式，我們會得到以下錯誤訊息：

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0277]: cannot add `Option<i8>` to `i8`
 --> src/main.rs:5:17
  |
5 |     let sum = x + y;
  |                 ^ no implementation for `i8 + Option<i8>`
  |
  = help: the trait `std::ops::Add<Option<i8>>` is not implemented for `i8`
  = help: the following other types implement trait `Add<Rhs>`:
            <&'a f32 as Add<f32>>
            <&'a f64 as Add<f64>>
            <&'a i128 as Add<i128>>
            <&'a i16 as Add<i16>>
            <&'a i32 as Add<i32>>
            <&'a i64 as Add<i64>>
            <&'a i8 as Add<i8>>
            <&'a isize as Add<isize>>
          and 48 others

For more information about this error, try `rustc --explain E0277`.
error: could not compile `enums` due to previous error

這樣其實很好！此錯誤訊息事實上指的是 Rust 不知道如何將 i8 與 Option<i8> 相加，因為它們是不同的型別。當我們在 Rust 中有個型別像是 i8，編譯器將會確保我們永遠會擁有有效數值。我們可以很放心地使用該值，而不必檢查是不是空的。我們只有在使用 Option<i8> （或者任何其他要使用的型別）時才需要去擔心會不會沒有值。然後編譯器會確保我們在使用該值前，有處理過該有的條件。

換句話說，你必須將 Option<T> 轉換為 T 你才能對 T 做運算。這通常就能幫助我們抓到空值最常見的問題：認為某值不為空，但它其實就是空值。

消除掉非空值是否正確的風險，可以讓你對你寫的程式碼更有信心。要讓一個值變成可能為空的話，你必須顯式建立成對應型別的 Option<T>。然後當你要使用該值時，你就得顯式處理數值是否為空的條件。只要一個數值的型別不是 Option<T>，你就可以安全地認定該值不為空。這是 Rust 刻意考慮的設計決定，限制無所不在的空值，並增強 Rust 程式碼的安全性。

所以當我們有一個數值型別 Option<T>，我們要怎麼從 Some 變體取出 T，好讓我們可以使用該值呢？Option<T> 列舉有大量實用的方法可以在不同的場合下使用。你可以在它的技術文件查閱。更加熟悉 Option<T> 的方法十分益於你接下來的 Rust 旅程。

整體來說，要使用 Option<T> 數值的話，你要讓程式碼可以處理每個變體。你會希望有一些程式碼只會在當我們有 Some(T) 時執行，然後這些程式碼允許使用內部的 T。你會希望有另一部分的程式碼能在只有 None 時執行，且這些程式碼不會拿到有效的 T 數值。match 表達式正是處理此列舉行為的控制流結構：它會針對不同的列舉變體執行不同的程式碼，而且程式碼可以使用配對到的數值資料。

match 控制流建構子

Rust 有個功能非常強大的控制流建構子叫做 match，你可以使用一系列模式來配對數值並依據配對到的模式來執行對應的程式。模式（Patterns）可以是字面數值、變數名稱、萬用字元（wildcards）和其他更多元件來組成。第十八章會涵蓋所有不同類型的模式，以及它們的用途。match 強大的地方在於模式表達的清楚程度以及編譯器會確保所有可能的情況都處理了。

你可以想像 match 表達式成一個硬幣分類機器：硬幣會滑到不同大小的軌道，然後每個硬幣會滑入第一個符合大小的軌道。同樣地，數值會依序遍歷 match 的每個模式，然後進入第一個「配對」到該數值的模式所在的程式碼區塊，並在執行過程中使用。

既然我們都提到硬幣了，就讓我們用它們來作為 match 的範例吧！我們可以寫一個接收未知美國硬幣的函式，以類似驗鈔機的方式，決定它是何種硬幣並以美分作為單位回傳其值。如範例 6-3 所示。

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

範例 6-3：列舉以及用列舉變體作為模式的 match 表達式

讓我們一一介紹 value_in_cents 函式中 match 的每個部分。首先我們使用 match 並加上一個表達式，在此例的話就是指 coin。這和 if 中條件表達式的用法很像。不過差別在於 if 中的條件必須是布林值，而在此它可以回傳任何型別。在此範例中 coin 的型別是我們在第一行定義的列舉 Coin。

接下來是 match 的分支，每個分支有兩個部分：一個模式以及對應的程式碼。這邊第一個分支的模式是 Coin::Penny 然後 => 會將模式與要執行的程式碼分開來，而在此例的程式碼就只是個 1。每個分支之間由逗號區隔開來。

當 match 表達式執行時，他會將計算的數據結果依序與每個分支的模式做比較。如果有模式配對到該值的話，其對應的程式碼就會執行。如果該模式與數值不符的話，就繼續執行下一個分支，就像硬幣分類機器。

每個分支對應的程式碼都是表達式，然後在配對到的分支中表達式的數值結果就會是整個 match 表達式的回傳值。

如果配對分支的程式碼很短的話，我們通常就不會用到大括號，像是範例 6-3 每個分支就只回傳一個數值。如果你想要在配對分支執行多行程式碼的話，你就必須用大括號，然後你可以在括號後選擇性加上逗號。舉例來說，以下程式會在每次配對到 Coin::Penny 時印出「幸運幣！」再回傳程式碼區塊最後的數值 1：

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("幸運幣！");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

綁定數值的模式

另一項配對分支的實用功能是它們可以綁定配對模式中部分的數值，這讓我們可以取出列舉變體中的數值。

舉例來說，讓我們改變我們其中一個列舉變體成擁有資料。從 1999 年到 2008 年，美國在鑄造 25 美分硬幣時，其中一側會有 50 個州不同的設計。不過其他的硬幣就沒有這樣的設計，只有 25 美分會有特殊值而已。我們可以改變我們的 enum 中的 Quarter 變體成儲存 UsState 數值，如範例 6-4 所示。

#[derive(Debug)] // 這讓我們可以顯示每個州
enum UsState {
    Alabama,
    Alaska,
    // --省略--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

範例 6-4：修改 Coin 列舉的 Quarter 變體來包含一個 UsState 數值

讓我們想像有一個朋友想要收集所有 50 州的 25 美分硬幣。當我們在排序零錢的同時，我們會在拿到 25 美分時喊出該硬幣對應的州，好讓我們的朋友知道，如果他沒有的話就可以納入收藏。

在此程式中的配對表達式中，我們在 Coin::Quarter 變體的配對模式中新增了一個變數 state。當 Coin::Quarter 配對符合時，變數 state 會綁定該 25 美分的數值，然後我們就可以在分支程式碼中使用 state，如以下所示：

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --省略--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("此 25 美分所屬的州為 {:?}!", state);
            25
        }
    }
}

fn main() {
    value_in_cents(Coin::Quarter(UsState::Alaska));
}

如果我們呼叫 value_in_cents(Coin::Quarter(UsState::Alaska)) 的話，coin 就會是 Coin::Quarter(UsState::Alaska)。當我們比較每個配對分支時，我們會到 Coin::Quarter(state) 的分支才配對成功。此時 state 綁定的數值就會是 UsState::Alaska。我們就可以在 println! 表達式中使用該綁定的值，以此取得 Coin 列舉中 Quarter 變體內的值。

配對 Option<T>

在上一個段落，我們想要在使用 Option<T> 時取得 Some 內部的 T 值。如同列舉 Coin，我們一樣可以使用 match 來處理 Option<T>！相對於比較硬幣，我們要比較的是 Option<T> 的變體，不過 match 表達式運作的方式一模一樣。

假設我們要寫個接受 Option<i32> 的函式，而且如果內部有值的話就將其加上 1。如果內部沒有數值的話，該函式就回傳 None 且不再嘗試做任何動作。

拜 match 所賜，這樣的函式很容易寫出來，長得就像範例 6-5。

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

範例 6-5：對 Option<i32> 使用 match 表達式的函式

讓我們來仔細分析 plus_one 第一次的執行結果。當我們呼叫 plus_one(five) 時，plus_one 本體中的變數 x 會擁有 Some(5)。我們接著就拿去和每個配對分支比較：

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Some(5) 並不符合 None 這樣的模式，所以我們繼續進行下一個分支：

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Some(5) 有符合 Some(i) 這樣的模式嗎？這是當然的囉！我們有相同的變體。i 會綁定 Some 中的值，所以 i 會取得 5。接下來配對分支中的程式碼就會執行，我們將 1 加入 i 並產生新的 Some 其內部的值就會是 6。

現在讓我們看看範例 6-5 第二次的 plus_one 呼叫，這次的 x 是 None。我們進入 match 然後比較第一個分支：

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

配對成功！因為沒有任何數值可以相加，程式就停止並在 => 之後馬上回傳 None。因為第一個分支就配對成功了，沒有其他的分支需要再做比較。

用 match 與列舉組合起來在很多地方都很實用。你將會在許多 Rust 程式碼看到這樣的模式，使用 match 配對列舉，綁定內部的資料，然後執行對應的程式碼。一開始使用的確會有點陌生，但當你熟悉以後，你會希望所有語言都能提供這樣的功能。這一直是使用者最愛的功能之一。

配對必須是徹底的

我們還有一個 match 的細節要討論：分支的模式必須涵蓋所有可能性。今天要是我們像這樣寫了一個有錯誤的 plus_one 函式版本，它會無法編譯：

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

我們沒有處理到 None 的情形，所以此程式碼會產生錯誤。幸運的是這是 Rust 能夠抓到的錯誤。如果我們嘗試編譯此程式的話，我們會得到以下錯誤：

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` not covered
 --> src/main.rs:3:15
  |
3 |         match x {
  |               ^ pattern `None` not covered
  |
note: `Option<i32>` defined here
  = note: the matched value is of type `Option<i32>`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
  |
4 ~             Some(i) => Some(i + 1),
5 ~             None => todo!(),
  |

For more information about this error, try `rustc --explain E0004`.
error: could not compile `enums` due to previous error

Rust 發現我們沒有考慮到所有可能條件，而且還知道我們少了哪些模式！Rust 中的配對必須是徹底（exhaustive）的：我們必須列舉出所有可能的情形，程式碼才能夠被視為有效。尤其是在 Option<T> 的情況下，當 Rust 防止我們忘記處理 None 的情形時，它也使我們免於以為擁有一個有效實際上卻是空的值。因此要造成之前提過的十億美元級錯誤在這邊基本上是不可能的。

Catch-all 模式與 _ 佔位符

使用列舉的話，我們可以針對特定數值作特別的動作，而對其他所有數值採取預設動作。想像一下我們正在做款骰子遊戲，如果你骰出 3 的話，你的角色就動不了，但是可以拿頂酷炫的帽子。如果你骰出 7 你的角色就損失那頂帽子。至於其他的數值，你的角色就按照那個數值在遊戲桌上移動步數。以下是用 match 實作出的邏輯，骰子的結果並非隨機數而是寫死的，且所有邏輯對應的函式本體都是空的，因為實際去實作並非本範例的重點：

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        other => move_player(other),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn move_player(num_spaces: u8) {}
}

在前兩個分支中的模式分別為數值 3 和 7。至於最後一個涵蓋其他可能數值的分支，我們用變數 other 作為模式。在 other 分支執行的程式碼會將該變數傳入函式 move_player 中。

此程式碼就算我們沒有列完所有 u8 可能的數字也能編譯完成，因為最後的模式會配對所有尚未被列出來的數值。這樣的 catch-all 模式能滿足 match 必須要徹底的要求。注意到我們需要將 catch-all 分支放在最後面，因為模式是按照順序配對的。如果我們將 catch-all 放在其他分支前的話，這樣一來其他後面的分支就永遠配對不到了，所以要是我們在 catch-all 之後仍加上分支的話 Rust 會警告我們！

當我們想使用 catch-all 模式但不想使用其數值時，Rust 還有一種模式能讓我們使用：_ 這是個特殊模式，用來配對任意數值且不綁定該數值。這告訴 Rust 我們不會用到該數值，所以 Rust 不會警告我們沒使用到變數。

讓我們來改變一下遊戲規則：如果你骰到除了 3 與 7 以外的話，你必須要重新擲骰。我們不需要用到 catch-all 的數值，所以我們可以修改我們的程式碼來使用 _，而不必繼續用變數 other：

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => reroll(),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn reroll() {}
}

此範例一樣也滿足徹底的要求，因為我們在最後的分支顯式地忽略其他所有數值，我們沒有遺漏任何值。

我們再改最後一次遊戲規則，改成如果你骰到除了 3 與 7 以外，不會有任何事發生的話，我們可以用單元數值（我們在元組型別段落提到的空元組）作為 _ 的程式碼：

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => (),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
}

這裡我們顯式地告訴 Rust 我們不會使用任何其他沒被先前分支配對到的數值，而且我們也不想在此執行任何程式碼。

我們會在第十八章更進一步探討模式與配對，現在我們要先去看看 if let 語法。當 match 表達式變得太囉嗦時，這語法就會變得很有用。

透過 if let 簡化控制流

if let 語法讓你可以用 if 與 let 的組合來以比較不冗長的方式，來處理只在乎其中一種模式而忽略其餘的數值。現在考慮一支程式如範例 6-6 所示，我們在配對 config_max 中 Option<u8> 的值，但只想在數值為 Some 變體時執行程式。

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("最大值被設為 {}", max),
        _ => (),
    }
}

範例 6-6：match 只在數值為 Some 時執行程式

如果數值為 Some，我們就在分支中綁定 max 變數，印出 Some 變體內的數值。我們不想對 None 作任何事情。為了滿足 match 表達式，我們必須在只處理一種變體的分支後面，再加上 _ => ()。這樣就加了不少樣板程式碼。

不過我們可以使用 if let 以更精簡的方式寫出來，以下程式碼的行為就與範例 6-6 的 match 一樣：

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("最大值被設為 {}", max);
    }
}

if let 接收一個模式與一個表達式，然後用等號區隔開來。它與 match 的運作方式相同，表達式的意義與 match 相同，然後前面的模式就是第一個分支。 在此例中的模式就是 Some(max)，然後 max 會綁定 Some 內的數值。我們就和 match 分支中使用 max 一樣，在 if let 區塊的本體中使用 max。如果數值沒有配對到模式，if let 中的程式碼就不會執行。

使用 if let 可以少打些字、減少縮排以及不用寫多餘的樣板程式碼。不過你就少了 match 強制的徹底窮舉檢查。要何時選擇 match 還是 if let 得依據你在的場合是要做什麼事情，以及在精簡度與徹底檢查之間做取捨。

換句話說，你可以想像 if let 是 match 的語法糖（syntax sugar），它只會配對一種模式來執行程式碼並忽略其他數值。

我們也可以在 if let 之後加上 else，else 之後的程式碼區塊等同於 match 表達式中 _ 情形的程式碼區塊。這樣一來的 if let 和 else 組合就等同於 match 了。回想一下範例 6-4 的 Coin 列舉定義， Quarter 變體擁有數值 UsState。如果我們希望統計所有不是 25 美分的硬幣的同時，也能繼續回報 25 美分所屬的州的話，我們可以用 match 像這樣寫：

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --省略--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    match coin {
        Coin::Quarter(state) => println!("此 25 美分所屬的州為 {:?}!", state),
        _ => count += 1,
    }
}

或是我們也可以用 if let 和 else 表達式這樣寫：

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --省略--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    if let Coin::Quarter(state) = coin {
        println!("此 25 美分所屬的州為 {:?}!", state);
    } else {
        count += 1;
    }
}

如果你的程式碼邏輯遇到使用 match 表達會太囉唆的話，記得 if let 也在你的 Rust 工具箱中供你使用。

總結

我們現在涵蓋了如何使用列舉來建立一系列列舉數值的自訂型別。我們展示了標準函式庫的 Option<T> 型別如何用型別系統來預防錯誤。當列舉數值其內有資料時，你可以依照你想處理的情況數量，使用 match 或 if let 來取出並使用那些數值。

你的 Rust 程式碼現在能夠使用結構體與列舉來表達你所相關研究領域的概念了。在你的 API 建立自訂型別可以確保型別安全，編譯器會保證你的函式只會取得該函式預期的型別數值。

接下來為了提供組織完善且直觀的的 API 供你的使用者使用，並只表達出使用者確切所需要的內容，我們需要瞭解 Rust 的模組。

透過套件、Crate 與模組管理成長中的專案

當你寫的程式規模更大時，組織你的程式碼就很重要。因為用你的腦袋要記住整個程式碼是幾乎不可能的。要是能組織相關功能的程式碼並將它們分成明確功能的話，你就能清楚地找到實作特定功能的程式碼，以及該在哪裏修改該功能的行為。

我們之前寫過的程式都只在一個檔案內的一個模組（module）中。隨著專案成長，我們應該要組織程式碼，拆成數個模組與數個檔案。一個套件（package）可以包含數個執行檔 crate 以及選擇性提供一個函式庫 crate。隨著套件增長，你可以取出不同的部分作為獨立的 crate，成為對外的依賴函式庫。此章節將會介紹這些所有概念。對於非常龐大的專案，需要一系列的關聯套件組合在一起的話，Cargo 有提供工作空間（workspaces），我們會在第十四章的「Cargo 工作空間」做介紹。

我們還會討論對實作細節進行封裝，讓你的程式碼在頂層更好使用。一旦你實作了某項功能，其他程式就可以用程式碼的公開介面呼叫該程式碼，而不必去知道它實作如何運作。你在寫程式碼時會去定義哪些部分是給其他程式碼公開使用的，以及哪些部分是私底下你可以任意修改的實作細節。這能再減少你的腦袋需要煩惱的細節數量。

還有一個概念需要再提一次，也就是作用域（scope）：程式碼需要能被定義在「作用域內」並要能夠指明此作用域。當讀取寫入或編譯程式碼時，程式設計師與編譯器需要知道特定地點的名稱，才能知道其內的變數、函式、結構體、列舉、常數或其他任何有意義的項目。你可以建立作用域，並改變其在作用域內與作用域外的名稱。你無法在同個作用域內擁有兩個相同名稱的項目。我們可以使用一些工具來解決名稱衝突的問題。

Rust 有一系列的功能能讓你管理你的程式碼組織，包含哪些細節能對外提供、哪些細節是私有的，以及程式中每個作用域的名稱為何。這些功能有時會統一稱作模組系統（module system），其中包含：

• 套件（Package）： 讓你建構、測試並分享 crate 的 Cargo 功能
• Crates： 產生函式庫或執行檔的模組集合
• 模組（Modules）與 use： 讓你控制組織、作用域與路徑的隱私權
• 路徑（Paths）: 對一個項目的命名方式，像是一個結構體、函式或模組

在本章節中，我們會涵蓋所有這些功能，討論它們如何互動，並解釋如何使用它們來管理作用域。在讀完後，你應該就會對模組系統有紮實的認知，並能夠對作用域的使用駕輕就熟！

套件與 Crates

首先我們要介紹的第一個模組系統部分為套件與 crates。

一個 crate 是 Rust 編譯器同個時間內視為程式碼的最小單位。就算你執行的是 rustc 而非 cargo，然後傳入單一源碼檔案（就像我們在第一章的「編寫並執行 Rust 程式」那樣），編譯器會將該檔案視為一個 crate。Crate 能包含模組，而模組可以在其他檔案中定義然後同時與 crate 一起編譯，我們會在接下來的段落看到。

一個 crate 可以有兩種形式：執行檔 crate 或函式庫 crate。執行檔（Binary）crate 是種你能編譯成執行檔並執行的程式，像是命令列程式或伺服器。這種 crate 需要有一個函式 main 來定義執行檔執行時該做什麼事。目前我們建立的所有 crate 都是執行檔 crate。

函式庫（Library）crate 則不會有 main 函式，而且它們也不會編譯成執行檔。這種 crate 定義的功能用來分享給多重專案使用。舉例來說，我們在第二章用到的 rand crate 就提供了產生隨機數值的功能。當大多數的 Rustacean 講到「crate」時，他們其實指的是函式庫 crate，所以他們講到「crate」時相當於就是在講其他程式語言概念中的「函式庫」。

crate 的源頭會是一個原始檔案，讓 Rust 的編譯器可以作為起始點並組織 crate 模組的地方（我們會在「定義模組來控制作用域與隱私權」的段落更加解釋模組）。

套件（package）則是提供一系列功能的一或數個 crate。一個套件會包含一個 Cargo.toml 檔案來解釋如何建構那些 crate。Cargo 本身其實就是個套件，包含了你已經用來建構程式碼的命令列工具。Cargo 套件還包含執行檔 crate 需要依賴的函式庫 crate。其他專案可以依賴 Cargo 函式庫來使用與 Cargo 命令列工具用到的相同邏輯功能。

一個套件能依照你的喜好擁有數個執行檔 crate，但最多只能有一個函式庫 crate。而一個套件至少要有一個 crate，無論是函式庫或執行檔 crate。

讓我們看看當我們建立一個套件時發生了什麼事。首先我們先輸入 cargo new 命令：

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

在我們執行 cargo new 之後，我們使用 ls 來查看 Cargo 建立了什麼。在專案的目錄中會有個 Cargo.toml 檔案，這是套件的設定檔。然後還會有個 src 目錄底下包含了 main.rs。透過你的文字編輯器打開 Cargo.toml，你會發現沒有提到 src/main.rs。Cargo 遵循的常規是 src/main.rs 就是與套件同名的執行檔 crate 的 crate 源頭。同樣地，Cargo 也會知道如果套件目錄包含 src/lib.rs的話，則該套件就會包含與套件同名的函式庫 crate。Cargo 會將 crate 源頭檔案傳遞給 rustc 來建構函式庫或執行檔。

我們在此的套件只有包含 src/main.rs 代表它只有一個同名的執行檔 crate 叫做 my-project。如果套件包含 src/main.rs 與 src/lib.rs 的話，它就有兩個 crate：一個執行檔與一個函式庫，兩者都與套件同名。一個套件可以有多個執行檔 crate，只要將檔案放在 src/bin 目錄底下就好，每個檔案會被視為獨立的執行檔 crate。

定義模組來控制作用域與隱私權

在此段落，我們將討論模組以及其他模組系統的部分，像是路徑（paths）允許你來命名項目，而 use 關鍵字可以將路徑引入作用域，再來 pub 關鍵字可以讓指定的項目對外公開。我們還會討論到 as 關鍵字、外部套件以及全域（glob）運算子。

首先，讓我們先介紹一些規則好讓你在之後組織程式碼時能更容易理解初步概念。然後我們會再詳細解釋每個規則。

模組懶人包

這裡我們先快速帶過模組、路徑、use 關鍵字以及 pub 關鍵字在編譯器中是怎麼運作的，以及多數開發者會怎麼組織他們的程式碼。我們會在此章節透過範例逐依介紹，不過這裡能讓你快速理解模組是怎麼運作的。

• 從 crate 源頭開始：在編譯 crate 時，編譯器會先尋找 crate 源頭檔案（函式庫 crate 的話，通常就是 src/lib.rs；執行檔 crate 的話，通常就是 src/main.rs）來編譯程式碼。
• 宣告模組：在 crate 源頭檔案中，你可以宣告新的模組，比如說你宣告了一個「garden」模組 mod garden;。編譯器會在以下這幾處尋找模組的程式碼：
  • 同檔案內用 mod garden 加上大括號，寫在括號內的程式碼
  • src/garden.rs 檔案中
  • src/garden/mod.rs 檔案中
• 宣告子模組：除了 crate 源頭以外，其他檔案也可以宣告子模組。舉例來說，你可能會在 src/garden.rs 中宣告個 mod vegetables;。編譯器會與當前模組同名的目錄底下這幾處尋找子模組的程式碼：
  • 同檔案內，直接用 mod vegetables 加上大括號，寫在括號內的程式碼
  • src/garden/vegetables.rs 檔案中
  • src/garden/vegetables/mod.rs 檔案中
• 模組的路徑：一旦有個模組成為 crate 的一部分，只要隱私權規則允許，你可以在 crate 裡任何地方使用該模組的程式碼。舉例來說，「garden」模組底下的「vegetables」模組的 Asparagus 型別可以用 crate::garden::vegetables::Asparagus 來找到。
• 私有 vs 公開：模組內的程式碼從上層模組來看預設是私有的。要公開的話，將它宣告為 pub mod 而非只是 mod。要讓公開模組內的項目也公開的話，在這些項目前面也加上 pub 即可。
• use 關鍵字：在一個作用域內，use 關鍵字可以建立項目的捷徑，來縮短冗長的路徑名稱。在任何能使用 crate::garden::vegetables::Asparagus 的作用域中，你可以透過 use crate::garden::vegetables::Asparagus; 來建立捷徑，接著你只需要寫 Asparagus 就能在作用域內使用該型別了。

這裡我們建立個執行檔 crate 叫做 backyard 來展示這些規則。Crate 的目錄也叫做 backyard，其中包含了這些檔案與目錄：

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

此例的 crate 源頭檔案就是 src/main.rs，它包含了：

檔案名稱：src/main.rs

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {:?}!", plant);
}

pub mod garden; 這行告訴編譯器要包含在 src/garden.rs 中的程式碼，也就是：

檔案名稱：src/garden.rs

pub mod vegetables;

這裡的 pub mod vegetables; 代表 src/garden/vegetables.rs 的程式碼也包含在內。而這段程式碼就是：

#[derive(Debug)]
pub struct Asparagus {}

現在讓我們詳細介紹這些規則並解釋如何運作的吧！

組織相關程式碼成模組

模組（Modules）能讓我們在 crate 內組織程式碼成數個群組以便使用且增加閱讀性。模組也能控制項目的隱私權，因為模組內的程式碼預設是私有的。私有項目是內部的實作細節，並不打算讓外部能使用。我們能讓模組與其內的項目公開，讓外部程式碼能夠使用並依賴它們。

舉例來說，讓我們建立一個提供餐廳功能的函式庫 crate。我們定義一個函式簽名不過本體會是空的，好讓我們專注在程式組織，而非餐廳程式碼的實作。

在餐飲業中，餐廳有些地方會被稱作前台（front of house）而其他部分則是後台（back of house）。前台是消費者的所在區域，這裡是安排顧客座位、點餐並結帳、吧台調酒的地方。而後台則是主廚與廚師工作的廚房、洗碗工洗碗以及經理管理行政工作的地方。

要讓 crate 架構長這樣的話，我們可以組織函式進入模組中。要建立一個新的函式庫叫做 restaurant 的話，請執行 cargo new --lib restaurant。然後將範例 7-1 的程式碼放入 src/lib.rs 中，這定義了一些模組與函式簽名。以下是前台的段落：

檔案名稱：src/lib.rs

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

範例 7-1：front_of_house 模組包含了其他擁有函式的模組

我們用 mod 關鍵字加上模組的名稱（在此例為 front_of_house）來定義一個模組，並用大括號涵蓋模組的本體。在模組中，我們可以再包含其他模組，在此例中我們包含了 hosting 和 serving。模組還能包含其他項目，像是結構體、列舉、常數、特徵、以及像是範例 7-1 的函式。

使用模組的話，我們就能將相關的定義組合起來，並用名稱指出會與它們互相關聯。程式設計師在使用此程式碼時只要觀察依據組合起來的模組名稱就好，不必遍歷所有的定義。這樣就能快速找到他們想使用的定義。要對此程式碼增加新功能的開發者也能知道該將程式碼放在哪裡，以維持程式碼的組織。

稍早我們提到說 src/main.rs 和 src/lib.rs 屬於 crate 的源頭。之所以這樣命名的原因是因為這兩個文件的內容都會在 crate 源頭模組架構中組成一個模組叫做 crate，這樣的結構稱之為模組樹（module tree）。

範例 7-2 顯示了範例 7-1 的模組樹架構。

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

範例 7-2：範例 7-1 的模組樹

此樹顯示了有些模組是包含在其他模組內的，比方說 hosting 就在 front_of_house 底下。此樹也顯示了有些模組是其他模組的同輩（siblings），代表它們是在同模組底下定義的，hosting 和 serving 都在 front_of_house 底下定義。如果模組 A 被包含在模組 B 中，我們會說模組 A 是模組 B 的下一代（child），而模組 B 是模組 A 的上一代（parent）。注意到整個模組樹的根是一個隱性模組叫做 crate。

模組樹可能會讓你想到電腦中檔案系統的目錄樹，這是一個非常恰當的比喻！就像檔案系統中的目錄，你使用模組來組織你的程式碼。而且就像目錄中的檔案，我們需要有方法可以找到我們的模組。

參考模組項目的路徑

要展示 Rust 如何從模組樹中找到一個項目，我們要使用和查閱檔案系統時一樣的路徑方法。要呼叫函式的話，我們需要知道它的路徑：

路徑可以有兩種形式：

• 絕對路徑（absolute path）是從 crate 的源頭起始的完整路徑。如果是外部 crate 的話，絕對路徑起始於該 crate 的名稱；如果是當前 crate 的話，則是 crate 作為起頭。
• 相對路徑（relative path）則是從本身的模組開始，使用 self、super 或是當前模組的標識符（identifiers）。

無論是絕對或相對路徑其後都會接著一或多個標識符，並使用雙冒號（::）區隔開來。

回頭看看範例 7-1，假設我們想呼叫函式 add_to_waitlist。這就像在問函式 add_to_waitlist 的路徑在哪？範例 7-3 移除了一些範例 7-1 的模組與函式來精簡程式碼的呈現方式。

我們會展示兩種從 crate 源頭定義的 eat_at_restaurant 函式內呼叫 add_to_waitlist 的方法。這些路徑是正確的，不過目前還有其他問題會導致此範例無法編譯，我們會在稍後說明。

eat_at_restaurant 函式是我們函式庫 crate 公開 API 的一部分，所以我們會加上 pub 關鍵字。在「使用 pub 關鍵字公開路徑」的段落中，我們會提到更多 pub 的細節。

檔案名稱：src/lib.rs

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // 絕對路徑
    crate::front_of_house::hosting::add_to_waitlist();

    // 相對路徑
    front_of_house::hosting::add_to_waitlist();
}

範例 7-3：使用絕對與相對路徑呼叫 add_to_waitlist 函式

我們在 eat_at_restaurant 中第一次呼叫 add_to_waitlist 函式的方式是用絕對路徑。add_to_waitlist 函式和 eat_at_restaurant 都是在同一個 crate 底下，所以我們可以使用 crate 關鍵字來作為絕對路徑的開頭。我們接續加上對應的模組直到抵達 add_to_waitlist。你可以想像一個有相同架構的檔案系統，然後我們指定 /front_of_house/hosting/add_to_waitlist 這樣的路徑來執行 add_to_waitlist 程式。使用 crate 這樣的名稱作為 crate 源頭的開始，就像在你的 shell 使用 / 作為檔案系統的根一樣。

而我們第二次在 eat_at_restaurant 呼叫 add_to_waitlist 的方式是使用相對路徑。路徑的起頭是 front_of_house，因為它和 eat_at_restaurant 都被定義在模組樹的同一層中。這裡相對應的檔案系統路徑就是 front_of_house/hosting/add_to_waitlist。使用一個模組名稱作為開頭通常就是代表相對路徑。

何時該用相對或絕對路徑是你在你的專案中要做的選擇，依照你想將程式碼的定義連帶與使用它們的程式碼一起移動，或是分開移動到不同地方。舉例來說，如果我們同時將 front_of_house 模組和 eat_at_restaurant 函式移入另一個模組叫做 customer_experience 的話，就會需要修改 add_to_waitlist 的絕對路徑，但是相對路徑就可以原封不動。而如果我們只單獨將 eat_at_restaurant 函式移入一個叫做 dining 模組的話，add_to_waitlist 的絕對路徑就不用修改，但相對路徑就需要更新。我們通常會傾向於指定絕對路徑，因為分別移動程式碼定義與項目呼叫的位置通常是比較常見的。

讓我們嘗試編譯範例 7-3 並看看為何不能編譯吧！以下範例 7-4 是我們得到的錯誤資訊。

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: module `hosting` is private
 --> src/lib.rs:9:28
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                            ^^^^^^^ private module
  |
note: the module `hosting` is defined here
 --> src/lib.rs:2:5
  |
2 |     mod hosting {
  |     ^^^^^^^^^^^

error[E0603]: module `hosting` is private
  --> src/lib.rs:12:21
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                     ^^^^^^^ private module
   |
note: the module `hosting` is defined here
  --> src/lib.rs:2:5
   |
2  |     mod hosting {
   |     ^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` due to 2 previous errors

範例 7-4：範例 7-3 嘗試編譯程式碼出現的錯誤

錯誤訊息表示 hosting 模組是私有的。換句話說，我們指定 hosting 模組與 add_to_waitlist 函式的路徑是正確的，但是因為它沒有私有部分的存取權，所以 Rust 不讓我們使用。在 Rust 中所有項目（函式、方法、結構體、列舉、模組與常數）的隱私權都是私有的。如果你想要建立私有的函式或結構體，你可以將它們放入模組內。

上層模組的項目無法使用下層模組的私有項目，但下層模組能使用它們上方所有模組的項目。這麼做的原因是因為下層模組用來實現實作細節，而下層模組應該要能夠看到在自己所定義的地方的其他內容。讓我們繼續用餐廳做比喻的話，我們可以想像隱私權規則就像是餐廳的後台辦公室。對餐廳顧客來說裡面發生什麼事情都是未知的，但是辦公室經理可以知道經營餐廳時的所有事物。

Rust 選擇這樣的模組系統，讓內部實作細節預設都是隱藏起來的。這樣一來，你就能知道內部哪些程式碼需要修改，而不會破壞到外部的程式碼。不過 Rust 有提供 pub 關鍵字能讓項目公開，讓你可以將下層模組內部的一些程式碼公開給上層模組來使用。

使用 pub 關鍵字公開路徑

讓我們再執行一次範例 7-4 的錯誤，它告訴我們 hosting 模組是私有的。我們希望上層模組中的 eat_at_restaurant 函式可以呼叫下層模組的 add_to_waitlist 函式，所以我們將 hosting 模組加上 pub 關鍵字，如範例 7-5 所示。

檔案名稱：src/lib.rs

mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // 絕對路徑
    crate::front_of_house::hosting::add_to_waitlist();

    // 相對路徑
    front_of_house::hosting::add_to_waitlist();
}

範例 7-5：宣告 hosting 模組為 pub 好讓 eat_at_restaurant 可以使用

不幸的是範例 7-5 的程式碼仍然回傳了另一個錯誤，如範例 7-6 所示。

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
 --> src/lib.rs:9:37
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                                     ^^^^^^^^^^^^^^^ private function
  |
note: the function `add_to_waitlist` is defined here
 --> src/lib.rs:3:9
  |
3 |         fn add_to_waitlist() {}
  |         ^^^^^^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:12:30
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
3  |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` due to 2 previous errors

範例 7-6：編譯範例 7-5 時產生的錯誤

到底發生了什麼事？在 mod hosting 之前加上 pub 關鍵字確實公開了模組。有了這項修改後，我們的確可以在取得 front_of_house 的後繼續進入 hosting。但是 hosting 的所有內容仍然是私有的。模組中的 pub 關鍵字只會讓該模組公開讓上層模組使用而已，而不是存取它所有的內部程式碼。因為模組相當於一個容器，如果我們只公開模組的話，本身並不能做多少事情。我們需要再進一步選擇公開模組內一些項目才行。

範例 7-6 的錯誤訊息表示 add_to_waitlist 函式是私有的。隱私權規則如同模組一樣適用於結構體、列舉、函式與方法。

讓我們在 add_to_waitlist 的函式定義加上 pub 公開它吧，如範例 7-7 所示。

檔案名稱：src/lib.rs

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // 絕對路徑
    crate::front_of_house::hosting::add_to_waitlist();

    // 相對路徑
    front_of_house::hosting::add_to_waitlist();
}

範例 7-7：將 mod hosting 和 fn add_to_waitlist 都加上 pub 關鍵字，讓我們可以從 eat_at_restaurant 呼叫函式

現在程式碼就能成功編譯了！要理解為何加上 pub 關鍵字讓我們可以在 add_to_waitlist 取得這些路徑，同時遵守隱私權規則，讓我們來看看絕對路徑與相對路徑。

在絕對路徑中，我們始於 crate，這是 crate 模組樹的根。再來 front_of_house 模組被定義在 crate 源頭中，front_of_house 模組不是公開，但因為 eat_at_restaurant 函式被定義在與 front_of_house 同一層模組中（也就是 eat_at_restaurant 與 front_of_house 同輩（siblings）），我們可以從 eat_at_restaurant 參考 front_of_house。接下來是有 pub 標記的 hosting 模組，我們可以取得 hosting 的上層模組，所以我們可以取得 hosting。最後 add_to_waitlist 函式也有 pub 標記而我們可以取得它的上層模組，所以整個程式呼叫就能執行了！

而在相對路徑中，基本邏輯與絕對路徑一樣，不過第一步有點不同。我們不是從 crate 源頭開始，路徑是從 front_of_house 開始。front_of_house 與 eat_at_restaurant 被定義在同一層模組中，所以從 eat_at_restaurant 開始定義的相對路徑是有效的。再來因為 hosting 與 add_to_waitlist 都有 pub 標記，其餘的路徑也都是可以進入的，所以此函式呼叫也是有效的！

如果你計畫分享你的函式庫 crate 來讓其他專案能使用你的程式碼，你的公開 API 就是你對 crate 使用者的合約，這會決定他們能如何使用你的程式碼。這需要考量管理你的公開 API，好讓其他人能輕鬆依賴你的 crate。這類的考量不在本書的範疇，如果你對於此議題有興趣的話，請查看 Rust API Guidelines。

執行檔與函式庫套件的最佳實踐

我們提到套件能同時包含 src/main.rs 作為執行檔 crate 源頭以及 src/lib.rs 作為函式庫 crate 源頭，兩者預設都是用套件的名稱。通常來說，一個函式庫與一個執行檔 crate 這樣的套件模式，在執行檔中只會留下必要的程式碼，其餘則呼叫函式庫的程式碼。這樣其他專案也能運用到套件提供的多數功能，因為函式庫 crate 的程式碼可以分享。

模組要定義在 src/lib.rs。然後在執行檔 crate 中，任何公開項目都能用套件名稱作為開頭找到。執行檔 crate 應視為函式庫 crate 的使用者，就像外部 crate 那樣使用一樣，只能使用公開 API。這有助於你設計出良好的 API，你不僅是作者，同時還是自己的客戶！

在第十二章中，我們會透過寫個命令列程式來介紹這樣的組織練習，該程式會包含一個執行檔 crate 與一個函式庫 crate。

使用 super 作為相對路徑的開頭

我們可以在路徑開頭使用 super 來建構從上層模組出發的相對路徑，而不用從 crate 源頭開始。這就像在檔案系統中使用 .. 作為路徑開頭一樣。使用 super 讓我們能參考確定位於上層模組的項目。當模組與上層模組有高度關聯，且上層模組可能以後會被移到模組樹的其他地方時，這能讓組織模組樹更加輕鬆。

請考慮範例 7-8 的程式碼，這模擬了一個主廚修正一個錯誤的訂單，並親自提供給顧客的場景。定義在 back_of_house 模組的函式 fix_incorrect_order 呼叫了定義在上層模組的函式 deliver_order，不過這次是使用 super 來指定 deliver_order 的路徑：

檔案名稱：src/lib.rs

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

範例 7-8：使用 super 作為呼叫函式路徑的開頭

fix_incorrect_order 函式在 back_of_house 模組中，所以我們可以使用 super 前往 back_of_house 的上層模組，在此例的話就是源頭 crate。然後在此時我們就能找到 deliver_order。成功！我們認定 back_of_house 模組與 deliver_order 函式應該會維持這樣相同的關係，在我們要組織 crate 的模組樹時，它們理當一起被移動。因此我們使用 super 讓我們在未來程式碼被移動到不同模組時，我們不用更新太多程式路徑。

公開結構體與列舉

我們也可以使用 pub 來公開結構體與列舉，但是我們有些額外細節要考慮到。如果我們在結構體定義之前加上 pub 的話，我們的確能公開結構體，但是結構體內的欄位仍然會是私有的。我們可以視情況決定每個欄位要不要公開。在範例 7-9 我們定義了一個公開的結構體 back_of_house::Breakfast 並公開欄位 toast，不過將欄位 seasonal_fruit 維持是私有的。這次範例模擬的情境是，餐廳顧客可以選擇早餐要點什麼類型的麵包，但是由主廚視庫存與當季食材來決定提供何種水果。餐廳提供的水果種類隨季節變化很快，所以顧客無法選擇或預先知道他們會拿到何種水果。

檔案名稱：src/lib.rs

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("桃子"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // 點夏季早餐並選擇黑麥麵包
    let mut meal = back_of_house::Breakfast::summer("黑麥");
    // 我們想改成全麥麵包
    meal.toast = String::from("全麥");
    println!("我想要{}麵包，謝謝", meal.toast);

    // 接下來這行取消註解的話，我們就無法編譯通過
    // 我們無法擅自更改餐點搭配的季節水果
    // meal.seasonal_fruit = String::from("藍莓");
}

範例 7-9：一個有些欄位公開而有些是私有欄位的結構體

因為 back_of_house::Breakfast 結構體中的 toast 欄位是公開的，在 eat_at_restaurant 中我們可以加上句點來對 toast 欄位進行讀寫。注意我們不能在 eat_at_restaurant 使用 seasonal_fruit 欄位，因為它是私有的。請嘗試解開修改 seasonal_fruit 欄位數值的那行程式註解，看看你會獲得什麼錯誤！

另外因為 back_of_house::Breakfast 擁有私有欄位，該結構體必須提供一個公開的關聯函式（associated function）才有辦法產生 Breakfast 的實例（我們在此例命名為 summer）。如果 Breakfast 沒有這樣的函式的話，我們就無法在 eat_at_restaurant 建立 Breakfast 的實例，因為我們無法在 eat_at_restaurant 設置私有欄位 seasonal_fruit 的數值。

接下來，如果我們公開列舉的話，那它所有的變體也都會公開。我們只需要在 enum 關鍵字之前加上 pub 就好，如範例 7-10 所示。

檔案名稱：src/lib.rs

mod back_of_house {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

pub fn eat_at_restaurant() {
    let order1 = back_of_house::Appetizer::Soup;
    let order2 = back_of_house::Appetizer::Salad;
}

範例 7-10：公開列舉會讓其所有變體也公開

因為我們公開了 Appetizer 列舉，我們可以在 eat_at_restaurant 使用 Soup 和 Salad。

列舉的變體沒有全部都公開的話，通常會讓列舉很不好用。要用 pub 標註所有的列舉變體都公開的話又很麻煩。所以公開列舉的話，預設就會公開其變體。相反地，結構體不讓它的欄位全部都公開的話，通常反而比較實用。因此結構體欄位的通用原則是預設為私有，除非有 pub 標註。

我們還有一個 pub 的使用情境還沒提到，也就是我們模組系統最後一項功能：use 關鍵字。我們接下來會先解釋 use，再來研究如何組合 pub 和 use。

透過 use 關鍵字引入路徑

要是每次都得寫出呼叫函式的路徑的話是很冗長、重複且不方便的。舉例來說範例 7-7 我們在考慮要使用絕對或相對路徑來呼叫 add_to_waitlist 函式時，每次想要呼叫 add_to_waitlist 我們都得指明 front_of_house 以及 hosting。幸運的是，我們有簡化過程的辦法：我們可以用 use 關鍵字建立路徑的捷徑，然後在作用域內透過更短的名稱來使用。

在範例 7-11 中，我們引入了 crate::front_of_house::hosting 模組進 eat_at_restaurant 函式的作用域中，所以我們要呼叫函式 add_to_waitlist 的話我們只需要指明 hosting::add_to_waitlist。

檔案名稱：src/lib.rs

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

範例 7-11：使用 use 將模組引入

使用 use 將路徑引入作用域就像是在檔案系統中產生符號連結一樣（symbolic link）。在 crate 源頭加上 use crate::front_of_house::hosting 後，hosting 在作用域內就是個有效的名稱了。使用 use 的路徑也會檢查隱私權，就像其他路徑一樣。

注意到 use 只會在它所位在的特定作用域內建立捷徑。範例 7-12 將 eat_at_restaurant 移入子模組 customer，這樣就會與 use 陳述式的作用域不同，所以其函式本體將無法編譯。

檔案名稱：src/lib.rs

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

mod customer {
    pub fn eat_at_restaurant() {
        hosting::add_to_waitlist();
    }
}

範例 7-12：use 陳述式只適用於所在的作用域

編譯器錯誤顯示了該捷徑無法用在 customer 模組內：

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0433]: failed to resolve: use of undeclared crate or module `hosting`
  --> src/lib.rs:11:9
   |
11 |         hosting::add_to_waitlist();
   |         ^^^^^^^ use of undeclared crate or module `hosting`

warning: unused import: `crate::front_of_house::hosting`
 --> src/lib.rs:7:5
  |
7 | use crate::front_of_house::hosting;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` on by default

For more information about this error, try `rustc --explain E0433`.
warning: `restaurant` (lib) generated 1 warning
error: could not compile `restaurant` due to previous error; 1 warning emitted

你會發現還有另外一個警告說明 use 在它的作用域中並沒有被用到！要解決此問題的話，我們可以將 use 也移動到 customer 模組內，或是在customer 子模組透過 super::hosting 參考上層模組的捷徑。

建立慣用的 use 路徑

在範例 7-11 你可能會好奇為何我們指明 use crate::front_of_house::hosting 然後在 eat_at_restaurant 呼叫，而不是直接用 use 指明 add_to_waitlist 函式的整個路徑就好。像範例 7-13 這樣寫。

檔案名稱：src/lib.rs

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting::add_to_waitlist;

pub fn eat_at_restaurant() {
    add_to_waitlist();
}

範例 7-13：使用 use 將 add_to_waitlist 函式引入作用域，但這較不符合習慣

雖然範例 7-11 與範例 7-13 都能完成相同的任務，但是範例 7-11 的做法比較符合習慣用法。使用 use 將函式的上層模組引入作用域，讓我們必須在呼叫函式時得指明對應模組。在呼叫函式時指定上層模組能清楚地知道該函式並非本地定義的，同時一樣能簡化路徑。範例 7-13 的程式碼會不清楚 add_to_waitlist 是在哪定義的。

另一方面，如果是要使用 use 引入結構體、列舉或其他項目的話，直接指明完整路徑反而是符合習慣的方式。範例 7-14 顯示了將標準函式庫的 HashMap 引入執行檔 crate 作用域的習慣用法。

檔案名稱：src/main.rs

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

範例 7-14：引入 HashMap 進作用域的習慣用法

此習慣沒什麼強硬的理由：就只是大家已經習慣這樣的用法來讀寫 Rust 的程式碼。

這樣的習慣有個例外，那就是如果我們將兩個相同名稱的項目使用 use 陳述式引入作用域時，因為 Rust 不會允許。範例 7-15 展示了如何引入兩個同名但屬於不同模組的 Result 型別進作用域中並使用的方法。

檔案名稱：src/lib.rs

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --省略--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --省略--
    Ok(())
}

範例 7-15：要將兩個同名的型別引入相同作用域的話，必須使用它們所屬的模組

如同你所見使用對應的模組可以分辨出是在使用哪個 Result 型別。如果我們直接指明 use std::fmt::Result 和 use std::io::Result 的話，我們會在同一個作用域中擁有兩個 Result 型別，這樣一來 Rust 就無法知道我們想用的 Result 是哪一個。

使用 as 關鍵字提供新名稱

要在相同作用域中使用 use 引入兩個同名型別的話，還有另一個辦法。在路徑之後，我們可以用 as 指定一個該型別在本地的新名稱，或者說別名（alias）。範例 7-16 展示重寫了範例 7-15，將其中一個 Result 型別使用 as 重新命名。

檔案名稱：src/lib.rs

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

fn function1() -> Result {
    // --省略--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --省略--
    Ok(())
}

範例 7-16：使用 as 將型別引入作用域的同時重新命名

在第二個 use 陳述式，我們選擇了將 std::io::Result 型別重新命名為 IoResult，這樣就不會和同樣引入作用域內 std::fmt 的 Result 有所衝突。範例 7-15 與 範例 7-16 都屬於習慣用法，你可以選擇你比較喜歡的方式！

使用 pub use 重新匯出名稱

當我們使用 use 關鍵字將名稱引入作用域時，該有效名稱在新的作用域中是私有的。要是我們希望呼叫我們這段程式碼時，也可以使用這個名稱的話（就像該名稱是在此作用域內定義的），我們可以組合 pub 和 use。這樣的技巧稱之為重新匯出（re-exporting），因為我們將項目引入作用域，並同時公開給其他作用域參考。

範例 7-17 將範例 7-11 在源頭模組中原本的 use 改成 pub use。

檔案名稱：src/lib.rs

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

範例 7-17：使用 pub use 使名稱公開給任何程式的作用域中參考

在此之前，外部程式碼會需要透過 restaurant::front_of_house::hosting::add_to_waitlist() 這樣的路徑才能呼叫 add_to_waitlist。現在 pub use 從源頭模組重新匯出了 hosting 模組，外部程式碼現在可以使用 restaurant::hosting::add_to_waitlist() 這樣的路徑就好。

當程式碼的內部結構與使用程式的開發者對於該領域所想像的結構不同時，重新匯出會很有用。我們再次用餐廳做比喻的話就像是，經營餐廳的人可能會想像餐廳是由「前台」與「後台」所組成，但光顧的顧客可能不會用這些術語來描繪餐廳的每個部分。使用 pub use 的話，我們可以用某種架構寫出程式碼，再以不同的架構對外公開。這樣讓我們的的函式庫可以完整的組織起來，且對開發函式庫的開發者與使用函式庫的開發者都提供友善的架構。我們會在第十四章的「透過 pub use 匯出理想的公開 API」段落再看看另一個 pub use 的範例並了解它會如何影響 crate 的技術文件。

使用外部套件

在第二章我們寫了一支猜謎遊戲專案時，有用到一個外部套件叫做 rand 來取得隨機數字。要在專案內使用 rand 的話，我們會在 Cargo.toml 加上此行：

檔案名稱：Cargo.toml

rand = "0.8.5"

在 Cargo.toml 新增 rand 作為依賴函式庫會告訴 Cargo 要從 crates.io 下載 rand 以及其他相關的依賴，讓我們的專案可以使用 rand。

接下來要將 rand 的定義引入我們套件的作用域的話，我們加上一行 use 後面接著 crate 的名稱 rand 然後列出我們想要引入作用域的項目。回想一下在第二章「產生隨機數字」的段落，我們將 Rng 特徵引入作用域中，並呼叫函式 rand::thread_rng：

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

fn main() {
    println!("請猜測一個數字！");

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

    println!("祕密數字為：{secret_number}");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取該行失敗");

    println!("你的猜測數字：{guess}");
}

Rust 社群成員在 crates.io 發佈了不少套件可供使用，要將這些套件引入到你的套件的步驟是一樣的。在你的套件的 Cargo.toml 檔案列出它們，然後使用 use 將這些 crate 內的項目引入作用域中。

請注意到標準函式庫 std 對於我們的套件來說也是一個外部 crate。由於標準函式庫會跟著 Rust 語言發佈，所以我們不需要更改 Cargo.toml 來包含 std。但是我們仍然需使用 use 來將它的項目引入我們套件的作用域中。舉例來說，要使用 HashMap 我們可以這樣寫：

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

這是個用標準函式庫的 crate 名稱 std 起頭的絕對路徑。

使用巢狀路徑來清理大量的 use 行數

如果我們要使用在相同 crate 或是相同模組內定義的數個項目，針對每個項目都單獨寫一行的話，會佔據我們檔案內很多空間。舉例來說，範例 2-4 中的猜謎遊戲我們用了這兩個 use 陳述式來引入作用域中：

檔案名稱：src/main.rs

use rand::Rng;
// --省略--
use std::cmp::Ordering;
use std::io;
// --省略--

fn main() {
    println!("請猜測一個數字！");

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

    println!("祕密數字為：{secret_number}");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取行數失敗");

    println!("你的猜測數字：{guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("太小了！"),
        Ordering::Greater => println!("太大了！"),
        Ordering::Equal => println!("獲勝！"),
    }
}

我們可以改使用巢狀路徑（nested paths）來只用一行就能將數個項目引入作用域中。我們先指明相同路徑的部分，加上雙冒號，然後在大括號內列出各自不同的路徑部分，如範例 7-18 所示。

檔案名稱：src/main.rs

use rand::Rng;
// --省略--
use std::{cmp::Ordering, io};
// --省略--

fn main() {
    println!("請猜測一個數字！");

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

    println!("祕密數字為：{secret_number}");

    println!("請輸入你的猜測數字。");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("讀取行數失敗");

    let guess: u32 = guess.trim().parse().expect("請輸入一個數字！");

    println!("你的猜測數字：{guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("太小了！"),
        Ordering::Greater => println!("太大了！"),
        Ordering::Equal => println!("獲勝！"),
    }
}

範例 7-18：使用巢狀路徑引入有部分相同前綴的數個路徑至作用域中

在較大的程式中，使用巢狀路徑將相同 crate 或相同模組中的許多項目引入作用域，可以大量減少 use 陳述式的數量！

我們可以在路徑中的任何部分使用巢狀路徑，這在組合兩個享有相同子路徑的 use 陳述式時非常有用。舉例來說，範例 7-19 顯示了兩個 use 陳述式：一個將 std::io 引入作用域，另一個將 std::io::Write 引入作用域。

檔案名稱：src/lib.rs

use std::io;
use std::io::Write;

範例 7-19：兩個 use 陳述式且其中一個是另一個的子路徑

這兩個路徑的相同部分是 std::io，這也是整個第一個路徑。要將這兩個路徑合為一個 use 陳述式的話，我們可以在巢狀路徑使用 self，如範例 7-20 所示。

檔案名稱：src/lib.rs

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

範例 7-20：組合範例 7-19 的路徑為一個 use 陳述式

此行就會將 std::io 和 std::io::Write 引入作用域。

全域運算子

如果我們想要將在一個路徑中所定義的所有公開項目引入作用域的話，我們可以在指明路徑之後加上全域（glob）運算子 *：

#![allow(unused)]
fn main() {
use std::collections::*;
}

此 use 陳述式會將 std::collections 定義的所有公開項目都引入作用域中。不過請小心使用全域運算子！它容易讓我們無法分辨作用域內的名稱，以及程式中使用的名稱是從哪定義來的。

全域運算子很常用在 tests 模組下，將所有東西引入測試中。我們會在第十一章的「如何寫測試」段落來討論。全域運算子也常拿來用在 prelude 模式中，你可以查閱標準函式庫的技術文件來瞭解此模式的更多資訊。

將模組拆成不同檔案

本章節目前所有的範例將數個模組定義在同一個檔案中。當模組增長時，你可能會想要將它們的定義拆開到別的檔案中，好讓程式碼容易瀏覽。

舉例來說，讓我們從範例 7-17 餐廳的多重模組開始。我們會將模組拆成數個檔案，而不只是將所有模組都放在 crate 源頭檔案。在此例中，源頭檔案為 src/lib.rs 不過這步驟在執行檔 crate 的 src/main.rs 一樣可行。

首先，我們將 front_of_house 模組移到獨立的檔案中。刪掉 front_of_house 模組大括號內的程式碼，只留下宣告 mod front_of_house;，讓 src/lib.rs 包含的程式碼如範例 7-21 所示。請注意在我們加上範例 7-22 的 src/front_of_house.rs 檔案前這會仍無法編譯。

檔案名稱：src/lib.rs

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

範例 7-21：宣告 front_of_house 模組，其本體位於 src/front_of_house.rs

接著，將原本大括號內的程式碼寫到新的檔案 src/front_of_house.rs 中，如範例 7-22 所示。編譯器知道要查看這個檔案，因為 crate 源頭有宣告這個模組的名稱 front_of_house。

檔案名稱：src/front_of_house.rs

pub mod hosting {
    pub fn add_to_waitlist() {}
}

範例 7-22：front_of_house 模組的定義位於 src/front_of_house.rs

你只需要在模組樹中使用 mod 宣告一次來讀取檔案就好。一旦編譯器知道該檔案屬於專案的一部分（且知道其位在模組樹中的何處，因為你有宣告 mod 陳述式），專案中的其他檔案就能用宣告的路徑讀取檔案的程式碼，如同「參考模組項目的路徑」段落提到的一樣。換句話說，mod 和你在其他程式語言可能會看到的「include」動作並不一樣。

要開始移動 hosting 的話，我們先改變 src/front_of_house.rs，讓它只包含 hosting 模組的宣告：

檔案名稱：src/front_of_house.rs

pub mod hosting;

然後我們建立一個目錄 src/front_of_house 以及一個檔案 src/front_of_house/hosting.rs 來包含 hosting 模組的定義：

檔案名稱：src/front_of_house/hosting.rs

pub fn add_to_waitlist() {}

如果我們將 hosting.rs 放在 src 目錄下，編譯器會將 hosting.rs 的程式碼視為是宣告在 crate 源頭底下的 hosting 模組。編譯器決定哪些檔案屬於哪些模組的規則讓目錄與檔案架構能更貼近模組樹的架構。

其他種的檔案路徑

目前我們涵蓋了 Rust 編譯器使用的最佳檔案路徑形式，但 Rust 仍然支援舊版的檔案路徑。當 crate 源頭宣告了一個模組 front_of_house 時，編譯器會在以下幾處尋找模組的程式碼：

• src/front_of_house.rs（我們介紹的）
• src/front_of_house/mod.rs（舊版風格，仍然支援的路徑形式）

當有個 front_of_house 的子模組 hosting 宣告時，編譯器會在以下幾處尋找模組的程式碼：

• src/front_of_house/hosting.rs（我們介紹的）
• src/front_of_house/hosting/mod.rs（舊版風格，仍然支援的路徑形式）

如果你對同個模組同時使用兩種風格的話，你會收到編譯器錯誤。在同個專案對不同模組使用不同風格則是允許的，但這有可能會讓瀏覽專案的人感到困惑。

使用 mod.rs 檔案名稱的風格最主要的缺點是你的專案可能最後會有很多檔案都叫做 mod.rs，當你在編輯器同時開啟這些檔案時可能會被混淆。

我們將模組的程式碼搬到了不同的檔案，而模組樹仍維持完好如初。就算函式定義被移動不同檔案，eat_at_restaurant 內的函式呼叫不用任何修改仍能維持運作。這樣的方式讓你可以隨著模組成長時，移動到新的檔案中。

另外 src/lib.rs 內的 pub use crate::front_of_house::hosting 陳述式沒有改變，在檔案作為 crate 的一部分來編譯時，使用 use 的方式也沒有改變。mod 關鍵字能宣告模組，然後 Rust 會去同名的檔案尋找該模組的程式碼。

總結

Rust 讓你能夠將套件拆成數個 crate，然後 crate 能再分成數個模組，好讓你可以從一個模組內指定其他模組的項目。而你可以使用絕對或相對路徑來達成。這些路徑可以用 use 陳述式來引入作用域，讓你可以在該作用域用更短的路徑來多次呼叫該項目。模組程式碼預設為私有的，但你可以使用 pub 關鍵字公開它的定義內容。

在下個章節，我們將探討在標準函式庫中的一些資料結構集合，讓你可以利用它們寫出整潔有組織的程式碼。

常見集合

Rust 的標準函式庫提供一些非常實用的資料結構稱之為集合（collections）。多數其他資料型別只會呈現一個特定數值，但是集合可以包含數個數值。不像內建的陣列與元組型別，這些集合指向的資料位於堆積上，代表資料的數量不必在編譯期就知道，而且可以隨著程式執行增長或縮減。每種集合都有不同的能力以及消耗，依照你的情形選擇適當的集合，是一項你會隨著開發時間漸漸掌握的技能。在本章節我們會介紹三種在 Rust 程式中十分常用的集合：

• 向量（Vector）允許你接二連三地儲存數量不定的數值。
• 字串（String）是字元的集合。我們在之前就提過 String 型別，本章會正式深入介紹。
• 雜湊映射（Hash map）允許你將值（value）與特定的鍵（key）相關聯。這是從一種更通用的資料結構映射（map）衍生出來的特定實作。

想瞭解更多標準函式庫提供的集合種類的話，歡迎查閱技術文件。

我們將討論如何建立與更新向量、字串與雜湊映射，以及它們的所長。

透過向量儲存列表

我們第一個要來看的集合是 Vec<T> 常稱為向量（vector）。向量允許你在一個資料結構儲存不止一個數值，而且該結構的記憶體會接連排列所有數值。它們很適合用來處理你手上的項目列表，像是一個檔案中每行的文字，或是購物車內每項物品。

建立新的向量

要建立一個新的空向量的話，我們呼叫 Vec::new 函式，如範例 8-1 所示。

fn main() {
    let v: Vec<i32> = Vec::new();
}

範例 8-1 建立一個儲存數值型別為 i32 的空向量

注意到我們在此加了型別詮釋。因為我們沒有對此向量插入任何數值，Rust 不知道我們想儲存什麼類型的元素。這是一項重點，向量是用泛型（generics）實作，我們會在第十章說明如何為你自己的型別使用泛型。現在我們只需要知道標準函式庫提供的 Vec<T> 型別可以持有任意型別，然後當特定向量要持有特定型別時，我們可以在尖括號內指定該型別。在範例 8-1，我們告訴 Rust 在 v 中的 Vec<T> 會持有 i32 型別的元素。

不過通常你在建立 Vec<T> 時只需要給予初始數值，Rust 就能推導出你想儲存的數值型別，所以你不太常會需要指明型別詮釋。Rust 還提供了 vec! 巨集讓我們能方便地建立一個新的向量並取得你提供的數值。在範例 8-2 中，我們建立了一個新的 Vec<i32> 並擁有數值 1、2 和 3。整數型別為 i32 是因為這是預設整數型別，如同我們在第三章的「資料型別」 段落提到的一樣。

fn main() {
    let v = vec![1, 2, 3];
}

範例 8-2：建立一個擁有數值的新向量

因為我們給予了初始的 i32 數值，Rust 可以推導出 v 的型別為 Vec<i32>，所以型別詮釋就不是必要的了。接下來，讓我們看看如何修改向量。

更新向量

要在建立向量之後新增元素的話，我們可以使用 push 方法，如範例 8-3 所示。

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

範例 8-3：使用 push 方法來新增數值到向量

與其他變數一樣，如果我們想要變更其數值的話，我們需要使用 mut 關鍵字使它成為可變的，如同第三章提到的一樣。我們插入的數值所屬型別均為 i32，然後 Rust 可以從資料推導，所以我們不必指明 Vec<i32>。

讀取向量元素

要參考向量儲存的數值有兩種方式。為了更加清楚說明此範例，我們詮釋了函式回傳值的型別。

範例 8-4 顯示了取得向量中數值的方法，可以使用索引語法與 get 方法。

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let third: &i32 = &v[2];
    println!("第三個元素是 {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("第三個元素是 {third}"),
        None => println!("第三個元素並不存在。"),
    }
}

範例 8-4：使用索引語法或 get 方法來取得向量項目

這邊我們要注意一些地方。我們使用了索引數值 2 來獲取第三個元素：向量可以用數字來索引，從零開始計算。使用 & 和 [] 會給我們索引數值的元素參考，而使用 get 方法加上一個索引作為引數，則會給我們 Option<&T>，我們可以用 match 來配對。

Rust 提供兩種取得元素參考方式，所以當你嘗試使用索引數值取得向量範圍外的元素時，你可以決定程式的行為。讓我們看看一個範例，我們有一個向量擁有五個元素，但我們嘗試用索引 100 來取得對應數值，如範例 8-5 所示。

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let does_not_exist = &v[100];
    let does_not_exist = v.get(100);
}

範例 8-5：嘗試對只有五個元素的向量取得索引 100 的值

當我們執行程式時，第一個 [] 方法會讓程式恐慌，因為它參考了不存在的元素。此方法適用於當你希望一有無效索引時就讓程式崩潰的狀況。

當你使用 get 方法來索取向量不存在的索引時，它會回傳 None 而不會恐慌。如果正常情況下偶而會不小心存取超出向量範圍索引的話，你就會想要只用此方法。你的程式碼就會有個邏輯專門處理 Some(&element) 或 None，如同第六章所述。舉例來說，可能會有由使用者輸入的索引。如果他不小心輸入太大的數字的話，程式可以回傳 None，你可以告訴使用者目前向量有多少項目，並讓他們可以再輸入一次。這會比直接讓程式崩潰還來的友善，他們可能只是不小心打錯而已！

當程式有個有效參考時，借用檢查器（borrow checker）會貫徹所有權以及借用規則（如第四章所述）來確保此參考及其他對向量內容的參考都是有效的。回想一下有個規則是我們不能在同個作用域同時擁有可變與不可變參考。這個規則一樣適用於範例 8-6，在此我們有一個向量第一個元素的不可變參考，然後我們嘗試在向量後方新增元素。如果我們嘗試在此動作後繼續使用第一個參考的話，程式會無法執行：

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("第一個元素是：{first}");
}

範例 8-6：在持有一個項目的參考時，還嘗試對向量新增元素

編譯此程式會得到以下錯誤：

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:5
  |
4 |     let first = &v[0];
  |                  - immutable borrow occurs here
5 |
6 |     v.push(6);
  |     ^^^^^^^^^ mutable borrow occurs here
7 |
8 |     println!("第一個元素為 {first}");
  |                           ----- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `collections` due to previous error

範例 8-6 的程式碼看起來好像能執行。為何第一個元素的參考要在意向量的最後端發生了什麼事呢？此錯誤其實跟向量運作的方式有關：由於向量會將元素放在前一位的記憶體位置後方，在向量後方新增元素時，如果當前向量的空間不夠再塞入另一個值的話，可能會需要配置新的記憶體並複製舊的元素到新的空間中。這樣一來，第一個元素的索引可能就會指向已經被釋放的記憶體，借用規則會防止程式遇到這樣的情形。

注意：關於 Vec<T> 型別更多的實作細節，歡迎查閱「The Rustonomicon」。

遍歷向量的元素

想要依序存取向量中每個元素的話，我們可以遍歷所有元素而不必用索引一個一個取得。範例 8-7 闡釋了如何使用 for 迴圈來取得一個 i32 向量中每個元素的不可變參考並印出他們。

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

範例 8-7：使用 for 迴圈遍歷向量中每個元素

我們還可以遍歷可變向量中的每個元素取得可變參考來改變每個元素。像是範例 8-8 就使用 for 迴圈來為每個元素加上 50。

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

範例 8-8：遍歷向量中的元素取得可變參考

要改變可變參考指向的數值，在使用 += 運算子之前，我們需要使用 * 解參考運算子來取得 i 的數值。我們會在第十五章的「追蹤指標的數值」段落來講解更多解參考運算子的細節。

當遍歷向量時，無論是不可變或可變地都是安全，因為借用檢查器的規則能確保如此。如果我們嘗試在範例 8-7 或範例 8-8 的 for 迴圈本體插入或刪除項目，我們就會獲得和範例 8-6 程式碼類似的編譯錯誤。for 迴圈持有的向量參考能避免同時修改整個向量。

使用列舉來儲存多種型別

向量只能儲存同型別的數值，這在某些情況會很不方便，一定會有場合是要儲存不同型別到一個列表中。幸運的是，列舉的變體是定義在相同的列舉型別，所以當我們需要在向量儲存不同型別的元素時，我們可以用列舉來定義！

舉例來說，假設我們想從表格中的一行取得數值，但是有些行內的列會包含整數、浮點數以及一些字串。我們可以定義一個列舉，其變體會持有不同的數值型別，然後所有的列舉變體都會被視為相同型別：就是它們的列舉。接著我們就可以建立一個擁有此列舉型別的向量，最終達成持有不同型別。如範例 8-9 所示。

fn main() {
    enum SpreadsheetCell {
        Int(i32),
        Float(f64),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell::Int(3),
        SpreadsheetCell::Text(String::from("藍色")),
        SpreadsheetCell::Float(10.12),
    ];
}

範例 8-9：用 enum 定義儲存不同型別的列舉並作為向量的型別

Rust 需要在編譯時期知道向量的型別以及要在堆積上用到多少記憶體才能儲存每個元素。我們必須明確知道哪些型別可以放入向量中。如果 Rust 允許向量一次持有任意型別的話，在對向量中每個元素進行處理時，可能就會有一或多種型別會產生錯誤。使用列舉和 match 表達式讓 Rust 可以在編譯期間確保每個可能的情形都已經處理完善了，如同第六章提到的一樣。

如果你無法確切知道執行時程式所處理的所有型別的話，列舉就不管用了。這時使用特徵物件會比較好，我們會在第十七章再來解釋。

現在我們已經講了一些向量常見的用法，有時間的話記得到向量的 API 技術文件瞭解標準函式庫中 Vec<T> 所有實用的方法。舉例來說，除了 push 方法以外，還有個 pop 方法可以移除並回傳最後一個元素。

釋放向量的同時也會釋放其元素

就像其它 struct 一樣，向量會在作用域結束時被釋放，如範例 8-10 所示。

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // 使用 v 做些事情
    } // <- v 在此離開作用域並釋放
}

範例 8-10：顯示向量及其元素在哪裡被釋放

當向量被釋放時，其所有內容也都會被釋放，代表它持有的那些整數都會被清除。這雖然聽起來很直觀，但是當我們開始參考向量中的元素時可能就會變得有點複雜。讓我們看看怎麼處理這種情形吧！

接下來讓我們看看下一個集合型別：String！

透過字串儲存 UTF-8 編碼的文字

我們已經在第四章提到字串（String），但現在我們要更加深入探討。Rustaceans 初學者常常會卡在三個環節：Rust 傾向於回報可能的錯誤、字串的資料結構比開發者所熟悉的還要複雜，以及 UTF-8。這些要素讓來自其他程式語言背景的開發者會遇到一些困難。

我們會在集合章節討論字串的原因是，字串本身就是位元組的集合，且位元組作為文字呈現時，它會提供一些實用的方法。在此段落我們將和其他集合型別一樣討論 String 的操作，像是建立、更新與讀取。我們還會討論到 String 與其他集合不一樣的地方，像是 String 的索引就比其他集合還複雜，因為它會依據人們對於 String 資料型別的理解而有所不同。

什麼是字串？

首先我們要好好定義字串（String）這個術語。Rust 在核心語言中只有一個字串型別，那就是字串切片 str，它通常是以借用的形式存在 &str。在第四章中我們提到字串切片是一個針對存在某處的 UTF-8 編碼資料的參考。舉例來說，字串字面值（String literals）就儲存在程式的執行檔中，因此就是字串切片。

String 型別是 Rust 標準函式庫所提供的型別，並不是核心語言內建的型別，它是可增長的、可變的、可擁有所有權的 UTF-8 編碼字串型別。當 Rustaceans 提及 Rust 中的「字串」時，他們通常指的是 String 以及字串切片 &str 型別，而不只是其中一種型別。雖然此段落大部分都在討論 String，這兩個型別都時常用在 Rust 的標準函式庫中，且 String 與字串切片都是 UTF-8 編碼的。

建立新的字串

許多 Vec<T> 可使用的方法在 String 也都能用，因為 String 其實就是一種位元組向量的封裝再加上一些額外的保障、限制與能力。其中一個 Vec<T> 與 String 都有且用途相同的函式就是 new，這用來產生新的實例，如範例 8-11 所示。

fn main() {
    let mut s = String::new();
}

範例 8-11：建立新的空 String

此行會建立新的字串叫做 s，我們之後可以再寫入資料。不過通常我們會希望建立字串的同時能夠初始化資料。為此我們可以使用 to_string 方法，任何有實作 Display 特徵的型別都可以使用此方法，就像字串字面值的使用方式一樣。範例 8-12 就展示了兩種例子。

fn main() {
    let data = "初始內容";

    let s = data.to_string();

    // 此方法也能直接用於字面值上
    let s = "初始內容".to_string();
}

範例 8-12：從字串字面值使用 to_string 方法來建立 String

此程式碼建立了一個字串內容為 初始內容。

我們也可以用函式 String::from 從字串字面值建立 String。範例 8-13 的程式碼和使用 to_string 的範例 8-12 效果一樣。

fn main() {
    let s = String::from("初始內容");
}

範例 8-13：使用函式 String::from 從字串字面值建立 String

因為字串用在許多地方，我們可以使用許多不同的通用字串 API 供我們選擇。有些看起來似乎是多餘的，但是它們都有一席之地的！在上面的範例中 String::from 和 to_string 都在做相同的事，所以你的選擇跟喜好風格與閱讀性比較有關。

另外記得字串是 UTF-8 編碼的，所以我們可以包含任何正確編碼的資料，如範例 8-14 所示。

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שָׁלוֹם");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

範例 8-14：用字串儲存各種語言打招呼的文字

以上全是合理的 String 數值。

更新字串

就和 Vec<T> 一樣，如果你插入更多資料的話，String 可以增長大小並變更其內容。除此之外你也可以使用 + 運算子或 format! 巨集來串接 String 數值。

使用 push_str 和 push 追加字串

我們可以使用 push_str 方法來追加一個字串切片使字串增長，如範例 8-15 所示。

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

範例 8-15：使用 push_str 方法向 String 追加字串切片

在這兩行之後，s 會包含 foobar。push_str 方法取得的是字串切片因為我們並不需要取得參數的所有權。舉例來說，在範例 8-16 我們想在 s2 追加其內容給 s1 之後仍能使用。

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 is {s2}");
}

範例 8-16：在內容追加給 String 後繼續使用字串切片

如果 push_str 方法會取得 s2 的所有權，我們就無法在最後一行印出其數值了。幸好這段程式碼是可以執行的！

而 push 方法會取得一個字元作為參數並加到 String 上。範例 8-17 顯示了一個使用 push 方法將字母 "l" 加到 String 的程式碼。

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

範例 8-17：使用 push 將一個字元加到 String

結果就是 s 會包含 lol。

使用 + 運算子或 format! 巨集串接字串

你通常會想要組合兩個字串在一起，其中一種方式是用 + 運算子。如範例 8-18 所示。

fn main() {
    let s1 = String::from("Hello, ");
    let s2 = String::from("world!");
    let s3 = s1 + &s2; // 注意到 s1 被移動因此無法再被使用
}

範例 8-18：使用 + 運算子組合兩個 String 數值成一個新的 String 數值

程式碼最後的字串 s3 就會獲得 Hello, world!。s1 之所以在相加後不再有效，以及 s2 是使用參考的原因，都和我們使用 + 運算子時呼叫的方法簽名有關。+ 運算子使用的是 add 方法，其簽名會長得像這樣：

fn add(self, s: &str) -> String {

在標準函式庫中 add 是用泛型（generics）與關聯型別（associated types）定義。我們在此使用實際型別代替的 add 簽名。我們會在第十章討論到泛型。此簽名給了一些我們需要瞭解 + 運算子的一些線索。

首先 s2 有 & 代表我們是將第二個字串的參考與第一個字串相加，因為函式 add 中的參數 s 說明我們只能將 &str 與 String 相加，我們無法將兩個 String 數值相加。但等等 &s2 是 &String 才對，並非 add 第二個參數所指定的 &str。為何範例 8-18 可以編譯呢？

我們可以在 add 的呼叫中使用 &s2 的原因是因為編譯器可以強制（coerce） &String 引數轉換成 &str。當我們我們呼叫 add 方法時，Rust 強制解參考（deref coercion）讓 &s2 變成 &s2[..]。我們會在第十五章深入探討強制解參考。因為 add 不會取得 s 參數的所有權，s2 在此運算後仍然是個有效的 String。

再來，我們可以看到 add 的簽名會取得 self 的所有權，因為 self 沒有 &。這代表範例 8-18 的 s1 會移動到 add 的呼叫內，在之後就不再有效。所以雖然 let s3 = s1 + &s2; 看起來像是它拷貝了兩個字串的值並產生了一個新的，但此陳述式實際上是取得 s1 的所有權、追加一份 s2 的複製內容、然後回傳最終結果的所有權。換句話說，雖然它看起來像是產生了很多拷貝，但實際上並不是。此實作反而比較有效率。

如果我們需要串接數個字串的話，+ 運算子的行為看起來就顯得有點笨重了：

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = s1 + "-" + &s2 + "-" + &s3;
}

此時 s 會是 tic-tac-toe。有這麼多的 + 和 " 字元，我們很難看清楚發生什麼事。如果要完成更複雜的字串組合的話，我們可以改使用 format! 巨集：

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = format!("{s1}-{s2}-{s3}");
}

此程式碼一樣能設置 s 為 tic-tac-toe。format! 巨集運作的方式和 println! 類似，但不會將輸出結果顯示在螢幕上，它做的是回傳內容的 String。使用 format! 的程式碼版本看起來比較好讀懂，而且 format! 產生的程式碼使用的是參考，所以此呼叫不會取走任何參數的所有權。

索引字串

在其他許多程式語言中，使用索引參考字串來取得獨立字元是有效且常見的操作。然而在 Rust 中如果你嘗試對 String 使用索引語法的話，你會得到錯誤。請看看範例 8-19 這段無效的程式碼。

fn main() {
    let s1 = String::from("hello");
    let h = s1[0];
}

範例 8-19：嘗試在字串使用索引語法

此程式會有以下錯誤結果：

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0277]: the type `String` cannot be indexed by `{integer}`
 --> src/main.rs:3:13
  |
3 |     let h = s1[0];
  |             ^^^^^ `String` cannot be indexed by `{integer}`
  |
  = help: the trait `Index<{integer}>` is not implemented for `String`
  = help: the following other types implement trait `Index<Idx>`:
            <String as Index<RangeFrom<usize>>>
            <String as Index<RangeFull>>
            <String as Index<RangeInclusive<usize>>>
            <String as Index<RangeTo<usize>>>
            <String as Index<RangeToInclusive<usize>>>
            <String as Index<std::ops::Range<usize>>>
            <str as Index<I>>

For more information about this error, try `rustc --explain E0277`.
error: could not compile `collections` due to previous error

錯誤訊息與提示告訴了我們 Rust 字串並不支援索引。但為何不支援呢？要回答此問題，我們需要先討論 Rust 如何儲存字串進記憶體的。

內部呈現

String 基本上就是 Vec<u8> 的封裝。讓我們看看範例 8-14 中一些正確編碼為 UTF-8 字串的例子，像是這一個：

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שָׁלוֹם");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

在此例中 len 會是 4，也就是向量儲存的字串「Hola」長度為 4 個位元組。每個字母在用 UTF-8 編碼時長度均為 1 個位元組。但接下來這行可能就會讓你感到驚訝了（請注意字串的開頭是西里爾字母 Ze 的大寫，而不是阿拉伯數字 3）。

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שָׁלוֹם");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

你可能會以為這字串的長度為 12，事實上 Rust 給的答案卻是 24。這是將「Здравствуйте」用 UTF-8 編碼後的位元組長度，因為該字串的每個 Unicode 純量都佔據兩個位元組。因此字串位元組的索引不會永遠都能對應到有效的 Unicode 純量數值。我們用以下無效的 Rust 程式碼進一步說明：

let hello = "Здравствуйте";
let answer = &hello[0];

你已經知道第一個字母 answer 不會是 З。當經過 UTF-8 編碼時，З 的第一個位元組會是 208 然後第二個是 151。所以 answer 實際上會拿到 208，但 208 本身又不是個有效字元。回傳 208 可能不會是使用者想要的，他們希望的應該是此字串的第一個字母，但這是 Rust 在位元組索引 0 唯一能回傳的資料。就算字串都只包含拉丁字母，使用者通常也不會希望看到位元組數值作為回傳值。如果 &"hello"[0] 是有效程式碼且會回傳位元組數值的話，它會回傳的是 104 並非 h。

為了預防回傳意外數值進而導致無法立刻察覺的錯誤，Rust 不會成功編譯這段程式碼，並在開發過程前期就杜絕誤會發生。

位元組、純量數值與形素群集！我的天啊！

UTF-8 還有一個重點是在 Rust 中我們實際上可以有三種觀點來理解字串：位元組、純量數值（scalar values）以及形素群集（grapheme clusters，最接近人們常說的「字母」）。

如果我們觀察用天成體寫的印度語「नमस्ते」，它存在向量中的 u8 數值就會長這樣：

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

這 18 個位元組是電腦最終儲存的資料？如果我們用 Unicode 純量數值觀察的話，也就是 Rust 的 char 型別，這些位元組會組成像這樣：

['न', 'म', 'स', '्', 'त', 'े']

這邊有六個 char 數值，但第四個和第六個卻不是字母，它們是單獨存在不具任何意義的變音符號。最後如果我們以形素群集的角度來看的話，我們就會得到一般人所說的構成此印度語的四個字母：

["न", "म", "स्", "ते"]

Rust 提供多種不同的方式來解釋電腦中儲存的原始字串資料，讓每個程式無論是何種人類語言的資料，都可以選擇它們需要的呈現方式。

Rust 還有一個不允許索引 String 來取得字元的原因是因為，索引運算必須永遠預期是花費常數時間（O(1)）。但在 String 上無法提供這樣的效能保證，因為 Rust 會需要從索引的開頭遍歷每個內容才能決定多少有效字元存在。

字串切片

索引字串通常不是個好點子，因為字串索引要回傳的型別是不明確的，是要一個位元組數值、一個字元、一個形素群集還是一個字串切片呢。因此如果你真的想要使用索引建立字串切片的話，Rust 會要你更明確些。要明確指定你的索引與你想要的字串切片。

與其在 [] 只使用一個數字來索引，你可以在 [] 指定一個範圍來建立包含特定位元組的字串切片：

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

s 在此會是 &str 並包含字串前 4 個位元組。稍早我們提過這些字元各佔 2 個位元組，所以這裡的 s 就是 Зд。

如果我們嘗試只用 &hello[0..1] 來取得字元部分的位元組的話，Rust 會和在向量中取得無效索引一樣在執行時恐慌：

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
    Finished dev [unoptimized + debuginfo] target(s) in 0.43s
     Running `target/debug/collections`
thread 'main' panicked at 'byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `Здравствуйте`', src/main.rs:4:14
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

你在使用範圍來建立字串切片時要格外小心，因為這樣做有可能會使你的程式崩潰。

遍歷字串的方法

要對字串的部分進行操作最好的方式是明確表達你想要的是字元還是位元組。對獨立的 Unicode 純量型別來說的話，就是使用 chars 方法。對「Зд」呼叫 chars 會將兩個擁有 char 型別的數值拆開並回傳，這樣一來你就可以遍歷每個元素：

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

此程式碼會顯示以下輸出：

З
д

而 bytes 方法會回傳每個原始位元組，可能會在某些場合適合你：

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

此程式碼會印出此字串的四個位元組：

208
151
208
180

請確定你已經瞭解有效的 Unicode 純量數值可能不止佔 1 個位元組。

而要從天成體組成的字串取得形素群集的話就非常複雜了，所以標準函式庫並未提供這項功能。如果你需要的話，crates.io 上會有提供這項功能的 crate。

字串並不簡單

總結來說，字串是很複雜的。不同的程式語言會選擇不同的決定來呈現給程式設計師。Rust 選擇正確處理 String 的方式作為所有 Rust 程式的預設行為，這也代表開發者在處理 UTF-8 資料時需要多加考量。這樣的取捨的確對比其他程式語言來說，增加了不少字串的複雜程度，但是這能讓你在開發週期免於處理非 ASCII 字元相關的錯誤。

好消息是標準函式庫針對 String 與 &str 型別提供了許多功能，來幫助正確處理這些複雜的情況。別忘了翻翻技術文件來學習這些實用的方法，像是 contains 能搜尋字串，而 replace 能替換部份字串成另一個字串。

讓我們接下去看一個較簡單地集合吧：雜湊映射（hash maps）！

透過雜湊映射儲存鍵值配對

我們最後一個常見的集合是雜湊映射（hash map），HashMap<K, V> 型別會儲存一個鍵（key）型別 K 對應到一個數值（value）型別 V。它透過雜湊函式（hashing function）來決定要將這些鍵與值放在記憶體何處。許多程式語言都有支援這種類型的資料結構，不過通常它們會提供不同的名稱，像是 hash、map、object、hash table、dictionary 或 associative array 等等。

雜湊映射適合用於當你不想像向量那樣用索引搜尋資料，而是透過一個可以為任意型別的鍵來搜尋的情況。舉例來說，在比賽中我們可以使用雜湊映射來儲存每隊的分數，每個鍵代表隊伍名稱，而每個值代表隊伍分數。給予一個隊伍名稱，你就能取得該隊伍分數。

我們會在此段落介紹雜湊映射的基本 API，但還有很多實用的函式定義在標準函式庫的 HashMap<K, V> 中，所以別忘了查閱標準函式庫的技術文件來瞭解更多資訊。

建立新的雜湊映射

其中一種建立空的雜湊映射的方式是使用 new 並透過 insert 加入新元素。在範例 8-20 我們追蹤兩支隊伍的分數，分別為藍隊與黃隊。藍隊初始分數有 10 分，黃隊則有 50 分。

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("藍隊"), 10);
    scores.insert(String::from("黃隊"), 50);
}

範例 8-20：建立新的雜湊映射並插入一些鍵值

注意到我們需要先使用 use 將標準函式庫的 HashMap 集合引入。在我們介紹的三個常見集合中，此集合是最少被用到的，所以它並沒有包含在 prelude 內讓我們能自動參考。雜湊映射也沒有像前者那麼多標準函式庫提供的支援，像是內建建構它們的巨集。

和向量一樣，雜湊映射會將它們的資料儲存在堆積上。此 HashMap 的鍵是 String 型別而值是 i32 型別。和向量一樣，雜湊函式宣告後就都得是同類的，所有的鍵都必須是同型別，且所有的值也都必須是同型別。

取得雜湊映射的數值

我們可以透過 get 方法並提供鍵來取得其在雜湊映射對應的值，如範例 8-21 所示。

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("藍隊"), 10);
    scores.insert(String::from("黃隊"), 50);

    let team_name = String::from("藍隊");
    let score = scores.get(&team_name).copied().unwrap_or(0);
}

範例 8-21：取得雜湊映射中藍隊的分數

score 在此將會是對應藍隊的分數，而且結果會是 10。結果是使用 Some 的原因是因為 get 回傳的是 Option<&V>。如果雜湊映射中該鍵沒有對應值的話，get 就會回傳 None。所以程式會需要透過我們在第六章談到的方式處理 Option。

我們也可以使用 for 迴圈用類似的方式來遍歷雜湊映射中每個鍵值配對：

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("藍隊"), 10);
    scores.insert(String::from("黃隊"), 50);

    for (key, value) in &scores {
        println!("{key}: {value}");
    }
}

此程式會以任意順序印出每個配對：

黃隊: 50
藍隊: 10

雜湊映射與所有權

像是 i32 這種有實作 Copy 特徵的型別其數值可以被拷貝進雜湊映射之中。但對於像是 String 這種擁有所有權的數值則會被移動到雜湊映射，並成為該數值新的擁有者，如範例 8-22 所示。

fn main() {
    use std::collections::HashMap;

    let field_name = String::from("Favorite color");
    let field_value = String::from("藍隊");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name 和 field_value 在這之後就不能使用了，你可以試著使用它們並看看編譯器回傳什麼錯誤
}

範例 8-22：展示當鍵值插入雜湊映射後就會擁有它們

我們之後就無法使用變數 field_name 和 field_value，因為它們的值已經透過呼叫 insert 被移入雜湊映射之中。

如果我們插入雜湊映射的數值是參考的話，該值就不會被移動到雜湊映射之中。不過該值的參考就必須一直有效，至少直到該雜湊映射離開作用域為止。我們會在第十章的「透過生命週期驗證參考」段落討落更多細節。

更新雜湊映射

雖然鍵值配對的數量可以增加，但每個鍵同一時間就只能有一個對應的值而已。（反之並不成立：比如藍隊黃隊可以同時都在 scores 雜湊映射內儲存 10 分）

當你想要改變雜湊映射的資料的話，你必須決定如何處理當一個鍵已經有一個值的情況。你可以不管舊的值，直接用新值取代。你也可以保留舊值、忽略新值，只有在該鍵尚未擁有對應數值時才賦值給它。或者你也可以將舊值與新值組合起來。讓我們看看分別怎麼處理吧！

覆蓋數值

如果我們在雜湊映射插入一個鍵值配對，然後又在相同鍵插入不同的數值的話，該鍵相對應的數值就會被取代。如範例 8-23 雖然我們呼叫了兩次 insert，但是雜湊映射只會保留一個鍵值配對，因為我們向藍隊的鍵插入了兩次數值。

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("藍隊"), 10);
    scores.insert(String::from("藍隊"), 25);

    println!("{:?}", scores);
}

範例 8-23：替換某個特定鍵對應的數值

此程式碼會印出 {"藍隊": 25}，原本的數值 10 會被覆蓋。

只在鍵不存在的情況下插入鍵值

通常檢查雜湊映射有沒有存在某個特定的鍵值是很常見的。我們接下來的動作通常就是檢查如果鍵存在於雜湊映射的話，就不改變其值。但如果鍵不存在的話，就插入數值給它。

雜湊映射提供了一個特別的 API 叫做 entry 讓你可以用想要檢查的鍵作為參數。entry 方法的回傳值是一個列舉叫做 Entry，它代表了一個可能存在或不存在的數值。假設我們想要檢查黃隊的鍵有沒有對應的數值。如果沒有的話，我們想插入 50。而對藍隊也一樣。使用 entry API 的話，程式碼會長得像範例 8-24。

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("藍隊"), 10);

    scores.entry(String::from("黃隊")).or_insert(50);
    scores.entry(String::from("藍隊")).or_insert(50);

    println!("{:?}", scores);
}

範例 8-24：使用 entry 方法在只有該鍵尚無任何數值時插入數值

Entry 中的 or_insert 方法定義了如果 Entry 的鍵有對應的數值的話，就回傳該值的可變參考；如果沒有的話，那就插入參數作為新數值，並回傳此值的可變參考。這樣的技巧比我們親自寫邏輯還來的清楚，而且更有利於借用檢查器的檢查。

執行範例 8-25 的程式碼會印出 {"黃隊": 50, "藍隊": 10}。第一次 entry 的呼叫會對黃隊插入數值 50，因為黃隊尚未有任何數值。第二次 entry 的呼叫則不會改變雜湊映射，因為藍隊已經有數值 10。

依據舊值更新數值

雜湊映射還有另一種常見的用法是，依照鍵的舊數值來更新它。舉例來說，範例 8-25 展示了一支如何計算一些文字內每個單字各出現多少次的程式碼。我們使用雜湊映射，鍵為單字然後值為我們每次追蹤計算對應單字出現多少次的次數。如果我們是第一次看到該單字的話，我們插入數值 0。

fn main() {
    use std::collections::HashMap;

    let text = "hello world wonderful world";

    let mut map = HashMap::new();

    for word in text.split_whitespace() {
        let count = map.entry(word).or_insert(0);
        *count += 1;
    }

    println!("{:?}", map);
}

範例 8-25：使用雜湊映射儲存單字與次數來計算每個字出現的次數

此程式碼會印出 {"world": 2, "hello": 1, "wonderful": 1}。你可能會看到鍵值配對的順序不太一樣，回想一下「取得雜湊映射的數值」段落中提過遍歷雜湊映射的順序是任意的。

split_whitespace 方法會遍歷 text 中被空格分開來的切片。or_insert 方法會回傳該鍵對應數值的可變參考（&mut V）。在此我們將可變參考儲存在 count 變數中，所以要賦值的話，我們必須先使用 * 來解參考（dereference）count。可變參考會在 for 結束時離開作用域，所以所有的改變都是安全的且符合借用規則。

雜湊函式

HashMap 預設是使用一種叫做 SipHash 的雜湊函式（hashing function），這可以透過 ¹ 雜湊表（hash table）抵禦阻斷服務（Denial of Service, DoS）的攻擊。這並不是最快的雜湊演算法，但為了提升安全性而犧牲一點效能是值得的。如果你做評測時覺得預設的雜湊函式太慢無法滿足你的需求的話，你可以指定不同的 hasher 來切換成其他雜湊函式。Hasher 是一個有實作 BuildHasher 特徵的型別。我們會在第十章討論到特徵以及如何實作它們。你不必從頭自己實作一個 hasher，crates.io 上有其他 Rust 使用者分享的函式庫，其中就有不少提供許多常見雜湊演算法的 hasher 實作。

總結

當你的程式需要儲存、取得、修改資料時，向量、字串與雜湊映射可以提供大量的功能。以下是一些你應該能夠解決的練習題：

• 給予一個整數列表，請使用向量並回傳中位數（排序列表後正中間的值）以及眾數（出現最多次的值，雜湊映射在此應該會很有用）。
• 將字串轉換成 pig latin。每個單字的第一個字母為子音的話，就將該字母移到單字後方，並加上「ay」，所以「first」會變成「irst-fay」。而單字第一個字母為母音的話，就在單字後方加上「hay」，所以「apple」會變成「apple-hay」。請注意要考慮到 UTF-8 編碼！
• 使用雜湊映射與向量來建立文字介面，讓使用者能新增員工名字到公司內的一個部門。舉來來說「將莎莉加入工程部門」或「將阿米爾加入業務部門」。然後讓使用者可以索取一個部門所有的員工列表，或是依據部門用字典順序排序，取得公司內所有的員工。

標準函式庫的 API 技術文件有詳細介紹向量、字串與雜湊映射的所有方法，這對於這些練習題應該會很有幫助！

我們現在已經開始遇到有可能會運作失敗的複雜程式了，所以接下來正是來討論錯誤處理的時候！

錯誤處理

錯誤是軟體開發中不可避免的一環，所以 Rust 有一些特色能夠處理發生錯誤的情形。在許多情況下，Rust 要求你要能知道可能出錯的地方，並在編譯前採取行動。這樣的要求能讓你的程式更穩定，確保你能發現錯誤並在程式碼發佈到生產環境前妥善處理它們！

Rust 將錯誤分成兩大類：可復原的（recoverable）和不可復原的（unrecoverable）錯誤。像是找不到檔案這種可復原的錯誤，我們通常很可能只想回報問題給使用者並重試。而不可復原的錯誤就會是程式錯誤的跡象，像是嘗試取得陣列結尾之後的位置。

許多語言不會區分這兩種錯誤，並以相同的方式處理，使用像是例外（exceptions）這樣統一的機制處理。Rust 沒有例外處理機制，取而代之的是它對可復原的錯誤提供 Result<T, E> 型別，對不可復原的錯誤使用 panic! 將程式停止執行。本章節會先介紹 panic! 再來討論 Result<T, E> 數值的回傳。除此之外，我們也將探討何時該從錯誤中復原，何時該選擇停止程式。

對無法復原的錯誤使用 panic!

有時候壞事就是會發生在你的程式中，這本來就是你沒辦法全部避免的。在這種情況，Rust 有提供 panic! 巨集。在實際情況下我們有兩種方式可以造成恐慌：做出確定會讓程式碼恐慌的動作（像是存取陣列範圍外的元素），或是直接呼叫 panic! 巨集。在這兩種狀況下，我們都對程式造成了恐慌。這些恐慌預設會印出程式出錯的訊息，展開並清理堆疊，然後離開程式。再加上環境變數的話，你還可以讓 Rust 顯示恐慌時呼叫的堆疊，讓你能更簡單地追蹤恐慌的源頭。

恐慌時該解開堆疊還是直接終止

當恐慌（panic）發生時，程式預設會開始做解開（unwind）堆疊的動作，這代表 Rust 會回溯整個堆疊，並清理每個它遇到的函式資料。但是這樣回溯並清理的動作很花力氣。另一種方式是直接終止（abort）程式而不清理，程式使用的記憶體會需要由作業系統來清理。

如果你需要你的專案產生的執行檔越小越好，你可以從解開切換成終止，只要在 Cargo.toml 檔案中的 [profile] 段落加上 panic = 'abort' 就好。舉例來說，如果你希望在發佈模式（release mode）恐慌時直接終止，那就加上：

[profile.release]
panic = 'abort'

讓我們先在小程式內試試呼叫 panic!：

檔案名稱：src/main.rs

fn main() {
    panic!("◢▆▅▄▃ 崩╰(〒皿〒)╯潰▃▄▅▆◣");
}

當你執行程式時，你會看到像這樣的結果：

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished dev [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`
thread 'main' panicked at '◢▆▅▄▃ 崩╰(〒皿〒)╯潰▃▄▅▆◣', src/main.rs:2:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

panic! 的呼叫導致印出了最後兩行的錯誤訊息。第一行顯示了我們的恐慌訊息以及該恐慌是在原始碼何處發生的：src/main.rs:2:5 指的是它發生在我們的 src/main.rs 檔案第二行第五個字元。

在此例中，該行指的就是我們寫的程式碼。如果我們查看該行，我們會看到 panic! 巨集的呼叫。在其他情形，panic! 的呼叫可能會發生在我們呼叫的程式碼內，所以錯誤訊息回報的檔案名稱與行數可能就會是其他人呼叫 panic! 巨集的程式碼，而不是因為我們的程式碼才導致 panic! 的呼叫。我們可以在呼叫 panic! 程式碼的地方使用 backtrace 來找出出現問題的地方。接下來我們就會深入瞭解 backtrace。

使用 panic! Backtrace

讓我們看看另一個例子，這是函式庫發生錯誤而呼叫 panic!，而不是來自於我們在程式碼自己呼叫的巨集。範例 9-1 是個嘗試從向量有效範圍外取得索引的例子。

檔案名稱：src/main.rs

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

範例 9-1：嘗試取得超出向量長度的元素，進而導致 panic! 被呼叫

我們在這邊嘗試取得向量中第 100 個元素（不過因為索引從零開始，所以是索引 99），但是該向量只有 3 個元素。在此情況下，Rust 就會恐慌。使用 [] 會回傳元素，但是如果你傳遞了無效的索引，Rust 就回傳不了正確的元素。

在 C 中，嘗試讀取資料結構結束之後的元素屬於未定義行為。你可能會得到該記憶體位置對應其資料結構的元素，即使該記憶體完全不屬於該資料結構。這就稱做緩衝區過讀（buffer overread）而且會導致安全漏洞。攻擊者可能故意操縱該索引來取得在資料結構後面他們原本不應該讀寫的值。

為了保護你的程式免於這樣的漏洞，如果你嘗試用一個不存在的索引讀取元素的話，Rust 會停止執行並拒絕繼續運作下去。讓我們嘗試執行並看看會如何：

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished dev [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/panic`
thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', src/main.rs:4:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

此錯誤指向 main.rs 的第四行，也就是我們嘗試存取索引 99 的地方。下一行提示告訴我們可以設置 RUST_BACKTRACE 環境變數來取得 backtrace 以知道錯誤發生時到底發生什麼事。backtrace 是一個函式列表，指出得到此錯誤時到底依序呼叫了哪些函式。Rust 的 backtraces 運作方式和其他語言一樣：讀取 backtrace 關鍵是從最一開始讀取直到你看到你寫的檔案。那就會是問題發生的源頭。那行以上的行數就是你所呼叫的程式，而以下則是其他呼叫你的程式碼的程式。這些行數可能還會包含 Rust 核心程式碼、標準函式庫程式碼，或是你所使用的 crate。我們設置 RUST_BACKTRACE 環境變數的值不為 0，來嘗試取得 backtrace 吧。你應該會看到和範例 9-2 類似的結果。

$ RUST_BACKTRACE=1 cargo run
thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', src/main.rs:4:5
stack backtrace:
   0: rust_begin_unwind
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/std/src/panicking.rs:584:5
   1: core::panicking::panic_fmt
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/panicking.rs:142:14
   2: core::panicking::panic_bounds_check
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/panicking.rs:84:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/slice/index.rs:242:10
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/slice/index.rs:18:9
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/alloc/src/vec/mod.rs:2591:9
   6: panic::main
             at ./src/main.rs:4:5
   7: core::ops::function::FnOnce::call_once
             at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/ops/function.rs:248:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

範例 9-2：當 RUST_BACKTRACE 設置時，透過呼叫 panic! 產生的 backtrace

輸出結果有點多啊！你看到的實際輸出可能會因你的作業系統與 Rust 版本而有所不同。要取得這些資訊的 backtrace，除錯符號（debug symbols）必須啟用。當我們在使用 cargo build 或 cargo run 且沒有加上 --release 時，除錯符號預設是啟用的。

在範例 9-2 的輸出結果中，第 6 行的 backtrace 指向了我們專案中產生問題的地方：src/main.rs 中的第四行。如果我們不想讓程式恐慌，我們就要來調查我們所寫的程式中第一個被錯誤訊息指向的位置。在範例 9-1 中，我們故意寫出會恐慌的程式碼。要修正的方法就是不要索取超出向量索引範圍的元素。當在未來你的程式碼恐慌時，你會需要知道是程式碼中的什麼動作造成的、什麼數值導致恐慌以及正確的程式碼該怎麼處理。

我們會在本章節「要 panic! 還是不要 panic!」的段落中再回來看 panic! 並研究何時該與不該使用 panic! 來處理錯誤條件。接下來，我們要看如何使用 Result來處理可回復的錯誤。

Result 與可復原的錯誤

大多數的錯誤沒有嚴重到需要讓整個程式停止執行。有時候當函式失敗時，你是可以輕易理解並作出反應的。舉例來說，如果你嘗試開啟一個檔案，但該動作卻因為沒有該檔案而失敗的話，你可能會想要建立檔案，而不是終止程序。

回憶一下第二章的「使用 Result 型別可能的錯誤」提到 Result 列舉的定義有兩個變體 Ok 和 Err，如以下所示：

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T 和 E 是泛型型別參數，我們會在第十章深入討論泛型。你現在需要知道的是 T 代表我們在成功時會在 Ok 變體回傳的型別，而 E 則代表失敗時在 Err 變體會回傳的錯誤型別。因為 Result 有這些泛型型別參數，我們可以將 Result 型別和它的函式用在許多不同場合，讓成功與失敗時回傳的型別不相同。

讓我們呼叫一個可能會失敗的函式並回傳 Result 型別。在範例 9-3 我們嘗試開啟一個檔案。

檔案名稱：src/main.rs

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");
}

範例 9-3：嘗試開啟一個檔案

File::open 的回傳型別為 Result<T, E>。泛型參數 T 在此已經被 File::open 指明成功時會用到的型別 std::fs::File，也就是檔案的控制代碼（handle）。用於錯誤時的 E 型別則是 std::io::Error。這樣的回傳型別代表 File::open 的呼叫在成功時會回傳我們可以讀寫的檔案控制代碼，但該函式呼叫也可能失敗。舉例來說，該檔案可能會不存在，或者我們沒有檔案的存取權限。File::open 需要有某種方式能告訴我們它的結果是成功或失敗，並回傳檔案控制代碼或是錯誤資訊。這樣的資訊正是 Result 列舉想表達的。

如果 File::open 成功的話，變數 greeting_file_result 的數值就會獲得包含檔案控制代碼的 Ok 實例。如果失敗的話，greeting_file_result 的值就會是包含為何產生該錯誤的資訊的 Err 實例。

我們需要讓範例 9-3 的程式碼依據 File::open 回傳不同的結果採取不同的動作。範例 9-4 展示了其中一種處理 Result 的方式，我們使用第六章提到的 match 表達式。

檔案名稱：src/main.rs

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => panic!("開啟檔案時發生問題：{:?}", error),
    };
}

範例 9-4：使用 match 表達式來處理回傳的 Result 變體

和 Option 列舉一樣，Result 列舉與其變體都會透過 prelude 引入作用域，所以我們不需要指明 Result::，可以直接在 match 的分支中使用 Ok 和 Err 變體。

當結果是 Ok 時，這裡的程式碼就會回傳 Ok 變體中內部的 file，然後我們就可以將檔案控制代碼賦值給變數 greeting_file。在 match 之後，我們就可以使用檔案控制代碼來讀寫。

match 的另一個分支則負責處理我們從 File::open 中取得的 Err 數值。在此範例中，我們選擇呼叫 panic! 巨集。如果檔案 hello.txt 不存在我們當前的目錄的話，我們就會執行此程式碼，接著就會看到來自 panic! 巨集的輸出結果：

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
    Finished dev [unoptimized + debuginfo] target(s) in 0.73s
     Running `target/debug/error-handling`
thread 'main' panicked at '開啟檔案時發生問題：Os { code: 2, kind: NotFound, message: "No such file or directory" }', src/main.rs:8:23
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

如往常一樣，此輸出告訴我們哪裡出錯了。

配對不同種的錯誤

範例 9-4 的程式碼不管 File::open 為何失敗都會呼叫 panic!。不過我們想要依據不同的錯誤原因採取不同的動作，如果 File::open 是因為檔案不存在的話，我們想要建立檔案並回傳新檔案的控制代碼。如果 File::open 是因為其他原因失敗的話，像是我們沒有開啟檔案的權限，我們仍然要像範例 9-4 這樣呼叫 panic!。對此我們可以加上 match 表達式，如範例 9-5 所示。

檔案名稱：src/main.rs

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("建立檔案時發生問題：{:?}", e),
            },
            other_error => {
                panic!("開啟檔案時發生問題：{:?}", other_error);
            }
        },
    };
}

範例 9-5：針對不同種類的錯誤採取不同動作

File::open 在 Err 變體的回傳型別為 io::Error，這是標準函式庫提供的結構體。此結構體有個 kind 方法讓我們可以取得 io::ErrorKind 數值。標準函式庫提供的列舉 io::ErrorKind 有從 io 運算可能發生的各種錯誤。我們想處理的變體是 ErrorKind::NotFound，這指的是我們嘗試開啟的檔案還不存在。所以我們對 greeting_file_result 配對並在用 error.kind() 繼續配對下去。

我們從內部配對檢查 error.kind() 的回傳值是否是 ErrorKind 列舉中的 NotFound 變體。如果是的話，我們就嘗試使用 File::create 建立檔案。不過 File::create 也可能會失敗，所以我們需要第二個內部 match 表達式來處理。如果檔案無法建立的話，我們就會印出不同的錯誤訊息。第二個分支的外部 match 分支保持不變，如果程式遇到其他錯誤的話就會恐慌。

除了使用 match 配對 Result<T, E> 以外的方式

我們用的 match 的確有點多！match 表達式雖然很實用，不過它的行為非常基本。在第十三章你會學到閉包（closure），Result<T, E> 型別有很多接收閉包的方法。使用這些方法可以讓你的程式碼更簡潔。

舉例來說，以下是另一種能寫出與範例 9-5 邏輯相同的程式碼，這次則是使用到閉包與 unwrap_or_else 方法：

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("建立檔案時發生問題：{:?}", error);
            })
        } else {
            panic!("開啟檔案時發生問題：{:?}", error);
        }
    });
}

雖然此程式碼的行為和範例 9-5 一樣，但他沒有包含任何 match 表達式而且更易閱讀。當你讀完第十三章後，別忘了回來看看此範例，並查閱標準函式庫中的 unwrap_or_else 方法。除此方法以外，還有更多方法可以來解決處理錯誤時龐大的 match 表達式。

錯誤發生時產生恐慌的捷徑：unwrap 與 expect

雖然 match 已經足以勝任指派的任務了，但它還是有點冗長，而且可能無法正確傳遞錯誤的嚴重性。Result<T, E> 型別有非常多的輔助方法來執行不同的特定任務。unwrap 就和我們在範例 9-4 所寫的 match 表達式一樣，擁有類似效果的捷徑方法。如果 Result 的值是 Ok 變體，unwrap會回傳 Ok 裡面的值；如果 Result 是 Err 變體的話，unwrap 會呼叫 panic! 巨集。以下是使用 unwrap 的方式：

檔案名稱：src/main.rs

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap();
}

如果我們沒有 hello.txt 這個檔案並執行此程式碼的話，我們會看到從 unwrap 方法所呼叫的 panic! 回傳訊息：

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Os {
code: 2, kind: NotFound, message: "No such file or directory" }',
src/main.rs:4:49

還有另一個方法 expect 和 unwrap 類似，不過能讓我們選擇 panic! 回傳的錯誤訊息。使用 expect 而非 unwrap 並提供完善的錯誤訊息可以表明你的意圖，讓追蹤恐慌的源頭更容易。expect 的語法看起來就像這樣：

檔案名稱：src/main.rs

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt 應該要存在此專案中");
}

我們使用 expect 的方式和 unwrap 一樣，不是回傳檔案控制代碼就是呼叫 panic! 巨集。使用 expect 呼叫 panic! 時的錯誤訊息會是我們傳遞給 expect 的參數，而不是像 unwrap 使用 panic! 預設的訊息。訊息看起來就會像這樣：

thread 'main' panicked at 'hello.txt 應該要存在此專案中: Os {
code: 2, kind: NotFound, message: "No such file or directory" }',
src/main.rs:5:10

在正式環境等級的程式碼，大多數 Rustaceans 會選擇 expect 而不是 unwrap，這樣能在出錯時提供更多資訊，告訴我們為何預期該動作永遠成功。這樣一來就算你的假設證明錯誤，你都能夠在除錯時有足夠的資訊來理解。

傳播錯誤

當函式實作呼叫的程式碼可能會失敗時，與其直接在該函式本身處理錯誤，你可以回傳錯誤給呼叫此程式的程式碼，由它們決定如何處理。這稱之為傳播（propagating）錯誤並讓呼叫者可以有更多的控制權，因為比起你程式碼當下的內容，回傳的錯誤可能提供更多資訊與邏輯以利處理。

舉例來說，範例 9-6 展示了一個從檔案讀取使用者名稱的函式。如果檔案不存在或無法讀取的話，此函式會回傳該錯誤給呼叫該函式的程式碼。

檔案名稱：src/main.rs

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let username_file_result = File::open("hello.txt");

    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut username = String::new();

    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(e) => Err(e),
    }
}
}

範例 9-6：使用 match 回傳錯誤給呼叫者的函式

此函式還能再更簡化，但我們要先繼續手動處理來進一步探討錯誤處理，最後我們會展示最精簡的方式。讓我們先看看此函式的回傳型別 Result<String, io::Error>。這代表此函式回傳的型別為 Result<T, E>，其中泛型型別 T 已經指明為實際型別 String，而泛型型別 E 則指明為實際型別 io::Error。

如果函式正確無誤的話，程式碼會呼叫此函式並收到擁有 String 的 Ok 數值。如果程式遇到任何問題的話，呼叫此函式的程式碼就會獲得擁有包含相關問題發生資訊的 io::Error 實例的 Err 數值。我們選擇 io::Error 作為函式的回傳值是因為它正是 File::open 函式和 read_to_string 方法失敗時的回傳的錯誤型別。

函式本體從呼叫 File::open 開始，然後我們使用 match 回傳 Result 數值，就和範例 9-4 的 match 類似。如果 File::open 成功的話，變數 file 中的檔案控制代碼賦值給可變變數 username_file 並讓函式繼續執行下去。但在 Err 的情形時，與其呼叫 panic!，我們使用 return 關鍵字來讓函式提早回傳，並將 File::open 的錯誤值，也就是模式中的變數 e，作為此函式的錯誤值回傳給呼叫的程式碼。

所以如果我們在 username_file 有拿到檔案控制代碼的話，接著函式就會在變數 username 建立新的 String 並對檔案控制代碼 username_file 呼叫 read_to_string 方法來讀取檔案內容至 username。read_to_string 也會回傳 Result 因為它也可能失敗，就算 File::open 是執行成功的。所以我們需要另一個 match 來處理該 Result，如果 read_to_string 成功的話，我們的函式就是成功的，然後在 Ok 回傳 username 中該檔案的使用者名稱。如果 read_to_string 失敗的話，我們就像處理 File::open 的 match 一樣回傳錯誤值。不過我們不需要顯式寫出 return，因為這是函式中的最後一個表達式。

呼叫此程式碼的程式就會需要處理包含使用者名稱的 Ok 數值以及包含 io::Error 的 Err 數值。這交給呼叫的程式碼來決定如何處理這些數值。舉例來說，如果呼叫此程式碼而獲得錯誤的話，它可能選擇呼叫 panic! 讓程式崩潰，或者使用預設的使用者名稱從檔案以外的地方尋找該使用者。所以我們傳播所有成功或錯誤的資訊給呼叫者，讓它們能妥善處理。

這樣傳播錯誤的模式是非常常見的，所以 Rust 提供了 ? 來簡化流程。

傳播錯誤的捷徑：? 運算子

範例 9-7 是另一個 read_username_from_file的實作，擁有和範例 9-6 一樣的效果，不過這次使用了 ? 運算子。

檔案名稱：src/main.rs

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username_file = File::open("hello.txt")?;
    let mut username = String::new();
    username_file.read_to_string(&mut username)?;
    Ok(username)
}
}

範例 9-7：使用 ? 運算子回傳錯誤給呼叫者的函式

定義在 Result 數值後的 ? 運作方式幾乎與範例 9-6 的 match 表達式處理 Result 的方式一樣。如果 Result 的數值是 Ok 的話，Ok 內的數值就會從此表達式回傳，然後程式就會繼續執行。如果數值是 Err 的話，Err 就會使用 return 關鍵字作為整個函式的回傳值回傳，讓錯誤數值可以傳遞給呼叫者的程式碼。

不過範例 9-6 的 match 表達式做的事和 ? 運算子做的事還是有不同的地方：? 運算子呼叫所使用的錯誤數值會傳遞到 from 函式中，這是定義在標準函式庫的 From 特徵中，用來將數值從一種型別轉換另一種型別。當 ? 運算子呼叫 from 函式時，接收到的錯誤型別會轉換成目前函式回傳值的錯誤型別。這在當函式要回傳一個錯誤型別來代表所有函式可能的失敗是很有用的，即使可能會失敗的原因有很多種。

舉例來說，我們可以將範例 9-7 的函式 read_username_from_file 改成回傳一個我們自訂的錯誤型別叫做 OurError。如果我們有定義 impl From<io::Error> for OurError 能從 io::Error 建立一個 OurError 實例的話，那麼 read_username_from_file 本體中的 ? 運算就會呼叫 from 然後轉換錯誤型別，不必在函式那多加任何程式碼。

在範例 9-7 中，在 File::open 的結尾中 ? 回傳 Ok 中的數值給變數 username_file。如果有錯誤發生時，? 運算子會提早回傳整個函式並將 Err 的數值傳給呼叫的程式碼。同理也適用在呼叫 read_to_string 結尾的 ?。

? 運算子可以消除大量樣板程式碼並讓函式實作更簡單。我們還可以再進一步將方法直接串接到 ? 後來簡化程式碼，如範例 9-8 所示。

檔案名稱：src/main.rs

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username = String::new();

    File::open("hello.txt")?.read_to_string(&mut username)?;

    Ok(username)
}
}

範例 9-8：在 ? 運算子後方串接方法呼叫

我們將建立新 String 的變數 username 移到函式的開頭，這部分沒有任何改變。再來與建立變數 username_file 的地方不同的是，我們直接將 read_to_string 串接到 File::open("hello.txt")? 的結果後方。我們在 read_to_string 呼叫的結尾還是有 ?，然後我們還是在 File::open 和 read_to_string 成功沒有失敗時，回傳包含 username 的 Ok 數值。函式達成的效果仍然與範例 9-6 與 9-7 相同。這只是一個比較不同但慣用的寫法。

說到此函式不同的寫法，範例 9-9 展示了使用 fs::read_to_string 更短的寫法。

檔案名稱：src/main.rs

#![allow(unused)]
fn main() {
use std::fs;
use std::io;

fn read_username_from_file() -> Result<String, io::Error> {
    fs::read_to_string("hello.txt")
}
}

範例 9-9：使用 fs::read_to_string 而不是開啟檔案後才讀取

讀取檔案至字串中算是個常見動作，所以標準函式庫提供了一個方便的函式 fs::read_to_string 來開啟檔案、建立新的 String、讀取檔案內容、將內容放入該 String 並回傳它。不過使用 fs::read_to_string 就沒有機會讓我們來解釋所有的錯誤處理，所以我們一開始才用比較長的寫法。

? 運算子可以用哪裡？

? 運算子只能用在有函式的回傳值相容於 ? 使用的值才行。這是因為 ? 運算子會在函式中提早回傳數值，就像我們在範例 9-6 那樣用 match 表達式提早回傳一樣。在範例 9-6 中，match 使用的是 Result 數值，函式的回傳值必須是 Result 才能相容於此 return。

讓我們看看在範例 9-10 的 main 函式中的回傳值要是不相容於我們用在 ? 的型別，如果我們使用 ? 運算子會發生什麼事：

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")?;
}

檔案名稱：src/main.rs

範例 9-10：嘗試在回傳 () 的 main 函式中使用 ? 會無法編譯

此程式碼會開啟檔案，所以可能會失敗。? 運算子會拿到 File::open 回傳的 Result 數值，但是此 main 函式的回傳值為() 而非 Result。當我們編譯此程式碼時，我們會得到以下錯誤訊息：

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`)
 --> src/main.rs:4:48
  |
3 | fn main() {
  | --------- this function should return `Result` or `Option` to accept `?`
4 |     let greeting_file = File::open("hello.txt")?;
  |                                                ^ cannot use the `?` operator in a function that returns `()`
  |
  = help: the trait `FromResidual<Result<Infallible, std::io::Error>>` is not implemented for `()`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `error-handling` due to previous error

此錯誤告訴我們只能在回傳型別為 Result 或 Option 或其他有實作 FromResidual 的型別的函式才能使用 ? 運算子。

要修正此錯誤的話，你有兩種選擇。其中一種是如果你沒有任何限制的話，你可以將函式回傳值變更成與 ? 運算子相容的型別。另一種則是依照可能的情境使用 match 或 Result<T, E> 其中一種方法來處理 Result<T, E>。

錯誤訊息還提到了 ? 也能用在 Option<T> 的數值。就像 ? 能用在 Result一樣，你只能在有回傳 Option 的函式中，對 Option 的值使用 ?。在 Option<T> 呼叫 ? 的行為與在 Result<T, E> 上呼叫類似：如果數值為 None，None 就會在函式該處被提早回傳；如果數值為 Some，Some 中的值就會是表達式的結果數值，且程式會繼續執行下去。以下範例 9-11 的函式會尋找給予文字的第一行中最後一個字元：

fn last_char_of_first_line(text: &str) -> Option<char> {
    text.lines().next()?.chars().last()
}

fn main() {
    assert_eq!(
        last_char_of_first_line("Hello, world\nHow are you today?"),
        Some('d')
    );

    assert_eq!(last_char_of_first_line(""), None);
    assert_eq!(last_char_of_first_line("\nhi"), None);
}

範例 9-11：Option<T> 的數值上使用在 ? 運算子

此函式會回傳 Option<char>，因為它可能會在此真的找到字元，或者可能根本沒有半個字存在。此程式碼接受引數 text 字串切片，並呼叫它的 lines 方法，這會回傳一個遍歷字串每一行的疊代器。因為此函式想要的是第一行，它對疊代器只呼叫 next 來取得疊代器的第一個數值。如果 text 是空字串的話，這裡 next 的呼叫就會回傳 None。我們這裡就可以使用 ? 來中斷 last_char_of_first_line 並回傳 None。如果 text 不是空字串的話，next 會用 Some 數值來回傳 text 的第一行字串切片。

? 會取出字串切片，然後我們可以對字串切片呼叫 chars 來取得它的疊代器。我們在意的是第一行的最後一個字元，所以我們呼叫 last 來取得疊代器的最後一個值。這也是個 Option 因為第一行可能是個空字串。如果 text 開頭就換行，但在下一行有字元的話，它可能就會是 "\nhi"。不過如果第一行真的有最後一個字元的話，它就會回傳 Some 變體。在這過程中的 ? 運算子讓我們能簡潔地表達此邏輯，並讓我們能只用一行就能實作出來。如果我們對 Option 無法使用 ? 運算子的話，我們使用更多方法呼叫或 match 表達式才能實作此邏輯。

請注意你可以在有回傳 Result 的函式對 Result 的值使用 ? 運算子，你可以在有回傳 Option 的函式對 Option 的值使用 ? 運算子，但你無法混合使用。? 運算子無法自動轉換 Result 與 Option 之間的值。在這種狀況下會需要顯式表達，Result 的話有提供 ok 方法，Option 的話有提供 ok_or 方法。

目前為止，所有我們使用過的 main 函式都是回傳 ()。main 是個特別的函式，因為它是可執行程式的進入點與出口點，而要讓程式可預期執行的話，它的回傳型別就得要有些限制。

幸運的是 main 也可以回傳 Result<(), E>。範例 9-12 取自範例 9-10，不過我們更改 main 的回傳型別為Result<(), Box<dyn Error>>，並在結尾的回傳數值加上 Ok(())。這樣的程式碼是能編譯的：

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let greeting_file = File::open("hello.txt")?;

    Ok(())
}

範例 9-12：將 main 改成回傳 Result<(), E> 就能允許在 Result 數值上使用 ? 運算子

Box<dyn Error> 型別使用了特徵物件（trait object）我們會在第十七章的「允許不同型別數值的特徵物件」討論到。現在你可以將 Box<dyn Error> 視為它是「任何種類的錯誤」。在有 Box<dyn Error> 錯誤型別的 main 函式中的 Result 使用 ? 是允許的，因為現在 Err 數值可以被提早回傳。盡管此 main 函式本來只會回傳錯誤型別 std::io::Error，但有了 Box<dyn Error> 的話，此簽名就能允許其他錯誤型別加入 main 本體中。

當 main 函式回傳 Result<(), E> 時，如果 main 回傳 Ok(()) 的話，執行檔就會用 0 退出；如果 main 回傳 Err 數值的話，就會用非零數值退出。用 C 語言寫的執行檔在退出時會回傳整數：程式成功退出的話會回傳整數 0，而程式退出錯誤的話則會回傳不是 0 的其他整數。而 Rust 執行檔也遵循相容這項規則。

main 函式可以回傳任何有實作 std::process::Termination 特徵的型別，該特徵包含了一個函式 report 來回傳 ExitCode。你可以查閱標準函式庫技術文件來了解如何對你的型別實作 Termination 特徵。

現在我們已經討論了呼叫 panic! 與回傳 Result 的細節。現在讓我們回到何時該使用何種辦法的主題上吧。

要 panic! 還是不要 panic!

所以你該如何決定何時要呼叫 panic! 還是要回傳 Result 呢？當程式碼恐慌時，就沒有任何恢復的方式。你可以在任何錯誤場合呼叫 panic!，無論是可能或不可能復原的情況。不過這樣你就等於替呼叫你的程式碼的呼叫者做出決定，讓情況變成無法復原的錯誤了。當你選擇回傳 Result 數值，你將決定權交給呼叫者的程式碼。呼叫者可能會選擇符合當下場合的方式嘗試復原錯誤，或者它可以選擇 Err 內的數值是不可恢復的，所以它就呼叫 panic! 讓你原本可恢復的錯誤轉成不可恢復。因此，當你定義可能失敗的函式時預設回傳 Result 是不錯的選擇。

在像是範例、草稿與測試的情況下，程式碼恐慌會比回傳 Result 來得恰當。讓我們來探討為何比較好。然後我們再來討論編譯器無法辨別出不可能失敗，但身為人類的你卻可以的情況。本章節會總結一些通用指導原則來決定何時在函式庫程式碼中恐慌。

範例、程式碼原型與測試

當你在寫解釋一些概念的範例時，寫出完善錯誤處理的範例，反而會讓範例變得較不清楚。在範例中，使用像是 unwrap 這樣會恐慌的方法可以被視為是一種要求使用者自行決定如何處理錯誤的表現，因為他們可以依據程式碼執行的方式來修改此方法。

同樣地 unwrap 與 expect 方法也很適用在試做原型，你可以在決定準備開始處理錯誤前使用它們。它們會留下清楚的痕跡，當你準備好要讓程式碼更穩固時，你就能回來修改。

如果有方法在測試內失敗時，你會希望整個測試都失敗，就算該方法不是要測試的功能。因為 panic! 會將測試標記為失敗，所以在此呼叫 unwrap 或 expect 是很正確的。

當你知道的比編譯器還多的時候

如果你知道一些編譯器不知道的邏輯的話，直接在 Result 呼叫 unwrap 或 expect 來直接取得 Ok 的數值是很有用的。你還是會有個 Result 數值需要做處理，你呼叫的程式碼還是有機會失敗的，就算在你的特定場合中邏輯上是不可能的。如果你能保證在親自審閱程式碼後，你絕對不可能會有 Err 變體的話，那麼呼叫 unwrap 是完全可以接受的。而更好的話，用 expect 說明為何你一定不會遇到 Err 變體。以下範例就是如此：

fn main() {
    use std::net::IpAddr;

    let home: IpAddr = "127.0.0.1"
        .parse()
        .expect("寫死的 IP 位址應該要有效");
}

我們傳遞寫死的字串來建立 IpAddr 的實例。我們可以看出 127.0.0.1 是完全合理的 IP 位址，所以這邊我們可以直接 expect。不過使用寫死的合理字串並不會改變 parse 方法的回傳型別，我們還是會取得 Result 數值，編譯器仍然會要我們處理 Result 並認為 Err 變體是有可能發生的。因為編譯器並沒有聰明到可以看出此字串是個有效的 IP 位址。如果 IP 位址的字串是來自使用者輸入而非我們寫死進程式的話，它的確有可能會失敗，這時我們就得要認真處理 Result 了。註明該 IP 位址是寫死的能在未來我們想拿掉 expect 並改善錯誤處理時，幫助我們理解需要如何從其他來源處理 IP 位址。

錯誤處理的指導原則

當你的程式碼可能會導致嚴重狀態的話，就建議讓你的程式恐慌。這裡的嚴重狀態是指一些假設、保證、協議或不可變性被打破時的狀態，像是當你的程式碼有無效的數值、互相矛盾的數值或缺少數值。另外還加上以下情形：

• 該嚴重狀態並非預期會發生的，而不是像使用者輸入了錯誤格式這種偶而可能會發生的。
• 你的程式在此時需要避免這種嚴重狀態，而不是在每一步都處理此問題。
• 你所使用的型別沒有適合的方式能夠處理此嚴重狀態。我們會在第十七章的「定義狀態與行為成型別」段落用範例解釋我們指的是什麼。

如果有人呼叫了你的程式碼卻傳遞了不合理的數值，如果可以的話最好的辦法是回傳個錯誤，這樣函式庫的使用者可以決定在該情況下該如何處理。不過要是繼續執行下去可能會造成危險或不安全的話，最好的辦法是呼叫 panic! 並警告使用函式庫的人他們程式碼錯誤發生的位置，好讓他們在開發時就能修正。同樣地，panic! 也適合用於如果你呼叫了你無法掌控的外部程式碼，然後它回傳了你無法修正的無效狀態。

不過如果失敗是可預期的，回傳 Result 就會比呼叫 panic! 來得好。類似的例子有，語法分析器（parser）收到格式錯誤的資訊，或是 HTTP 請求回傳了一個狀態，告訴你已經達到請求上限了。在這樣的案例，回傳 Result 代表失敗是預期有時會發生的，而且呼叫者必須決定如何處理。

當你的程式碼可能會因為進行運算時輸入無效數值，而造成使用者安危的話，你的程式需要先驗證該數值，如果數值無效的話就要恐慌。這是基於安全原則，嘗試對無效資料做運算的話可能會導致你的程式碼產生漏洞。這也是標準函式庫在你嘗試取得超出界限的記憶體存取會呼叫 panic! 的主要原因。嘗試取得不屬於當前資料結構的記憶體是常見的安全問題。函式通常都會訂下一些合約（contracts），它們的行為只有在輸入資料符合特定要求時才帶有保障。當違反合約時恐慌是十分合理的，因為違反合約就代表這是呼叫者的錯誤，這不是你的程式碼該主動處理的錯誤。事實上，呼叫者也沒有任何合理的理由來復原這樣的錯誤。函式的合約應該要寫在函式的技術文件中解釋，尤其是違反時會恐慌的情況。

然而要在你的函式寫一大堆錯誤檢查有時是很冗長且麻煩的。幸運的是你可以利用 Rust 的型別系統（以及編譯器的型別檢查）來幫你完成檢驗。如果你的函式用特定型別作為參數的話，你就可以認定你的程式邏輯是編輯器已經幫你確保你拿到的數值是有效的。舉例來說，如果你有一個型別而非 Option 的話，你的程式就會預期取得某個值而不是沒拿到值。你的程式就不必處理 Some 和 None 這兩個變體情形，它只會有一種情況並絕對會拿到數值。要是有人沒有傳遞任何值給你的函式會根本無法編譯，所以你的函式就不需要在執行時做檢查。另一個例子是使用非帶號整數像是 u32 來確保參數不會是負數。

建立自訂型別來驗證

讓我們來試著使用 Rust 的型別系統來進一步確保我們擁有有效數值，並建立自訂型別來驗證。回想一下第二章的猜謎遊戲，我們的程式碼要使用者從 1 到 100 之間猜一個數字。在開始與祕密數字做比較之前，我們從未驗證使用者輸入的值，我們只驗證了它是否為正的。在這種情況帶來的後果還不算嚴重：我們還是會顯示「太大」或「太小」。但是我們可以改善這段來引導使用者輸入有效數值，並在使用者輸入時猜了超出範圍的數字或字母時呈現不同行為。

我們可以將輸入的猜測分析改成 i32 而非 u32 來允許負數，並檢查數字是否在範圍內，如以下所示：

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("請猜測一個數字！");

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

    loop {
        // --省略--

        println!("請輸入你的猜測數字。");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("讀取行數失敗");

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

        if guess < 1 || guess > 100 {
            println!("祕密數字介於 1 到 100 之間。");
            continue;
        }

        match guess.cmp(&secret_number) {
            // --省略--
            Ordering::Less => println!("太小了！"),
            Ordering::Greater => println!("太大了！"),
            Ordering::Equal => {
                println!("獲勝！");
                break;
            }
        }
    }
}

if 表達式檢查我們的數值是否超出範圍，如果是的話就告訴使用者問題原因，並呼叫 continue 來進行下一次的猜測循環，要求再猜一次。在 if 表達式之後我們就能用已經知道範圍是在 1 到 100 的 guess 與祕密數字做比較。

不過這並非理想解決方案：如果程式必定要求數值一定要是 1 到 100，而且我們有很多函式都有此需求的話，在每個函式都檢查就太囉唆了（而且可能會影響效能）。

對此我們可以建立一個新的型別，並且建立一個驗證產生實例的函式，這樣我們就不必在每個地方都做驗證。這樣一來函式就可以安全地以這個新型別作為簽名，並放心地使用收到的數值。範例 9-13 顯示了定義 Guess 型別的例子，它的 new 函式只會在接收值為 1 到 100 時才會建立 Guess 實例。

#![allow(unused)]
fn main() {
pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("猜測數字必須介於 1 到 100 之間，你輸入的是 {}。", value);
        }

        Guess { value }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}
}

範例 9-13：只會擁有 1 到 100 的 Guess 型別

首先我們定義了一個結構體叫做 Guess，其欄位叫做 value 並會持有 i32。這就是數字會被儲存的地方。

接著我們實作一個 Guess 的關聯函式叫做 new 來建立 Guess 的值。new 函式定義的參數叫做 value 並擁有型別 i32，且最後會回傳 Guess。函式 new 本體中的程式碼會驗證 value 確保它位於 1 到 100 之間。如果 value 沒有通過驗證，我們呼叫 panic! 來警告呼叫此程式碼的開發者，他們可能有需要修正的程式錯誤，因為使用超出範圍的 value 來建立 Guess 違反了 Guess::new 的合約。Guess::new 會恐慌的情況需要在公開的 API 技術文件中提及。我們會在第十四章討論如何寫出技術文件並在 API 技術文件中指出可能發生 panic! 的情形。如果 value 通過驗證的話，我們就建立一個新的 Guess 並將參數 value 賦值給 value 欄位，最後回傳 Guess。

接著我們實作了個方法叫做 value，它會借用 self 且沒有任何參數，並會回傳 i32。這種方法有時會被稱為 getter，因為它的目的是從它的欄位中取得一些資料並回傳它。此公開方法是必要的，因為 Guess 結構體中的 value 欄位是私有的。將 Guess 結構體的 value 欄位設為私有是很重要的，這樣就無法直接設置 value ，模組外的程式碼必須使用 Guess::new 函式來建立 Guess 的實例，因而確保 Guess 不可能會有沒有經過 Guess::new 函式驗證的 value。

這樣當函式的參數或回傳值只能是數字 1 到 100 的話，它的簽名就能使用或回傳 Guess 而不是 i32，因此就不必在它的本體內做任何額外檢查。

總結

Rust 的錯誤檢查功能的設計旨在協助你寫出可靠的程式碼。panic! 巨集告訴你的程式遇到了它無法處理的狀態，並讓你告訴程序停止，而不是繼續嘗試使用無效或不正確的數值。Result 列舉使用 Rust 的型別系統來指出可能會失敗的運算，並讓你的程式碼有辦法恢復。你可以使用 Result 來告訴使用你的程式碼的呼叫者，他們需要處理可能成功與失敗的情形。在適當的場合使用 panic! 與 Result 能讓你的程式碼在不可避免的問題中更加可靠。

現在你已經看過標準函式庫中 Option 與 Result 使用泛型的優勢了，就讓我們來討論泛型如何運作的，以及你如何在程式碼中使用它們。

泛型型別、特徵與生命週期

每個程式語言都有能夠高效處理概念複製的工具。在 Rust 此工具就是泛型（generics）：實際型別或其他屬性的抽象替代。我們可以表達泛型的行為，或是它們與其他泛型有何關聯，而不必在編譯與執行程式時知道它們實際上是什麼。

函式也可以接受一些泛型型別參數，而不是實際型別像是 i32 或 String，就像函式有辦法能接收多種未知數值作為參數來執行相同程式碼。事實上我們已經在第六章的 Option<T>、第八章的 Vec<T> 和 HashMap<K, V> 以及第九章的 Result<T, E> 使用過泛型了。在本章節，你將會探索如何用泛型定義你自己的型別、函式與方法！

首先我們會先檢視如何提取參數來減少重複的程式碼。接著我們會以相同的技巧使用泛型將兩個只有參數型別不同的函式轉變成泛型函式。我們還會解釋如何在結構體和列舉使用泛型型別。

再來你會學會如何使用特徵（traits） 來定義共同行為。你可以組合特徵與泛型型別來限制泛型型別只適用在有特定行為的型別，而不是任意型別。

最後我們會來介紹生命週期（lifetimes）：一種能讓編譯器知道參考如何互相關聯的泛型。生命週期讓我們能提供給編譯器更多關於借用數值的資訊，好讓它在更多情況下可以確保參考是有效的。

提取函數來減少重複性

泛型讓我們可以用佔位符（placeholder）替代特定型別，來表示多重型別並減少程式碼的重複性。在我們深入泛型語法之前，讓我們先來看如何不用泛型型別的情況下，用提取函式的方式減少重複的程式碼。之後我們就會用相同的方式來提取泛型函式！和你透過找出重複的程式碼來提取程式一樣，你也將找出重複的函式來轉成泛型。

我們先從範例 10-1 中一支尋找列表中最大數字的小程式開始。

檔案名稱：src/main.rs

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("最大數字為 {}", largest);
    assert_eq!(*largest, 100);
}

範例 10-1：在數字列表中尋找最大數字的程式碼

我們儲存整數列表到變數 number_list 並將列表第一個數字的參考放入變數 largest。接著我們遍歷列表中的所有元素，如果目前數字比 largest 內儲存的數字還大的話，就會替代成該變數的參考。不過如果目前數值小於或等於最大值的話，變數就不會被改變，程式會接續檢查列表中的下一個數字。在考慮完列表中的所有數字後，largest 就應該會指向最大數字，在此例就是 100。

現在我們要從兩個不同的數字列表中找到最大值，我們可以重複範例 10-1 的程式碼，然後在程式中兩個不同的地方使用相同的邏輯，如範例 10-2 所示。

檔案名稱：src/main.rs

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("最大數字為 {}", largest);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("最大數字為 {}", largest);
}

範例 10-2：在兩個數字列表中尋找最大值

雖然這樣的程式碼能執行，寫出重複的程式碼很囉唆而且容易出錯。我們還得記住每次更新時就得一起更新各個地方。

要去除重複的部分，我們可以建立一層抽象，定義一個可以處理任意整數列表作為參數的函式。這樣的解決辦法讓我們的程式更清晰，而且讓我們能抽象表達出從列表中尋找最大值這樣的概念。

在範例 10-3 我們提取了尋找最大值的程式碼成一個函式叫做 largest。然後我們呼叫函式來尋找範例 10-2 兩個列表中最大的數字。我們還可以在未來對其他任何 i32 的列表使用此函式。

檔案名稱：src/main.rs

fn largest(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("最大數字為 {}", result);
    assert_eq!(*result, 100);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let result = largest(&number_list);
    println!("最大數字為 {}", result);
    assert_eq!(*result, 6000);
}

範例 10-3：抽象出尋找最大值的概念並用在兩個不同的列表

largest 函式有個參數 list 可以代表我們傳遞給函式的 i32 型別切片。所以當我們呼叫此函式時，程式可以依據我們傳入的特定數值執行。

總結來說，以下是我們將範例 10-2 的程式碼轉換成範例 10-3 的步驟：

1. 找出重複的程式碼。
2. 將重複的程式碼提取置函式本體內，並指定函式簽名輸入與回傳數值。
3. 更新重複使用程式碼的實例，改呼叫我們定義的函式。

接著我們將以相同的步驟來使用泛型來減少重複的程式碼。就像函式本體可以抽象出 list 而不用特定數值，泛型允許程式碼執行抽象型別。

舉例來說，假設我們有兩個函式：一個會找出 i32 型別切片中的最大值而另一個會找出 char 型別切片的最大值。我們要如何刪除重複的部分呢？讓我們拭目以待！

泛型資料型別

我們使用泛型（generics）來建立項目的定義，像是函式簽名或結構體，讓我們在之後可以使用在不同的實際資料型別。讓我們先看看如何使用泛型定義函式、列舉與方法。然後我們會在來看泛型對程式碼的效能影響如何。

在函式中定義

當要使用泛型定義函數時，我們通常會將泛型置於函式簽名中指定參數與回傳值資料型別的位置。這樣做能讓我們的程式碼更具彈性並向呼叫者提供更多功能，同時還能防止重複程式碼。

接續我們 largest 函式的例子，範例 10-4 展示了兩個都在切片上尋找最大值的函式。我們要使用泛型將它們融合成一個函式。

檔案名稱：src/main.rs

fn largest_i32(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn largest_char(list: &[char]) -> &char {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest_i32(&number_list);
    println!("最大數字為 {}", result);
    assert_eq!(*result, 100);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("最大字元為 {}", result);
    assert_eq!(*result, 'y');
}

範例 10-4：兩個名稱與其簽名中的型別都不同的函式

largest_i32 函式和我們在範例 10-3 提取的函式一樣都是尋找切片中最大的 i32。而 largest_char 函式則尋找切片中最大的 char。函式本體都擁有相同的程式碼，讓我們來開始用泛型型別參數來消除重複的部分，轉變成只有一個函式吧。

要在新定義的函式中參數化型別的話，我們需要為參數型別命名，就和我們在函式中的參數數值所做的一樣。你可以用任何標識符來命名型別參數名稱。但我們習慣上會用 T，因為 Rust 的型別參數名稱都盡量很短，常常只會有一個字母，而且 Rust 對於型別命名的慣用規則是駝峰式大小寫（CamelCase）。所以 T 作為「type」的簡稱是大多數 Rust 程式設計師的選擇。

當我們在函式本體使用參數時，我們必須在簽名中宣告參數名稱，編譯器才能知道該名稱代表什麼。同樣地，當我們要在函式簽名中使用型別參數名稱，我們必須在使用前宣告該型別參數名稱。要定義泛型 largest 函式的話，我們在函式名稱與參數列表之間加上尖括號，其內就是型別名稱的宣告，如以下所示：

fn largest<T>(list: &[T]) -> &T {

我們可以這樣理解定義：函式 largest 有泛型型別 T，此函式有一個參數叫做 list，它的型別為數值 T 的切片。largest 函式會回傳與型別 T 相同型別的參考數值。

範例 10-5 顯示了使用泛型資料型別於函式簽名組合出的 largest 函式。此範例還展示了我們如何依序用 i32 和 char 的切片呼叫函式。注意此程式碼尚未能編譯，不過我們會在本章之後修改它。

檔案名稱：src/main.rs

fn largest<T>(list: &[T]) -> &T {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("最大數字為 {}", result);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("最大字元為 {}", result);
}

範例 10-5：使用泛型型別參數的 largest 函式，但現在還不能編譯

如果我們現在就編譯程式碼的話，我們會得到此錯誤：

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0369]: binary operation `>` cannot be applied to type `&T`
 --> src/main.rs:5:17
  |
5 |         if item > largest {
  |            ---- ^ ------- &T
  |            |
  |            &T
  |
help: consider restricting type parameter `T`
  |
1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T {
  |             ++++++++++++++++++++++

For more information about this error, try `rustc --explain E0369`.
error: could not compile `chapter10` due to previous error

提示文字中提到了 std::cmp::PartialOrd 這個特徵（trait）。我們會在下個段落來討論特徵。現在只需要知道 largest 本體無法適用於所有可能的 T 型別，因為我們想要在本體中比較型別 T 的數值，我們只能在能夠排序的型別中做比較。要能夠比較的話，標準函式庫有提供 std::cmp::PartialOrd 特徵讓你可以針對你的型別來實作（請查閱附錄 C 來瞭解更多此特徵的細節）。照著提示文字的建議，我們限制 T 只對有實作 PartialOrd 的型別有效。這樣此範例就能編譯，因為標準函式庫有對 i32 與 char 實作 PartialOrd。

在結構體中定義

我們一樣能以 <> 語法來對結構體中一或多個欄位使用泛型型別參數。範例 10-6 展示了定義 Point<T> 結構體並讓 x 與 y 可以是任意型別數值。

檔案名稱：src/main.rs

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
}

範例 10-6：Point<T> 結構體的 x 與 y 會有型別 T 的數值

在結構體定義使用泛型的語法與函式定義類似。首先，我們在結構體名稱後方加上尖括號，並在其內宣告型別參數名稱。接著我們能在原本指定實際資料型別的地方，使用泛型型別來定義結構體。

注意到我們使用了一個泛型型別來定義 Point<T>，此定義代表 Point<T> 是某型別 T 下之通用的，而且欄位 x 與 y 擁有相同型別，無論最終是何種型別。如果我們用不同的型別數值來建立 Point<T> 實例，我們的程式碼會無法編譯，如範例 10-7 所示。

檔案名稱：src/main.rs

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wont_work = Point { x: 5, y: 4.0 };
}

範例 10-7：欄位 x 與 y 必須是相同型別，因為它們擁有相同的泛型資料型別 T

在此例中，當我們賦值 5 給 x 時，我們讓編譯器知道 Point<T> 實例中的泛型型別 T 會是整數。然後我們將 4.0 賦值給 y，這應該要和 x 有相同型別，所以我們會獲得以下錯誤：

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0308]: mismatched types
 --> src/main.rs:7:38
  |
7 |     let wont_work = Point { x: 5, y: 4.0 };
  |                                      ^^^ expected integer, found floating-point number

For more information about this error, try `rustc --explain E0308`.
error: could not compile `chapter10` due to previous error

要將結構體 Point 的 x 與 y 定義成擁有不同型別卻仍然是泛型的話，我們可以使用多個泛型型別參數。舉例來說，在範例 10-8 我們改變了 Point 的定義為擁有兩個泛型型別 T 與 U，x 擁有型別 T 而 y 擁有型別 U。

檔案名稱：src/main.rs

struct Point<T, U> {
    x: T,
    y: U,
}

fn main() {
    let both_integer = Point { x: 5, y: 10 };
    let both_float = Point { x: 1.0, y: 4.0 };
    let integer_and_float = Point { x: 5, y: 4.0 };
}

範例 10-8：Point<T, U> 擁有兩個泛型型別，所以 x 和 y 可以有不同的型別數值

現在這些所有的 Point 實例都是允許的了！你要在定義中使用多少泛型型別參數都沒問題，但用太多的話會讓你的程式碼難以閱讀。如果你發現你的程式碼需要使用大量泛型的話，這通常代表你的程式碼需要重新組織成更小的元件。

在列舉中定義

如同結構體一樣，我們可以定義列舉讓它們的變體擁有泛型資料型別。讓我們看看我們在第六章標準函式庫提供的 Option<T> 列舉：

#![allow(unused)]
fn main() {
enum Option<T> {
    Some(T),
    None,
}
}

此定義現在對你來說應該就說得通了。如同你所看到的 Option<T> 列舉有個泛型型別參數 T 以及兩個變體：Some 擁有型別 T 的數值；而 None 則是不具任何數值的變體。使用 Option<T> 列舉我們可以表達出一個可能擁有的數值這樣的抽象概念。而且因為 Option<T> 是泛型，不管可能的數值型別為何，我們都能使用此抽象。

列舉也能有數個泛型型別。我們在第九章所使用列舉 Result 的定義就是個例子：

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

Result 列舉有兩個泛型型別 T 和 E 且有兩個變體：Ok 擁有型別 T 的數值；而 Err 擁有型別 E 的數值。這樣的定義讓我們很方便能表達 Result 列舉可能擁有一個成功的數值（回傳型別 T 的數值）或失敗的數值（回傳型別為 E 的錯誤值）。事實上這就是我們在範例 9-3 開啟檔案的方式，當我們成功開啟檔案時的 T 就會是型別 std::fs::File，然後當開啟檔案會發生問題時 E 就會是型別 std::io::Error。

當你發現你的程式碼有許多結構體或列舉都只有儲存的值有所不同時，你可以使用泛型型別來避免重複。

在方法中定義

我們可以對結構體或列舉定義方法（如第五章所述）並也可以使用泛型型別來定義。範例 10-9 展示了我們在範例 10-6 定義的結構體 Point<T> 並實作了一個叫做 x 的方法。

檔案名稱：src/main.rs

struct Point<T> {
    x: T,
    y: T,
}

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

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

範例 10-9：在 Point<T> 結構體實作一個方法叫做 x，其會回傳 x 欄位中型別為 T 的參考

我們在這 Point<T> 定義了一個方法叫做 x 並回傳欄位 x 的資料參考。

注意到我們需要在 impl 宣告 T，才有 T 可以用來標明我們在替型別 Point<T> 實作其方法。在 impl 之後宣告泛型型別 T，Rust 可以識別出 Point 尖括號內的型別為泛型型別而非實際型別。我們其實可以選用不同的泛型參數名稱，而不用和結構體定義的泛型參數一樣，不過通常使用相同名稱還是比較常見。無論該泛型型別最終會是何種實際型別，任何方法在有宣告泛型型別的 impl 內，都會被定義成適用於各種型別實例。

當我們在定義方法時，我們也可以對泛型型別加上些限制。舉例來說，我們可以只針對 Point<f32> 的實例來實作方法，而非適用於任何泛型型別的 Point<T> 實例。在範例 10-10 我們使用了實例型別 f32 而沒有在 impl 宣告任何型別。

檔案名稱：src/main.rs

struct Point<T> {
    x: T,
    y: T,
}

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

impl Point<f32> {
    fn distance_from_origin(&self) -> f32 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

範例 10-10：一個只適用於擁有泛型 T 結構體其中的特定實際型別的 impl 區塊

此程式碼代表 Point<f32> 會有個方法 distance_from_origin，其他 Point<T> 只要 T 不是型別 f32 的實例都不會定義此方法。此方法測量我們的點距離座標 (0.0, 0.0) 有多遠並使用只有浮點數型別能使用的數學運算。

在結構體定義中的泛型型別參數不會總是和結構體方法簽名中的相同。舉例來說，範例 10-11 在 Point 結構體中使用泛型型別 X1 和 Y1，但在 mixup 方法中就使用 X2 Y2 以便清楚辨別。該方法用 self Point 的 x 值（型別為 X1）與參數傳進來的 Point 的 y 值（型別為 Y2）來建立新的 Point 實例。

檔案名稱：src/main.rs

struct Point<X1, Y1> {
    x: X1,
    y: Y1,
}

impl<X1, Y1> Point<X1, Y1> {
    fn mixup<X2, Y2>(self, other: Point<X2, Y2>) -> Point<X1, Y2> {
        Point {
            x: self.x,
            y: other.y,
        }
    }
}

fn main() {
    let p1 = Point { x: 5, y: 10.4 };
    let p2 = Point { x: "Hello", y: 'c' };

    let p3 = p1.mixup(p2);

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

範例 10-11：結構體定義中使用不同的泛型型別的方法

在 main 中，我們定義了一個 Point，其 x 型別為 i32（數值為 5），y 型別為 f64（數值為 10.4）。變數 p2 是個 Point 結構體，x 為字串切片（數值為 "Hello"），y 為 char（數值為 c）。在 p1 呼叫 mixup 並加上引數 p2 的話會給我們 p3，它的 x 會有型別 i32，因為 x 來自 p1。而且變數 p3 還會有型別為 char 的 y，因為 y 來自 p2。println! 巨集的呼叫就會顯示 p3.x = 5, p3.y = c。

此例是是為了展示一些泛型參數是透過 impl 宣告而有些則是透過方法定義來取得。泛型參數 X1 和 Y1 是宣告在 impl 之後，因為它們與結構體定義有關聯。泛型參數 X2 和 Y2 則是宣告在 fn mixup 之後，因為它們只與方法定義有關聯。

使用泛型的程式碼效能

你可能會好奇當你使用泛型型別參數會不會有執行時的消耗。好消息是使用泛型型別不會比使用實際型別還來的慢。

Rust 在編譯時對使用泛型的程式碼進行單型化（monomorphization）。單型化是個讓泛型程式碼轉換成特定程式碼的過程，在編譯時填入實際的型別。在此過程中，編譯器會做與我們在範例 10-5 建立泛型函式相反的事：編譯器檢查所有泛型程式碼被呼叫的地方，並依據泛型程式碼被呼叫的情況產生實際型別的程式碼。

讓我們看看這在標準函式庫的泛型列舉 Option<T> 中是怎麼做到的：

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

當 Rust 編譯此程式碼時中，他會進行單型化。在此過程中，會讀取 Option<T> 實例中使用的數值並識別出兩種 Option<T>：一種是 i32 而另一種是 f64。接著它就會將 Option<T> 的泛型定義展開為兩種定義 i32 與 f64，以此替換函式定義為特定型別。

單型化的版本看起來會像這樣（編譯器實際使用的名稱會和我們這邊示範的不同）：

檔案名稱：src/main.rs

enum Option_i32 {
    Some(i32),
    None,
}

enum Option_f64 {
    Some(f64),
    None,
}

fn main() {
    let integer = Option_i32::Some(5);
    let float = Option_f64::Some(5.0);
}

泛型 Option<T> 會被替換成編譯器定義的特定定義。因為 Rust 會編譯泛型程式碼成個別實例的特定型別，我們使用泛型就不會造成任何執行時消耗。當程式執行時，它就會和我們親自寫重複定義的版本一樣。單型化的過程讓 Rust 的泛型在執行時十分有效率。

特徵：定義共同行為

特徵（trait）會定義特定型別與其他型別共享的功能。我們可以使用特徵定義來抽象出共同行為。我們可以使用特徵界限（trait bounds）來指定泛型型別為擁有特定行為的任意型別。

注意：特徵類似於其他語言常稱作介面（interfaces）的功能，但還是有些差異。

定義特徵

一個型別的行為包含我們對該型別可以呼叫的方法。如果我們可以對不同型別呼叫相同的方法，這些型別就能定義共同行為了。特徵定義是一個將方法簽名統整起來，來達成一些目的而定義一系列行為的方法。

舉例來說，如果我們有數個結構體各自擁有不同種類與不同數量的文字：結構體 NewsArticle 儲存特定地點的新聞故事，然後 Tweet 則有最多 280 字元的內容，且有個欄位來判斷是全新的推文、轉推或其他推文的回覆。

我們想要建立ㄧ個多媒體聚集器函式庫 crate 叫 aggregator 來顯示可能存在 NewsArticle 或 Tweet 實例的資料總結。要達成此目的的話，我們需要每個型別的總結，且我們會呼叫該實例的 summarize 方法來索取總結。範例 10-12 顯示了表達此行為的 Summary 特徵定義。

檔案名稱：src/lib.rs

pub trait Summary {
    fn summarize(&self) -> String;
}

範例 10-12：Summary 特徵包含 summarize 方法所定義的行為

我們在此使用 trait 關鍵字定義一個特徵，其名稱為 Summary。我們也將特徵宣告成 pub 所以其他會依賴此函式庫的 crate 也能用到此特徵，我們之後會再看到其他範例。在大括號中，我們宣告方法簽名來描述有實作此特徵的型別行為，在此例就是 fn summarize(&self) -> String。

在方法簽名之後，我們並沒有加上大括號提供實作細節，而是使用分號。每個有實作此特徵的型別必須提供其自訂行為的方法本體。編譯器會強制要求任何有 Summary 特徵的型別都要有定義相同簽名的 summarize 方法。

特徵本體中可以有多個方法，每行會有一個方法簽名並都以分號做結尾。

為型別實作特徵

現在我們已經用 Summary 特徵定義了所需的方法簽名。我們可以在我們多媒體聚集器的型別中實作它。範例 10-13 顯示了 NewsArticle 結構體實作 Summary 特徵的方式，其使用頭條、作者、位置來建立 summerize 的回傳值。至於結構體 Tweet，我們使用使用者名稱加上整個推文的文字來定義 summarize，因為推文的內容長度已經被限制在 280 個字元以內了。

檔案名稱：src/lib.rs

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{} {} 著 ({})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

範例 10-13：在型別 NewsArticle 與 Tweet 實作 Summary 特徵

為一個型別實作一個特徵類似於實作一般的方法。不同的地方在於在 impl 之後我們加上的是想要實作的特徵，然後在用 for 關鍵字加上我們想要實作特徵的型別名稱。在 impl 的區塊內我們置入該特徵所定義的方法簽名，我們使用大括號並填入方法本體來為對特定型別實作出特徵方法的指定行為。

現在，我們就能像呼叫正常方法一樣，來呼叫 NewsArticle 和 Tweet 實例的方法，如以下所示： 現在函式庫已經對 NewsArticle 和 Tweet 實作 Summary 特徵了，crate 的使用者能像我們平常呼叫方法那樣，對 NewsArticle 和 Tweet 的實例呼叫特徵方法。唯一的不同是使用者必須將特徵也加入作用域中。以下的範例展示執行檔 crate 如何使用我們的 aggregator 函式庫 crate：

use aggregator::{self, Summary, Tweet};

fn main() {
    let tweet = Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        retweet: false,
    };

    println!("1 則新推文：{}", tweet.summarize());
}

此程式碼會印出「1 則新推文：horse_ebooks: of course, as you probably already know, people」。

其他依賴 aggregator 函式庫的 crate 也能將 Summary 特徵引入作用域並對他們自己的型別實作 Summary 特徵。不過實作特徵時有一個限制，那就是我們只能在該特徵或該型別位於我們的 crate 時，才能對型別實作特徵。舉例來說，我們可以對自訂型別像是 Tweet 來實作標準函式庫的 Display 特徵來為我們 crate aggregator 增加更多功能。因為 Tweet 位於我們的 aggregator crate 裡面。我們也可以在我們的 crate aggregator 內對 Vec<T> 實作 Summary。因為特徵 Summary 也位於我們的 aggregator crate 裡面。

但是我們無法對外部型別實作外部特徵。舉例來說我們無法在我們的 aggregator crate 裡面對 Vec<T> 實作 Display 特徵。因為 Display 與 Vec<T> 都定義在標準函式庫中，並沒有在我們 aggregator crate 裡面。此限制叫做「連貫性（coherence）」是程式屬性的一部分。更具體來說我們會稱作「孤兒原則（orphan rule）」，因為上一代（parent）型別不存在。此原則能確保其他人的程式碼不會破壞你的程式碼，反之亦然。沒有此原則的話，兩個 crate 可以都對相同型別實作相同特徵，然後 Rust 就會不知道該用哪個實作。

預設實作

有時候對特徵內的一些或所有方法定義預設行為是很實用的，而不必要求每個型別都實作所有方法。然後當我們對特定型別實作特徵時，我們可以保留或覆蓋每個方法的預設行為。

在範例 10-14 我們在 Summary 特徵內指定 summarize 方法的預設字串，而不必像範例 10-12 只定義了方法簽名。

檔案名稱：src/lib.rs

pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(閱讀更多...)")
    }
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

範例 10-14：Summary 特徵定義了 summarize 方法的預設實作

要使用預設實作來總結 NewsArticle 的話，我們可以指定一個空的 impl 區塊，像是 impl Summary for NewsArticle {}。

我們沒有直接對 NewsArticle 定義 summarize 方法，因為我們使用的是預設實作並聲明對 NewsArticle 實作 Summary 特徵。所以最後我們仍然能在 NewsArticle 實例中呼叫 summarize，如以下所示：

use aggregator::{self, NewsArticle, Summary};

fn main() {
    let article = NewsArticle {
        headline: String::from("Penguins win the Stanley Cup Championship!"),
        location: String::from("Pittsburgh, PA, USA"),
        author: String::from("Iceburgh"),
        content: String::from(
            "The Pittsburgh Penguins once again are the best \
             hockey team in the NHL.",
        ),
    };

    println!("有新文章發佈！{}", article.summarize());
}

此程式碼會印出 有新文章發佈！(閱讀更多...)。

建立預設實作不會影響範例 10-13 中 Tweet 實作的 Summary。因為要取代預設實作的語法，與當沒有預設實作時實作特徵方法的語法是一樣的。

預設實作也能呼叫同特徵中的其他方法，就算那些方法沒有預設實作。這樣一來，特徵就可以提供一堆實用的功能，並要求實作者只需處理一小部分就好。舉例來說，我們可以定義 Summary 特徵，使其擁有一個必須要實作的summarize_author 方法，以及另一個擁有預設實作會呼叫 summarize_author 的方法：

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(從 {} 閱讀更多...)", self.summarize_author())
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

要使用這個版本的 Summary，我們只需要在對型別實作特徵時定義 summarize_author 就好：

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(從 {} 閱讀更多...)", self.summarize_author())
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

在我們定義 summarize_author 之後，我們可以在結構體 Tweet 的實例呼叫 summarize，然後 summarize 的預設實作會呼叫我們提供的 summarize_author。因為我們已經定義了summarize_author，且 Summary 特徵有提供 summarize 方法的預設實作，所以我們不必再寫任何程式碼。

use aggregator::{self, Summary, Tweet};

fn main() {
    let tweet = Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        retweet: false,
    };

    println!("1 則新推文：{}", tweet.summarize());
}

此程式碼會印出 1 則新推文：(從 @horse_ebooks 閱讀更多...)。

注意要是對相同方法覆寫實作的話，就無法呼叫預設實作。

特徵作為參數

現在你知道如何定義與實作特徵，我們可以來探討如何使用特徵來定義函式來接受多種不同的型別。我們會使用範例 10-13 中 NewsArticle 與 Tweet 實作的 Summary 特徵，來定義一個函式 notify 使用它自己的參數 item 來呼叫 summarize 方法，所以此參數的型別預期有實作 Summary 特徵。 為此我們可以使用 impl Trait 語法，如以下所示：

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{} {} 著 ({})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

pub fn notify(item: &impl Summary) {
    println!("頭條新聞！{}", item.summarize());
}

與其在 item 參數指定實際型別，我們用的是 impl 關鍵字並加上特徵名稱。這樣此參數就會接受任何有實作指定特徵的型別。在 notify 本體中我們就可以用 item 呼叫 Summary 特徵的任何方法，像是 summarize。我們可以呼叫 notify 並傳遞任何 NewsArticle 或 Tweet 的實例。但如果用其他型別像是 String 或 i32 來呼叫此程式碼的話會無法編譯，因為那些型別沒有實作 Summary。

特徵界限語法

impl Trait 語法看起來很直觀，不過它其實是一個更長格式的語法糖，這個格式稱之為「特徵界限（trait bound）」，它長得會像這樣：

pub fn notify<T: Summary>(item: &T) {
    println!("頭條新聞！{}", item.summarize());
}

此格式等同於之前段落的範例，只是比較長一點。我們將特徵界限置於泛型型別參數的宣告中，在尖括號內接在冒號之後。

impl Trait 語法比較方便，且在簡單的案例中可以讓程式碼比較簡潔；而特徵界限語法則適合用於其他比較複雜的案例。舉例來說我們可以有兩個有實作 Summary 的參數，使用 impl Trait 語法看起來會像這樣：

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

如果我們想要此函式允許 item1 和 item2 是不同型別的話，使用 impl Trait 的確是正確的（只要它們都有實作 Summary）。不過如果我們希望兩個參數都是同一型別的話，我們就得使用特徵界限來表達，如以下所示：

pub fn notify<T: Summary>(item1: &T, item2: &T) {

泛型型別 T 作為 item1 和 item2 的參數會限制函式，讓傳遞給 item1 和 item2 參數的數值型別必須相同。

透過 + 來指定多個特徵界限

我們也可以指定不只一個特徵界限。假設我們還想要 notify 中的 item 不只能夠呼叫 summarize 方法，還能顯示格式化訊息的話，我們可以在 notify 定義中指定 item 必須同時要有 Display 和 Summary。這可以使用 + 語法來達成：

pub fn notify(item: &(impl Summary + Display)) {

+ 也能用在泛型型別的特徵界限中：

pub fn notify<T: Summary + Display>(item: &T) {

有了這兩個特徵界限，notify 本體就能呼叫 summarize 以及使用 {} 來格式化 item。

透過 where 來使特徵界限更清楚

使用太多特徵界限也會帶來壞處。每個泛型都有自己的特徵界限，所以有數個泛型型別的函式可以在函式名稱與參數列表之間包含大量的特徵界限資訊，讓函式簽名難以閱讀。因此 Rust 有提供另一個在函式簽名之後指定特徵界限的語法 where。所以與其這樣寫：

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

我們可以這樣寫 where 的語法，如以下所示：

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{
    unimplemented!()
}

此函式簽名就沒有這麼複雜了，函式名稱、參數列表與回傳型別能靠得比較近，就像沒有一堆特徵界限的函式一樣。

回傳有實作特徵的型別

我們也能在回傳的位置使用 impl Trait 語法來回傳某個有實作特徵的型別數值，如以下所示：

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{} {} 著 ({})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable() -> impl Summary {
    Tweet {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        retweet: false,
    }
}

將 impl Summary 作為回傳型別的同時，我們在函式 returns_summarizable 指定回傳有實作 Summary 特徵的型別而不必指出實際型別。在此例中，returns_summarizable 回傳 Tweet，但呼叫此函式的程式碼不需要知道。

回傳一個只有指定所需實作特徵的型別在閉包（closures）與疊代器（iterators）中非常有用，我們會在第十三章介紹它們。閉包與疊代器能建立只有編譯器知道的型別，或是太長而難以指定的型別。impl Trait 語法允許你不用寫出很長的型別，而是只要指定函數會回傳有實作 Iterator 特徵的型別就好。

然而如果你使用 impl Trait 的話，你就只能回傳單一型別。舉例來說此程式碼指定回傳型別為 impl Summary ，但是寫說可能會回傳 NewsArticle 或 Tweet 的話就會無法執行：

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{} {} 著 ({})", self.headline, self.author, self.location)
    }
}

pub struct Tweet {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub retweet: bool,
}

impl Summary for Tweet {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable(switch: bool) -> impl Summary {
    if switch {
        NewsArticle {
            headline: String::from(
                "Penguins win the Stanley Cup Championship!",
            ),
            location: String::from("Pittsburgh, PA, USA"),
            author: String::from("Iceburgh"),
            content: String::from(
                "The Pittsburgh Penguins once again are the best \
                 hockey team in the NHL.",
            ),
        }
    } else {
        Tweet {
            username: String::from("horse_ebooks"),
            content: String::from(
                "of course, as you probably already know, people",
            ),
            reply: false,
            retweet: false,
        }
    }
}

寫說可能回傳 NewsArticle 或 Tweet 的話是不被允許的，因為 impl Trait 語法會限制在編譯器中最終決定的型別。我們會在第十七章的「允許不同型別數值的特徵物件」來討論如何寫出這種行為的函式。

透過特徵界限來選擇性實作方法

在有使用泛型型別參數 impl 區塊中使用特徵界限，我們可以選擇性地對有實作特定特徵的型別來實作方法。舉例來說，範例 10-15 的 Pair<T> 對所有 T 實作了 new 函式來回傳新的 Pair<T> 實例（回想一下第五章的「定義方法」段落，Self 是 impl 區塊內的型別別名，在此例就是 Pair<T>）。但在下一個 impl 區塊中，只有在其內部型別 T 有實作能夠做比較的 PartialOrd 特徵以及能夠顯示在螢幕的 Display 特徵的話，才會實作 cmp_display 方法。

檔案名稱：src/lib.rs

use std::fmt::Display;

struct Pair<T> {
    x: T,
    y: T,
}

impl<T> Pair<T> {
    fn new(x: T, y: T) -> Self {
        Self { x, y }
    }
}

impl<T: Display + PartialOrd> Pair<T> {
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("最大的是 x = {}", self.x);
        } else {
            println!("最大的是 y = {}", self.y);
        }
    }
}

範例 10-15：依據特徵界限來選擇性地在泛型型別實作方法

我們還可以對有實作其他特徵的型別選擇性地來實作特徵。對滿足特徵界限的型別實作特徵會稱之為全面實作（blanket implementations），這被廣泛地用在 Rust 標準函式庫中。舉例來說，標準函式庫會對任何有實作 Display 特徵的型別實作 ToString。標準函式庫中的 impl 區塊會有類似這樣的程式碼：

impl<T: Display> ToString for T {
    // --省略--
}

因為標準函式庫有此全面實作，我們可以在任何有實作 Display 特徵的型別呼叫 ToString 特徵的 to_string 方法。舉例來說，我們可以像這樣將整數轉變成對應的 String 數值，因為整數有實作 Display：

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

全面實作在特徵技術文件的「Implementors」段落有做說明。

特徵與特徵界限讓我們能使用泛型型別參數來減少重複的程式碼的同時，告訴編譯器該泛型型別該擁有何種行為。編譯器可以利用特徵界限資訊來檢查程式碼提供的實際型別有沒有符合特定行為。在動態語言中，我們要是呼叫一個該型別沒有的方法的話，我們會在執行時才發生錯誤。但是 Rust 將此錯誤移到編譯期間，讓我們必須在程式能夠執行之前確保有修正此問題。除此之外，我們還不用寫在執行時檢查此行為的程式碼，因為我們已經在編譯時就檢查了。這麼做我們可以在不失去泛型彈性的情況下，提升效能。

透過生命週期驗證參考

生命週期（lifetime）是另一種我們已經使用過的泛型。不同於確保一個型別有沒有我們要的行為，生命週期確保我們在需要參考的時候，它們都是有效的。

我們在第四章的「參考與借用」段落沒談到的是，Rust 中的每個參考都有個生命週期，這是決定該參考是否有效的作用域。大多情況下生命週期是隱式且可推導出來的，就像大多情況下型別是可推導出來的。當多種型別都有可能時，我們就得詮釋型別。同樣地，當生命週期的參考能以不同方式關聯的話，我們就得詮釋生命週期。Rust 要求我們用泛型生命週期參數來詮釋參考之間的關係，以確保實際在執行時的參考絕對是有效的。

詮釋生命週期在大多數的程式語言中都沒有這個概念，所以這段可能會有點讓你覺得陌生。雖然我們不會在此章涵蓋所有生命週期的內容，但是我們會講些你可能遇到生命週期的常見場景，好讓你更加熟悉這個概念。

透過生命週期預防迷途參考

生命週期最主要的目的就是要預防迷途參考（dangling references），其會導致程式參考到其他資料，而非它原本想要的參考。請看一下範例 10-16 的程式，它有一個外部作用域與內部作用域。

fn main() {
    let r;

    {
        let x = 5;
        r = &x;
    }

    println!("r: {}", r);
}

範例 10-16：嘗試使用其值已經離開作用域的參考

注意：範例 10-16、10-17 與 10-23 宣告變數時都沒有給予初始數值，所以變數名稱可以存在於外部作用域。乍看之下這似乎違反 Rust 不存在空值的原則。但是如果我們嘗試在賦值前使用變數的話，我們就會獲得編譯期錯誤，這證明 Rust 的確不允許空值。

外部作用域宣告了一個沒有初始值的變數 r，然後內部作用域宣告了一個初始值為 5 的變數 x。在內部作用域中，我們嘗試將 x 的參考賦值給 r。然後內部作用域結束後，我們嘗試印出 r。此程式碼不會編譯成功，因為數值 r 指向的數值在我們嘗試使用它時已經離開作用域。以下是錯誤訊息。

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0597]: `x` does not live long enough
 --> src/main.rs:6:13
  |
6 |         r = &x;
  |             ^^ borrowed value does not live long enough
7 |     }
  |     - `x` dropped here while still borrowed
8 |
9 |     println!("r: {}", r);
  |                       - borrow later used here

For more information about this error, try `rustc --explain E0597`.
error: could not compile `chapter10` due to previous error

變數 x 「存在的不夠久」。原因是因為當內部作用域在第 7 行結束時，x 會離開作用域。但是 r 卻還在外部作用域中有效，我們會說的「活得比較久」。如果 Rust 允許此程式碼可以執行的話，r 就會參考到 x 離開作用域後被釋放的記憶體位置，然後我們嘗試對 r 做的事情都不會是正確的了。所以 Rust 如何決定此程式碼無效呢？它使用了借用檢查器。

借用檢查器

Rust 編譯器有個借用檢查器（borrow checker）會比較作用域來檢測所有的借用是否有效。範例 10-17 顯示了範例 10-16 的程式碼，但加上了變數生命週期的詮釋。

fn main() {
    let r;                // ---------+-- 'a
                          //          |
    {                     //          |
        let x = 5;        // -+-- 'b  |
        r = &x;           //  |       |
    }                     // -+       |
                          //          |
    println!("r: {}", r); //          |
}                         // ---------+

範例 10-17：變數 r 與 x 的生命週期詮釋，分別以 'a 和 'b 作為表示