The Rust Programming Language The Rust Programming Language Steve Klabnik and Carol Nichols, with Contributions from the Rust Community The Rust Programming Language, © Steve Klabnik and Carol Nichols, with Contributions from the Rust Community. Contents I Getting started 7 1 Introduction 9 1.1 Contributing to the book ................. 10 1.2 ................................ 10 1.3 ................................ 12 2 Guessing Game 21 2.1 Setting Up a New Project ................. 21 2.2 Processing a Guess ..................... 22 2.3 Generating a Secret Number ............... 27 2.4 Comparing the Guess to the Secret Number ....... 33 2.5 Allowing Multiple Guesses with Looping ......... 38 2.6 Summary .......................... 44 3 Common Programming Concepts 45 3.1 ................................ 46 3.2 ................................ 50 3.3 ................................ 58 3.4 ................................ 65 3.5 ................................ 66 4 Understanding Ownership 77 4.1 ................................ 77 4.2 ................................ 90 4.3 ................................ 97 5 Using Structs to Structure Related Data 105 5.1 ................................ 105 5.2 ................................ 111 5.3 ................................ 117 6 6 Enums and Pattern Matching 123 6.1 ................................ 123 6.2 ................................ 132 6.3 ................................ 138 II Basic Rust Literacy 143 1 Using Modules to Reuse and Organize Code 145 1.1 ................................ 146 1.2 ................................ 155 1.3 ................................ 162 2 Common Collections 169 2.1 ................................ 170 2.2 ................................ 175 2.3 ................................ 183 3 Error Handling 191 3.1 ................................ 192 3.2 ................................ 196 3.3 ................................ 206 4 Generic Types, Traits, and Lifetimes 213 4.1 Removing Duplication by Extracting a Function .... 214 4.2 ................................ 217 4.3 ................................ 227 4.4 ................................ 237 5 Testing 255 5.1 ................................ 256 5.2 ................................ 273 5.3 ................................ 280 6 An I/O Project Building a Small Grep 287 6.1 ................................ 288 6.2 ................................ 291 6.3 ................................ 294 6.4 ................................ 309 6.5 ................................ 317 6.6 ................................ 324 7 III Thinking in Rust 329 1 Functional Language features in Rust: Iterators and Closures 331 1.1 ................................ 332 1.2 ................................ 350 1.3 ................................ 360 1.4 ................................ 365 2 More about Cargo and Crates.io 369 2.1 ................................ 369 2.2 ................................ 371 2.3 ................................ 379 2.4 ................................ 383 2.5 ................................ 384 3 Smart Pointers 385 3.1 ................................ 386 3.2 ................................ 390 3.3 ................................ 395 3.4 ................................ 398 3.5 ................................ 402 3.6 ................................ 408 4 Fearless Concurrency 419 4.1 ................................ 420 4.2 ................................ 428 4.3 ................................ 436 4.4 ................................ 446 5 Is Rust an Object-Oriented Programming Language? 449 5.1 ................................ 449 5.2 ................................ 454 5.3 ................................ 464 IV Advanced Topics 481 1 Patterns Match the Structure of Values 483 1.1 ................................ 483 1.2 ................................ 489 1.3 ................................ 491 8 2 Advanced Features 507 2.1 ................................ 508 2.2 ................................ 518 2.3 ................................ 527 2.4 ................................ 540 2.5 ................................ 547 3 Final Project: Building a Multithreaded Web Server 551 3.1 ................................ 553 3.2 ................................ 565 3.3 ................................ 568 3.4 ................................ 574 3.5 ................................ 580 3.6 ................................ 592 Part I Getting started Chapter 1 Introduction Welcome to “The Rust Programming Language,” an introductory book about Rust. Rust is a programming language that’s focused on safety, speed, and concurrency. Its design lets you create programs that have the performance and control of a low-level language, but with the pow- erful abstractions of a high-level language. These properties make Rust suitable for programmers who have experience in languages like C and are looking for a safer alternative, as well as those from languages like Python who are looking for ways to write code that performs better without sacrificing expressiveness. Rust performs the majority of its safety checks and memory man- agement decisions at compile time, so that your program’s runtime performance isn’t impacted. This makes it useful in a number of use cases that other languages aren’t good at: programs with predictable space and time requirements, embedding in other languages, and writ- ing low-level code, like device drivers and operating systems. It’s also great for web applications: it powers the Rust package registry site, crates.io! We’re excited to see what you create with Rust. This book is written for a reader who already knows how to program in at least one programming language. After reading this book, you should be comfortable writing Rust programs. We’ll be learning Rust through small, focused examples that build on each other to demon- strate how to use various features of Rust as well as how they work behind the scenes. 12 1.1 Contributing to the book This book is open source. If you find an error, please don’t hesitate to file an issue or send a pull request on GitHub. Please see CON- TRIBUTING.md for more details. 1.2 Installation The first step to using Rust is to install it. You’ll need an internet con- nection to run the commands in this chapter, as we’ll be downloading Rust from the internet. We’ll be showing off a number of commands using a terminal, and those lines all start with $. You don’t need to type in the $ character; they are there to indicate the start of each command. You’ll see many tutorials and examples around the web that follow this convention: $ for commands run as a regular user, and # for commands you should be running as an administrator. Lines that don’t start with $ are typically showing the output of the previous command. Installing on Linux or Mac If you’re on Linux or a Mac, all you need to do is open a terminal and type this: $ curl https://sh.rustup.rs -sSf | sh This will download a script and start the installation. You may be prompted for your password. If it all goes well, you’ll see this appear: Rust is installed now. Great! Of course, if you disapprove of the curl | sh pattern, you can down- load, inspect and run the script however you like. Installing on Windows On Windows, go to https://rustup.rs and follow the instructions to download rustup-init.exe. Run that and follow the rest of the instruc- tions it gives you. The rest of the Windows-specific commands in the book will assume that you are using cmd as your shell. If you use a different shell, you 13 may be able to run the same commands that Linux and Mac users do. If neither work, consult the documentation for the shell you are using. Custom installations If you have reasons for preferring not to use rustup.rs, please see the Rust installation page for other options. Updating Once you have Rust installed, updating to the latest version is easy. From your shell, run the update script: $ rustup update Uninstalling Uninstalling Rust is as easy as installing it. From your shell, run the uninstall script: $ rustup self uninstall Troubleshooting If you’ve got Rust installed, you can open up a shell, and type this: $ rustc --version You should see the version number, commit hash, and commit date in a format similar to this for the latest stable version at the time you install: rustc x.y.z (abcabcabc yyyy-mm-dd) If you see this, Rust has been installed successfully! Congrats! If you don’t and you’re on Windows, check that Rust is in your %PATH% system variable. If it still isn’t working, there are a number of places where you can get help. The easiest is the #rust IRC channel on irc.mozilla.org, which you can access through Mibbit. Go to that address, and you’ll be chatting with other Rustaceans (a silly nickname we call ourselves) who can help you out. Other great resources include the Users forum and Stack Overflow. 14 Local documentation The installer also includes a copy of the documentation locally, so you can read it offline. Run rustup doc to open the local documentation in your browser. Any time there’s a type or function provided by the standard library and you’re not sure what it does, use the API documentation to find out! 1.3 Hello, World! Now that you have Rust installed, let’s write your first Rust program. It’s traditional when learning a new language to write a little program to print the text “Hello, world!” to the screen, and in this section, we’ll follow that tradition. Note: This book assumes basic familiarity with the com- mand line. Rust itself makes no specific