The Rust Programming Language › Introduction › How to Use This Book

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. Ferris will also help you distinguish code that isn’t
meant to work:
| Ferris                                                                                | Meaning                                          |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
|             | This code does not compile!                      |
|                    | This code panics!                                |
|  | This code does not produce the desired behavior. |
In most situations, we’ll lead you to the correct version of any code that
doesn’t compile.


The Rust Programming Language › Introduction › Source Code

The source files from which this book is generated can be found on
GitHub.


The Rust Programming Language › Getting Started

Let’s start your Rust journey! There’s a lot to learn, but every journey starts
somewhere. In this chapter, we’ll discuss:
- Installing Rust on Linux, macOS, and Windows
- Writing a program that prints `Hello, world!`
- Using `cargo`, Rust’s package manager and build system


The Rust Programming Language › Installation

The first step is to install Rust. We’ll download Rust through `rustup`, a
command line tool for managing Rust versions and associated tools. You’ll need
an internet connection for the download.
Note: If you prefer not to use `rustup` for some reason, please see the
Other Rust Installation Methods page for more options.
The following steps install the latest stable version of the Rust compiler.
Rust’s stability guarantees ensure that all the examples in the book that
compile will continue to compile with newer Rust versions. The output might
differ slightly between versions because Rust often improves error messages and
warnings. In other words, any newer, stable version of Rust you install using
these steps should work as expected with the content of this book.


The Rust Programming Language › Installation › Command Line Notation

In this chapter and throughout the book, we’ll show some commands used in the
terminal. Lines that you should enter in a terminal all start with `$`. You
don’t need to type the `$` character; it’s the command line prompt shown to
indicate the start of each command. Lines that don’t start with `$` typically
show the output of the previous command. Additionally, PowerShell-specific
examples will use `>` rather than `$`.


The Rust Programming Language › Installation › Installing `rustup` on Linux or macOS

If you’re using Linux or macOS, open a terminal and enter the following command:
```console
$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
```
The command downloads a script and starts the installation of the `rustup`
tool, which installs the latest stable version of Rust. You might be prompted
for your password. If the install is successful, the following line will appear:
```text
Rust is installed now. Great!
```
You will also need a _linker_, which is a program that Rust uses to join its
compiled outputs into one file. It is likely you already have one. If you get
linker errors, you should install a C compiler, which will typically include a
linker. A C compiler is also useful because some common Rust packages depend on
C code and will need a C compiler.
On macOS, you can get a C compiler by running:
```console
$ xcode-select --install
```
Linux users should generally install GCC or Clang, according to their
distribution’s documentation. For example, if you use Ubuntu, you can install
the `build-essential` package.

Installation
Installing `rustup` on Linux or macOS


The Rust Programming Language › Installation › Installing `rustup` on Windows

On Windows, go to https://www.rust-lang.org/tools/install
 and follow the instructions for installing Rust. At some point in the
installation, you’ll be prompted to install Visual Studio. This provides a
linker and the native libraries needed to compile programs. If you need more
help with this step, see
https://rust-lang.github.io/rustup/installation/windows-msvc.html
.
The rest of this book uses commands that work in both _cmd.exe_ and PowerShell.
If there are specific differences, we’ll explain which to use.

Installation
Installing `rustup` on Windows


The Rust Programming Language › Installation › Troubleshooting

To check whether you have Rust installed correctly, open a shell and enter this
line:
```console
$ rustc --version
```
You should see the version number, commit hash, and commit date for the latest
stable version that has been released, in the following format:
```text
rustc x.y.z (abcabcabc yyyy-mm-dd)
```
If you see this information, you have installed Rust successfully! If you don’t
see this information, check that Rust is in your `%PATH%` system variable as
follows.
In Windows CMD, use:
```console
echo %PATH%
```
In PowerShell, use:
```powershell
echo $env:Path
```
In Linux and macOS, use:
```console
$ echo $PATH
```
If that’s all correct and Rust still isn’t working, there are a number of
places you can get help. Find out how to get in touch with other Rustaceans (a
silly nickname we call ourselves) on the community page.


The Rust Programming Language › Installation › Updating and Uninstalling

Once Rust is installed via `rustup`, updating to a newly released version is
easy. From your shell, run the following update script:
```console
$ rustup update
```
To uninstall Rust and `rustup`, run the following uninstall script from your
shell:
```console
$ rustup self uninstall
```


The Rust Programming Language › Installation › Reading the Local Documentation

The installation of Rust also includes a local copy of the documentation so
that you can read it offline. Run `rustup doc` to open the local documentation
in your browser.
Any time a type or function is provided by the standard library and you’re not
sure what it does or how to use it, use the application programming interface
(API) documentation to find out!

Installation
Reading the Local Documentation


The Rust Programming Language › Installation › Using Text Editors and IDEs

This book makes no assumptions about what tools you use to author Rust code.
Just about any text editor will get the job done! However, many text editors and
integrated development environments (IDEs) have built-in support for Rust. You
can always find a fairly current list of many editors and IDEs on the tools
page on the Rust website.

Installation
Using Text Editors and IDEs


The Rust Programming Language › Installation › Working Offline with This Book

In several examples, we will use Rust packages beyond the standard library. To
work through those examples, you will either need to have an internet connection
or to have downloaded those dependencies ahead of time. To download the
dependencies ahead of time, you can run the following commands. (We’ll explain
what `cargo` is and what each of these commands does in detail later.)
```console
$ cargo new get-dependencies
$ cd get-dependencies
$ cargo add rand@0.10.1 trpl@0.2.0
```
This will cache the downloads for these packages so you will not need to
download them later. Once you have run this command, you do not need to keep the
`get-dependencies` folder. If you have run this command, you can use the
`--offline` flag with all `cargo` commands in the rest of the book to use these
cached versions instead of attempting to use the network.

Installation
Working Offline with This Book


The Rust Programming Language › Hello, World!

Now that you’ve installed Rust, it’s time to write your first Rust program.
It’s traditional when learning a new language to write a little program that
prints the text `Hello, world!` to the screen, so we’ll do the same here!
Note: This book assumes basic familiarity with the command line. Rust makes
no specific demands about your editing or tooling or where your code lives, so
if you prefer to use an IDE instead of the command line, feel free to use your
favorite IDE. Many IDEs now have some degree of Rust support; check the IDE’s
documentation for details. The Rust team has been focusing on enabling great
IDE support via `rust-analyzer`. See Appendix D
for more details.


The Rust Programming Language › Hello, World! › Project Directory Setup

You’ll start by making a directory to store your Rust code. It doesn’t matter
to Rust where your code lives, but for the exercises and projects in this book,
we suggest making a _projects_ directory in your home directory and keeping all
your projects there.
Open a terminal and enter the following commands to make a _projects_ directory
and a directory for the “Hello, world!” project within the _projects_ directory.
For Linux, macOS, and PowerShell on Windows, enter this:
```console
$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world
```
For Windows CMD, enter this:
```cmd
mkdir "%USERPROFILE%\projects"
cd /d "%USERPROFILE%\projects"
mkdir hello_world
cd hello_world
```


The Rust Programming Language › Hello, World! › Rust Program Basics

Next, make a new source file and call it _main.rs_. Rust files always end with
the _.rs_ extension. If you’re using more than one word in your filename, the
convention is to use an underscore to separate them. For example, use
_hello_world.rs_ rather than _helloworld.rs_.
Now open the _main.rs_ file you just created and enter the code in Listing 1-1.
Listing 1-1: A program that prints `Hello, world!` (main.rs)
```rust
fn main() {
    println!("Hello, world!");
}
```
Save the file and go back to your terminal window in the
_~/projects/hello_world_ directory. On Linux or macOS, enter the following
commands to compile and run the file:
```console
$ rustc main.rs
$ ./main
Hello, world!
```
On Windows, enter the command `.\main` instead of `./main`:
```powershell
rustc main.rs
.\main
Hello, world!
```
Regardless of your operating system, the string `Hello, world!` should print to
the terminal. If you don’t see this output, refer back to the
“Troubleshooting” part of the Installation
section for ways to get help.
If `Hello, world!` did print, congratulations! You’ve officially written a Rust
program. That makes you a Rust programmer—welcome!


The Rust Programming Language › Hello, World! › The Anatomy of a Rust Program

Let’s review this “Hello, world!” program in detail. Here’s the first piece of
the puzzle:
```rust
fn main() {

}
```
These lines define a function named `main`. The `main` function is special: It
is always the first code that runs in every executable Rust program. Here, the
first line declares a function named `main` that has no parameters and returns
nothing. If there were parameters, they would go inside the parentheses (`()`).
The function body is wrapped in `{}`. Rust requires curly brackets around all
function bodies. It’s good style to place the opening curly bracket on the same
line as the function declaration, adding one space in between.
Note: If you want to stick to a standard style across Rust projects, you can
use an automatic formatter tool called `rustfmt` to format your code in a
particular style (more on `rustfmt` in
Appendix D). The Rust team has included this tool
with the standard Rust distribution, as `rustc` is, so it should already be
installed on your computer!
The body of the `main` function holds the following code:
```rust
println!("Hello, world!");
```
This line does all the work in this little program: It prints text to the
screen. There are three important details to notice here.
First, `println!` calls a Rust macro. If it had called a function instead, it
would be entered as `println` (without the `!`). Rust macros are a way to write
code that generates code to extend Rust syntax, and we’ll discuss them in more
detail in Chapter 20. For now, you just need to
know that using a `!` means that you’re calling a macro instead of a normal
function and that macros don’t always follow the same rules as functions.

Hello, World!
The Anatomy of a Rust Program


The Rust Programming Language › Hello, World! › The Anatomy of a Rust Program

Second, you see the `"Hello, world!"` string. We pass this string as an argument
to `println!`, and the string is printed to the screen.
Third, we end the line with a semicolon (`;`), which indicates that this
expression is over, and the next one is ready to begin. Most lines of Rust code
end with a semicolon.


The Rust Programming Language › Hello, World! › Compilation and Execution

You’ve just run a newly created program, so let’s examine each step in the
process.
Before running a Rust program, you must compile it using the Rust compiler by
entering the `rustc` command and passing it the name of your source file, like
this:
```console
$ rustc main.rs
```
If you have a C or C++ background, you’ll notice that this is similar to `gcc`
or `clang`. After compiling successfully, Rust outputs a binary executable.
On Linux, macOS, and PowerShell on Windows, you can see the executable by
entering the `ls` command in your shell:
```console
$ ls
main  main.rs
```
On Linux and macOS, you’ll see two files. With PowerShell on Windows, you’ll
see the same three files that you would see using CMD. With CMD on Windows, you
would enter the following:
```cmd
dir /B %= the /B option says to only show the file names =%
main.exe
main.pdb
main.rs
```
This shows the source code file with the _.rs_ extension, the executable file
(_main.exe_ on Windows, but _main_ on all other platforms), and, when using
Windows, a file containing debugging information with the _.pdb_ extension.
From here, you run the _main_ or _main.exe_ file, like this:
```console
$ ./main # or .\main on Windows
```
If your _main.rs_ is your “Hello, world!” program, this line prints `Hello,
world!` to your terminal.


The Rust Programming Language › Hello, World! › Compilation and Execution

If you’re more familiar with a dynamic language, such as Ruby, Python, or
JavaScript, you might not be used to compiling and running a program as
separate steps. Rust is an _ahead-of-time compiled_ language, meaning you can
compile a program and give the executable to someone else, and they can run it
even without having Rust installed. If you give someone a _.rb_, _.py_, or
_.js_ file, they need to have a Ruby, Python, or JavaScript implementation
installed (respectively). But in those languages, you only need one command to
compile and run your program. Everything is a trade-off in language design.
Just compiling with `rustc` is fine for simple programs, but as your project
grows, you’ll want to manage all the options and make it easy to share your
code. Next, we’ll introduce you to the Cargo tool, which will help you write
real-world Rust programs.


The Rust Programming Language › Hello, Cargo!

Cargo is Rust’s build system and package manager. Most Rustaceans use this tool
to 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
building those libraries. (We call the libraries that your code needs
_dependencies_.)
The simplest Rust programs, like the one we’ve written so far, don’t have any
dependencies. If we had built the “Hello, world!” project with Cargo, it would
only use the part of Cargo that handles building your code. As you write more
complex Rust programs, you’ll add dependencies, and if you start a project
using Cargo, adding dependencies will be much easier to do.
Because the vast majority of Rust projects use Cargo, the rest of this book
assumes that you’re using Cargo too. Cargo comes installed with Rust if you
used the official installers discussed in the
“Installation” section. If you installed Rust
through some other means, check whether Cargo is installed by entering the
following in your terminal:
```console
$ cargo --version
```
If you see a version number, you have it! If you see an error, such as `command
not found`, look at the documentation for your method of installation to
determine how to install Cargo separately.


The Rust Programming Language › Hello, Cargo! › Creating a Project with Cargo

Let’s create a new project using Cargo and look at how it differs from our
original “Hello, world!” project. Navigate back to your _projects_ directory
(or wherever you decided to store your code). Then, on any operating system,
run the following:
```console
$ cargo new hello_cargo
$ cd hello_cargo
```
The first command creates a new directory and project called _hello_cargo_.
We’ve named our project _hello_cargo_, and Cargo creates its files in a
directory of the same name.
Go into the _hello_cargo_ directory and list the files. You’ll see that Cargo
has generated two files and one directory for us: a _Cargo.toml_ file and a
_src_ directory with a _main.rs_ file inside.
It has also initialized a new Git repository along with a _.gitignore_ file.
Git files won’t be generated if you run `cargo new` within an existing Git
repository; you can override this behavior by using `cargo new --vcs=git`.
Note: Git is a common version control system. You can change `cargo new` to
use a different version control system or no version control system by using
the `--vcs` flag. Run `cargo new --help` to see the available options.
Open _Cargo.toml_ in your text editor of choice. It should look similar to the
code in Listing 1-2.
Listing 1-2: Contents of *Cargo.toml* generated by `cargo new` (Cargo.toml)
```toml
[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2024"

[dependencies]
```
This file is in the _TOML_ (_Tom’s Obvious, Minimal
Language_) format, which is Cargo’s configuration format.

Hello, Cargo!
Creating a Project with Cargo


The Rust Programming Language › Hello, Cargo! › Creating a Project with Cargo

The first line, `[package]`, is a section heading that indicates that the
following statements are configuring a package. As we add more information to
this file, we’ll add other sections.
The next three lines set the configuration information Cargo needs to compile
your program: the name, the version, and the edition of Rust to use. We’ll talk
about the `edition` key in Appendix E.
The last line, `[dependencies]`, is the start of a section for you to list any
of your project’s dependencies. In Rust, packages of code are referred to as
_crates_. We won’t need any other crates for this project, but we will in the
first project in Chapter 2, so we’ll use this dependencies section then.
Now open _src/main.rs_ and take a look:
Filename: src/main.rs
```rust
fn main() {
    println!("Hello, world!");
}
```
Cargo has generated a “Hello, world!” program for you, just like the one we
wrote in Listing 1-1! So far, the differences between our project and the
project Cargo generated are that Cargo placed the code in the _src_ directory,
and we have a _Cargo.toml_ configuration file in the top directory.
Cargo expects your source files to live inside the _src_ directory. The
top-level project directory is just for README files, license information,
configuration files, and anything else not related to your code. Using Cargo
helps you organize your projects. There’s a place for everything, and
everything is in its place.


The Rust Programming Language › Hello, Cargo! › Creating a Project with Cargo

If you started a project that doesn’t use Cargo, as we did with the “Hello,
world!” project, you can convert it to a project that does use Cargo. Move the
project code into the _src_ directory and create an appropriate _Cargo.toml_
file. One easy way to get that _Cargo.toml_ file is to run `cargo init`, which
will create it for you automatically.


The Rust Programming Language › Hello, Cargo! › Building and Running a Cargo Project

Now let’s look at what’s different when we build and run the “Hello, world!”
program with Cargo! From your _hello_cargo_ directory, build your project by
entering the following command:
```console
$ cargo build
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs
```
This command creates an executable file in _target/debug/hello_cargo_ (or
_target\debug\hello_cargo.exe_ on Windows) rather than in your current
directory. Because the default build is a debug build, Cargo puts the binary in
a directory named _debug_. You can run the executable with this command:
```console
$ ./target/debug/hello_cargo # or .\target\debug\hello_cargo.exe on Windows
Hello, world!
```
If all goes well, `Hello, world!` should print to the terminal. Running `cargo
build` for the first time also causes Cargo to create a new file at the top
level: _Cargo.lock_. This file keeps track of the exact versions of
dependencies in your project. This project doesn’t have dependencies, so the
file is a bit sparse. You won’t ever need to change this file manually; Cargo
manages its contents for you.
We just built a project with `cargo build` and ran it with
`./target/debug/hello_cargo`, but we can also use `cargo run` to compile the
code and then run the resultant executable all in one command:
```console
$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_cargo`
Hello, world!
```
Using `cargo run` is more convenient than having to remember to run `cargo
build` and then use the whole path to the binary, so most developers use `cargo
run`.

Hello, Cargo!
Building and Running a Cargo Project


The Rust Programming Language › Hello, Cargo! › Building and Running a Cargo Project

Notice that this time we didn’t see output indicating that Cargo was compiling
`hello_cargo`. Cargo figured out that the files hadn’t changed, so it didn’t
rebuild but just ran the binary. If you had modified your source code, Cargo
would have rebuilt the project before running it, and you would have seen this
output:
```console
$ 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 also provides a command called `cargo check`. This command quickly checks
your code to make sure it compiles but doesn’t produce an executable:
```console
$ cargo check
   Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs
```
Why would you not want an executable? Often, `cargo check` is much faster than
`cargo build` because it skips the step of producing an executable. If you’re
continually checking your work while writing the code, using `cargo check` will
speed up the process of letting you know if your project is still compiling! As
such, many Rustaceans run `cargo check` periodically as they write their
program to make sure it compiles. Then, they run `cargo build` when they’re
ready to use the executable.
Let’s recap what we’ve learned so far about Cargo:


The Rust Programming Language › Hello, Cargo! › Building and Running a Cargo Project

- We can create a project using `cargo new`.
- We can build a project using `cargo build`.
- We can build and run a project in one step using `cargo run`.
- We can build a project without producing a binary to check for errors using
  `cargo check`.
- Instead of saving the result of the build in the same directory as our code,
  Cargo stores it in the _target/debug_ directory.
An additional advantage of using Cargo is that the commands are the same no
matter which operating system you’re working on. So, at this point, we’ll no
longer provide specific instructions for Linux and macOS versus Windows.


The Rust Programming Language › Hello, Cargo! › Building for Release

When your project is finally ready for release, you can use `cargo build
--release` to compile it with optimizations. This command will create an
executable in _target/release_ instead of _target/debug_. The optimizations
make your Rust code run faster, but turning them on lengthens the time it takes
for your program to compile. This is why there are two different profiles: one
for development, when you want to rebuild quickly and often, and another for
building the final program you’ll give to a user that won’t be rebuilt
repeatedly and that will run as fast as possible. If you’re benchmarking your
code’s running time, be sure to run `cargo build --release` and benchmark with
the executable in _target/release_.


The Rust Programming Language › Hello, Cargo! › Leveraging Cargo’s Conventions

With simple projects, Cargo doesn’t provide a lot of value over just using
`rustc`, but it will prove its worth as your programs become more intricate.
Once programs grow to multiple files or need a dependency, it’s much easier to
let Cargo coordinate the build.
Even though the `hello_cargo` project is simple, it now uses much of the real
tooling you’ll use in the rest of your Rust career. In fact, to work on any
existing projects, you can use the following commands to check out the code
using Git, change to that project’s directory, and build:
```console
$ git clone example.org/someproject
$ cd someproject
$ cargo build
```
For more information about Cargo, check out its documentation.

Hello, Cargo!
Leveraging Cargo’s Conventions


The Rust Programming Language › Summary

You’re already off to a great start on your Rust journey! In this chapter, you
learned how to:
- Install the latest stable version of Rust using `rustup`.
- Update to a newer Rust version.
- Open locally installed documentation.
- Write and run a “Hello, world!” program using `rustc` directly.
- Create and run a new project using the conventions of Cargo.
This is a great time to build a more substantial program to get used to reading
and writing Rust code. So, in Chapter 2, we’ll build a guessing game program.
If you would rather start by learning how common programming concepts work in
Rust, see Chapter 3 and then return to Chapter 2.


The Rust Programming Language › Programming a Guessing Game

Let’s jump into Rust by working through a hands-on project together! This
chapter introduces you to a few common Rust concepts by showing you how to use
them in a real program. You’ll learn about `let`, `match`, methods, associated
functions, external crates, and more! In the following chapters, we’ll explore
these ideas in more detail. In this chapter, you’ll just practice the
fundamentals.
We’ll implement a classic beginner programming problem: a guessing game. Here’s
how it works: The program will generate a random integer between 1 and 100. It
will then prompt the player to enter a guess. After a guess is entered, the
program will indicate whether the guess is too low or too high. If the guess is
correct, the game will print a congratulatory message and exit.


The Rust Programming Language › Programming a Guessing Game › Setting Up a New Project

To set up a new project, go to the _projects_ directory that you created in
Chapter 1 and make a new project using Cargo, like so:
```console
$ cargo new guessing_game
$ cd guessing_game
```
The first command, `cargo new`, takes the name of the project (`guessing_game`)
as the first argument. The second command changes to the new project’s
directory.
Look at the generated _Cargo.toml_ file:
Filename: Cargo.toml
```toml
[package]
name = "guessing_game"
version = "0.1.0"
edition = "2024"

[dependencies]
```
As you saw in Chapter 1, `cargo new` generates a “Hello, world!” program for
you. Check out the _src/main.rs_ file:
Filename: src/main.rs
```rust
fn main() {
    println!("Hello, world!");
}
```
Now let’s compile this “Hello, world!” program and run it in the same step
using the `cargo run` command:
```console
$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/guessing_game`
Hello, world!
```
The `run` command comes in handy when you need to rapidly iterate on a project,
as we’ll do in this game, quickly testing each iteration before moving on to
the next one.
Reopen the _src/main.rs_ file. You’ll be writing all the code in this file.

Programming a Guessing Game
Setting Up a New Project


The Rust Programming Language › Programming a Guessing Game › Processing a Guess

The first part of the guessing game program will ask for user input, process
that input, and check that the input is in the expected form. To start, we’ll
allow the player to input a guess. Enter the code in Listing 2-1 into
_src/main.rs_.
Listing 2-1: Code that gets a guess from the user and prints it (src/main.rs)
```rust,ignore
use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}
```
This code contains a lot of information, so let’s go over it line by line. To
obtain user input and then print the result as output, we need to bring the
`io` input/output library into scope. The `io` library comes from the standard
library, known as `std`:
```rust,ignore
use std::io;
```
By default, Rust has a set of items defined in the standard library that it
brings into the scope of every program. This set is called the _prelude_, and
you can see everything in it in the standard library documentation.
If a type you want to use isn’t in the prelude, you have to bring that type
into scope explicitly with a `use` statement. Using the `std::io` library
provides you with a number of useful features, including the ability to accept
user input.
As you saw in Chapter 1, the `main` function is the entry point into the
program:
```rust,ignore
fn main() {
```
The `fn` syntax declares a new function; the parentheses, `()`, indicate there
are no parameters; and the curly bracket, `{`, starts the body of the function.

Programming a Guessing Game
Processing a Guess


The Rust Programming Language › Programming a Guessing Game › Processing a Guess

As you also learned in Chapter 1, `println!` is a macro that prints a string to
the screen:
```rust,ignore
    println!("Guess the number!");

    println!("Please input your guess.");
```
This code is printing a prompt stating what the game is and requesting input
from the user.


The Rust Programming Language › Programming a Guessing Game › Processing a Guess › Storing Values with Variables

Next, we’ll create a _variable_ to store the user input, like this:
```rust,ignore
    let mut guess = String::new();
```
Now the program is getting interesting! There’s a lot going on in this little
line. We use the `let` statement to create the variable. Here’s another example:
```rust,ignore
let apples = 5;
```
This line creates a new variable named `apples` and binds it to the value `5`.
In Rust, variables are immutable by default, meaning once we give the variable
a value, the value won’t change. We’ll be discussing this concept in detail in
the “Variables and Mutability”
section in Chapter 3. To make a variable mutable, we add `mut` before the
variable name:
```rust,ignore
let apples = 5; // immutable
let mut bananas = 5; // mutable
```
Note: The `//` syntax starts a comment that continues until the end of the
line. Rust ignores everything in comments. We’ll discuss comments in more
detail in Chapter 3.
Returning to the guessing game program, you now know that `let mut guess` will
introduce a mutable variable named `guess`. The equal sign (`=`) tells Rust we
want to bind something to the variable now. On the right of the equal sign is
the value that `guess` is bound to, which is the result of calling
`String::new`, a function that returns a new instance of a `String`.
`String` is a string type provided by the standard
library that is a growable, UTF-8 encoded bit of text.

Programming a Guessing Game
Processing a Guess
Storing Values with Variables


The Rust Programming Language › Programming a Guessing Game › Processing a Guess › Storing Values with Variables

The `::` syntax in the `::new` line indicates that `new` is an associated
function of the `String` type. An _associated function_ is a function that’s
implemented on a type, in this case `String`. This `new` function creates a
new, empty string. You’ll find a `new` function on many types because it’s a
common name for a function that makes a new value of some kind.
In full, the `let mut guess = String::new();` line has created a mutable
variable that is currently bound to a new, empty instance of a `String`. Whew!


The Rust Programming Language › Programming a Guessing Game › Processing a Guess › Receiving User Input

Recall that we included the input/output functionality from the standard
library with `use std::io;` on the first line of the program. Now we’ll call
the `stdin` function from the `io` module, which will allow us to handle user
input:
```rust,ignore
    io::stdin()
        .read_line(&mut guess)
```
If we hadn’t imported the `io` module with `use std::io;` at the beginning of
the program, we could still use the function by writing this function call as
`std::io::stdin`. The `stdin` function returns an instance of
`std::io::Stdin`, which is a type that represents a
handle to the standard input for your terminal.
Next, the line `.read_line(&mut guess)` calls the `read_line`
 method on the standard input handle to get input from the user.
We’re also passing `&mut guess` as the argument to `read_line` to tell it what
string to store the user input in. The full job of `read_line` is to take
whatever the user types into standard input and append that into a string
(without overwriting its contents), so we therefore pass that string as an
argument. The string argument needs to be mutable so that the method can change
the string’s content.

Programming a Guessing Game
Processing a Guess
Receiving User Input


The Rust Programming Language › Programming a Guessing Game › Processing a Guess › Receiving User Input

The `&` indicates that this argument is a _reference_, which gives you a way to
let multiple parts of your code access one piece of data without needing to
copy that data into memory multiple times. References are a complex feature,
and one of Rust’s major advantages is how safe and easy it is to use
references. You don’t need to know a lot of those details to finish this
program. For now, all you need to know is that, like variables, references are
immutable by default. Hence, you need to write `&mut guess` rather than
`&guess` to make it mutable. (Chapter 4 will explain references more
thoroughly.)


The Rust Programming Language › Programming a Guessing Game › Processing a Guess › Handling Potential Failure with `Result`

We’re still working on this line of code. We’re now discussing a third line of
text, but note that it’s still part of a single logical line of code. The next
part is this method:
```rust,ignore
        .expect("Failed to read line");
```
We could have written this code as:
```rust,ignore
io::stdin().read_line(&mut guess).expect("Failed to read line");
```
However, one long line is difficult to read, so it’s best to divide it. It’s
often wise to introduce a newline and other whitespace to help break up long
lines when you call a method with the `.method_name()` syntax. Now let’s
discuss what this line does.
As mentioned earlier, `read_line` puts whatever the user enters into the string
we pass to it, but it also returns a `Result` value. `Result`
 is an _enumeration_, often called an _enum_,
which is a type that can be in one of multiple possible states. We call each
possible state a _variant_.
Chapter 6 will cover enums in more detail. The purpose
of these `Result` types is to encode error-handling information.
`Result`’s variants are `Ok` and `Err`. The `Ok` variant indicates the
operation was successful, and it contains the successfully generated value.
The `Err` variant means the operation failed, and it contains information
about how or why the operation failed.


The Rust Programming Language › Programming a Guessing Game › Processing a Guess › Handling Potential Failure with `Result`

Values of the `Result` type, like values of any type, have methods defined on
them. An instance of `Result` has an `expect` method
that you can call. If this instance of `Result` is an `Err` value, `expect`
will cause the program to crash and display the message that you passed as an
argument to `expect`. If the `read_line` method returns an `Err`, it would
likely be the result of an error coming from the underlying operating system.
If this instance of `Result` is an `Ok` value, `expect` will take the return
value that `Ok` is holding and return just that value to you so that you can
use it. In this case, that value is the number of bytes in the user’s input.
If you don’t call `expect`, the program will compile, but you’ll get a warning:
```console
$ 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: this `Result` may be an `Err` variant, which should be handled
   = note: `#[warn(unused_must_use)]` (part of `#[warn(unused)]`) on by default
help: use `let _ = ...` to ignore the resulting value
   |
10 |     let _ = io::stdin().read_line(&mut guess);
   |     +++++++

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


The Rust Programming Language › Programming a Guessing Game › Processing a Guess › Handling Potential Failure with `Result`

Rust warns that you haven’t used the `Result` value returned from `read_line`,
indicating that the program hasn’t handled a possible error.
The right way to suppress the warning is to actually write error-handling code,
but in our case we just want to crash this program when a problem occurs, so we
can use `expect`. You’ll learn about recovering from errors in Chapter
9.


The Rust Programming Language › Programming a Guessing Game › Processing a Guess › Printing Values with `println!` Placeholders

Aside from the closing curly bracket, there’s only one more line to discuss in
the code so far:
```rust,ignore
    println!("You guessed: {guess}");
```
This line prints the string that now contains the user’s input. The `{}` set of
curly brackets is a placeholder: Think of `{}` as little crab pincers that hold
a value in place. When printing the value of a variable, the variable name can
go inside the curly brackets. When printing the result of evaluating an
expression, place empty curly brackets in the format string, then follow the
format string with a comma-separated list of expressions to print in each empty
curly bracket placeholder in the same order. Printing a variable and the result
of an expression in one call to `println!` would look like this:
```rust
let x = 5;
let y = 10;

println!("x = {x} and y + 2 = {}", y + 2);
```
This code would print `x = 5 and y + 2 = 12`.


The Rust Programming Language › Programming a Guessing Game › Processing a Guess › Testing the First Part

Let’s test the first part of the guessing game. Run it using `cargo run`:
```console
$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.44s
     Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
6
You guessed: 6
```
At this point, the first part of the game is done: We’re getting input from the
keyboard and then printing it.

Programming a Guessing Game
Processing a Guess
Testing the First Part


The Rust Programming Language › Programming a Guessing Game › Generating a Secret Number

Next, we need to generate a secret number that the user will try to guess. The
secret number should be different every time so that the game is fun to play
more than once. We’ll use a random number between 1 and 100 so that the game
isn’t too difficult. Rust doesn’t yet include random number functionality in
its standard library. However, the Rust team does provide a `rand`
crate with said functionality.

Programming a Guessing Game
Generating a Secret Number


The Rust Programming Language › Programming a Guessing Game › Generating a Secret Number › Increasing Functionality with a Crate

Remember that a crate is a collection of Rust source code files. The project
we’ve been building is a binary crate, which is an executable. The `rand` crate
is a library crate, which contains code that is intended to be used in other
programs and can’t be executed on its own.
Cargo’s coordination of external crates is where Cargo really shines. Before we
can write code that uses `rand`, we need to modify the _Cargo.toml_ file to
include the `rand` crate as a dependency. Open that file now and add the
following line to the bottom, beneath the `[dependencies]` section header that
Cargo created for you. Be sure to specify `rand` exactly as we have here, with
this version number, or the code examples in this tutorial may not work:
Filename: Cargo.toml
```toml
[dependencies]
rand = "0.10.1"
```
In the _Cargo.toml_ file, everything that follows a header is part of that
section that continues until another section starts. In `[dependencies]`, you
tell Cargo which external crates your project depends on and which versions of
those crates you require. In this case, we specify the `rand` crate with the
semantic version specifier `0.10.1`. Cargo understands Semantic
Versioning (sometimes called _SemVer_), which is a
standard for writing version numbers. The specifier `0.10.1` is actually
shorthand for `^0.10.1`, which means any version that is at least 0.10.1 but
below 0.11.0.

Programming a Guessing Game
Generating a Secret Number
Increasing Functionality with a Crate


The Rust Programming Language › Programming a Guessing Game › Generating a Secret Number › Increasing Functionality with a Crate

Cargo considers these versions to have public APIs compatible with version
0.10.1, and this specification ensures that you’ll get the latest patch release
that will still compile with the code in this chapter. Any version 0.11.0 or
greater is not guaranteed to have the same API as what the following examples
use.
Now, without changing any of the code, let’s build the project, as shown in
Listing 2-2.
Listing 2-2: The output from running `cargo build` after adding the `rand` crate as a dependency
```console
$ cargo build
    Updating crates.io index
     Locking 8 packages to latest Rust 1.96.0 compatible versions
  Downloaded rand_core v0.10.1
  Downloaded chacha20 v0.10.1
  Downloaded rand v0.10.1
  Downloaded 3 crates (162.9KiB) in 0.59s
   Compiling libc v0.2.186
   Compiling rand_core v0.10.1
   Compiling getrandom v0.4.3
   Compiling cfg-if v1.0.4
   Compiling chacha20 v0.10.1
   Compiling rand v0.10.1
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.03s
```
You may see different version numbers (but they will all be compatible with the
code, thanks to SemVer!) and different lines (depending on the operating
system), and the lines may be in a different order.


The Rust Programming Language › Programming a Guessing Game › Generating a Secret Number › Increasing Functionality with a Crate › Ensuring Reproducible Builds

When we include an external dependency, Cargo fetches the latest versions of
everything that dependency needs from the _registry_, which is a copy of data
from Crates.io. Crates.io is where people in the Rust ecosystem
post their open source Rust projects for others to use.
After updating the registry, Cargo checks the `[dependencies]` section and
downloads any crates listed that aren’t already downloaded. In this case,
although we only listed `rand` as a dependency, Cargo also grabbed other crates
that `rand` depends on to work. After downloading the crates, Rust compiles
them and then compiles the project with the dependencies available.
If you immediately run `cargo build` again without making any changes, you
won’t get any output aside from the `Finished` line. Cargo knows it has already
downloaded and compiled the dependencies, and you haven’t changed anything
about them in your _Cargo.toml_ file. Cargo also knows that you haven’t changed
anything about your code, so it doesn’t recompile that either. With nothing to
do, it simply exits.
If you open the _src/main.rs_ file, make a trivial change, and then save it and
build again, you’ll only see two lines of output:
```console
$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s
```
These lines show that Cargo only updates the build with your tiny change to the
_src/main.rs_ file. Your dependencies haven’t changed, so Cargo knows it can
reuse what it has already downloaded and compiled for those.

Programming a Guessing Game
Generating a Secret Number
Increasing Functionality with a Crate
Ensuring Reproducible Builds


The Rust Programming Language › Programming a Guessing Game › Generating a Secret Number › Increasing Functionality with a Crate › Updating a Crate to Get a New Version

Cargo has a mechanism that ensures that you can rebuild the same artifact every
time you or anyone else builds your code: Cargo will use only the versions of
the dependencies you specified until you indicate otherwise. For example, say
that next week version 0.10.2 of the `rand` crate comes out, and that version
contains an important bug fix, but it also contains a regression that will
break your code. To handle this, Rust creates the _Cargo.lock_ file the first
time you run `cargo build`, so we now have this in the _guessing_game_
directory.
When you build a project for the first time, Cargo figures out all the versions
of the dependencies that fit the criteria and then writes them to the
_Cargo.lock_ file. When you build your project in the future, Cargo will see
that the _Cargo.lock_ file exists and will use the versions specified there
rather than doing all the work of figuring out versions again. This lets you
have a reproducible build automatically. In other words, your project will
remain at 0.10.1 until you explicitly upgrade, thanks to the _Cargo.lock_ file.
Because the _Cargo.lock_ file is important for reproducible builds, it’s often
checked into source control with the rest of the code in your project.
When you _do_ want to update a crate, Cargo provides the command `update`,
which will ignore the _Cargo.lock_ file and figure out all the latest versions
that fit your specifications in _Cargo.toml_. Cargo will then write those
versions to the _Cargo.lock_ file. Otherwise, by default, Cargo will only look
for versions greater than 0.10.1 and less than 0.11.0. If the `rand` crate has
released the two new versions 0.10.2 and 0.999.0, you would see the following if
you ran `cargo update`:

Programming a Guessing Game
Generating a Secret Number
Increasing Functionality with a Crate
Updating a Crate to Get a New Version


The Rust Programming Language › Programming a Guessing Game › Generating a Secret Number › Increasing Functionality with a Crate › Updating a Crate to Get a New Version

```console
$ cargo update
    Updating crates.io index
     Locking 1 package to latest Rust 1.96.0 compatible version
    Updating rand v0.10.1 -> v0.10.2 (available: v0.999.0)
```
Cargo ignores the 0.999.0 release. At this point, you would also notice a
change in your _Cargo.lock_ file noting that the version of the `rand` crate
you are now using is 0.10.2. To use `rand` version 0.999.0 or any version in the
0.999._x_ series, you’d have to update the _Cargo.toml_ file to look like this
instead (don’t actually make this change because the following examples assume
you’re using `rand` 0.10):
```toml
[dependencies]
rand = "0.999.0"
```
The next time you run `cargo build`, Cargo will update the registry of crates
available and reevaluate your `rand` requirements according to the new version
you have specified.
There’s a lot more to say about Cargo and its
ecosystem, which we’ll discuss in Chapter 14, but
for now, that’s all you need to know. Cargo makes it very easy to reuse
libraries, so Rustaceans are able to write smaller projects that are assembled
from a number of packages.


The Rust Programming Language › Programming a Guessing Game › Generating a Secret Number › Generating a Random Number

Let’s start using `rand` to generate a number to guess. The next step is to
update _src/main.rs_, as shown in Listing 2-3.
Listing 2-3: Adding code to generate a random number (src/main.rs)
```rust,ignore
use std::io;

use rand::prelude::*;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::rng().random_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}
```
First, we add the line `use rand::prelude::*;`. The `prelude` module contains
the most commonly used parts of the `rand` crate, and `use` makes those items
available in our program's scope.

Programming a Guessing Game
Generating a Secret Number
Generating a Random Number


The Rust Programming Language › Programming a Guessing Game › Generating a Secret Number › Generating a Random Number

Next, we’re adding two lines in the middle. In the first line, we call the
`rand::rng` function that gives us the particular random number generator we’re
going to use: one that is local to the current thread of execution and is
seeded by the operating system. Then, we call the `random_range` method on the
random number generator. This method is defined by the `RngExt` trait that is
part of the `rand::prelude` module that we brought into scope with the `use
rand::prelude::*;` statement. The `random_range` method takes a range
expression as an argument and generates a random number in the range. The kind
of range expression we’re using here takes the form `start..=end` and is
inclusive on the lower and upper bounds, so we need to specify `1..=100` to
request a number between 1 and 100.
Note: You won’t just know what to bring into scope and which methods and
functions to call from a crate, so each crate has documentation with
instructions for using it. Another neat feature of Cargo is that running the
`cargo doc --open` command will build documentation provided by all your
dependencies locally and open it in your browser. If you’re interested in
other functionality in the `rand` crate, for example, run `cargo doc --open`
and click `rand` in the sidebar on the left.
The second new line prints the secret number. This is useful while we’re
developing the program to be able to test it, but we’ll delete it from the
final version. It’s not much of a game if the program prints the answer as soon
as it starts!
Try running the program a few times:


The Rust Programming Language › Programming a Guessing Game › Generating a Secret Number › Generating a Random Number

```console
$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 7
Please input your guess.
4
You guessed: 4

$ cargo run
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 83
Please input your guess.
5
You guessed: 5
```
You should get different random numbers, and they should all be numbers between
1 and 100. If you get warnings, they are safe to ignore. If you get errors,
please check that you have `rand = "0.10.1"` in your *Cargo.toml* as future
versions of `rand` may have a different API, but any version in the `0.10`
series should work with the code in this chapter.


The Rust Programming Language › Programming a Guessing Game › Comparing the Guess to the Secret Number

Now that we have user input and a random number, we can compare them. That step
is shown in Listing 2-4. Note that this code won’t compile just yet, as we will
explain.
Listing 2-4: Handling the possible return values of comparing two numbers (src/main.rs)
```rust,ignore,does_not_compile
use std::cmp::Ordering;
use std::io;

use rand::prelude::*;

fn main() {
    // --snip--

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}
```
First, we add another `use` statement, bringing a type called
`std::cmp::Ordering` into scope from the standard library. The `Ordering` type
is another enum and has the variants `Less`, `Greater`, and `Equal`. These are
the three outcomes that are possible when you compare two values.
Then, we add five new lines at the bottom that use the `Ordering` type. The
`cmp` method compares two values and can be called on anything that can be
compared. It takes a reference to whatever you want to compare with: Here, it’s
comparing `guess` to `secret_number`. Then, it returns a variant of the
`Ordering` enum we brought into scope with the `use` statement. We use a
`match` expression to decide what to do next based on
which variant of `Ordering` was returned from the call to `cmp` with the values
in `guess` and `secret_number`.


The Rust Programming Language › Programming a Guessing Game › Comparing the Guess to the Secret Number

A `match` expression is made up of _arms_. An arm consists of a _pattern_ to
match against, and the code that should be run if the value given to `match`
fits that arm’s pattern. Rust takes the value given to `match` and looks
through each arm’s pattern in turn. Patterns and the `match` construct are
powerful Rust features: They let you express a variety of situations your code
might encounter, and they make sure you handle them all. These features will be
covered in detail in Chapter 6 and Chapter 19, respectively.
Let’s walk through an example with the `match` expression we use here. Say that
the user has guessed 50 and the randomly generated secret number this time is
38.
When the code compares 50 to 38, the `cmp` method will return
`Ordering::Greater` because 50 is greater than 38. The `match` expression gets
the `Ordering::Greater` value and starts checking each arm’s pattern. It looks
at the first arm’s pattern, `Ordering::Less`, and sees that the value
`Ordering::Greater` does not match `Ordering::Less`, so it ignores the code in
that arm and moves to the next arm. The next arm’s pattern is
`Ordering::Greater`, which _does_ match `Ordering::Greater`! The associated
code in that arm will execute and print `Too big!` to the screen. The `match`
expression ends after the first successful match, so it won’t look at the last
arm in this scenario.
However, the code in Listing 2-4 won’t compile yet. Let’s try it:


The Rust Programming Language › Programming a Guessing Game › Comparing the Guess to the Secret Number

```console
$ cargo build
   Compiling libc v0.2.186
   Compiling rand_core v0.10.1
   Compiling getrandom v0.4.3
   Compiling cfg-if v1.0.0
   Compiling chacha20 v0.10.1
   Compiling rand v0.10.1
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
error[E0308]: mismatched types
  --> src/main.rs:23:21
   |
23 |     match guess.cmp(&secret_number) {
   |                 --- ^^^^^^^^^^^^^^ expected `&String`, found `&{integer}`
   |                 |
   |                 arguments to this method are incorrect
   |
   = note: expected reference `&String`
              found reference `&{integer}`
note: method defined here
  --> /rustc/2d8144b7880597b6e6d3dfd63a9a9efae3f533d3/library/core/src/cmp.rs:1000:7

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


The Rust Programming Language › Programming a Guessing Game › Comparing the Guess to the Secret Number

The core of the error states that there are _mismatched types_. Rust has a
strong, static type system. However, it also has type inference. When we wrote
`let mut guess = String::new()`, Rust was able to infer that `guess` should be
a `String` and didn’t make us write the type. The `secret_number`, on the other
hand, is a number type. A few of Rust’s number types can have a value between 1
and 100: `i32`, a 32-bit number; `u32`, an unsigned 32-bit number; `i64`, a
64-bit number; as well as others. Unless otherwise specified, Rust defaults to
an `i32`, which is the type of `secret_number` unless you add type information
elsewhere that would cause Rust to infer a different numerical type. The reason
for the error is that Rust cannot compare a string and a number type.
Ultimately, we want to convert the `String` the program reads as input into a
number type so that we can compare it numerically to the secret number. We do
so by adding this line to the `main` function body:
Filename: src/main.rs
```rust,ignore
    // --snip--

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
```
The line is:


The Rust Programming Language › Programming a Guessing Game › Comparing the Guess to the Secret Number

```rust,ignore
let guess: u32 = guess.trim().parse().expect("Please type a number!");
```
We create a variable named `guess`. But wait, doesn’t the program already have
a variable named `guess`? It does, but helpfully Rust allows us to shadow the
previous value of `guess` with a new one. _Shadowing_ lets us reuse the `guess`
variable name rather than forcing us to create two unique variables, such as
`guess_str` and `guess`, for example. We’ll cover this in more detail in
Chapter 3, but for now, know that this feature is
often used when you want to convert a value from one type to another type.
We bind this new variable to the expression `guess.trim().parse()`. The `guess`
in the expression refers to the original `guess` variable that contained the
input as a string. The `trim` method on a `String` instance will eliminate any
whitespace at the beginning and end, which we must do before we can convert the
string to a `u32`, which can only contain numerical data. The user must press
enter to satisfy `read_line` and input their guess, which adds a
newline character to the string. For example, if the user types 5 and
presses enter, `guess` looks like this: `5\n`. The `\n` represents
“newline.” (On Windows, pressing enter results in a carriage return
and a newline, `\r\n`.) The `trim` method eliminates `\n` or `\r\n`, resulting
in just `5`.


The Rust Programming Language › Programming a Guessing Game › Comparing the Guess to the Secret Number

The `parse` method on strings converts a string to
another type. Here, we use it to convert from a string to a number. We need to
tell Rust the exact number type we want by using `let guess: u32`. The colon
(`:`) after `guess` tells Rust we’ll annotate the variable’s type. Rust has a
few built-in number types; the `u32` seen here is an unsigned, 32-bit integer.
It’s a good default choice for a small positive number. You’ll learn about
other number types in Chapter 3.
Additionally, the `u32` annotation in this example program and the comparison
with `secret_number` means Rust will infer that `secret_number` should be a
`u32` as well. So, now the comparison will be between two values of the same
type!
The `parse` method will only work on characters that can logically be converted
into numbers and so can easily cause errors. If, for example, the string
contained `A👍%`, there would be no way to convert that to a number. Because it
might fail, the `parse` method returns a `Result` type, much as the `read_line`
method does (discussed earlier in “Handling Potential Failure with
`Result`”). We’ll treat
this `Result` the same way by using the `expect` method again. If `parse`
returns an `Err` `Result` variant because it couldn’t create a number from the
string, the `expect` call will crash the game and print the message we give it.
If `parse` can successfully convert the string to a number, it will return the
`Ok` variant of `Result`, and `expect` will return the number that we want from
the `Ok` value.
Let’s run the program now:


The Rust Programming Language › Programming a Guessing Game › Comparing the Guess to the Secret Number

```console
$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.26s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 58
Please input your guess.
  76
You guessed: 76
Too big!
```
Nice! Even though spaces were added before the guess, the program still figured
out that the user guessed 76. Run the program a few times to verify the
different behavior with different kinds of input: Guess the number correctly,
guess a number that is too high, and guess a number that is too low.
We have most of the game working now, but the user can make only one guess.
Let’s change that by adding a loop!


The Rust Programming Language › Programming a Guessing Game › Allowing Multiple Guesses with Looping

The `loop` keyword creates an infinite loop. We’ll add a loop to give users
more chances at guessing the number:
Filename: src/main.rs
```rust,ignore
    // --snip--

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => println!("You win!"),
        }
    }
}
```
As you can see, we’ve moved everything from the guess input prompt onward into
a loop. Be sure to indent the lines inside the loop another four spaces each
and run the program again. The program will now ask for another guess forever,
which actually introduces a new problem. It doesn’t seem like the user can quit!
The user could always interrupt the program by using the keyboard shortcut
ctrl-C. But there’s another way to escape this insatiable
monster, as mentioned in the `parse` discussion in “Comparing the Guess to the
Secret Number”: If
the user enters a non-number answer, the program will crash. We can take
advantage of that to allow the user to quit, as shown here:

Programming a Guessing Game
Allowing Multiple Guesses with Looping


The Rust Programming Language › Programming a Guessing Game › Allowing Multiple Guesses with Looping

```console
$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.23s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 59
Please input your guess.
45
You guessed: 45
Too small!
Please input your guess.
60
You guessed: 60
Too big!
Please input your guess.
59
You guessed: 59
You win!
Please input your guess.
quit

thread 'main' (6694925) panicked at src/main.rs:28:47:
Please type a number!: ParseIntError { kind: InvalidDigit }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```
Typing `quit` will quit the game, but as you’ll notice, so will entering any
other non-number input. This is suboptimal, to say the least; we want the game
to also stop when the correct number is guessed.


The Rust Programming Language › Programming a Guessing Game › Allowing Multiple Guesses with Looping › Quitting After a Correct Guess

Let’s program the game to quit when the user wins by adding a `break` statement:
Filename: src/main.rs
```rust,ignore
        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}
```
Adding the `break` line after `You win!` makes the program exit the loop when
the user guesses the secret number correctly. Exiting the loop also means
exiting the program, because the loop is the last part of `main`.

Programming a Guessing Game
Allowing Multiple Guesses with Looping
Quitting After a Correct Guess


The Rust Programming Language › Programming a Guessing Game › Allowing Multiple Guesses with Looping › Handling Invalid Input

To further refine the game’s behavior, rather than crashing the program when
the user inputs a non-number, let’s make the game ignore a non-number so that
the user can continue guessing. We can do that by altering the line where
`guess` is converted from a `String` to a `u32`, as shown in Listing 2-5.
Listing 2-5: Ignoring a non-number guess and asking for another guess instead of crashing the program (src/main.rs)
```rust,ignore
        // --snip--

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

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

        println!("You guessed: {guess}");

        // --snip--
```
We switch from an `expect` call to a `match` expression to move from crashing
on an error to handling the error. Remember that `parse` returns a `Result`
type and `Result` is an enum that has the variants `Ok` and `Err`. We’re using
a `match` expression here, as we did with the `Ordering` result of the `cmp`
method.
If `parse` is able to successfully turn the string into a number, it will
return an `Ok` value that contains the resultant number. That `Ok` value will
match the first arm’s pattern, and the `match` expression will just return the
`num` value that `parse` produced and put inside the `Ok` value. That number
will end up right where we want it in the new `guess` variable we’re creating.

Programming a Guessing Game
Allowing Multiple Guesses with Looping
Handling Invalid Input


The Rust Programming Language › Programming a Guessing Game › Allowing Multiple Guesses with Looping › Handling Invalid Input

If `parse` is _not_ able to turn the string into a number, it will return an
`Err` value that contains more information about the error. The `Err` value
does not match the `Ok(num)` pattern in the first `match` arm, but it does
match the `Err(_)` pattern in the second arm. The underscore, `_`, is a
catch-all value; in this example, we’re saying we want to match all `Err`
values, no matter what information they have inside them. So, the program will
execute the second arm’s code, `continue`, which tells the program to go to the
next iteration of the `loop` and ask for another guess. So, effectively, the
program ignores all errors that `parse` might encounter!
Now everything in the program should work as expected. Let’s try it:
```console
$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 61
Please input your guess.
10
You guessed: 10
Too small!
Please input your guess.
99
You guessed: 99
Too big!
Please input your guess.
foo
Please input your guess.
61
You guessed: 61
You win!
```
Awesome! With one tiny final tweak, we will finish the guessing game. Recall
that the program is still printing the secret number. That worked well for
testing, but it ruins the game. Let’s delete the `println!` that outputs the
secret number. Listing 2-6 shows the final code.
Listing 2-6: Complete guessing game code (src/main.rs)


The Rust Programming Language › Programming a Guessing Game › Allowing Multiple Guesses with Looping › Handling Invalid Input

```rust,ignore
use std::cmp::Ordering;
use std::io;

use rand::prelude::*;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::rng().random_range(1..=100);

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

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

        println!("You guessed: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}
```
At this point, you’ve successfully built the guessing game. Congratulations!


The Rust Programming Language › Programming a Guessing Game › Summary

This project was a hands-on way to introduce you to many new Rust concepts:
`let`, `match`, functions, the use of external crates, and more. In the next
few chapters, you’ll learn about these concepts in more detail. Chapter 3
covers concepts that most programming languages have, such as variables, data
types, and functions, and shows how to use them in Rust. Chapter 4 explores
ownership, a feature that makes Rust different from other languages. Chapter 5
discusses structs and method syntax, and Chapter 6 explains how enums work.


The Rust Programming Language › Common Programming Concepts › Keywords

This chapter covers concepts that appear in almost every programming language
and how they work in Rust. Many programming languages have much in common at
their core. None of the concepts presented in this chapter are unique to Rust,
but we’ll discuss them in the context of Rust and explain the conventions
around using them.
Specifically, you’ll learn about variables, basic types, functions, comments,
and control flow. These foundations will be in every Rust program, and learning
them early will give you a strong core to start from.
The Rust language has a set of _keywords_ that are reserved for use by the
language only, much as in other languages. Keep in mind that you cannot use
these words as names of variables or functions. Most of the keywords have
special meanings, and you’ll be using them to do various tasks in your Rust
programs; a few have no current functionality associated with them but have
been reserved for functionality that might be added to Rust in the future. You
can find the list of the keywords in Appendix A.


The Rust Programming Language › Variables and Mutability

As mentioned in the “Storing Values with
Variables” section, by default,
variables are immutable. This is one of many nudges Rust gives you to write
your code in a way that takes advantage of the safety and easy concurrency that
Rust offers. However, you still have the option to make your variables mutable.
Let’s explore how and why Rust encourages you to favor immutability and why
sometimes you might want to opt out.
When a variable is immutable, once a value is bound to a name, you can’t change
that value. To illustrate this, generate a new project called _variables_ in
your _projects_ directory by using `cargo new variables`.
Then, in your new _variables_ directory, open _src/main.rs_ and replace its
code with the following code, which won’t compile just yet:
Filename: src/main.rs
```rust,ignore,does_not_compile
fn main() {
    let x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}
```
Save and run the program using `cargo run`. You should receive an error message
regarding an immutability error, as shown in this output:


The Rust Programming Language › Variables and Mutability

```console
$ 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`
3 |     println!("The value of x is: {x}");
4 |     x = 6;
  |     ^^^^^ cannot assign twice to immutable variable
  |
help: consider making this binding mutable
  |
2 |     let mut x = 5;
  |         +++

For more information about this error, try `rustc --explain E0384`.
error: could not compile `variables` (bin "variables") due to 1 previous error
```
This example shows how the compiler helps you find errors in your programs.
Compiler errors can be frustrating, but really they only mean your program
isn’t safely doing what you want it to do yet; they do _not_ mean that you’re
not a good programmer! Experienced Rustaceans still get compiler errors.
You received the error message `` cannot assign twice to immutable variable `x` `` because you tried to assign a second value to the immutable `x` variable.


The Rust Programming Language › Variables and Mutability

It’s important that we get compile-time errors when we attempt to change a
value that’s designated as immutable, because this very situation can lead to
bugs. If one part of our code operates on the assumption that a value will
never change and another part of our code changes that value, it’s possible
that the first part of the code won’t do what it was designed to do. The cause
of this kind of bug can be difficult to track down after the fact, especially
when the second piece of code changes the value only _sometimes_. The Rust
compiler guarantees that when you state that a value won’t change, it really
won’t change, so you don’t have to keep track of it yourself. Your code is thus
easier to reason through.
But mutability can be very useful and can make code more convenient to write.
Although variables are immutable by default, you can make them mutable by
adding `mut` in front of the variable name as you did in Chapter
2. Adding `mut` also conveys
intent to future readers of the code by indicating that other parts of the code
will be changing this variable’s value.
For example, let’s change _src/main.rs_ to the following:
Filename: src/main.rs
```rust
fn main() {
    let mut x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}
```
When we run the program now, we get this:
```console
$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/variables`
The value of x is: 5
The value of x is: 6
```


The Rust Programming Language › Variables and Mutability

We’re allowed to change the value bound to `x` from `5` to `6` when `mut` is
used. Ultimately, deciding whether to use mutability or not is up to you and
depends on what you think is clearest in that particular situation.


The Rust Programming Language › Variables and Mutability › Declaring Constants

Like immutable variables, _constants_ are values that are bound to a name and
are not allowed to change, but there are a few differences between constants
and variables.
First, you aren’t allowed to use `mut` with constants. Constants aren’t just
immutable by default—they’re always immutable. You declare constants using the
`const` keyword instead of the `let` keyword, and the type of the value _must_
be annotated. We’ll cover types and type annotations in the next section,
“Data Types”, so don’t worry about the details
right now. Just know that you must always annotate the type.
Constants can be declared in any scope, including the global scope, which makes
them useful for values that many parts of code need to know about.
The last difference is that constants may be set only to a constant expression,
not the result of a value that could only be computed at runtime.
Here’s an example of a constant declaration:
```rust
const THREE_HOURS_IN_SECONDS: u32 = 60 * 60 * 3;
```
The constant’s name is `THREE_HOURS_IN_SECONDS`, and its value is set to the
result of multiplying 60 (the number of seconds in a minute) by 60 (the number
of minutes in an hour) by 3 (the number of hours we want to count in this
program). Rust’s naming convention for constants is to use all uppercase with
underscores between words. The compiler is able to evaluate a limited set of
operations at compile time, which lets us choose to write out this value in a
way that’s easier to understand and verify, rather than setting this constant
to the value 10,800. See the Rust Reference’s section on constant
evaluation for more information on what operations can be used
when declaring constants.

Variables and Mutability
Declaring Constants


The Rust Programming Language › Variables and Mutability › Declaring Constants

Constants are valid for the entire time a program runs, within the scope in
which they were declared. This property makes constants useful for values in
your application domain that multiple parts of the program might need to know
about, such as the maximum number of points any player of a game is allowed to
earn, or the speed of light.
Naming hardcoded values used throughout your program as constants is useful in
conveying the meaning of that value to future maintainers of the code. It also
helps to have only one place in your code that you would need to change if the
hardcoded value needed to be updated in the future.


The Rust Programming Language › Variables and Mutability › Shadowing

As you saw in the guessing game tutorial in Chapter
2, you can declare a
new variable with the same name as a previous variable. Rustaceans say that the
first variable is _shadowed_ by the second, which means that the second
variable is what the compiler will see when you use the name of the variable.
In effect, the second variable overshadows the first, taking any uses of the
variable name to itself until either it itself is shadowed or the scope ends.
We can shadow a variable by using the same variable’s name and repeating the
use of the `let` keyword as follows:
Filename: src/main.rs
```rust
fn main() {
    let x = 5;

    let x = x + 1;

    {
        let x = x * 2;
        println!("The value of x in the inner scope is: {x}");
    }

    println!("The value of x is: {x}");
}
```
This program first binds `x` to a value of `5`. Then, it creates a new variable
`x` by repeating `let x =`, taking the original value and adding `1` so that
the value of `x` is `6`. Then, within an inner scope created with the curly
brackets, the third `let` statement also shadows `x` and creates a new
variable, multiplying the previous value by `2` to give `x` a value of `12`.
When that scope is over, the inner shadowing ends and `x` returns to being `6`.
When we run this program, it will output the following:


The Rust Programming Language › Variables and Mutability › Shadowing

```console
$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/variables`
The value of x in the inner scope is: 12
The value of x is: 6
```
Shadowing is different from marking a variable as `mut` because we’ll get a
compile-time error if we accidentally try to reassign to this variable without
using the `let` keyword. By using `let`, we can perform a few transformations
on a value but have the variable be immutable after those transformations have
completed.
The other difference between `mut` and shadowing is that because we’re
effectively creating a new variable when we use the `let` keyword again, we can
change the type of the value but reuse the same name. For example, say our
program asks a user to show how many spaces they want between some text by
inputting space characters, and then we want to store that input as a number:
```rust
    let spaces = "   ";
    let spaces = spaces.len();
```
The first `spaces` variable is a string type, and the second `spaces` variable
is a number type. Shadowing thus spares us from having to come up with
different names, such as `spaces_str` and `spaces_num`; instead, we can reuse
the simpler `spaces` name. However, if we try to use `mut` for this, as shown
here, we’ll get a compile-time error:
```rust,ignore,does_not_compile
    let mut spaces = "   ";
    spaces = spaces.len();
```
The error says we’re not allowed to mutate a variable’s type:


The Rust Programming Language › Variables and Mutability › Shadowing

```console
$ 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` (bin "variables") due to 1 previous error
```
Now that we’ve explored how variables work, let’s look at more data types they
can have.


The Rust Programming Language › Data Types

Every value in Rust is of a certain _data type_, which tells Rust what kind of
data is being specified so that it knows how to work with that data. We’ll look
at two data type subsets: scalar and compound.
Keep in mind that Rust is a _statically typed_ language, which means that it
must know the types of all variables at compile time. The compiler can usually
infer what type we want to use based on the value and how we use it. In cases
when many types are possible, such as when we converted a `String` to a numeric
type using `parse` in the “Comparing the Guess to the Secret
Number” section in
Chapter 2, we must add a type annotation, like this:
```rust
let guess: u32 = "42".parse().expect("Not a number!");
```
If we don’t add the `: u32` type annotation shown in the preceding code, Rust
will display the following error, which means the compiler needs more
information from us to know which type we want to use:


The Rust Programming Language › Data Types

```console
$ cargo build
   Compiling no_type_annotations v0.1.0 (file:///projects/no_type_annotations)
error[E0284]: type annotations needed
 --> src/main.rs:2:9
  |
2 |     let guess = "42".parse().expect("Not a number!");
  |         ^^^^^        ----- type must be known at this point
  |
  = note: cannot satisfy `<_ as FromStr>::Err == _`
help: consider giving `guess` an explicit type
  |
2 |     let guess: /* Type */ = "42".parse().expect("Not a number!");
  |              ++++++++++++

For more information about this error, try `rustc --explain E0284`.
error: could not compile `no_type_annotations` (bin "no_type_annotations") due to 1 previous error
```
You’ll see different type annotations for other data types.


The Rust Programming Language › Data Types › Scalar Types › Integer Types

A _scalar_ type represents a single value. Rust has four primary scalar types:
integers, floating-point numbers, Booleans, and characters. You may recognize
these from other programming languages. Let’s jump into how they work in Rust.
An _integer_ is a number without a fractional component. We used one integer
type in Chapter 2, the `u32` type. This type declaration indicates that the
value it’s associated with should be an unsigned integer (signed integer types
start with `i` instead of `u`) that takes up 32 bits of space. Table 3-1 shows
the built-in integer types in Rust. We can use any of these variants to declare
the type of an integer value.
Table 3-1: Integer Types in Rust
| Length  | Signed  | Unsigned |
| ------- | ------- | -------- |
| 8-bit   | `i8`    | `u8`     |
| 16-bit  | `i16`   | `u16`    |
| 32-bit  | `i32`   | `u32`    |
| 64-bit  | `i64`   | `u64`    |
| 128-bit | `i128`  | `u128`   |
| Architecture-dependent | `isize` | `usize`  |


The Rust Programming Language › Data Types › Scalar Types › Integer Types

Each variant can be either signed or unsigned and has an explicit size.
_Signed_ and _unsigned_ refer to whether it’s possible for the number to be
negative—in other words, whether the number needs to have a sign with it
(signed) or whether it will only ever be positive and can therefore be
represented without a sign (unsigned). It’s like writing numbers on paper: When
the sign matters, a number is shown with a plus sign or a minus sign; however,
when it’s safe to assume the number is positive, it’s shown with no sign.
Signed numbers are stored using two’s complement
 representation.
Each signed variant can store numbers from −(2n − 1) to 2n −
1 − 1 inclusive, where _n_ is the number of bits that variant uses. So, an
`i8` can store numbers from −(27) to 27 − 1, which equals
−128 to 127. Unsigned variants can store numbers from 0 to 2n − 1,
so a `u8` can store numbers from 0 to 28 − 1, which equals 0 to 255.
Additionally, the `isize` and `usize` types depend on the architecture of the
computer your program is running on: 64 bits if you’re on a 64-bit architecture
and 32 bits if you’re on a 32-bit architecture.


The Rust Programming Language › Data Types › Scalar Types › Integer Types › Integer Overflow

You can write integer literals in any of the forms shown in Table 3-2. Note
that number literals that can be multiple numeric types allow a type suffix,
such as `57u8`, to designate the type. Number literals can also use `_` as a
visual separator to make the number easier to read, such as `1_000`, which will
have the same value as if you had specified `1000`.
Table 3-2: Integer Literals in Rust
| Number literals  | Example       |
| ---------------- | ------------- |
| Decimal          | `98_222`      |
| Hex              | `0xff`        |
| Octal            | `0o77`        |
| Binary           | `0b1111_0000` |
| Byte (`u8` only) | `b'A'`        |
So how do you know which type of integer to use? If you’re unsure, Rust’s
defaults are generally good places to start: Integer types default to `i32`.
The primary situation in which you’d use `isize` or `usize` is when indexing
some sort of collection.
Let’s say you have a variable of type `u8` that can hold values between 0 and
255. If you try to change the variable to a value outside that range, such as
256, _integer overflow_ will occur, which can result in one of two behaviors.
When you’re compiling in debug mode, Rust includes checks for integer overflow
that cause your program to _panic_ at runtime if this behavior occurs. Rust
uses the term _panicking_ when a program exits with an error; we’ll discuss
panics in more depth in the “Unrecoverable Errors with
`panic!`” section in Chapter
9.

Data Types
Scalar Types
Integer Types
Integer Overflow


The Rust Programming Language › Data Types › Scalar Types › Floating-Point Types

When you’re compiling in release mode with the `--release` flag, Rust does
_not_ include checks for integer overflow that cause panics. Instead, if
overflow occurs, Rust performs _two’s complement wrapping_. In short, values
greater than the maximum value the type can hold “wrap around” to the minimum
of the values the type can hold. In the case of a `u8`, the value 256 becomes
0, the value 257 becomes 1, and so on. The program won’t panic, but the
variable will have a value that probably isn’t what you were expecting it to
have. Relying on integer overflow’s wrapping behavior is considered an error.
To explicitly handle the possibility of overflow, you can use these families
of methods provided by the standard library for primitive numeric types:
- Wrap in all compilation modes with the `wrapping_*` methods, such as
  `wrapping_add`.
- Return the `None` value if there is overflow with the `checked_*` methods.
- Return the value and a Boolean indicating whether there was overflow with
  the `overflowing_*` methods.
- Saturate at the value’s minimum or maximum values with the `saturating_*`
  methods.
Rust also has two primitive types for _floating-point numbers_, which are
numbers with decimal points. Rust’s floating-point types are `f32` and `f64`,
which are 32 bits and 64 bits in size, respectively. The default type is `f64`
because on modern CPUs, it’s roughly the same speed as `f32` but is capable of
more precision. All floating-point types are signed.
Here’s an example that shows floating-point numbers in action:
Filename: src/main.rs

Data Types
Scalar Types
Floating-Point Types


The Rust Programming Language › Data Types › Scalar Types › The Character Type

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

    let y: f32 = 3.0; // f32
}
```
Floating-point numbers are represented according to the IEEE-754 standard.
Rust supports the basic mathematical operations you’d expect for all the number
types: addition, subtraction, multiplication, division, and remainder. Integer
division truncates toward zero to the nearest integer. The following code shows
how you’d use each numeric operation in a `let` statement:
Filename: src/main.rs
```rust
fn main() {
    // addition
    let sum = 5 + 10;

    // subtraction
    let difference = 95.5 - 4.3;

    // multiplication
    let product = 4 * 30;

    // division
    let quotient = 56.7 / 32.2;
    let truncated = -5 / 3; // Results in -1

    // remainder
    let remainder = 43 % 5;
}
```
Each expression in these statements uses a mathematical operator and evaluates
to a single value, which is then bound to a variable. Appendix
B contains a list of all operators that Rust
provides.
As in most other programming languages, a Boolean type in Rust has two possible
values: `true` and `false`. Booleans are one byte in size. The Boolean type in
Rust is specified using `bool`. For example:
Filename: src/main.rs
```rust
fn main() {
    let t = true;

    let f: bool = false; // with explicit type annotation
}
```
The main way to use Boolean values is through conditionals, such as an `if`
expression. We’ll cover how `if` expressions work in Rust in the “Control
Flow” section.

Data Types
Scalar Types
The Character Type


The Rust Programming Language › Data Types › Scalar Types › The Character Type

Rust’s `char` type is the language’s most primitive alphabetic type. Here are
some examples of declaring `char` values:
Filename: src/main.rs
```rust
fn main() {
    let c = 'z';
    let z: char = 'ℤ'; // with explicit type annotation
    let heart_eyed_cat = '😻';
}
```
Note that we specify `char` literals with single quotation marks, as opposed to
string literals, which use double quotation marks. Rust’s `char` type is 4
bytes in size and represents a Unicode scalar value, which means it can
represent a lot more than just ASCII. Accented letters; Chinese, Japanese, and
Korean characters; emojis; and zero-width spaces are all valid `char` values in
Rust. Unicode scalar values range from `U+0000` to `U+D7FF` and `U+E000` to
`U+10FFFF` inclusive. However, a “character” isn’t really a concept in Unicode,
so your human intuition for what a “character” is may not match up with what a
`char` is in Rust. We’ll discuss this topic in detail in “Storing UTF-8
Encoded Text with Strings” in Chapter 8.


The Rust Programming Language › Data Types › Compound Types › The Tuple Type

_Compound types_ can group multiple values into one type. Rust has two
primitive compound types: tuples and arrays.
A _tuple_ is a general way of grouping together a number of values with a
variety of types into one compound type. Tuples have a fixed length: Once
declared, they cannot grow or shrink in size.
We create a tuple by writing a comma-separated list of values inside
parentheses. Each position in the tuple has a type, and the types of the
different values in the tuple don’t have to be the same. We’ve added optional
type annotations in this example:
Filename: src/main.rs
```rust
fn main() {
    let tup: (i32, f64, u8) = (500, 6.4, 1);
}
```
The variable `tup` binds to the entire tuple because a tuple is considered a
single compound element. To get the individual values out of a tuple, we can
use pattern matching to destructure a tuple value, like this:
Filename: src/main.rs
```rust
fn main() {
    let tup = (500, 6.4, 1);

    let (x, y, z) = tup;

    println!("The value of y is: {y}");
}
```
This program first creates a tuple and binds it to the variable `tup`. It then
uses a pattern with `let` to take `tup` and turn it into three separate
variables, `x`, `y`, and `z`. This is called _destructuring_ because it breaks
the single tuple into three parts. Finally, the program prints the value of
`y`, which is `6.4`.
We can also access a tuple element directly by using a period (`.`) followed by
the index of the value we want to access. For example:

Data Types
Compound Types
The Tuple Type


The Rust Programming Language › Data Types › Compound Types › The Array Type

Filename: src/main.rs
```rust
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;
}
```
This program creates the tuple `x` and then accesses each element of the tuple
using their respective indices. As with most programming languages, the first
index in a tuple is 0.
The tuple without any values has a special name, _unit_. This value and its
corresponding type are both written `()` and represent an empty value or an
empty return type. Expressions implicitly return the unit value if they don’t
return any other value.
Another way to have a collection of multiple values is with an _array_. Unlike
a tuple, every element of an array must have the same type. Unlike arrays in
some other languages, arrays in Rust have a fixed length.
We write the values in an array as a comma-separated list inside square
brackets:
Filename: src/main.rs
```rust
fn main() {
    let a = [1, 2, 3, 4, 5];
}
```

Data Types
Compound Types
The Array Type


The Rust Programming Language › Data Types › Compound Types › The Array Type

Arrays are useful when you want your data allocated on the stack, the same as
the other types we have seen so far, rather than the heap (we will discuss the
stack and the heap more in Chapter 4) or when
you want to ensure that you always have a fixed number of elements. An array
isn’t as flexible as the vector type, though. A vector is a similar collection
type provided by the standard library that _is_ allowed to grow or shrink in
size because its contents live on the heap. If you’re unsure whether to use an
array or a vector, chances are you should use a vector. Chapter
8 discusses vectors in more detail.
However, arrays are more useful when you know the number of elements will not
need to change. For example, if you were using the names of the month in a
program, you would probably use an array rather than a vector because you know
it will always contain 12 elements:
```rust
let months = ["January", "February", "March", "April", "May", "June", "July",
              "August", "September", "October", "November", "December"];
```
You write an array’s type using square brackets with the type of each element,
a semicolon, and then the number of elements in the array, like so:
```rust
let a: [i32; 5] = [1, 2, 3, 4, 5];
```
Here, `i32` is the type of each element. After the semicolon, the number `5`
indicates the array contains five elements.
You can also initialize an array to contain the same value for each element by
specifying the initial value, followed by a semicolon, and then the length of
the array in square brackets, as shown here:
```rust
let a = [3; 5];
```


The Rust Programming Language › Data Types › Compound Types › Invalid Array Element Access

The array named `a` will contain `5` elements that will all be set to the value
`3` initially. This is the same as writing `let a = [3, 3, 3, 3, 3];` but in a
more concise way.
An array is a single chunk of memory of a known, fixed size that can be
allocated on the stack. You can access elements of an array using indexing,
like this:
Filename: src/main.rs
```rust
fn main() {
    let a = [1, 2, 3, 4, 5];

    let first = a[0];
    let second = a[1];
}
```
In this example, the variable named `first` will get the value `1` because that
is the value at index `[0]` in the array. The variable named `second` will get
the value `2` from index `[1]` in the array.
Let’s see what happens if you try to access an element of an array that is past
the end of the array. Say you run this code, similar to the guessing game in
Chapter 2, to get an array index from the user:
Filename: src/main.rs
```rust,ignore,panics
use std::io;

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

    println!("Please enter an array index.");

    let mut index = String::new();

    io::stdin()
        .read_line(&mut index)
        .expect("Failed to read line");

    let index: usize = index
        .trim()
        .parse()
        .expect("Index entered was not a number");

    let element = a[index];

    println!("The value of the element at index {index} is: {element}");
}
```

Data Types
Compound Types
Invalid Array Element Access


The Rust Programming Language › Data Types › Compound Types › Invalid Array Element Access

This code compiles successfully. If you run this code using `cargo run` and
enter `0`, `1`, `2`, `3`, or `4`, the program will print out the corresponding
value at that index in the array. If you instead enter a number past the end of
the array, such as `10`, you’ll see output like this:
```console
thread 'main' panicked at src/main.rs:19:19:
index out of bounds: the len is 5 but the index is 10
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```
The program resulted in a runtime error at the point of using an invalid
value in the indexing operation. The program exited with an error message and
didn’t execute the final `println!` statement. When you attempt to access an
element using indexing, Rust will check that the index you’ve specified is less
than the array length. If the index is greater than or equal to the length,
Rust will panic. This check has to happen at runtime, especially in this case,
because the compiler can’t possibly know what value a user will enter when they
run the code later.
This is an example of Rust’s memory safety principles in action. In many
low-level languages, this kind of check is not done, and when you provide an
incorrect index, invalid memory can be accessed. Rust protects you against this
kind of error by immediately exiting instead of allowing the memory access and
continuing. Chapter 9 discusses more of Rust’s error handling and how you can
write readable, safe code that neither panics nor allows invalid memory access.