Welcome to The Rust Programming Language book! This version of the text assumesyou are using Rust 1.31.0 or later, with edition="2018" in Cargo.toml ofall projects to use Rust 2018 Edition idioms. See the [“Installation” section

It wasn’t always so clear, but the Rust programming language is fundamentallyabout empowerment: no matter what kind of code you are writing now, Rustempowers you to reach farther, to program with confidence in a wider variety of

Note: This edition of the book is the same as [The Rust ProgrammingLanguage][nsprust] available in print and ebook format from [No StarchPress][nsp].

Let’s start your Rust journey! There’s a lot to learn, but every journey startssomewhere. In this chapter, we’ll discuss:

The first step is to install Rust. We’ll download Rust through rustup, acommand line tool for managing Rust versions and associated tools. You’ll needan internet connection for the download.

Now that you’ve installed Rust, let’s write your first Rust program. It’straditional when learning a new language to write a little program that printsthe text Hello, world! to the screen, so we’ll do the same here!

Cargo is Rust’s build system and package manager. Most Rustaceans use this toolto manage their Rust projects because Cargo handles a lot of tasks for you,such as building your code, downloading the libraries your code depends on, and

Let’s jump into Rust by working through a hands-on project together! Thischapter introduces you to a few common Rust concepts by showing you how to usethem in a real program. You’ll learn about let, match, methods, associated

This chapter covers concepts that appear in almost every programming languageand how they work in Rust. Many programming languages have much in common attheir core. None of the concepts presented in this chapter are unique to Rust,

As mentioned in Chapter 2, by default variables are immutable. This is one ofmany nudges Rust gives you to write your code in a way that takes advantage ofthe safety and easy concurrency that Rust offers. However, you still have the

Every value in Rust is of a certain data type, which tells Rust what kind ofdata is being specified so it knows how to work with that data. We’ll look attwo data type subsets: scalar and compound.

Functions are pervasive in Rust code. You’ve already seen one of the mostimportant functions in the language: the main function, which is the entrypoint of many programs. You’ve also seen the fn keyword, which allows you to

All programmers strive to make their code easy to understand, but sometimesextra explanation is warranted. In these cases, programmers leave notes, orcomments, in their source code that the compiler will ignore but people

Deciding whether or not to run some code depending on if a condition is trueand deciding to run some code repeatedly while a condition is true are basicbuilding blocks in most programming languages. The most common constructs that

Ownership is Rust’s most unique feature, and it enables Rust to make memorysafety guarantees without needing a garbage collector. Therefore, it’simportant to understand how ownership works in Rust. In this chapter, we’ll

Rust’s central feature is ownership. Although the feature is straightforwardto explain, it has deep implications for the rest of the language.All programs have to manage the way they use a computer’s memory while running.

The issue with the tuple code in Listing 4-5 is that we have to return theString to the calling function so we can still use the String after thecall to calculate_length, because the String was moved into

Another data type that does not have ownership is the slice. Slices let youreference a contiguous sequence of elements in a collection rather than thewhole collection.

A struct, or structure, is a custom data type that lets you name andpackage together multiple related values that make up a meaningful group. Ifyou’re familiar with an object-oriented language, a struct is like an

Structs are similar to tuples, which were discussed in Chapter 3. Like tuples,the pieces of a struct can be different types. Unlike with tuples, you’ll nameeach piece of data so it’s clear what the values mean. As a result of these

To understand when we might want to use structs, let’s write a program thatcalculates the area of a rectangle. We’ll start with single variables, and thenrefactor the program until we’re using structs instead.

Methods are similar to functions: they’re declared with the fn keyword andtheir name, they can have parameters and a return value, and they contain somecode that is run when they’re called from somewhere else. However, methods are

In this chapter we’ll look at enumerations, also referred to as enums.Enums allow you to define a type by enumerating its possible values. First,we’ll define and use an enum to show how an enum can encode meaning along with

Let’s look at a situation we might want to express in code and see why enumsare useful and more appropriate than structs in this case. Say we need to workwith IP addresses. Currently, two major standards are used for IP addresses:

Rust has an extremely powerful control flow operator called match that allowsyou to compare a value against a series of patterns and then execute code basedon which pattern matches. Patterns can be made up of literal values, variable

The if let syntax lets you combine if and let into a less verbose way tohandle values that match one pattern while ignoring the rest. Consider theprogram in Listing 6-6 that matches on an Option<u8> value but only wants to

As you write large programs, organizing your code is important because it’llbecome impossible to keep track of your entire program in your head. Bygrouping related functionality and separating code with distinct features,

The first parts of the module system we’ll cover are packages and crates. Acrate is a binary or library. The crate root is a source file that the Rustcompiler starts from and makes up the root module of your crate (we’ll explain

In this section, we’ll talk about modules and other parts of the module system,namely paths that allow you to name items; the use keyword that brings apath into scope; and the pub keyword to make items public. We’ll also discuss

To show Rust where to find an item in a module tree, we use a path in thesame way we use a path when navigating a filesystem. If we want to call afunction, we need to know its path.

It might seem like the paths we’ve written to call functions so far areinconveniently long and repetitive. For example, in Listing 7-7, whether wechose the absolute or relative path to the add_to_waitlist function, every

So far, all the examples in this chapter defined multiple modules in one file.When modules get large, you might want to move their definitions to a separatefile to make the code easier to navigate.

Rust’s standard library includes a number of very useful data structures calledcollections. Most other data types represent one specific value, butcollections can contain multiple values. Unlike the built-in array and tuple

The first collection type we’ll look at is Vec<T>, also known as a vector.Vectors allow you to store more than one value in a single data structure thatputs all the values next to each other in memory. Vectors can only store values

We talked about strings in Chapter 4, but we’ll look at them in more depth now.New Rustaceans commonly get stuck on strings for a combination of threereasons: Rust’s propensity for exposing possible errors, strings being a more

The last of our common collections is the hash map. The type HashMap<K, V>stores a mapping of keys of type K to values of type V. It does this via ahashing function, which determines how it places these keys and values into

Rust’s commitment to reliability extends to error handling. Errors are a factof life in software, so Rust has a number of features for handling situationsin which something goes wrong. In many cases, Rust requires you to acknowledge

Sometimes, bad things happen in your code, and there’s nothing you can do aboutit. In these cases, Rust has the panic! macro. When the panic! macroexecutes, your program will print a failure message, unwind and clean up the

Most errors aren’t serious enough to require the program to stop entirely.Sometimes, when a function fails, it’s for a reason that you can easilyinterpret and respond to. For example, if you try to open a file and that

So how do you decide when you should call panic! and when you should returnResult? When code panics, there’s no way to recover. You could call panic!for any error situation, whether there’s a possible way to recover or not, but

Every programming language has tools for effectively handling the duplicationof concepts. In Rust, one such tool is generics. Generics are abstractstand-ins for concrete types or other properties. When we’re writing code, we

We can use generics to create definitions for items like function signatures orstructs, which we can then use with many different concrete data types. Let’sfirst look at how to define functions, structs, enums, and methods using

A trait tells the Rust compiler about functionality a particular type has andcan share with other types. We can use traits to define shared behavior in anabstract way. We can use trait bounds to specify that a generic can be any type

One detail we didn’t discuss in the [“References and Borrowing”][references-and-borrowing] section in Chapter 4 is that everyreference in Rust has a lifetime, which is the scope for which that reference

In his 1972 essay “The Humble Programmer,” Edsger W. Dijkstra said that“Program testing can be a very effective way to show the presence of bugs, butit is hopelessly inadequate for showing their absence.” That doesn’t mean we

Tests are Rust functions that verify that the non-test code is functioning inthe expected manner. The bodies of test functions typically perform these threeactions:

Just as cargo run compiles your code and then runs the resulting binary,cargo test compiles your code in test mode and runs the resulting testbinary. You can specify command line options to change the default behavior of

As mentioned at the start of the chapter, testing is a complex discipline, anddifferent people use different terminology and organization. The Rust communitythinks about tests in terms of two main categories: unit tests and

This chapter is a recap of the many skills you’ve learned so far and anexploration of a few more standard library features. We’ll build a command linetool that interacts with file and command line input/output to practice some of

Let’s create a new project with, as always, cargo new. We’ll call our projectminigrep to distinguish it from the grep tool that you might already haveon your system.

Now we’ll add functionality to read the file that is specified in thefilename command line argument. First, we need a sample file to test it with:the best kind of file to use to make sure minigrep is working is one with a

To improve our program, we’ll fix four problems that have to do with theprogram’s structure and how it’s handling potential errors.First, our main function now performs two tasks: it parses arguments and

Now that we’ve extracted the logic into src/lib.rs and left the argumentcollecting and error handling in src/main.rs, it’s much easier to write testsfor the core functionality of our code. We can call functions directly with

We’ll improve minigrep by adding an extra feature: an option forcase-insensitive searching that the user can turn on via an environmentvariable. We could make this feature a command line option and require that

At the moment, we’re writing all of our output to the terminal using theprintln! function. Most terminals provide two kinds of output: *standardoutput* (stdout) for general information and standard error (stderr)

Rust’s design has taken inspiration from many existing languages andtechniques, and one significant influence is functional programming.Programming in a functional style often includes using functions as values by

Rust’s closures are anonymous functions you can save in a variable or pass asarguments to other functions. You can create the closure in one place and thencall the closure to evaluate it in a different context. Unlike functions,

The iterator pattern allows you to perform some task on a sequence of items inturn. An iterator is responsible for the logic of iterating over each item anddetermining when the sequence has finished. When you use iterators, you don’t

With this new knowledge about iterators, we can improve the I/O project inChapter 12 by using iterators to make places in the code clearer and moreconcise. Let’s look at how iterators can improve our implementation of the

To determine whether to use loops or iterators, you need to know which versionof our search functions is faster: the version with an explicit for loop orthe version with iterators.

So far we’ve used only the most basic features of Cargo to build, run, and testour code, but it can do a lot more. In this chapter, we’ll discuss some of itsother, more advanced features to show you how to do the following:

In Rust, release profiles are predefined and customizable profiles withdifferent configurations that allow a programmer to have more control overvarious options for compiling code. Each profile is configured independently of

We’ve used packages from crates.io asdependencies of our project, but you can also share your code with other peopleby publishing your own packages. The crate registry at

In Chapter 12, we built a package that included a binary crate and a librarycrate. As your project develops, you might find that the library cratecontinues to get bigger and you want to split up your package further into

The cargo install command allows you to install and use binary crateslocally. This isn’t intended to replace system packages; it’s meant to be aconvenient way for Rust developers to install tools that others have shared on

Cargo is designed so you can extend it with new subcommands without having tomodify Cargo. If a binary in your $PATH is named cargo-something, you canrun it as if it was a Cargo subcommand by running cargo something. Custom

A pointer is a general concept for a variable that contains an address inmemory. This address refers to, or “points at,” some other data. The mostcommon kind of pointer in Rust is a reference, which you learned about in

The most straightforward smart pointer is a box, whose type is writtenBox<T>. Boxes allow you to store data on the heap rather than the stack. Whatremains on the stack is the pointer to the heap data. Refer to Chapter 4 to

Implementing the Deref trait allows you to customize the behavior of thedereference operator, * (as opposed to the multiplication or globoperator). By implementing Deref in such a way that a smart pointer can be

The second trait important to the smart pointer pattern is Drop, which letsyou customize what happens when a value is about to go out of scope. You canprovide an implementation for the Drop trait on any type, and the code you

In the majority of cases, ownership is clear: you know exactly which variableowns a given value. However, there are cases when a single value might havemultiple owners. For example, in graph data structures, multiple edges might

Interior mutability is a design pattern in Rust that allows you to mutatedata even when there are immutable references to that data; normally, this

Rust’s memory safety guarantees make it difficult, but not impossible, toaccidentally create memory that is never cleaned up (known as a memory leak).Preventing memory leaks entirely is not one of Rust’s guarantees in the same

Handling concurrent programming safely and efficiently is another of Rust’smajor goals. Concurrent programming, where different parts of a programexecute independently, and parallel programming, where different parts of a

In most current operating systems, an executed program’s code is run in aprocess, and the operating system manages multiple processes at once. Withinyour program, you can also have independent parts that run simultaneously. The

One increasingly popular approach to ensuring safe concurrency is *messagepassing*, where threads or actors communicate by sending each other messagescontaining data. Here’s the idea in a slogan from [the Go language

Message passing is a fine way of handling concurrency, but it’s not the onlyone. Consider this part of the slogan from the Go language documentation again:“communicate by sharing memory.”

Interestingly, the Rust language has very few concurrency features. Almostevery concurrency feature we’ve talked about so far in this chapter has beenpart of the standard library, not the language. Your options for handling

Object-oriented programming (OOP) is a way of modeling programs. Objects camefrom Simula in the 1960s. Those objects influenced Alan Kay’s programmingarchitecture in which objects pass messages to each other. He coined the term

There is no consensus in the programming community about what features alanguage must have to be considered object oriented. Rust is influenced by manyprogramming paradigms, including OOP; for example, we explored the features

In Chapter 8, we mentioned that one limitation of vectors is that they canstore elements of only one type. We created a workaround in Listing 8-10 wherewe defined a SpreadsheetCell enum that had variants to hold integers, floats,

The state pattern is an object-oriented design pattern. The crux of thepattern is that a value has some internal state, which is represented by a setof state objects, and the value’s behavior changes based on the internal

Patterns are a special syntax in Rust for matching against the structure oftypes, both complex and simple. Using patterns in conjunction with matchexpressions and other constructs gives you more control over a program’s

Patterns pop up in a number of places in Rust, and you’ve been using them a lotwithout realizing it! This section discusses all the places where patterns arevalid.

Patterns come in two forms: refutable and irrefutable. Patterns that will matchfor any possible value passed are irrefutable. An example would be x in thestatement let x = 5; because x matches anything and therefore cannot fail

Throughout the book, you’ve seen examples of many kinds of patterns. In thissection, we gather all the syntax valid in patterns and discuss why you mightwant to use each one.

By now, you’ve learned the most commonly used parts of the Rust programminglanguage. Before we do one more project in Chapter 20, we’ll look at a fewaspects of the language you might run into every once in a while. You can use

All the code we’ve discussed so far has had Rust’s memory safety guaranteesenforced at compile time. However, Rust has a second language hidden inside itthat doesn’t enforce these memory safety guarantees: it’s called unsafe Rust

In Chapter 10 in the [“Validating References with Lifetimes”][validating-references-with-lifetimes] section, you learned howto annotate references with lifetime parameters to tell Rust how lifetimes of

We first covered traits in the [“Traits: Defining Shared Behavior”][traits-defining-shared-behavior] section of Chapter 10, but aswith lifetimes, we didn’t discuss the more advanced details. Now that you know

The Rust type system has some features that we’ve mentioned in this book buthaven’t yet discussed. We’ll start by discussing newtypes in general as weexamine why newtypes are useful as types. Then we’ll move on to type aliases, a

Finally, we’ll explore some advanced features related to functions andclosures, which include function pointers and returning closures.We’ve talked about how to pass closures to functions; you can also pass regular

We’ve used macros like println! throughout this book, but we haven’t fullyexplored what a macro is and how it works. Macros refers to a family offeatures in Rust:

It’s been a long journey, but we’ve reached the end of the book. In thischapter, we’ll build one more project together to demonstrate some of theconcepts we covered in the final chapters, as well as recap some earlier

We’ll start by getting a single-threaded web server working. Before we begin,let’s look at a quick overview of the protocols involved in building webservers. The details of these protocols are beyond the scope of this book, but

Right now, the server will process each request in turn, meaning it won’tprocess a second connection until the first is finished processing. If theserver received more and more requests, this serial execution would be less and

The code in Listing 20-21 is responding to requests asynchronously through theuse of a thread pool, as we intended. We get some warnings about the workers,id, and thread fields that we’re not using in a direct way that reminds us

The following sections contain reference material you may find useful in yourRust journey.

The following list contains keywords that are reserved for current or futureuse by the Rust language. As such, they cannot be used as identifiers (exceptas raw identifiers as we’ll discuss in the “[Raw Identifiers][raw-identifiers]”

This appendix contains a glossary of Rust’s syntax, including operators andother symbols that appear by themselves or in the context of paths, generics,trait bounds, macros, attributes, comments, tuples, and brackets.

In various places in the book, we’ve discussed the derive attribute, whichyou can apply to a struct or enum definition. The derive attribute generatescode that will implement a trait with its own default implementation on the

In this appendix, we’ll talk about tools provided by the Rust project that areuseful when developing Rust code.The tool rustfmt reformats your code according to the community code style.

Way back in Chapter 1, we saw that cargo new adds a bit of metadata to yourCargo.toml about an edition. This appendix talks about what that means!The Rust language and compiler have a six-week release cycle. This means users

For resources in languages other than English. Most are still in progress; seethe Translations label to help or let us know about a new translation!

This appendix is about how Rust is made and how that affects you as a Rustdeveloper.As a language, Rust cares a lot about the stability of your code. We want