2022-09-13 16:54:09 +00:00
|
|
|
|
<!-- DO NOT EDIT THIS FILE.
|
|
|
|
|
|
|
|
|
|
This file is periodically generated from the content in the `/src/`
|
|
|
|
|
directory, so all fixes need to be made in `/src/`.
|
|
|
|
|
-->
|
2022-08-09 15:14:30 +00:00
|
|
|
|
## About the Authors
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
|
|
|
|
Carol Nichols is a member of the Rust Crates.io Team and a former member of the
|
|
|
|
|
Rust Core Team. She’s a co-founder of Integer 32, LLC, the world’s first
|
|
|
|
|
Rust-focused software consultancy. Nichols has also organized the Rust Belt
|
|
|
|
|
Rust Conference.
|
|
|
|
|
|
|
|
|
|
Steve Klabnik was the lead for the Rust documentation team and was one of
|
|
|
|
|
Rust’s core developers. A frequent speaker and a prolific open source
|
|
|
|
|
contributor, he previously worked on projects such as Ruby and Ruby on Rails.
|
|
|
|
|
|
|
|
|
|
## About the Technical Reviewer
|
|
|
|
|
|
|
|
|
|
JT is a Rust core team member and the co-creator of the Rust error message
|
|
|
|
|
format, Rust Language Server (RLS), and Nushell. They first started using Rust
|
2022-08-09 15:14:30 +00:00
|
|
|
|
in 2011, and in 2016 joined Mozilla to work on Rust full time, helping to shape
|
2022-07-14 00:32:13 +00:00
|
|
|
|
its direction for widespread use. These days, they are a freelance Rust trainer
|
|
|
|
|
and advocate for safe systems programming.
|
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
## Brief Contents
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
## Contents in Detail
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
## Foreword
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
It wasn’t always so clear, but the Rust programming language is fundamentally
|
|
|
|
|
about *empowerment*: no matter what kind of code you are writing now, Rust
|
2022-08-09 15:14:30 +00:00
|
|
|
|
empowers you to reach further, to program with confidence in a wider variety of
|
2022-07-14 00:47:46 +00:00
|
|
|
|
domains than you did before.
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
|
|
|
|
Take, for example, “systems-level” work that deals with low-level details of
|
|
|
|
|
memory management, data representation, and concurrency. Traditionally, this
|
2022-08-09 15:14:30 +00:00
|
|
|
|
realm of programming is seen as arcane, accessible to only a select few who
|
|
|
|
|
have devoted the necessary years learning it to avoid its infamous pitfalls.
|
|
|
|
|
And even those who practice it do so with caution, lest their code be open to
|
2022-07-14 00:32:13 +00:00
|
|
|
|
exploits, crashes, or corruption.
|
|
|
|
|
|
|
|
|
|
Rust breaks down these barriers by eliminating the old pitfalls and providing a
|
|
|
|
|
friendly, polished set of tools to help you along the way. Programmers who need
|
|
|
|
|
to “dip down” into lower-level control can do so with Rust, without taking on
|
2022-08-09 15:14:30 +00:00
|
|
|
|
the customary risk of crashes or security holes and without having to learn the
|
|
|
|
|
fine points of a fickle toolchain. Better yet, the language is designed to
|
|
|
|
|
guide you naturally toward reliable code that is efficient in terms of speed
|
2022-07-14 00:32:13 +00:00
|
|
|
|
and memory usage.
|
|
|
|
|
|
|
|
|
|
Programmers who are already working with low-level code can use Rust to raise
|
|
|
|
|
their ambitions. For example, introducing parallelism in Rust is a relatively
|
|
|
|
|
low-risk operation: the compiler will catch the classical mistakes for you. And
|
|
|
|
|
you can tackle more aggressive optimizations in your code with the confidence
|
|
|
|
|
that you won’t accidentally introduce crashes or vulnerabilities.
|
|
|
|
|
|
|
|
|
|
But Rust isn’t limited to low-level systems programming. It’s expressive and
|
|
|
|
|
ergonomic enough to make CLI apps, web servers, and many other kinds of code
|
2022-08-09 15:14:30 +00:00
|
|
|
|
quite pleasant to write—you’ll find simple examples later in the book. Working
|
|
|
|
|
with Rust allows you to build skills that transfer from one domain to another;
|
|
|
|
|
you can learn Rust by writing a web app, then apply those same skills to target
|
|
|
|
|
your Raspberry Pi.
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
|
|
|
|
This book fully embraces the potential of Rust to empower its users. It’s a
|
|
|
|
|
friendly and approachable text intended to help you level up not just your
|
|
|
|
|
knowledge of Rust, but also your reach and confidence as a programmer in
|
|
|
|
|
general. So dive in, get ready to learn—and welcome to the Rust community!
|
|
|
|
|
|
2022-09-05 18:36:01 +00:00
|
|
|
|
Nicholas Matsakis and Aaron Turon
|
2022-08-09 15:14:30 +00:00
|
|
|
|
|
|
|
|
|
## ACKNOWLEDGMENTS
|
|
|
|
|
|
|
|
|
|
We would like to thank everyone who has worked on the Rust language for
|
|
|
|
|
creating an amazing language worth writing a book about. We’re grateful to
|
|
|
|
|
everyone in the Rust community for being welcoming and creating an environment
|
|
|
|
|
worth welcoming more folks into.
|
|
|
|
|
|
|
|
|
|
We’re especially thankful for everyone who read early versions of this book
|
|
|
|
|
online and provided feedback, bug reports, and pull requests. Special thanks to
|
|
|
|
|
Eduard-Mihai Burtescu, Alex Crichton, and JT for providing technical review,
|
|
|
|
|
and to Karen Rustad Tölva for the cover art. Thank you to our team at No
|
|
|
|
|
Starch, including Bill Pollock, Liz Chadwick, and Janelle Ludowise, for
|
|
|
|
|
improving this book and bringing it to print.
|
|
|
|
|
|
|
|
|
|
Carol is grateful for the opportunity to work on this book. She thanks her
|
|
|
|
|
family for their constant love and support, especially her husband, Jake
|
|
|
|
|
Goulding, and her daughter, Vivian.
|
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
## Preface
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
This version of the text assumes you’re using Rust 1.62.0 (released 2022-06-30)
|
2022-08-24 13:12:29 +00:00
|
|
|
|
or later with `edition="2021"` in the *Cargo.toml* file of all projects to
|
|
|
|
|
configure them to use Rust 2021 edition idioms. See “Installation” on page XX
|
|
|
|
|
for instructions on installing or updating Rust, and see Appendix E for
|
|
|
|
|
information on editions.
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-08-09 15:14:30 +00:00
|
|
|
|
The 2021 edition of the Rust language includes a number of improvements that
|
|
|
|
|
make Rust more ergonomic and that correct some inconsistencies. On top of a
|
|
|
|
|
general update to reflect these improvements, this rendition of the book has a
|
|
|
|
|
number of improvements to address specific feedback:
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
* Chapter 7 contains a new quick reference section on organizing your code into
|
|
|
|
|
multiple files with modules.
|
|
|
|
|
* Chapter 13 has new and improved closure examples that more clearly illustrate
|
|
|
|
|
captures, the `move` keyword, and the `Fn` traits.
|
|
|
|
|
* We fixed a number of small errors and imprecise wording throughout the book.
|
|
|
|
|
Thank you to the readers who reported them!
|
2022-09-13 16:54:09 +00:00
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
Note that any code from earlier renditions of this book that compiled will
|
|
|
|
|
continue to compile with the relevant edition in the project’s *Cargo.toml*,
|
2022-07-14 00:32:13 +00:00
|
|
|
|
even as you update the Rust compiler version you’re using. That’s Rust’s
|
2022-08-09 15:14:30 +00:00
|
|
|
|
backward-compatibility guarantees at work!
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
## Introduction
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-08-24 13:12:29 +00:00
|
|
|
|
Welcome to *The Rust Programming Language*, an introductory book about Rust.
|
2022-07-14 00:47:46 +00:00
|
|
|
|
The Rust programming language helps you write faster, more reliable software.
|
|
|
|
|
High-level ergonomics and low-level control are often at odds in programming
|
|
|
|
|
language design; Rust challenges that conflict. Through balancing powerful
|
|
|
|
|
technical capacity and a great developer experience, Rust gives you the option
|
|
|
|
|
to control low-level details (such as memory usage) without all the hassle
|
|
|
|
|
traditionally associated with such control.
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
## Who Rust Is For
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
|
|
|
|
Rust is ideal for many people for a variety of reasons. Let’s look at a few of
|
|
|
|
|
the most important groups.
|
|
|
|
|
|
|
|
|
|
### Teams of Developers
|
|
|
|
|
|
|
|
|
|
Rust is proving to be a productive tool for collaborating among large teams of
|
|
|
|
|
developers with varying levels of systems programming knowledge. Low-level code
|
2022-08-09 15:14:30 +00:00
|
|
|
|
is prone to various subtle bugs, which in most other languages can only be
|
|
|
|
|
caught through extensive testing and careful code review by experienced
|
2022-07-14 00:32:13 +00:00
|
|
|
|
developers. In Rust, the compiler plays a gatekeeper role by refusing to
|
|
|
|
|
compile code with these elusive bugs, including concurrency bugs. By working
|
|
|
|
|
alongside the compiler, the team can spend their time focusing on the program’s
|
|
|
|
|
logic rather than chasing down bugs.
|
|
|
|
|
|
|
|
|
|
Rust also brings contemporary developer tools to the systems programming world:
|
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
* Cargo, the included dependency manager and build tool, makes adding,
|
|
|
|
|
compiling, and managing dependencies painless and consistent across the Rust
|
|
|
|
|
ecosystem.
|
2022-09-13 16:54:09 +00:00
|
|
|
|
* The `rustfmt` formatting tool ensures a consistent coding style across
|
2022-07-14 00:47:46 +00:00
|
|
|
|
developers.
|
2022-08-09 15:14:30 +00:00
|
|
|
|
* The Rust Language Server powers integrated development environment (IDE)
|
2022-07-14 00:47:46 +00:00
|
|
|
|
integration for code completion and inline error messages.
|
2022-09-13 16:54:09 +00:00
|
|
|
|
|
2022-07-14 00:47:46 +00:00
|
|
|
|
By using these and other tools in the Rust ecosystem, developers can be
|
2022-07-14 00:32:13 +00:00
|
|
|
|
productive while writing systems-level code.
|
|
|
|
|
|
|
|
|
|
### Students
|
|
|
|
|
|
|
|
|
|
Rust is for students and those who are interested in learning about systems
|
|
|
|
|
concepts. Using Rust, many people have learned about topics like operating
|
|
|
|
|
systems development. The community is very welcoming and happy to answer
|
2022-08-09 15:14:30 +00:00
|
|
|
|
students’ questions. Through efforts such as this book, the Rust teams want to
|
2022-07-14 00:32:13 +00:00
|
|
|
|
make systems concepts more accessible to more people, especially those new to
|
|
|
|
|
programming.
|
|
|
|
|
|
|
|
|
|
### Companies
|
|
|
|
|
|
|
|
|
|
Hundreds of companies, large and small, use Rust in production for a variety of
|
|
|
|
|
tasks, including command line tools, web services, DevOps tooling, embedded
|
|
|
|
|
devices, audio and video analysis and transcoding, cryptocurrencies,
|
|
|
|
|
bioinformatics, search engines, Internet of Things applications, machine
|
|
|
|
|
learning, and even major parts of the Firefox web browser.
|
|
|
|
|
|
|
|
|
|
### Open Source Developers
|
|
|
|
|
|
|
|
|
|
Rust is for people who want to build the Rust programming language, community,
|
|
|
|
|
developer tools, and libraries. We’d love to have you contribute to the Rust
|
|
|
|
|
language.
|
|
|
|
|
|
|
|
|
|
### People Who Value Speed and Stability
|
|
|
|
|
|
|
|
|
|
Rust is for people who crave speed and stability in a language. By speed, we
|
|
|
|
|
mean both how quickly Rust code can run and the speed at which Rust lets you
|
|
|
|
|
write programs. The Rust compiler’s checks ensure stability through feature
|
|
|
|
|
additions and refactoring. This is in contrast to the brittle legacy code in
|
|
|
|
|
languages without these checks, which developers are often afraid to modify. By
|
|
|
|
|
striving for zero-cost abstractions, higher-level features that compile to
|
|
|
|
|
lower-level code as fast as code written manually, Rust endeavors to make safe
|
|
|
|
|
code be fast code as well.
|
|
|
|
|
|
|
|
|
|
The Rust language hopes to support many other users as well; those mentioned
|
|
|
|
|
here are merely some of the biggest stakeholders. Overall, Rust’s greatest
|
|
|
|
|
ambition is to eliminate the trade-offs that programmers have accepted for
|
2022-07-14 00:47:46 +00:00
|
|
|
|
decades by providing safety *and* productivity, speed *and* ergonomics. Give
|
|
|
|
|
Rust a try and see if its choices work for you.
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
|
|
|
|
## Who This Book Is For
|
|
|
|
|
|
2022-08-09 15:14:30 +00:00
|
|
|
|
This book assumes that you’ve written code in another programming language, but
|
2022-07-14 00:32:13 +00:00
|
|
|
|
doesn’t make any assumptions about which one. We’ve tried to make the material
|
|
|
|
|
broadly accessible to those from a wide variety of programming backgrounds. We
|
2022-07-14 00:47:46 +00:00
|
|
|
|
don’t spend a lot of time talking about what programming *is* or how to think
|
2022-07-14 00:32:13 +00:00
|
|
|
|
about it. If you’re entirely new to programming, you would be better served by
|
|
|
|
|
reading a book that specifically provides an introduction to programming.
|
|
|
|
|
|
|
|
|
|
## How to Use This Book
|
|
|
|
|
|
|
|
|
|
In general, this book assumes that you’re reading it in sequence from front to
|
|
|
|
|
back. Later chapters build on concepts in earlier chapters, and earlier
|
|
|
|
|
chapters might not delve into details on a particular topic but will revisit
|
|
|
|
|
the topic in a later chapter.
|
|
|
|
|
|
|
|
|
|
You’ll find two kinds of chapters in this book: concept chapters and project
|
|
|
|
|
chapters. In concept chapters, you’ll learn about an aspect of Rust. In project
|
|
|
|
|
chapters, we’ll build small programs together, applying what you’ve learned so
|
2022-08-09 15:14:30 +00:00
|
|
|
|
far. Chapter 2, Chapter 12, and Chapter 20 are project chapters; the rest are
|
|
|
|
|
concept chapters.
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
2022-08-09 15:14:30 +00:00
|
|
|
|
**Chapter 1** explains how to install Rust, how to write a “Hello, world!”
|
|
|
|
|
program, and how to use Cargo, Rust’s package manager and build tool. **Chapter
|
|
|
|
|
2** is a hands-on introduction to writing a program in Rust, having you build
|
|
|
|
|
up a number-guessing game. Here, we cover concepts at a high level, and later
|
2022-07-14 00:32:13 +00:00
|
|
|
|
chapters will provide additional detail. If you want to get your hands dirty
|
2022-08-09 15:14:30 +00:00
|
|
|
|
right away, Chapter 2 is the place for that. **Chapter 3** covers Rust features
|
|
|
|
|
that are similar to those of other programming languages, and in **Chapter 4**
|
2022-07-14 00:32:13 +00:00
|
|
|
|
you’ll learn about Rust’s ownership system. If you’re a particularly meticulous
|
|
|
|
|
learner who prefers to learn every detail before moving on to the next, you
|
|
|
|
|
might want to skip Chapter 2 and go straight to Chapter 3, returning to Chapter
|
|
|
|
|
2 when you’d like to work on a project applying the details you’ve learned.
|
|
|
|
|
|
2022-08-09 15:14:30 +00:00
|
|
|
|
**Chapter 5** discusses structs and methods, and **Chapter 6** covers enums,
|
|
|
|
|
`match` expressions, and the `if let` control flow construct. You’ll use
|
|
|
|
|
structs and enums to make custom types in Rust.
|
|
|
|
|
|
|
|
|
|
In **Chapter 7**, you’ll learn about Rust’s module system and about privacy
|
|
|
|
|
rules for organizing your code and its public application programming interface
|
|
|
|
|
(API). **Chapter 8** discusses some common collection data structures that the
|
|
|
|
|
standard library provides, such as vectors, strings, and hash maps. **Chapter
|
|
|
|
|
9** explores Rust’s error-handling philosophy and techniques.
|
|
|
|
|
|
|
|
|
|
**Chapter 10** digs into generics, traits, and lifetimes, which give you the
|
|
|
|
|
power to define code that applies to multiple types. **Chapter 11** is all
|
|
|
|
|
about testing, which even with Rust’s safety guarantees is necessary to ensure
|
|
|
|
|
your program’s logic is correct. In **Chapter 12**, we’ll build our own
|
|
|
|
|
implementation of a subset of functionality from the `grep` command line tool
|
|
|
|
|
that searches for text within files. For this, we’ll use many of the concepts
|
|
|
|
|
we discussed in the previous chapters.
|
|
|
|
|
|
|
|
|
|
**Chapter 13** explores closures and iterators: features of Rust that come from
|
|
|
|
|
functional programming languages. In **Chapter 14**, we’ll examine Cargo in
|
|
|
|
|
more depth and talk about best practices for sharing your libraries with
|
|
|
|
|
others. **Chapter 15** discusses smart pointers that the standard library
|
|
|
|
|
provides and the traits that enable their functionality.
|
|
|
|
|
|
|
|
|
|
In **Chapter 16**, we’ll walk through different models of concurrent
|
|
|
|
|
programming and talk about how Rust helps you program in multiple threads
|
|
|
|
|
fearlessly. **Chapter 17** looks at how Rust idioms compare to object-oriented
|
|
|
|
|
programming principles you might be familiar with.
|
|
|
|
|
|
|
|
|
|
**Chapter 18** is a reference on patterns and pattern matching, which are
|
|
|
|
|
powerful ways of expressing ideas throughout Rust programs. **Chapter 19**
|
|
|
|
|
contains a smorgasbord of advanced topics of interest, including unsafe Rust,
|
|
|
|
|
macros, and more about lifetimes, traits, types, functions, and closures.
|
|
|
|
|
|
|
|
|
|
In **Chapter 20**, we’ll complete a project in which we’ll implement a
|
|
|
|
|
low-level multithreaded web server!
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
|
|
|
|
Finally, some appendices contain useful information about the language in a
|
2022-08-09 15:14:30 +00:00
|
|
|
|
more reference-like format**. Appendix A** covers Rust’s keywords, **Appendix
|
|
|
|
|
B** covers Rust’s operators and symbols, **Appendix C** covers derivable traits
|
|
|
|
|
provided by the standard library, **Appendix D** covers some useful development
|
|
|
|
|
tools, and **Appendix E** explains Rust editions.
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
|
|
|
|
There is no wrong way to read this book: if you want to skip ahead, go for it!
|
|
|
|
|
You might have to jump back to earlier chapters if you experience any
|
|
|
|
|
confusion. But do whatever works for you.
|
|
|
|
|
|
|
|
|
|
An important part of the process of learning Rust is learning how to read the
|
|
|
|
|
error messages the compiler displays: these will guide you toward working code.
|
|
|
|
|
As such, we’ll provide many examples that don’t compile along with the error
|
|
|
|
|
message the compiler will show you in each situation. Know that if you enter
|
|
|
|
|
and run a random example, it may not compile! Make sure you read the
|
|
|
|
|
surrounding text to see whether the example you’re trying to run is meant to
|
|
|
|
|
error. In most situations, we’ll lead you to the correct version of any code
|
|
|
|
|
that doesn’t compile.
|
|
|
|
|
|
|
|
|
|
## Resources and How to Contribute to This 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 at
|
2022-08-09 15:14:30 +00:00
|
|
|
|
*https://github.com/rust-lang/book*. Please see *CONTRIBUTING.md* at
|
2022-07-14 00:47:46 +00:00
|
|
|
|
*https://github.com/rust-lang/book/blob/main/CONTRIBUTING.md* for more details.
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|
|
|
|
|
The source code for the examples in this book, errata, and other information
|
2022-08-09 15:14:30 +00:00
|
|
|
|
are available at *https://www.nostarch.com/Rust2021*.
|
2022-07-14 00:32:13 +00:00
|
|
|
|
|