Platform support

The Rust compiler runs on, and compiles to, a great number of platforms, though not all platforms are equally supported. Rust’s support levels are organized into three tiers, each with a different set of guarantees.

Platforms are identified by their “target triple” which is the string to inform the compiler what kind of output should be produced. The columns below indicate whether the corresponding component works on the specified platform.

Installing on Linux or Mac

If we’re on Linux or a Mac, all we need to do is open a terminal and type this:

$ curl -sSf https://static.rust-lang.org/rustup.sh | sh

This will download a script, and start the installation. If it all goes well, you’ll see this appear:

Rust is ready to roll.

From here, press y for ‘yes’, and then follow the rest of the prompts.

Installing on Windows

If you’re on Windows, please download the appropriate installer.

Uninstalling

Uninstalling Rust is as easy as installing it. On Linux or Mac, run the uninstall script:

$ sudo /usr/local/lib/rustlib/uninstall.sh

If we used the Windows installer, we can re-run the .msi and it will give us an uninstall option.

Troubleshooting

If we’ve got Rust installed, we can open up a shell, and type this:

$ rustc --version

You should see the version number, commit hash, and commit date.

If you do, Rust has been installed successfully! Congrats!

If you don’t and you’re on Windows, check that Rust is in your %PATH% system variable. If it isn’t, run the installer again, select “Change” on the “Change, repair, or remove installation” page and ensure “Add to PATH” is installed on the local hard drive.

Rust does not do its own linking, and so you’ll need to have a linker installed. Doing so will depend on your specific system, consult its documentation for more details.

If not, there are a number of places where we can get help. The easiest is the #rust-beginners IRC channel on irc.mozilla.org and for general discussion the #rust IRC channel on irc.mozilla.org, which we can access through Mibbit. Then we’ll be chatting with other Rustaceans (a silly nickname we call ourselves) who can help us out. Other great resources include the user’s forum and Stack Overflow.

This installer also installs a copy of the documentation locally, so we can read it offline. On UNIX systems, /usr/local/share/doc/rust is the location. On Windows, it’s in a share/doc directory, inside the directory to which Rust was installed.

Creating a Project File

First, make a file to put your Rust code in. Rust doesn’t care where your code lives, but for this book, I 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 directory for this particular project:

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

Note: If you’re on Windows and not using PowerShell, the ~ may not work. Consult the documentation for your shell for more details.

Writing and Running a Rust Program

Next, make a new source file and call it main.rs. Rust files always end in a .rs extension. If you’re using more than one word in your filename, use an underscore to separate them; for example, you’d use hello_world.rs rather than helloworld.rs.

Now open the main.rs file you just created, and type the following code:

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

Save the file, and go back to your terminal window. On Linux or OSX, enter the following commands:

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

In Windows, replace main with main.exe. Regardless of your operating system, you should see the string Hello, world! print to the terminal. If you did, then congratulations! You’ve officially written a Rust program. That makes you a Rust programmer! Welcome.

Anatomy of a Rust Program

Now, let’s go over what just happened in your “Hello, world!” program in detail. Here’s the first piece of the puzzle:

fn main() {
  
  }

These lines define a function in Rust. The main function is special: it’s the beginning of every Rust program. The first line says, “I’m declaring a function named main that takes no arguments and returns nothing.” If there were arguments, they would go inside the parentheses (( and )), and because we aren’t returning anything from this function, we can omit the return type entirely.

Also note that the function body is wrapped in curly braces ({ and }). Rust requires these around all function bodies. It’s considered good style to put the opening curly brace on the same line as the function declaration, with one space in between.

Inside the main() function:

    println!("Hello, world!");

This line does all of the work in this little program: it prints text to the screen. There are a number of details that are important here. The first is that it’s indented with four spaces, not tabs.

The second important part is the println!() line. This is calling a Rust [macro], which is how metaprogramming is done in Rust. If it were calling a function instead, it would look like this: println() (without the !). We’ll discuss Rust macros in more detail later, but for now you only need to know that when you see a ! that means that you’re calling a macro instead of a normal function.

Next is "Hello, world!" which is a string. Strings are a surprisingly complicated topic in a systems programming language, and this is a [statically allocated] string. We pass this string as an argument to println!, which prints the string to the screen. Easy enough!

The line ends with a semicolon (;). Rust is an expression-oriented language, which means that most things are expressions, rather than statements. The ; indicates that this expression is over, and the next one is ready to begin. Most lines of Rust code end with a ;.

Compiling and Running Are Separate Steps

In “Writing and Running a Rust Program”, we showed you how to run a newly created program. We’ll break that process down and examine each step now.

Before running a Rust program, you have to compile it. You can use the Rust compiler by entering the rustc command and passing it the name of your source file, like this:

$ rustc main.rs

If you come from a C or C++ background, you’ll notice that this is similar to gcc or clang. After compiling successfully, Rust should output a binary executable, which you can see on Linux or OSX by entering the ls command in your shell as follows:

$ ls
  main  main.rs

On Windows, you’d enter:

$ dir
  main.exe  main.rs

This shows we have two files: the source code, with an .rs extension, and the executable (main.exe on Windows, main everywhere else). All that’s left to do from here is run the main or main.exe file, like this:

$ ./main  # or main.exe on Windows

If main.rs were your “Hello, world!” program, this would print Hello, world! to your terminal.

If you come from a dynamic language like Ruby, Python, or JavaScript, you may not be used to compiling and running a program being separate steps. Rust is an ahead-of-time compiled language, which means that you can compile a program, give it to someone else, and they can run it even without Rust installed. If you give someone a .rb or .py or .js file, on the other hand, they need to have a Ruby, Python, or JavaScript implementation installed (respectively), but you only need one command to both compile and run your program. Everything is a tradeoff in language design.

Just compiling with rustc is fine for simple programs, but as your project grows, you’ll want to be able to manage all of the options your project has, and make it easy to share your code with other people and projects. Next, I’ll introduce you to a tool called Cargo, which will help you write real-world Rust programs.

Converting to Cargo

Let’s convert the Hello World program to Cargo. To Cargo-fy a project, you need to do three things:

1. Put your source file in the right directory.
2. Get rid of the old executable (main.exe on Windows, main everywhere else).
3. Make a Cargo configuration file.

Let’s get started!

$ mkdir src
  $ mv main.rs src/main.rs # or 'move main.rs src/main.rs' on Windows
  $ rm main  # or 'del main.exe' on Windows

[package]
  
  name = "hello_world"
  version = "0.0.1"
  authors = [ "Your name <you@example.com>" ]

Building and Running a Cargo Project

With your Cargo.toml file in place in your project’s root directory, you should be ready to build and run your Hello World program! To do so, enter the following commands:

$ cargo build
     Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world)
  $ ./target/debug/hello_world
  Hello, world!

Bam! If all goes well, Hello, world! should print to the terminal once more.

You just built a project with cargo build and ran it with ./target/debug/hello_world, but you can actually do both in one step with cargo run as follows:

$ cargo run
       Running `target/debug/hello_world`
  Hello, world!

Notice that this example didn’t re-build the project. Cargo figured out that the file hasn’t changed, and so it just ran the binary. If you’d modified your source code, Cargo would have rebuilt the project before running it, and you would have seen something like this:

$ cargo run
     Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world)
       Running `target/debug/hello_world`
  Hello, world!

Cargo checks to see if any of your project’s files have been modified, and only rebuilds your project if they’ve changed since the last time you built it.

With simple projects, Cargo doesn’t bring a whole lot over just using rustc, but it will become useful in the future. This is especially true when you start using crates; these are synonymous with a ‘library’ or ‘package’ in other programming languages. For complex projects composed of multiple crates, it’s much easier to let Cargo coordinate the build. Using Cargo, you can run cargo build, and it should work the right way.

[root]
  name = "hello_world"
  version = "0.0.1"

$ git clone someurl.com/foo
  $ cd foo
  $ cargo build

Making A New Cargo Project the Easy Way

You don’t have to go through that previous process every time you want to start a new project! Cargo can quickly make a bare-bones project directory that you can start developing in right away.

To start a new project with Cargo, enter cargo new at the command line:

$ cargo new hello_world --bin

This command passes --bin because the goal is to get straight to making an executable application, as opposed to a library. Executables are often called binaries (as in /usr/bin, if you’re on a Unix system).

Cargo has generated two files and one directory for us: a Cargo.toml and a src directory with a main.rs file inside. These should look familiar, they’re exactly what we created by hand, above.

This output is all you need to get started. First, open Cargo.toml. It should look something like this:

[package]
  
  name = "hello_world"
  version = "0.1.0"
  authors = ["Your Name <you@example.com>"]
  
  [dependencies]

Do not worry about the [dependencies] line, we will come back to it later.

Cargo has populated Cargo.toml with reasonable defaults based on the arguments you gave it and your git global configuration. You may notice that Cargo has also initialized the hello_world directory as a git repository.

Here’s what should be in src/main.rs:

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

Cargo has generated a “Hello World!” for you, and you’re ready to start coding!

Note: If you want to look at Cargo in more detail, check out the official [Cargo guide], which covers all of its features.

Patterns

In many languages, a variable binding would be called a variable, but Rust’s variable bindings have a few tricks up their sleeves. For example the left-hand side of a let statement is a ‘pattern’, not a variable name. This means we can do things like:

let (x, y) = (1, 2);

After this statement is evaluated, x will be one, and y will be two. Patterns are really powerful, and have their own section in the book. We don’t need those features for now, so we’ll keep this in the back of our minds as we go forward.

Type annotations

Rust is a statically typed language, which means that we specify our types up front, and they’re checked at compile time. So why does our first example compile? Well, Rust has this thing called ‘type inference’. If it can figure out what the type of something is, Rust doesn’t require you to actually type it out.

We can add the type if we want to, though. Types come after a colon (:):

let x: i32 = 5;

If I asked you to read this out loud to the rest of the class, you’d say “x is a binding with the type i32 and the value five.”

In this case we chose to represent x as a 32-bit signed integer. Rust has many different primitive integer types. They begin with i for signed integers and u for unsigned integers. The possible integer sizes are 8, 16, 32, and 64 bits.

In future examples, we may annotate the type in a comment. The examples will look like this:

fn main() {
      let x = 5; // x: i32
  }

Note the similarities between this annotation and the syntax you use with let. Including these kinds of comments is not idiomatic Rust, but we’ll occasionally include them to help you understand what the types that Rust infers are.

Mutability

By default, bindings are immutable. This code will not compile:

let x = 5;
  x = 10;

It will give you this error:

error: re-assignment of immutable variable `x`
       x = 10;
       ^~~~~~~

If you want a binding to be mutable, you can use mut:

let mut x = 5; // mut x: i32
  x = 10;

There is no single reason that bindings are immutable by default, but we can think about it through one of Rust’s primary focuses: safety. If you forget to say mut, the compiler will catch it, and let you know that you have mutated something you may not have intended to mutate. If bindings were mutable by default, the compiler would not be able to tell you this. If you did intend mutation, then the solution is quite easy: add mut.

There are other good reasons to avoid mutable state when possible, but they’re out of the scope of this guide. In general, you can often avoid explicit mutation, and so it is preferable in Rust. That said, sometimes, mutation is what you need, so it’s not verboten.

Initializing bindings

Rust variable bindings have one more aspect that differs from other languages: bindings are required to be initialized with a value before you’re allowed to use them.

Let’s try it out. Change your src/main.rs file to look like this:

fn main() {
      let x: i32;
  
      println!("Hello world!");
  }

You can use cargo build on the command line to build it. You’ll get a warning, but it will still print “Hello, world!”:

   Compiling hello_world v0.0.1 (file:///home/you/projects/hello_world)
  src/main.rs:2:9: 2:10 warning: unused variable: `x`, #[warn(unused_variable)]
     on by default
  src/main.rs:2     let x: i32;
                        ^

Rust warns us that we never use the variable binding, but since we never use it, no harm, no foul. Things change if we try to actually use this x, however. Let’s do that. Change your program to look like this:

fn main() {
      let x: i32;
  
      println!("The value of x is: {}", x);
  }

And try to build it. You’ll get an error:

$ cargo build
     Compiling hello_world v0.0.1 (file:///home/you/projects/hello_world)
  src/main.rs:4:39: 4:40 error: use of possibly uninitialized variable: `x`
  src/main.rs:4     println!("The value of x is: {}", x);
                                                      ^
  note: in expansion of format_args!
  <std macros>:2:23: 2:77 note: expansion site
  <std macros>:1:1: 3:2 note: in expansion of println!
  src/main.rs:4:5: 4:42 note: expansion site
  error: aborting due to previous error
  Could not compile `hello_world`.

Rust will not let us use a value that has not been initialized. Next, let’s talk about this stuff we’ve added to println!.

If you include two curly braces ({}, some call them moustaches…) in your string to print, Rust will interpret this as a request to interpolate some sort of value. String interpolation is a computer science term that means “stick in the middle of a string.” We add a comma, and then x, to indicate that we want x to be the value we’re interpolating. The comma is used to separate arguments we pass to functions and macros, if you’re passing more than one.

When you use the curly braces, Rust will attempt to display the value in a meaningful way by checking out its type. If you want to specify the format in a more detailed manner, there are a wide number of options available. For now, we’ll stick to the default: integers aren’t very complicated to print.

Scope and shadowing

Let’s get back to bindings. Variable bindings have a scope - they are constrained to live in a block they were defined in. A block is a collection of statements enclosed by { and }. Function definitions are also blocks! In the following example we define two variable bindings, x and y, which live in different blocks. x can be accessed from inside the fn main() {} block, while y can be accessed only from inside the inner block:

fn main() {
      let x: i32 = 17;
      {
          let y: i32 = 3;
          println!("The value of x is {} and value of y is {}", x, y);
      }
      println!("The value of x is {} and value of y is {}", x, y); // This won't work
  }

The first println! would print “The value of x is 17 and the value of y is 3”, but this example cannot be compiled successfully, because the second println! cannot access the value of y, since it is not in scope anymore. Instead we get this error:

$ cargo build
     Compiling hello v0.1.0 (file:///home/you/projects/hello_world)
  main.rs:7:62: 7:63 error: unresolved name `y`. Did you mean `x`? [E0425]
  main.rs:7     println!("The value of x is {} and value of y is {}", x, y); // This won
  ↳ 't work
                                                                         ^
  note: in expansion of format_args!
  <std macros>:2:25: 2:56 note: expansion site
  <std macros>:1:1: 2:62 note: in expansion of print!
  <std macros>:3:1: 3:54 note: expansion site
  <std macros>:1:1: 3:58 note: in expansion of println!
  main.rs:7:5: 7:65 note: expansion site
  main.rs:7:62: 7:63 help: run `rustc --explain E0425` to see a detailed explanation
  error: aborting due to previous error
  Could not compile `hello`.
  
  To learn more, run the command again with --verbose.

Additionally, variable bindings can be shadowed. This means that a later variable binding with the same name as another binding, that’s currently in scope, will override the previous binding.

let x: i32 = 8;
  {
      println!("{}", x); // Prints "8"
      let x = 12;
      println!("{}", x); // Prints "12"
  }
  println!("{}", x); // Prints "8"
  let x =  42;
  println!("{}", x); // Prints "42"

Shadowing and mutable bindings may appear as two sides of the same coin, but they are two distinct concepts that can’t always be used interchangeably. For one, shadowing enables us to rebind a name to a value of a different type. It is also possible to change the mutability of a binding.

let mut x: i32 = 1;
  x = 7;
  let x = x; // x is now immutable and is bound to 7
  
  let y = 4;
  let y = "I can also be bound to text!"; // y is now of a different type

Expressions vs. Statements

Rust is primarily an expression-based language. There are only two kinds of statements, and everything else is an expression.

So what’s the difference? Expressions return a value, and statements do not. That’s why we end up with ‘not all control paths return a value’ here: the statement x + 1; doesn’t return a value. There are two kinds of statements in Rust: ‘declaration statements’ and ‘expression statements’. Everything else is an expression. Let’s talk about declaration statements first.

In some languages, variable bindings can be written as expressions, not statements. Like Ruby:

x = y = 5

In Rust, however, using let to introduce a binding is not an expression. The following will produce a compile-time error:

let x = (let y = 5); // expected identifier, found keyword `let`

The compiler is telling us here that it was expecting to see the beginning of an expression, and a let can only begin a statement, not an expression.

Note that assigning to an already-bound variable (e.g. y = 5) is still an expression, although its value is not particularly useful. Unlike other languages where an assignment evaluates to the assigned value (e.g. 5 in the previous example), in Rust the value of an assignment is an empty tuple () because the assigned value can have only one owner, and any other returned value would be too surprising:

let mut y = 5;
  
  let x = (y = 6);  // x has the value `()`, not `6`

The second kind of statement in Rust is the expression statement. Its purpose is to turn any expression into a statement. In practical terms, Rust’s grammar expects statements to follow other statements. This means that you use semicolons to separate expressions from each other. This means that Rust looks a lot like most other languages that require you to use semicolons at the end of every line, and you will see semicolons at the end of almost every line of Rust code you see.

What is this exception that makes us say “almost”? You saw it already, in this code:

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

Our function claims to return an i32, but with a semicolon, it would return () instead. Rust realizes this probably isn’t what we want, and suggests removing the semicolon in the error we saw before.

Early returns

But what about early returns? Rust does have a keyword for that, return:

fn foo(x: i32) -> i32 {
      return x;
  
      // we never run this code!
      x + 1
  }

Using a return as the last line of a function works, but is considered poor style:

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

The previous definition without return may look a bit strange if you haven’t worked in an expression-based language before, but it becomes intuitive over time.

Diverging functions

Rust has some special syntax for ‘diverging functions’, which are functions that do not return:

fn diverges() -> ! {
      panic!("This function never returns!");
  }

panic! is a macro, similar to println!() that we’ve already seen. Unlike println!(), panic!() causes the current thread of execution to crash with the given message. Because this function will cause a crash, it will never return, and so it has the type ‘!’, which is read ‘diverges’.

If you add a main function that calls diverges() and run it, you’ll get some output that looks like this:

thread ‘<main>’ panicked at ‘This function never returns!’, hello.rs:2

If you want more information, you can get a backtrace by setting the RUST_BACKTRACE environment variable:

$ RUST_BACKTRACE=1 ./diverges
  thread '<main>' panicked at 'This function never returns!', hello.rs:2
  stack backtrace:
     1:     0x7f402773a829 - sys::backtrace::write::h0942de78b6c02817K8r
     2:     0x7f402773d7fc - panicking::on_panic::h3f23f9d0b5f4c91bu9w
     3:     0x7f402773960e - rt::unwind::begin_unwind_inner::h2844b8c5e81e79558Bw
     4:     0x7f4027738893 - rt::unwind::begin_unwind::h4375279447423903650
     5:     0x7f4027738809 - diverges::h2266b4c4b850236beaa
     6:     0x7f40277389e5 - main::h19bb1149c2f00ecfBaa
     7:     0x7f402773f514 - rt::unwind::try::try_fn::h13186883479104382231
     8:     0x7f402773d1d8 - __rust_try
     9:     0x7f402773f201 - rt::lang_start::ha172a3ce74bb453aK5w
    10:     0x7f4027738a19 - main
    11:     0x7f402694ab44 - __libc_start_main
    12:     0x7f40277386c8 - <unknown>
    13:                0x0 - <unknown>

If you need to override an already set RUST_BACKTRACE, in cases when you cannot just unset the variable, then set it to 0 to avoid getting a backtrace. Any other value(even no value at all) turns on backtrace.

$ export RUST_BACKTRACE=1
  ...
  $ RUST_BACKTRACE=0 ./diverges 
  thread '<main>' panicked at 'This function never returns!', hello.rs:2
  note: Run with `RUST_BACKTRACE=1` for a backtrace.

RUST_BACKTRACE also works with Cargo’s run command:

$ RUST_BACKTRACE=1 cargo run
       Running `target/debug/diverges`
  thread '<main>' panicked at 'This function never returns!', hello.rs:2
  stack backtrace:
     1:     0x7f402773a829 - sys::backtrace::write::h0942de78b6c02817K8r
     2:     0x7f402773d7fc - panicking::on_panic::h3f23f9d0b5f4c91bu9w
     3:     0x7f402773960e - rt::unwind::begin_unwind_inner::h2844b8c5e81e79558Bw
     4:     0x7f4027738893 - rt::unwind::begin_unwind::h4375279447423903650
     5:     0x7f4027738809 - diverges::h2266b4c4b850236beaa
     6:     0x7f40277389e5 - main::h19bb1149c2f00ecfBaa
     7:     0x7f402773f514 - rt::unwind::try::try_fn::h13186883479104382231
     8:     0x7f402773d1d8 - __rust_try
     9:     0x7f402773f201 - rt::lang_start::ha172a3ce74bb453aK5w
    10:     0x7f4027738a19 - main
    11:     0x7f402694ab44 - __libc_start_main
    12:     0x7f40277386c8 - <unknown>
    13:                0x0 - <unknown>

A diverging function can be used as any type:

let x: i32 = diverges();
  let x: String = diverges();

Function pointers

We can also create variable bindings which point to functions:

let f: fn(i32) -> i32;

f is a variable binding which points to a function that takes an i32 as an argument and returns an i32. For example:

fn plus_one(i: i32) -> i32 {
      i + 1
  }
  
  // without type inference
  let f: fn(i32) -> i32 = plus_one;
  
  // with type inference
  let f = plus_one;

We can then use f to call the function:

let six = f(5);

Booleans

Rust has a built-in boolean type, named bool. It has two values, true and false:

let x = true;
  
  let y: bool = false;

A common use of booleans is in if conditionals.

You can find more documentation for bools in the standard library documentation.

char

The char type represents a single Unicode scalar value. You can create chars with a single tick: (')

let x = 'x';
  let two_hearts = '💕';

Unlike some other languages, this means that Rust’s char is not a single byte, but four.

You can find more documentation for chars in the standard library documentation.

Numeric types

Rust has a variety of numeric types in a few categories: signed and unsigned, fixed and variable, floating-point and integer.

These types consist of two parts: the category, and the size. For example, u16 is an unsigned type with sixteen bits of size. More bits lets you have bigger numbers.

If a number literal has nothing to cause its type to be inferred, it defaults:

let x = 42; // x has type i32
  
  let y = 1.0; // y has type f64

Here’s a list of the different numeric types, with links to their documentation in the standard library:

• i8
• i16
• i32
• i64
• u8
• u16
• u32
• u64
• isize
• usize
• f32
• f64

Let’s go over them by category:

Arrays

Like many programming languages, Rust has list types to represent a sequence of things. The most basic is the array, a fixed-size list of elements of the same type. By default, arrays are immutable.

let a = [1, 2, 3]; // a: [i32; 3]
  let mut m = [1, 2, 3]; // m: [i32; 3]

Arrays have type [T; N]. We’ll talk about this T notation in the generics section. The N is a compile-time constant, for the length of the array.

There’s a shorthand for initializing each element of an array to the same value. In this example, each element of a will be initialized to 0:

let a = [0; 20]; // a: [i32; 20]

You can get the number of elements in an array a with a.len():

let a = [1, 2, 3];
  
  println!("a has {} elements", a.len());

You can access a particular element of an array with subscript notation:

let names = ["Graydon", "Brian", "Niko"]; // names: [&str; 3]
  
  println!("The second name is: {}", names[1]);

Subscripts start at zero, like in most programming languages, so the first name is names[0] and the second name is names[1]. The above example prints The second name is: Brian. If you try to use a subscript that is not in the array, you will get an error: array access is bounds-checked at run-time. Such errant access is the source of many bugs in other systems programming languages.

You can find more documentation for arrays in the standard library documentation.

Slices

A ‘slice’ is a reference to (or “view” into) another data structure. They are useful for allowing safe, efficient access to a portion of an array without copying. For example, you might want to reference only one line of a file read into memory. By nature, a slice is not created directly, but from an existing variable binding. Slices have a defined length, can be mutable or immutable.

Internally, slices are represented as a pointer to the beginning of the data and a length.

let a = [0, 1, 2, 3, 4];
  let complete = &a[..]; // A slice containing all of the elements in a
  let middle = &a[1..4]; // A slice of a: only the elements 1, 2, and 3

str

Rust’s str type is the most primitive string type. As an unsized type, it’s not very useful by itself, but becomes useful when placed behind a reference, like &str. We’ll elaborate further when we cover Strings and [references].

You can find more documentation for str in the standard library documentation.

Tuples

A tuple is an ordered list of fixed size. Like this:

let x = (1, "hello");

The parentheses and commas form this two-length tuple. Here’s the same code, but with the type annotated:

let x: (i32, &str) = (1, "hello");

As you can see, the type of a tuple looks like the tuple, but with each position having a type name rather than the value. Careful readers will also note that tuples are heterogeneous: we have an i32 and a &str in this tuple. In systems programming languages, strings are a bit more complex than in other languages. For now, read &str as a string slice, and we’ll learn more soon.

You can assign one tuple into another, if they have the same contained types and arity. Tuples have the same arity when they have the same length.

let mut x = (1, 2); // x: (i32, i32)
  let y = (2, 3); // y: (i32, i32)
  
  x = y;

You can access the fields in a tuple through a destructuring let. Here’s an example:

let (x, y, z) = (1, 2, 3);
  
  println!("x is {}", x);

Remember before when I said the left-hand side of a let statement was more powerful than assigning a binding? Here we are. We can put a pattern on the left-hand side of the let, and if it matches up to the right-hand side, we can assign multiple bindings at once. In this case, let “destructures” or “breaks up” the tuple, and assigns the bits to three bindings.

This pattern is very powerful, and we’ll see it repeated more later.

You can disambiguate a single-element tuple from a value in parentheses with a comma:

(0,); // single-element tuple
  (0); // zero in parentheses

let tuple = (1, 2, 3);
  
  let x = tuple.0;
  let y = tuple.1;
  let z = tuple.2;
  
  println!("x is {}", x);

Functions

Functions also have a type! They look like this:

fn foo(x: i32) -> i32 { x }
  
  let x: fn(i32) -> i32 = foo;

In this case, x is a ‘function pointer’ to a function that takes an i32 and returns an i32.

loop

The infinite loop is the simplest form of loop available in Rust. Using the keyword loop, Rust provides a way to loop indefinitely until some terminating statement is reached. Rust’s infinite loops look like this:

loop {
      println!("Loop forever!");
  }

while

Rust also has a while loop. It looks like this:

let mut x = 5; // mut x: i32
  let mut done = false; // mut done: bool
  
  while !done {
      x += x - 3;
  
      println!("{}", x);
  
      if x % 5 == 0 {
          done = true;
      }
  }

while loops are the correct choice when you’re not sure how many times you need to loop.

If you need an infinite loop, you may be tempted to write this:

while true {

However, loop is far better suited to handle this case:

loop {

Rust’s control-flow analysis treats this construct differently than a while true, since we know that it will always loop. In general, the more information we can give to the compiler, the better it can do with safety and code generation, so you should always prefer loop when you plan to loop infinitely.

for

The for loop is used to loop a particular number of times. Rust’s for loops work a bit differently than in other systems languages, however. Rust’s for loop doesn’t look like this “C-style” for loop:

for (x = 0; x < 10; x++) {
      printf( "%d\n", x );
  }

Instead, it looks like this:

for x in 0..10 {
      println!("{}", x); // x: i32
  }

In slightly more abstract terms,

for var in expression {
      code
  }

The expression is an item that can be converted into an [iterator] using [IntoIterator]. The iterator gives back a series of elements. Each element is one iteration of the loop. That value is then bound to the name var, which is valid for the loop body. Once the body is over, the next value is fetched from the iterator, and we loop another time. When there are no more values, the for loop is over.

In our example, 0..10 is an expression that takes a start and an end position, and gives an iterator over those values. The upper bound is exclusive, though, so our loop will print 0 through 9, not 10.

Rust does not have the “C-style” for loop on purpose. Manually controlling each element of the loop is complicated and error prone, even for experienced C developers.

for (i,j) in (5..10).enumerate() {
      println!("i = {} and j = {}", i, j);
  }

i = 0 and j = 5
  i = 1 and j = 6
  i = 2 and j = 7
  i = 3 and j = 8
  i = 4 and j = 9

let lines = "hello\nworld".lines();
  
  for (linenumber, line) in lines.enumerate() {
      println!("{}: {}", linenumber, line);
  }

0: hello
  1: world

Ending iteration early

Let’s take a look at that while loop we had earlier:

let mut x = 5;
  let mut done = false;
  
  while !done {
      x += x - 3;
  
      println!("{}", x);
  
      if x % 5 == 0 {
          done = true;
      }
  }

We had to keep a dedicated mut boolean variable binding, done, to know when we should exit out of the loop. Rust has two keywords to help us with modifying iteration: break and continue.

In this case, we can write the loop in a better way with break:

let mut x = 5;
  
  loop {
      x += x - 3;
  
      println!("{}", x);
  
      if x % 5 == 0 { break; }
  }

We now loop forever with loop and use break to break out early. Issuing an explicit return statement will also serve to terminate the loop early.

continue is similar, but instead of ending the loop, goes to the next iteration. This will only print the odd numbers:

for x in 0..10 {
      if x % 2 == 0 { continue; }
  
      println!("{}", x);
  }

Loop labels

You may also encounter situations where you have nested loops and need to specify which one your break or continue statement is for. Like most other languages, by default a break or continue will apply to innermost loop. In a situation where you would like to break or continue for one of the outer loops, you can use labels to specify which loop the break or continue statement applies to. This will only print when both x and y are odd:

'outer: for x in 0..10 {
      'inner: for y in 0..10 {
          if x % 2 == 0 { continue 'outer; } // continues the loop over x
          if y % 2 == 0 { continue 'inner; } // continues the loop over y
          println!("x: {}, y: {}", x, y);
      }
  }

Accessing elements

To get the value at a particular index in the vector, we use []s:

let v = vec![1, 2, 3, 4, 5];
  
  println!("The third element of v is {}", v[2]);

The indices count from 0, so the third element is v[2].

It’s also important to note that you must index with the usize type:

let v = vec![1, 2, 3, 4, 5];
  
  let i: usize = 0;
  let j: i32 = 0;
  
  // works
  v[i];
  
  // doesn’t
  v[j];

Indexing with a non-usize type gives an error that looks like this:

error: the trait bound `collections::vec::Vec<_> : core::ops::Index<i32>`
  is not satisfied [E0277]
  v[j];
  ^~~~
  note: the type `collections::vec::Vec<_>` cannot be indexed by `i32`
  error: aborting due to previous error

There’s a lot of punctuation in that message, but the core of it makes sense: you cannot index with an i32.

Out-of-bounds Access

If you try to access an index that doesn’t exist:

let v = vec![1, 2, 3];
  println!("Item 7 is {}", v[7]);

then the current thread will [panic] with a message like this:

thread '<main>' panicked at 'index out of bounds: the len is 3 but the index is 7'

If you want to handle out-of-bounds errors without panicking, you can use methods like get or get_mut that return None when given an invalid index:

let v = vec![1, 2, 3];
  match v.get(7) {
      Some(x) => println!("Item 7 is {}", x),
      None => println!("Sorry, this vector is too short.")
  }

Iterating

Once you have a vector, you can iterate through its elements with for. There are three versions:

let mut v = vec![1, 2, 3, 4, 5];
  
  for i in &v {
      println!("A reference to {}", i);
  }
  
  for i in &mut v {
      println!("A mutable reference to {}", i);
  }
  
  for i in v {
      println!("Take ownership of the vector and its element {}", i);
  }

Note: You cannot use the vector again once you have iterated by taking ownership of the vector. You can iterate the vector multiple times by taking a reference to the vector whilst iterating. For example, the following code does not compile.

let v = vec![1, 2, 3, 4, 5];
  
  for i in v {
      println!("Take ownership of the vector and its element {}", i);
  }
  
  for i in v {
      println!("Take ownership of the vector and its element {}", i);
  }

Whereas the following works perfectly,

let v = vec![1, 2, 3, 4, 5];
  
  for i in &v {
      println!("This is a reference to {}", i);
  }
  
  for i in &v {
      println!("This is a reference to {}", i);
  }

Vectors have many more useful methods, which you can read about in their API documentation.

Meta

Before we get to the details, two important notes about the ownership system.

Rust has a focus on safety and speed. It accomplishes these goals through many ‘zero-cost abstractions’, which means that in Rust, abstractions cost as little as possible in order to make them work. The ownership system is a prime example of a zero-cost abstraction. All of the analysis we’ll talk about in this guide is done at compile time. You do not pay any run-time cost for any of these features.

However, this system does have a certain cost: learning curve. Many new users to Rust experience something we like to call ‘fighting with the borrow checker’, where the Rust compiler refuses to compile a program that the author thinks is valid. This often happens because the programmer’s mental model of how ownership should work doesn’t match the actual rules that Rust implements. You probably will experience similar things at first. There is good news, however: more experienced Rust developers report that once they work with the rules of the ownership system for a period of time, they fight the borrow checker less and less.

With that in mind, let’s learn about ownership.

Ownership

Variable bindings have a property in Rust: they ‘have ownership’ of what they’re bound to. This means that when a binding goes out of scope, Rust will free the bound resources. For example:

fn foo() {
      let v = vec![1, 2, 3];
  }

When v comes into scope, a new vector is created on the stack, and it allocates space on the heap for its elements. When v goes out of scope at the end of foo(), Rust will clean up everything related to the vector, even the heap-allocated memory. This happens deterministically, at the end of the scope.

We’ll cover vectors in detail later in this chapter; we only use them here as an example of a type that allocates space on the heap at runtime. They behave like arrays, except their size may change by push()ing more elements onto them.

Vectors have a generic type Vec<T>, so in this example v will have type Vec<i32>. We’ll cover generics in detail later in this chapter.

Move semantics

There’s some more subtlety here, though: Rust ensures that there is exactly one binding to any given resource. For example, if we have a vector, we can assign it to another binding:

let v = vec![1, 2, 3];
  
  let v2 = v;

But, if we try to use v afterwards, we get an error:

let v = vec![1, 2, 3];
  
  let v2 = v;
  
  println!("v[0] is: {}", v[0]);

It looks like this:

error: use of moved value: `v`
  println!("v[0] is: {}", v[0]);
                          ^

A similar thing happens if we define a function which takes ownership, and try to use something after we’ve passed it as an argument:

fn take(v: Vec<i32>) {
      // what happens here isn’t important.
  }
  
  let v = vec![1, 2, 3];
  
  take(v);
  
  println!("v[0] is: {}", v[0]);

Same error: ‘use of moved value’. When we transfer ownership to something else, we say that we’ve ‘moved’ the thing we refer to. You don’t need some sort of special annotation here, it’s the default thing that Rust does.

let x = 10;

let v = vec![1, 2, 3];
  
  let mut v2 = v;

v2.truncate(2);

let v = 1;
  
  let v2 = v;
  
  println!("v is: {}", v);

fn main() {
      let a = 5;
  
      let _y = double(a);
      println!("{}", a);
  }
  
  fn double(x: i32) -> i32 {
      x * 2
  }

fn main() {
      let a = true;
  
      let _y = change_truth(a);
      println!("{}", a);
  }
  
  fn change_truth(x: bool) -> bool {
      !x
  }

error: use of moved value: `a`
  println!("{}", a);
                 ^

More than ownership

Of course, if we had to hand ownership back with every function we wrote:

fn foo(v: Vec<i32>) -> Vec<i32> {
      // do stuff with v
  
      // hand back ownership
      v
  }

This would get very tedious. It gets worse the more things we want to take ownership of:

fn foo(v1: Vec<i32>, v2: Vec<i32>) -> (Vec<i32>, Vec<i32>, i32) {
      // do stuff with v1 and v2
  
      // hand back ownership, and the result of our function
      (v1, v2, 42)
  }
  
  let v1 = vec![1, 2, 3];
  let v2 = vec![1, 2, 3];
  
  let (v1, v2, answer) = foo(v1, v2);

Ugh! The return type, return line, and calling the function gets way more complicated.

Luckily, Rust offers a feature, borrowing, which helps us solve this problem. It’s the topic of the next section!

Meta

Before we get to the details, two important notes about the ownership system.

Rust has a focus on safety and speed. It accomplishes these goals through many ‘zero-cost abstractions’, which means that in Rust, abstractions cost as little as possible in order to make them work. The ownership system is a prime example of a zero-cost abstraction. All of the analysis we’ll talk about in this guide is done at compile time. You do not pay any run-time cost for any of these features.

However, this system does have a certain cost: learning curve. Many new users to Rust experience something we like to call ‘fighting with the borrow checker’, where the Rust compiler refuses to compile a program that the author thinks is valid. This often happens because the programmer’s mental model of how ownership should work doesn’t match the actual rules that Rust implements. You probably will experience similar things at first. There is good news, however: more experienced Rust developers report that once they work with the rules of the ownership system for a period of time, they fight the borrow checker less and less.

With that in mind, let’s learn about borrowing.

Borrowing

At the end of the ownership section, we had a nasty function that looked like this:

fn foo(v1: Vec<i32>, v2: Vec<i32>) -> (Vec<i32>, Vec<i32>, i32) {
      // do stuff with v1 and v2
  
      // hand back ownership, and the result of our function
      (v1, v2, 42)
  }
  
  let v1 = vec![1, 2, 3];
  let v2 = vec![1, 2, 3];
  
  let (v1, v2, answer) = foo(v1, v2);

This is not idiomatic Rust, however, as it doesn’t take advantage of borrowing. Here’s the first step:

fn foo(v1: &Vec<i32>, v2: &Vec<i32>) -> i32 {
      // do stuff with v1 and v2
  
      // return the answer
      42
  }
  
  let v1 = vec![1, 2, 3];
  let v2 = vec![1, 2, 3];
  
  let answer = foo(&v1, &v2);
  
  // we can use v1 and v2 here!

A more concrete example:

fn main() {
      // Don't worry if you don't understand how `fold` works, the point here is that an
  ↳  immutable reference is borrowed.
      fn sum_vec(v: &Vec<i32>) -> i32 {
          return v.iter().fold(0, |a, &b| a + b);
      }
      // Borrow two vectors and and sum them.
      // This kind of borrowing does not allow mutation to the borrowed.
      fn foo(v1: &Vec<i32>, v2: &Vec<i32>) -> i32 {
          // do stuff with v1 and v2
          let s1 = sum_vec(v1);
          let s2 = sum_vec(v2);
          // return the answer
          s1 + s2
      }
  
      let v1 = vec![1, 2, 3];
      let v2 = vec![4, 5, 6];
  
      let answer = foo(&v1, &v2);
      println!("{}", answer);
  }

Instead of taking Vec<i32>s as our arguments, we take a reference: &Vec<i32>. And instead of passing v1 and v2 directly, we pass &v1 and &v2. We call the &T type a ‘reference’, and rather than owning the resource, it borrows ownership. A binding that borrows something does not deallocate the resource when it goes out of scope. This means that after the call to foo(), we can use our original bindings again.

References are immutable, like bindings. This means that inside of foo(), the vectors can’t be changed at all:

fn foo(v: &Vec<i32>) {
       v.push(5);
  }
  
  let v = vec![];
  
  foo(&v);

errors with:

error: cannot borrow immutable borrowed content `*v` as mutable
  v.push(5);
  ^

Pushing a value mutates the vector, and so we aren’t allowed to do it.

&mut references

There’s a second kind of reference: &mut T. A ‘mutable reference’ allows you to mutate the resource you’re borrowing. For example:

let mut x = 5;
  {
      let y = &mut x;
      *y += 1;
  }
  println!("{}", x);

This will print 6. We make y a mutable reference to x, then add one to the thing y points at. You’ll notice that x had to be marked mut as well. If it wasn’t, we couldn’t take a mutable borrow to an immutable value.

You’ll also notice we added an asterisk (*) in front of y, making it *y, this is because y is a &mut reference. You’ll also need to use them for accessing the contents of a reference as well.

Otherwise, &mut references are like references. There is a large difference between the two, and how they interact, though. You can tell something is fishy in the above example, because we need that extra scope, with the { and }. If we remove them, we get an error:

error: cannot borrow `x` as immutable because it is also borrowed as mutable
      println!("{}", x);
                     ^
  note: previous borrow of `x` occurs here; the mutable borrow prevents
  subsequent moves, borrows, or modification of `x` until the borrow ends
          let y = &mut x;
                       ^
  note: previous borrow ends here
  fn main() {
  
  }
  ^

As it turns out, there are rules.

The Rules

Here’s the rules about borrowing in Rust:

First, any borrow must last for a scope no greater than that of the owner. Second, you may have one or the other of these two kinds of borrows, but not both at the same time:

• one or more references (&T) to a resource,
• exactly one mutable reference (&mut T).

You may notice that this is very similar to, though not exactly the same as, the definition of a data race:

There is a ‘data race’ when two or more pointers access the same memory location at the same time, where at least one of them is writing, and the operations are not synchronized.

With references, you may have as many as you’d like, since none of them are writing. However, as we can only have one &mut at a time, it is impossible to have a data race. This is how Rust prevents data races at compile time: we’ll get errors if we break the rules.

With this in mind, let’s consider our example again.

let mut x = 5;
  let y = &mut x;
  
  *y += 1;
  
  println!("{}", x);

error: cannot borrow `x` as immutable because it is also borrowed as mutable
      println!("{}", x);
                     ^

note: previous borrow ends here
  fn main() {
  
  }
  ^

let mut x = 5;
  
  let y = &mut x;    // -+ &mut borrow of x starts here
                     //  |
  *y += 1;           //  |
                     //  |
  println!("{}", x); // -+ - try to borrow x here
                     // -+ &mut borrow of x ends here

let mut x = 5;
  
  {
      let y = &mut x; // -+ &mut borrow starts here
      *y += 1;        //  |
  }                   // -+ ... and ends here
  
  println!("{}", x);  // <- try to borrow x here

let mut v = vec![1, 2, 3];
  
  for i in &v {
      println!("{}", i);
  }

let mut v = vec![1, 2, 3];
  
  for i in &v {
      println!("{}", i);
      v.push(34);
  }

error: cannot borrow `v` as mutable because it is also borrowed as immutable
      v.push(34);
      ^
  note: previous borrow of `v` occurs here; the immutable borrow prevents
  subsequent moves or mutable borrows of `v` until the borrow ends
  for i in &v {
            ^
  note: previous borrow ends here
  for i in &v {
      println!(“{}”, i);
      v.push(34);
  }
  ^

let y: &i32;
  {
      let x = 5;
      y = &x;
  }
  
  println!("{}", y);

error: `x` does not live long enough
      y = &x;
           ^
  note: reference must be valid for the block suffix following statement 0 at
  2:16...
  let y: &i32;
  {
      let x = 5;
      y = &x;
  }
  
  note: ...but borrowed value is only valid for the block suffix following
  statement 0 at 4:18
      let x = 5;
      y = &x;
  }

let y: &i32;
  let x = 5;
  y = &x;
  
  println!("{}", y);

error: `x` does not live long enough
  y = &x;
       ^
  note: reference must be valid for the block suffix following statement 0 at
  2:16...
      let y: &i32;
      let x = 5;
      y = &x;
  
      println!("{}", y);
  }
  
  note: ...but borrowed value is only valid for the block suffix following
  statement 1 at 3:14
      let x = 5;
      y = &x;
  
      println!("{}", y);
  }

Meta

Before we get to the details, two important notes about the ownership system.

Rust has a focus on safety and speed. It accomplishes these goals through many ‘zero-cost abstractions’, which means that in Rust, abstractions cost as little as possible in order to make them work. The ownership system is a prime example of a zero-cost abstraction. All of the analysis we’ll talk about in this guide is done at compile time. You do not pay any run-time cost for any of these features.

However, this system does have a certain cost: learning curve. Many new users to Rust experience something we like to call ‘fighting with the borrow checker’, where the Rust compiler refuses to compile a program that the author thinks is valid. This often happens because the programmer’s mental model of how ownership should work doesn’t match the actual rules that Rust implements. You probably will experience similar things at first. There is good news, however: more experienced Rust developers report that once they work with the rules of the ownership system for a period of time, they fight the borrow checker less and less.

With that in mind, let’s learn about lifetimes.

Lifetimes

Lending out a reference to a resource that someone else owns can be complicated. For example, imagine this set of operations:

1. I acquire a handle to some kind of resource.
2. I lend you a reference to the resource.
3. I decide I’m done with the resource, and deallocate it, while you still have your reference.
4. You decide to use the resource.

Uh oh! Your reference is pointing to an invalid resource. This is called a dangling pointer or ‘use after free’, when the resource is memory.

To fix this, we have to make sure that step four never happens after step three. The ownership system in Rust does this through a concept called lifetimes, which describe the scope that a reference is valid for.

When we have a function that takes an argument by reference, we can be implicit or explicit about the lifetime of the reference:

// implicit
  fn foo(x: &i32) {
  }
  
  // explicit
  fn bar<'a>(x: &'a i32) {
  }

The 'a reads ‘the lifetime a’. Technically, every reference has some lifetime associated with it, but the compiler lets you elide (i.e. omit, see “Lifetime Elision” below) them in common cases. Before we get to that, though, let’s break the explicit example down:

fn bar<'a>(...)

We previously talked a little about function syntax, but we didn’t discuss the <>s after a function’s name. A function can have ‘generic parameters’ between the <>s, of which lifetimes are one kind. We’ll discuss other kinds of generics later in the book, but for now, let’s focus on the lifetimes aspect.

We use <> to declare our lifetimes. This says that bar has one lifetime, 'a. If we had two reference parameters, it would look like this:

fn bar<'a, 'b>(...)

Then in our parameter list, we use the lifetimes we’ve named:

...(x: &'a i32)

If we wanted a &mut reference, we’d do this:

...(x: &'a mut i32)

If you compare &mut i32 to &'a mut i32, they’re the same, it’s that the lifetime 'a has snuck in between the & and the mut i32. We read &mut i32 as ‘a mutable reference to an i32’ and &'a mut i32 as ‘a mutable reference to an i32 with the lifetime 'a’.

In structs

You’ll also need explicit lifetimes when working with structs that contain references:

struct Foo<'a> {
      x: &'a i32,
  }
  
  fn main() {
      let y = &5; // this is the same as `let _y = 5; let y = &_y;`
      let f = Foo { x: y };
  
      println!("{}", f.x);
  }

As you can see, structs can also have lifetimes. In a similar way to functions,

struct Foo<'a> {

declares a lifetime, and

x: &'a i32,

uses it. So why do we need a lifetime here? We need to ensure that any reference to a Foo cannot outlive the reference to an i32 it contains.

struct Foo<'a> {
      x: &'a i32,
  }
  
  impl<'a> Foo<'a> {
      fn x(&self) -> &'a i32 { self.x }
  }
  
  fn main() {
      let y = &5; // this is the same as `let _y = 5; let y = &_y;`
      let f = Foo { x: y };
  
      println!("x is: {}", f.x());
  }

fn x_or_y<'a>(x: &'a str, y: &'a str) -> &'a str {

fn x_or_y<'a, 'b>(x: &'a str, y: &'b str) -> &'a str {

fn main() {
      let y = &5;     // -+ y goes into scope
                      //  |
      // stuff        //  |
                      //  |
  }                   // -+ y goes out of scope

struct Foo<'a> {
      x: &'a i32,
  }
  
  fn main() {
      let y = &5;           // -+ y goes into scope
      let f = Foo { x: y }; // -+ f goes into scope
      // stuff              //  |
                            //  |
  }                         // -+ f and y go out of scope

struct Foo<'a> {
      x: &'a i32,
  }
  
  fn main() {
      let x;                    // -+ x goes into scope
                                //  |
      {                         //  |
          let y = &5;           // ---+ y goes into scope
          let f = Foo { x: y }; // ---+ f goes into scope
          x = &f.x;             //  | | error here
      }                         // ---+ f and y go out of scope
                                //  |
      println!("{}", x);        //  |
  }                             // -+ x goes out of scope

let x: &'static str = "Hello, world.";

static FOO: i32 = 5;
  let x: &'static i32 = &FOO;

fn foo<'a>(bar: &'a str)

fn foo<'a>() -> &'a str

fn foo<'a>(bar: &'a str) -> &'a str

fn print(s: &str); // elided
  fn print<'a>(s: &'a str); // expanded
  
  fn debug(lvl: u32, s: &str); // elided
  fn debug<'a>(lvl: u32, s: &'a str); // expanded
  
  // In the preceding example, `lvl` doesn’t need a lifetime because it’s not a
  // reference (`&`). Only things relating to references (such as a `struct`
  // which contains a reference) need lifetimes.
  
  fn substr(s: &str, until: u32) -> &str; // elided
  fn substr<'a>(s: &'a str, until: u32) -> &'a str; // expanded
  
  fn get_str() -> &str; // ILLEGAL, no inputs
  
  fn frob(s: &str, t: &str) -> &str; // ILLEGAL, two inputs
  fn frob<'a, 'b>(s: &'a str, t: &'b str) -> &str; // Expanded: Output lifetime is ambig
  ↳ uous
  
  fn get_mut(&mut self) -> &mut T; // elided
  fn get_mut<'a>(&'a mut self) -> &'a mut T; // expanded
  
  fn args<T: ToCStr>(&mut self, args: &[T]) -> &mut Command; // elided
  fn args<'a, 'b, T: ToCStr>(&'a mut self, args: &'b [T]) -> &'a mut Command; // expande
  ↳ d
  
  fn new(buf: &mut [u8]) -> BufWriter; // elided
  fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a>; // expanded

Interior vs. Exterior Mutability

However, when we say something is ‘immutable’ in Rust, that doesn’t mean that it’s not able to be changed: we mean something has ‘exterior mutability’. Consider, for example, Arc<T>:

use std::sync::Arc;
  
  let x = Arc::new(5);
  let y = x.clone();

When we call clone(), the Arc<T> needs to update the reference count. Yet we’ve not used any muts here, x is an immutable binding, and we didn’t take &mut 5 or anything. So what gives?

To understand this, we have to go back to the core of Rust’s guiding philosophy, memory safety, and the mechanism by which Rust guarantees it, the ownership system, and more specifically, borrowing:

You may have one or the other of these two kinds of borrows, but not both at the same time:

• one or more references (&T) to a resource,
• exactly one mutable reference (&mut T).

So, that’s the real definition of ‘immutability’: is this safe to have two pointers to? In Arc<T>’s case, yes: the mutation is entirely contained inside the structure itself. It’s not user facing. For this reason, it hands out &T with clone(). If it handed out &mut Ts, though, that would be a problem.

Other types, like the ones in the std::cell module, have the opposite: interior mutability. For example:

use std::cell::RefCell;
  
  let x = RefCell::new(42);
  
  let y = x.borrow_mut();

RefCell hands out &mut references to what’s inside of it with the borrow_mut() method. Isn’t that dangerous? What if we do:

use std::cell::RefCell;
  
  let x = RefCell::new(42);
  
  let y = x.borrow_mut();
  let z = x.borrow_mut();

This will in fact panic, at runtime. This is what RefCell does: it enforces Rust’s borrowing rules at runtime, and panic!s if they’re violated. This allows us to get around another aspect of Rust’s mutability rules. Let’s talk about it first.

struct Point {
      x: i32,
      mut y: i32, // nope
  }

struct Point {
      x: i32,
      y: i32,
  }
  
  let mut a = Point { x: 5, y: 6 };
  
  a.x = 10;
  
  let b = Point { x: 5, y: 6};
  
  b.x = 10; // error: cannot assign to immutable field `b.x`

use std::cell::Cell;
  
  struct Point {
      x: i32,
      y: Cell<i32>,
  }
  
  let point = Point { x: 5, y: Cell::new(6) };
  
  point.y.set(7);
  
  println!("y: {:?}", point.y);

Update syntax

A struct can include .. to indicate that you want to use a copy of some other struct for some of the values. For example:

struct Point3d {
      x: i32,
      y: i32,
      z: i32,
  }
  
  let mut point = Point3d { x: 0, y: 0, z: 0 };
  point = Point3d { y: 1, .. point };

This gives point a new y, but keeps the old x and z values. It doesn’t have to be the same struct either, you can use this syntax when making new ones, and it will copy the values you don’t specify:

let origin = Point3d { x: 0, y: 0, z: 0 };
  let point = Point3d { z: 1, x: 2, .. origin };

Tuple structs

Rust has another data type that’s like a hybrid between a tuple and a struct, called a ‘tuple struct’. Tuple structs have a name, but their fields don’t. They are declared with the struct keyword, and then with a name followed by a tuple:

struct Color(i32, i32, i32);
  struct Point(i32, i32, i32);
  
  let black = Color(0, 0, 0);
  let origin = Point(0, 0, 0);

Here, black and origin are not equal, even though they contain the same values.

It is almost always better to use a struct than a tuple struct. We would write Color and Point like this instead:

struct Color {
      red: i32,
      blue: i32,
      green: i32,
  }
  
  struct Point {
      x: i32,
      y: i32,
      z: i32,
  }

Good names are important, and while values in a tuple struct can be referenced with dot notation as well, a struct gives us actual names, rather than positions.

There is one case when a tuple struct is very useful, though, and that is when it has only one element. We call this the ‘newtype’ pattern, because it allows you to create a new type that is distinct from its contained value and also expresses its own semantic meaning:

struct Inches(i32);
  
  let length = Inches(10);
  
  let Inches(integer_length) = length;
  println!("length is {} inches", integer_length);

As you can see here, you can extract the inner integer type through a destructuring let, as with regular tuples. In this case, the let Inches(integer_length) assigns 10 to integer_length.

Unit-like structs

You can define a struct with no members at all:

struct Electron;
  
  let x = Electron;

Such a struct is called ‘unit-like’ because it resembles the empty tuple, (), sometimes called ‘unit’. Like a tuple struct, it defines a new type.

This is rarely useful on its own (although sometimes it can serve as a marker type), but in combination with other features, it can become useful. For instance, a library may ask you to create a structure that implements a certain trait to handle events. If you don’t have any data you need to store in the structure, you can create a unit-like struct.

Constructors as functions

An enum constructor can also be used like a function. For example:

let m = Message::Write("Hello, world".to_string());

is the same as

fn foo(x: String) -> Message {
      Message::Write(x)
  }
  
  let x = foo("Hello, world".to_string());

This is not immediately useful to us, but when we get to closures, we’ll talk about passing functions as arguments to other functions. For example, with iterators, we can do this to convert a vector of Strings into a vector of Message::Writes:

  let v = vec!["Hello".to_string(), "World".to_string()];
  
  let v1: Vec<Message> = v.into_iter().map(Message::Write).collect();

Matching on enums

Another important use of the match keyword is to process the possible variants of an enum:

enum Message {
      Quit,
      ChangeColor(i32, i32, i32),
      Move { x: i32, y: i32 },
      Write(String),
  }
  
  fn quit() { /* ... */ }
  fn change_color(r: i32, g: i32, b: i32) { /* ... */ }
  fn move_cursor(x: i32, y: i32) { /* ... */ }
  
  fn process_message(msg: Message) {
      match msg {
          Message::Quit => quit(),
          Message::ChangeColor(r, g, b) => change_color(r, g, b),
          Message::Move { x: x, y: y } => move_cursor(x, y),
          Message::Write(s) => println!("{}", s),
      };
  }

Again, the Rust compiler checks exhaustiveness, so it demands that you have a match arm for every variant of the enum. If you leave one off, it will give you a compile-time error unless you use _ or provide all possible arms.

Unlike the previous uses of match, you can’t use the normal if statement to do this. You can use the if let statement, which can be seen as an abbreviated form of match.

Multiple patterns

You can match multiple patterns with |:

let x = 1;
  
  match x {
      1 | 2 => println!("one or two"),
      3 => println!("three"),
      _ => println!("anything"),
  }

This prints one or two.

Destructuring

If you have a compound data type, like a struct, you can destructure it inside of a pattern:

struct Point {
      x: i32,
      y: i32,
  }
  
  let origin = Point { x: 0, y: 0 };
  
  match origin {
      Point { x, y } => println!("({},{})", x, y),
  }

We can use : to give a value a different name.

struct Point {
      x: i32,
      y: i32,
  }
  
  let origin = Point { x: 0, y: 0 };
  
  match origin {
      Point { x: x1, y: y1 } => println!("({},{})", x1, y1),
  }

If we only care about some of the values, we don’t have to give them all names:

struct Point {
      x: i32,
      y: i32,
  }
  
  let origin = Point { x: 0, y: 0 };
  
  match origin {
      Point { x, .. } => println!("x is {}", x),
  }

This prints x is 0.

You can do this kind of match on any member, not only the first:

struct Point {
      x: i32,
      y: i32,
  }
  
  let origin = Point { x: 0, y: 0 };
  
  match origin {
      Point { y, .. } => println!("y is {}", y),
  }

This prints y is 0.

This ‘destructuring’ behavior works on any compound data type, like tuples or enums.

Ignoring bindings

You can use _ in a pattern to disregard the type and value. For example, here’s a match against a Result<T, E>:

match some_value {
      Ok(value) => println!("got a value: {}", value),
      Err(_) => println!("an error occurred"),
  }

In the first arm, we bind the value inside the Ok variant to value. But in the Err arm, we use _ to disregard the specific error, and print a general error message.

_ is valid in any pattern that creates a binding. This can be useful to ignore parts of a larger structure:

fn coordinate() -> (i32, i32, i32) {
      // generate and return some sort of triple tuple
  }
  
  let (x, _, z) = coordinate();

Here, we bind the first and last element of the tuple to x and z, but ignore the middle element.

It’s worth noting that using _ never binds the value in the first place, which means a value may not move:

let tuple: (u32, String) = (5, String::from("five"));
  
  // Here, tuple is moved, because the String moved:
  let (x, _s) = tuple;
  
  // The next line would give "error: use of partially moved value: `tuple`"
  // println!("Tuple is: {:?}", tuple);
  
  // However,
  
  let tuple = (5, String::from("five"));
  
  // Here, tuple is _not_ moved, as the String was never moved, and u32 is Copy:
  let (x, _) = tuple;
  
  // That means this works:
  println!("Tuple is: {:?}", tuple);

This also means that any temporary variables will be dropped at the end of the statement:

// Here, the String created will be dropped immediately, as it’s not bound:
  
  let _ = String::from("  hello  ").trim();

You can also use .. in a pattern to disregard multiple values:

enum OptionalTuple {
      Value(i32, i32, i32),
      Missing,
  }
  
  let x = OptionalTuple::Value(5, -2, 3);
  
  match x {
      OptionalTuple::Value(..) => println!("Got a tuple!"),
      OptionalTuple::Missing => println!("No such luck."),
  }

This prints Got a tuple!.

ref and ref mut

If you want to get a reference, use the ref keyword:

let x = 5;
  
  match x {
      ref r => println!("Got a reference to {}", r),
  }

This prints Got a reference to 5.

Here, the r inside the match has the type &i32. In other words, the ref keyword creates a reference, for use in the pattern. If you need a mutable reference, ref mut will work in the same way:

let mut x = 5;
  
  match x {
      ref mut mr => println!("Got a mutable reference to {}", mr),
  }

Ranges

You can match a range of values with ...:

let x = 1;
  
  match x {
      1 ... 5 => println!("one through five"),
      _ => println!("anything"),
  }

This prints one through five.

Ranges are mostly used with integers and chars:

let x = '💅';
  
  match x {
      'a' ... 'j' => println!("early letter"),
      'k' ... 'z' => println!("late letter"),
      _ => println!("something else"),
  }

This prints something else.

Bindings

You can bind values to names with @:

let x = 1;
  
  match x {
      e @ 1 ... 5 => println!("got a range element {}", e),
      _ => println!("anything"),
  }

This prints got a range element 1. This is useful when you want to do a complicated match of part of a data structure:

#[derive(Debug)]
  struct Person {
      name: Option<String>,
  }
  
  let name = "Steve".to_string();
  let x: Option<Person> = Some(Person { name: Some(name) });
  match x {
      Some(Person { name: ref a @ Some(_), .. }) => println!("{:?}", a),
      _ => {}
  }

This prints Some("Steve"): we’ve bound the inner name to a.

If you use @ with |, you need to make sure the name is bound in each part of the pattern:

let x = 5;
  
  match x {
      e @ 1 ... 5 | e @ 8 ... 10 => println!("got a range element {}", e),
      _ => println!("anything"),
  }

Guards

You can introduce ‘match guards’ with if:

enum OptionalInt {
      Value(i32),
      Missing,
  }
  
  let x = OptionalInt::Value(5);
  
  match x {
      OptionalInt::Value(i) if i > 5 => println!("Got an int bigger than five!"),
      OptionalInt::Value(..) => println!("Got an int!"),
      OptionalInt::Missing => println!("No such luck."),
  }

This prints Got an int!.

If you’re using if with multiple patterns, the if applies to both sides:

let x = 4;
  let y = false;
  
  match x {
      4 | 5 if y => println!("yes"),
      _ => println!("no"),
  }

This prints no, because the if applies to the whole of 4 | 5, and not to only the 5. In other words, the precedence of if behaves like this:

(4 | 5) if y => ...

not this:

4 | (5 if y) => ...

Mix and Match

Whew! That’s a lot of different ways to match things, and they can all be mixed and matched, depending on what you’re doing:

match x {
      Foo { x: Some(ref name), y: None } => ...
  }

Patterns are very powerful. Make good use of them.

Method calls

Here’s how it works:

struct Circle {
      x: f64,
      y: f64,
      radius: f64,
  }
  
  impl Circle {
      fn area(&self) -> f64 {
          std::f64::consts::PI * (self.radius * self.radius)
      }
  }
  
  fn main() {
      let c = Circle { x: 0.0, y: 0.0, radius: 2.0 };
      println!("{}", c.area());
  }

This will print 12.566371.

We’ve made a struct that represents a circle. We then write an impl block, and inside it, define a method, area.

Methods take a special first parameter, of which there are three variants: self, &self, and &mut self. You can think of this first parameter as being the foo in foo.bar(). The three variants correspond to the three kinds of things foo could be: self if it’s a value on the stack, &self if it’s a reference, and &mut self if it’s a mutable reference. Because we took the &self parameter to area, we can use it like any other parameter. Because we know it’s a Circle, we can access the radius like we would with any other struct.

We should default to using &self, as you should prefer borrowing over taking ownership, as well as taking immutable references over mutable ones. Here’s an example of all three variants:

struct Circle {
      x: f64,
      y: f64,
      radius: f64,
  }
  
  impl Circle {
      fn reference(&self) {
         println!("taking self by reference!");
      }
  
      fn mutable_reference(&mut self) {
         println!("taking self by mutable reference!");
      }
  
      fn takes_ownership(self) {
         println!("taking ownership of self!");
      }
  }

You can use as many impl blocks as you’d like. The previous example could have also been written like this:

struct Circle {
      x: f64,
      y: f64,
      radius: f64,
  }
  
  impl Circle {
      fn reference(&self) {
         println!("taking self by reference!");
      }
  }
  
  impl Circle {
      fn mutable_reference(&mut self) {
         println!("taking self by mutable reference!");
      }
  }
  
  impl Circle {
      fn takes_ownership(self) {
         println!("taking ownership of self!");
      }
  }

Chaining method calls

So, now we know how to call a method, such as foo.bar(). But what about our original example, foo.bar().baz()? This is called ‘method chaining’. Let’s look at an example:

struct Circle {
      x: f64,
      y: f64,
      radius: f64,
  }
  
  impl Circle {
      fn area(&self) -> f64 {
          std::f64::consts::PI * (self.radius * self.radius)
      }
  
      fn grow(&self, increment: f64) -> Circle {
          Circle { x: self.x, y: self.y, radius: self.radius + increment }
      }
  }
  
  fn main() {
      let c = Circle { x: 0.0, y: 0.0, radius: 2.0 };
      println!("{}", c.area());
  
      let d = c.grow(2.0).area();
      println!("{}", d);
  }

Check the return type:

fn grow(&self, increment: f64) -> Circle {

We say we’re returning a Circle. With this method, we can grow a new Circle to any arbitrary size.

Associated functions

You can also define associated functions that do not take a self parameter. Here’s a pattern that’s very common in Rust code:

struct Circle {
      x: f64,
      y: f64,
      radius: f64,
  }
  
  impl Circle {
      fn new(x: f64, y: f64, radius: f64) -> Circle {
          Circle {
              x: x,
              y: y,
              radius: radius,
          }
      }
  }
  
  fn main() {
      let c = Circle::new(0.0, 0.0, 2.0);
  }

This ‘associated function’ builds a new Circle for us. Note that associated functions are called with the Struct::function() syntax, rather than the ref.method() syntax. Some other languages call associated functions ‘static methods’.

Builder Pattern

Let’s say that we want our users to be able to create Circles, but we will allow them to only set the properties they care about. Otherwise, the x and y attributes will be 0.0, and the radius will be 1.0. Rust doesn’t have method overloading, named arguments, or variable arguments. We employ the builder pattern instead. It looks like this:

struct Circle {
      x: f64,
      y: f64,
      radius: f64,
  }
  
  impl Circle {
      fn area(&self) -> f64 {
          std::f64::consts::PI * (self.radius * self.radius)
      }
  }
  
  struct CircleBuilder {
      x: f64,
      y: f64,
      radius: f64,
  }
  
  impl CircleBuilder {
      fn new() -> CircleBuilder {
          CircleBuilder { x: 0.0, y: 0.0, radius: 1.0, }
      }
  
      fn x(&mut self, coordinate: f64) -> &mut CircleBuilder {
          self.x = coordinate;
          self
      }
  
      fn y(&mut self, coordinate: f64) -> &mut CircleBuilder {
          self.y = coordinate;
          self
      }
  
      fn radius(&mut self, radius: f64) -> &mut CircleBuilder {
          self.radius = radius;
          self
      }
  
      fn finalize(&self) -> Circle {
          Circle { x: self.x, y: self.y, radius: self.radius }
      }
  }
  
  fn main() {
      let c = CircleBuilder::new()
                  .x(1.0)
                  .y(2.0)
                  .radius(2.0)
                  .finalize();
  
      println!("area: {}", c.area());
      println!("x: {}", c.x);
      println!("y: {}", c.y);
  }

What we’ve done here is make another struct, CircleBuilder. We’ve defined our builder methods on it. We’ve also defined our area() method on Circle. We also made one more method on CircleBuilder: finalize(). This method creates our final Circle from the builder. Now, we’ve used the type system to enforce our concerns: we can use the methods on CircleBuilder to constrain making Circles in any way we choose.

Indexing

Because strings are valid UTF-8, they do not support indexing:

let s = "hello";
  
  println!("The first letter of s is {}", s[0]); // ERROR!!!

Usually, access to a vector with [] is very fast. But, because each character in a UTF-8 encoded string can be multiple bytes, you have to walk over the string to find the nᵗʰ letter of a string. This is a significantly more expensive operation, and we don’t want to be misleading. Furthermore, ‘letter’ isn’t something defined in Unicode, exactly. We can choose to look at a string as individual bytes, or as codepoints:

let hachiko = "忠犬ハチ公";
  
  for b in hachiko.as_bytes() {
      print!("{}, ", b);
  }
  
  println!("");
  
  for c in hachiko.chars() {
      print!("{}, ", c);
  }
  
  println!("");

This prints:

229, 191, 160, 231, 138, 172, 227, 131, 143, 227, 131, 129, 229, 133, 172,
  忠, 犬, ハ, チ, 公,

As you can see, there are more bytes than chars.

You can get something similar to an index like this:

let dog = hachiko.chars().nth(1); // kinda like hachiko[1]

This emphasizes that we have to walk from the beginning of the list of chars.

Slicing

You can get a slice of a string with slicing syntax:

let dog = "hachiko";
  let hachi = &dog[0..5];

But note that these are byte offsets, not character offsets. So this will fail at runtime:

let dog = "忠犬ハチ公";
  let hachi = &dog[0..2];

with this error:

thread '<main>' panicked at 'index 0 and/or 2 in `忠犬ハチ公` do not lie on
  character boundary'

Concatenation

If you have a String, you can concatenate a &str to the end of it:

let hello = "Hello ".to_string();
  let world = "world!";
  
  let hello_world = hello + world;

But if you have two Strings, you need an &:

let hello = "Hello ".to_string();
  let world = "world!".to_string();
  
  let hello_world = hello + &world;

This is because &String can automatically coerce to a &str. This is a feature called ‘Deref coercions’.

Generic functions

We can write functions that take generic types with a similar syntax:

fn takes_anything<T>(x: T) {
      // do something with x
  }

The syntax has two parts: the <T> says “this function is generic over one type, T”, and the x: T says “x has the type T.”

Multiple arguments can have the same generic type:

fn takes_two_of_the_same_things<T>(x: T, y: T) {
      // ...
  }

We could write a version that takes multiple types:

fn takes_two_things<T, U>(x: T, y: U) {
      // ...
  }

Generic structs

You can store a generic type in a struct as well:

struct Point<T> {
      x: T,
      y: T,
  }
  
  let int_origin = Point { x: 0, y: 0 };
  let float_origin = Point { x: 0.0, y: 0.0 };

Similar to functions, the <T> is where we declare the generic parameters, and we then use x: T in the type declaration, too.

When you want to add an implementation for the generic struct, you declare the type parameter after the impl:

impl<T> Point<T> {
      fn swap(&mut self) {
          std::mem::swap(&mut self.x, &mut self.y);
      }
  }

So far you’ve seen generics that take absolutely any type. These are useful in many cases: you’ve already seen Option<T>, and later you’ll meet universal container types like Vec<T>. On the other hand, often you want to trade that flexibility for increased expressive power. Read about trait bounds to see why and how.

Trait bounds on generic functions

Traits are useful because they allow a type to make certain promises about its behavior. Generic functions can exploit this to constrain, or bound, the types they accept. Consider this function, which does not compile:

fn print_area<T>(shape: T) {
      println!("This shape has an area of {}", shape.area());
  }

Rust complains:

error: no method named `area` found for type `T` in the current scope

Because T can be any type, we can’t be sure that it implements the area method. But we can add a trait bound to our generic T, ensuring that it does:

fn print_area<T: HasArea>(shape: T) {
      println!("This shape has an area of {}", shape.area());
  }

The syntax <T: HasArea> means “any type that implements the HasArea trait.” Because traits define function type signatures, we can be sure that any type which implements HasArea will have an .area() method.

Here’s an extended example of how this works:

trait HasArea {
      fn area(&self) -> f64;
  }
  
  struct Circle {
      x: f64,
      y: f64,
      radius: f64,
  }
  
  impl HasArea for Circle {
      fn area(&self) -> f64 {
          std::f64::consts::PI * (self.radius * self.radius)
      }
  }
  
  struct Square {
      x: f64,
      y: f64,
      side: f64,
  }
  
  impl HasArea for Square {
      fn area(&self) -> f64 {
          self.side * self.side
      }
  }
  
  fn print_area<T: HasArea>(shape: T) {
      println!("This shape has an area of {}", shape.area());
  }
  
  fn main() {
      let c = Circle {
          x: 0.0f64,
          y: 0.0f64,
          radius: 1.0f64,
      };
  
      let s = Square {
          x: 0.0f64,
          y: 0.0f64,
          side: 1.0f64,
      };
  
      print_area(c);
      print_area(s);
  }

This program outputs:

This shape has an area of 3.141593
  This shape has an area of 1

As you can see, print_area is now generic, but also ensures that we have passed in the correct types. If we pass in an incorrect type:

print_area(5);

We get a compile-time error:

error: the trait bound `_ : HasArea` is not satisfied [E0277]

Trait bounds on generic structs

Your generic structs can also benefit from trait bounds. All you need to do is append the bound when you declare type parameters. Here is a new type Rectangle<T> and its operation is_square():

struct Rectangle<T> {
      x: T,
      y: T,
      width: T,
      height: T,
  }
  
  impl<T: PartialEq> Rectangle<T> {
      fn is_square(&self) -> bool {
          self.width == self.height
      }
  }
  
  fn main() {
      let mut r = Rectangle {
          x: 0,
          y: 0,
          width: 47,
          height: 47,
      };
  
      assert!(r.is_square());
  
      r.height = 42;
      assert!(!r.is_square());
  }

is_square() needs to check that the sides are equal, so the sides must be of a type that implements the core::cmp::PartialEq trait:

impl<T: PartialEq> Rectangle<T> { ... }

Now, a rectangle can be defined in terms of any type that can be compared for equality.

Here we defined a new struct Rectangle that accepts numbers of any precision—really, objects of pretty much any type—as long as they can be compared for equality. Could we do the same for our HasArea structs, Square and Circle? Yes, but they need multiplication, and to work with that we need to know more about operator traits.

Rules for implementing traits

So far, we’ve only added trait implementations to structs, but you can implement a trait for any type. So technically, we could implement HasArea for i32:

trait HasArea {
      fn area(&self) -> f64;
  }
  
  impl HasArea for i32 {
      fn area(&self) -> f64 {
          println!("this is silly");
  
          *self as f64
      }
  }
  
  5.area();

It is considered poor style to implement methods on such primitive types, even though it is possible.

This may seem like the Wild West, but there are two restrictions around implementing traits that prevent this from getting out of hand. The first is that if the trait isn’t defined in your scope, it doesn’t apply. Here’s an example: the standard library provides a Write trait which adds extra functionality to Files, for doing file I/O. By default, a File won’t have its methods:

let mut f = std::fs::File::open("foo.txt").expect("Couldn’t open foo.txt");
  let buf = b"whatever"; // byte string literal. buf: &[u8; 8]
  let result = f.write(buf);

Here’s the error:

error: type `std::fs::File` does not implement any method in scope named `write`
  let result = f.write(buf);
                 ^~~~~~~~~~

We need to use the Write trait first:

use std::io::Write;
  
  let mut f = std::fs::File::open("foo.txt").expect("Couldn’t open foo.txt");
  let buf = b"whatever";
  let result = f.write(buf);

This will compile without error.

This means that even if someone does something bad like add methods to i32, it won’t affect you, unless you use that trait.

There’s one more restriction on implementing traits: either the trait or the type you’re implementing it for must be defined by you. Or more precisely, one of them must be defined in the same crate as the impl you’re writing. For more on Rust’s module and package system, see the chapter on crates and modules.

So, we could implement the HasArea type for i32, because we defined HasArea in our code. But if we tried to implement ToString, a trait provided by Rust, for i32, we could not, because neither the trait nor the type are defined in our crate.

One last thing about traits: generic functions with a trait bound use ‘monomorphization’ (mono: one, morph: form), so they are statically dispatched. What’s that mean? Check out the chapter on trait objects for more details.

Multiple trait bounds

You’ve seen that you can bound a generic type parameter with a trait:

fn foo<T: Clone>(x: T) {
      x.clone();
  }

If you need more than one bound, you can use +:

use std::fmt::Debug;
  
  fn foo<T: Clone + Debug>(x: T) {
      x.clone();
      println!("{:?}", x);
  }

T now needs to be both Clone as well as Debug.

Where clause

Writing functions with only a few generic types and a small number of trait bounds isn’t too bad, but as the number increases, the syntax gets increasingly awkward:

use std::fmt::Debug;
  
  fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
      x.clone();
      y.clone();
      println!("{:?}", y);
  }

The name of the function is on the far left, and the parameter list is on the far right. The bounds are getting in the way.

Rust has a solution, and it’s called a ‘where clause’:

use std::fmt::Debug;
  
  fn foo<T: Clone, K: Clone + Debug>(x: T, y: K) {
      x.clone();
      y.clone();
      println!("{:?}", y);
  }
  
  fn bar<T, K>(x: T, y: K) where T: Clone, K: Clone + Debug {
      x.clone();
      y.clone();
      println!("{:?}", y);
  }
  
  fn main() {
      foo("Hello", "world");
      bar("Hello", "world");
  }

foo() uses the syntax we showed earlier, and bar() uses a where clause. All you need to do is leave off the bounds when defining your type parameters, and then add where after the parameter list. For longer lists, whitespace can be added:

use std::fmt::Debug;
  
  fn bar<T, K>(x: T, y: K)
      where T: Clone,
            K: Clone + Debug {
  
      x.clone();
      y.clone();
      println!("{:?}", y);
  }

This flexibility can add clarity in complex situations.

where is also more powerful than the simpler syntax. For example:

trait ConvertTo<Output> {
      fn convert(&self) -> Output;
  }
  
  impl ConvertTo<i64> for i32 {
      fn convert(&self) -> i64 { *self as i64 }
  }
  
  // can be called with T == i32
  fn normal<T: ConvertTo<i64>>(x: &T) -> i64 {
      x.convert()
  }
  
  // can be called with T == i64
  fn inverse<T>() -> T
          // this is using ConvertTo as if it were "ConvertTo<i64>"
          where i32: ConvertTo<T> {
      42.convert()
  }

This shows off the additional feature of where clauses: they allow bounds on the left-hand side not only of type parameters T, but also of types (i32 in this case). In this example, i32 must implement ConvertTo<T>. Rather than defining what i32 is (since that’s obvious), the where clause here constrains T.

Default methods

A default method can be added to a trait definition if it is already known how a typical implementor will define a method. For example, is_invalid() is defined as the opposite of is_valid():

trait Foo {
      fn is_valid(&self) -> bool;
  
      fn is_invalid(&self) -> bool { !self.is_valid() }
  }

Implementors of the Foo trait need to implement is_valid() but not is_invalid() due to the added default behavior. This default behavior can still be overridden as in:

struct UseDefault;
  
  impl Foo for UseDefault {
      fn is_valid(&self) -> bool {
          println!("Called UseDefault.is_valid.");
          true
      }
  }
  
  struct OverrideDefault;
  
  impl Foo for OverrideDefault {
      fn is_valid(&self) -> bool {
          println!("Called OverrideDefault.is_valid.");
          true
      }
  
      fn is_invalid(&self) -> bool {
          println!("Called OverrideDefault.is_invalid!");
          true // overrides the expected value of is_invalid()
      }
  }
  
  let default = UseDefault;
  assert!(!default.is_invalid()); // prints "Called UseDefault.is_valid."
  
  let over = OverrideDefault;
  assert!(over.is_invalid()); // prints "Called OverrideDefault.is_invalid!"

Inheritance

Sometimes, implementing a trait requires implementing another trait:

trait Foo {
      fn foo(&self);
  }
  
  trait FooBar : Foo {
      fn foobar(&self);
  }

Implementors of FooBar must also implement Foo, like this:

struct Baz;
  
  impl Foo for Baz {
      fn foo(&self) { println!("foo"); }
  }
  
  impl FooBar for Baz {
      fn foobar(&self) { println!("foobar"); }
  }

If we forget to implement Foo, Rust will tell us:

error: the trait bound `main::Baz : main::Foo` is not satisfied [E0277]

Deriving

Implementing traits like Debug and Default repeatedly can become quite tedious. For that reason, Rust provides an attribute that allows you to let Rust automatically implement traits for you:

#[derive(Debug)]
  struct Foo;
  
  fn main() {
      println!("{:?}", Foo);
  }

However, deriving is limited to a certain set of traits:

• Clone
• Copy
• Debug
• Default
• Eq
• Hash
• Ord
• PartialEq
• PartialOrd

while let

In a similar fashion, while let can be used when you want to conditionally loop as long as a value matches a certain pattern. It turns code like this:

let mut v = vec![1, 3, 5, 7, 11];
  loop {
      match v.pop() {
          Some(x) =>  println!("{}", x),
          None => break,
      }
  }

Into code like this:

let mut v = vec![1, 3, 5, 7, 11];
  while let Some(x) = v.pop() {
      println!("{}", x);
  }

Background

For the rest of this chapter, we’ll need a trait and some implementations. Let’s make a simple one, Foo. It has one method that is expected to return a String.

trait Foo {
      fn method(&self) -> String;
  }

We’ll also implement this trait for u8 and String:

impl Foo for u8 {
      fn method(&self) -> String { format!("u8: {}", *self) }
  }
  
  impl Foo for String {
      fn method(&self) -> String { format!("string: {}", *self) }
  }

Static dispatch

We can use this trait to perform static dispatch with trait bounds:

fn do_something<T: Foo>(x: T) {
      x.method();
  }
  
  fn main() {
      let x = 5u8;
      let y = "Hello".to_string();
  
      do_something(x);
      do_something(y);
  }

Rust uses ‘monomorphization’ to perform static dispatch here. This means that Rust will create a special version of do_something() for both u8 and String, and then replace the call sites with calls to these specialized functions. In other words, Rust generates something like this:

fn do_something_u8(x: u8) {
      x.method();
  }
  
  fn do_something_string(x: String) {
      x.method();
  }
  
  fn main() {
      let x = 5u8;
      let y = "Hello".to_string();
  
      do_something_u8(x);
      do_something_string(y);
  }

This has a great upside: static dispatch allows function calls to be inlined because the callee is known at compile time, and inlining is the key to good optimization. Static dispatch is fast, but it comes at a tradeoff: ‘code bloat’, due to many copies of the same function existing in the binary, one for each type.

Furthermore, compilers aren’t perfect and may “optimize” code to become slower. For example, functions inlined too eagerly will bloat the instruction cache (cache rules everything around us). This is part of the reason that #[inline] and #[inline(always)] should be used carefully, and one reason why using a dynamic dispatch is sometimes more efficient.

However, the common case is that it is more efficient to use static dispatch, and one can always have a thin statically-dispatched wrapper function that does a dynamic dispatch, but not vice versa, meaning static calls are more flexible. The standard library tries to be statically dispatched where possible for this reason.

Dynamic dispatch

Rust provides dynamic dispatch through a feature called ‘trait objects’. Trait objects, like &Foo or Box<Foo>, are normal values that store a value of any type that implements the given trait, where the precise type can only be known at runtime.

A trait object can be obtained from a pointer to a concrete type that implements the trait by casting it (e.g. &x as &Foo) or coercing it (e.g. using &x as an argument to a function that takes &Foo).

These trait object coercions and casts also work for pointers like &mut T to &mut Foo and Box<T> to Box<Foo>, but that’s all at the moment. Coercions and casts are identical.

This operation can be seen as ‘erasing’ the compiler’s knowledge about the specific type of the pointer, and hence trait objects are sometimes referred to as ‘type erasure’.

Coming back to the example above, we can use the same trait to perform dynamic dispatch with trait objects by casting:

  fn do_something(x: &Foo) {
      x.method();
  }
  
  fn main() {
      let x = 5u8;
      do_something(&x as &Foo);
  }

or by coercing:

  fn do_something(x: &Foo) {
      x.method();
  }
  
  fn main() {
      let x = "Hello".to_string();
      do_something(&x);
  }

A function that takes a trait object is not specialized to each of the types that implements Foo: only one copy is generated, often (but not always) resulting in less code bloat. However, this comes at the cost of requiring slower virtual function calls, and effectively inhibiting any chance of inlining and related optimizations from occurring.

pub struct TraitObject {
      pub data: *mut (),
      pub vtable: *mut (),
  }

struct FooVtable {
      destructor: fn(*mut ()),
      size: usize,
      align: usize,
      method: fn(*const ()) -> String,
  }
  
  // u8:
  
  fn call_method_on_u8(x: *const ()) -> String {
      // the compiler guarantees that this function is only called
      // with `x` pointing to a u8
      let byte: &u8 = unsafe { &*(x as *const u8) };
  
      byte.method()
  }
  
  static Foo_for_u8_vtable: FooVtable = FooVtable {
      destructor: /* compiler magic */,
      size: 1,
      align: 1,
  
      // cast to a function pointer
      method: call_method_on_u8 as fn(*const ()) -> String,
  };
  
  
  // String:
  
  fn call_method_on_String(x: *const ()) -> String {
      // the compiler guarantees that this function is only called
      // with `x` pointing to a String
      let string: &String = unsafe { &*(x as *const String) };
  
      string.method()
  }
  
  static Foo_for_String_vtable: FooVtable = FooVtable {
      destructor: /* compiler magic */,
      // values for a 64-bit computer, halve them for 32-bit ones
      size: 24,
      align: 8,
  
      method: call_method_on_String as fn(*const ()) -> String,
  };

let a: String = "foo".to_string();
  let x: u8 = 1;
  
  // let b: &Foo = &a;
  let b = TraitObject {
      // store the data
      data: &a,
      // store the methods
      vtable: &Foo_for_String_vtable
  };
  
  // let y: &Foo = x;
  let y = TraitObject {
      // store the data
      data: &x,
      // store the methods
      vtable: &Foo_for_u8_vtable
  };
  
  // b.method();
  (b.vtable.method)(b.data);
  
  // y.method();
  (y.vtable.method)(y.data);

Object Safety

Not every trait can be used to make a trait object. For example, vectors implement Clone, but if we try to make a trait object:

let v = vec![1, 2, 3];
  let o = &v as &Clone;

We get an error:

error: cannot convert to a trait object because trait `core::clone::Clone` is not obje
  ↳ ct-safe [E0038]
  let o = &v as &Clone;
          ^~
  note: the trait cannot require that `Self : Sized`
  let o = &v as &Clone;
          ^~

The error says that Clone is not ‘object-safe’. Only traits that are object-safe can be made into trait objects. A trait is object-safe if both of these are true:

• the trait does not require that Self: Sized
• all of its methods are object-safe

So what makes a method object-safe? Each method must require that Self: Sized or all of the following:

• must not have any type parameters
• must not use Self

Whew! As we can see, almost all of these rules talk about Self. A good intuition is “except in special circumstances, if your trait’s method uses Self, it is not object-safe.”

Syntax

Closures look like this:

let plus_one = |x: i32| x + 1;
  
  assert_eq!(2, plus_one(1));

We create a binding, plus_one, and assign it to a closure. The closure’s arguments go between the pipes (|), and the body is an expression, in this case, x + 1. Remember that { } is an expression, so we can have multi-line closures too:

let plus_two = |x| {
      let mut result: i32 = x;
  
      result += 1;
      result += 1;
  
      result
  };
  
  assert_eq!(4, plus_two(2));

You’ll notice a few things about closures that are a bit different from regular named functions defined with fn. The first is that we did not need to annotate the types of arguments the closure takes or the values it returns. We can:

let plus_one = |x: i32| -> i32 { x + 1 };
  
  assert_eq!(2, plus_one(1));

But we don’t have to. Why is this? Basically, it was chosen for ergonomic reasons. While specifying the full type for named functions is helpful with things like documentation and type inference, the full type signatures of closures are rarely documented since they’re anonymous, and they don’t cause the kinds of error-at-a-distance problems that inferring named function types can.

The second is that the syntax is similar, but a bit different. I’ve added spaces here for easier comparison:

fn  plus_one_v1   (x: i32) -> i32 { x + 1 }
  let plus_one_v2 = |x: i32| -> i32 { x + 1 };
  let plus_one_v3 = |x: i32|          x + 1  ;

Small differences, but they’re similar.

Closures and their environment

The environment for a closure can include bindings from its enclosing scope in addition to parameters and local bindings. It looks like this:

let num = 5;
  let plus_num = |x: i32| x + num;
  
  assert_eq!(10, plus_num(5));

This closure, plus_num, refers to a let binding in its scope: num. More specifically, it borrows the binding. If we do something that would conflict with that binding, we get an error. Like this one:

let mut num = 5;
  let plus_num = |x: i32| x + num;
  
  let y = &mut num;

Which errors with:

error: cannot borrow `num` as mutable because it is also borrowed as immutable
      let y = &mut num;
                   ^~~
  note: previous borrow of `num` occurs here due to use in closure; the immutable
    borrow prevents subsequent moves or mutable borrows of `num` until the borrow
    ends
      let plus_num = |x| x + num;
                     ^~~~~~~~~~~
  note: previous borrow ends here
  fn main() {
      let mut num = 5;
      let plus_num = |x| x + num;
  
      let y = &mut num;
  }
  ^

A verbose yet helpful error message! As it says, we can’t take a mutable borrow on num because the closure is already borrowing it. If we let the closure go out of scope, we can:

let mut num = 5;
  {
      let plus_num = |x: i32| x + num;
  
  } // plus_num goes out of scope, borrow of num ends
  
  let y = &mut num;

If your closure requires it, however, Rust will take ownership and move the environment instead. This doesn’t work:

let nums = vec![1, 2, 3];
  
  let takes_nums = || nums;
  
  println!("{:?}", nums);

We get this error:

note: `nums` moved into closure environment here because it has type
    `[closure(()) -> collections::vec::Vec<i32>]`, which is non-copyable
  let takes_nums = || nums;
                   ^~~~~~~

Vec<T> has ownership over its contents, and therefore, when we refer to it in our closure, we have to take ownership of nums. It’s the same as if we’d passed nums to a function that took ownership of it.

let num = 5;
  
  let owns_num = move |x: i32| x + num;

let mut num = 5;
  
  {
      let mut add_num = |x: i32| num += x;
  
      add_num(5);
  }
  
  assert_eq!(10, num);

let mut num = 5;
  
  {
      let mut add_num = move |x: i32| num += x;
  
      add_num(5);
  }
  
  assert_eq!(5, num);

Closure implementation

Rust’s implementation of closures is a bit different than other languages. They are effectively syntax sugar for traits. You’ll want to make sure to have read the traits section before this one, as well as the section on trait objects.

Got all that? Good.

The key to understanding how closures work under the hood is something a bit strange: Using () to call a function, like foo(), is an overloadable operator. From this, everything else clicks into place. In Rust, we use the trait system to overload operators. Calling functions is no different. We have three separate traits to overload with:

pub trait Fn<Args> : FnMut<Args> {
      extern "rust-call" fn call(&self, args: Args) -> Self::Output;
  }
  
  pub trait FnMut<Args> : FnOnce<Args> {
      extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
  }
  
  pub trait FnOnce<Args> {
      type Output;
  
      extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
  }

You’ll notice a few differences between these traits, but a big one is self: Fn takes &self, FnMut takes &mut self, and FnOnce takes self. This covers all three kinds of self via the usual method call syntax. But we’ve split them up into three traits, rather than having a single one. This gives us a large amount of control over what kind of closures we can take.

The || {} syntax for closures is sugar for these three traits. Rust will generate a struct for the environment, impl the appropriate trait, and then use it.

Taking closures as arguments

Now that we know that closures are traits, we already know how to accept and return closures: the same as any other trait!

This also means that we can choose static vs dynamic dispatch as well. First, let’s write a function which takes something callable, calls it, and returns the result:

fn call_with_one<F>(some_closure: F) -> i32
      where F : Fn(i32) -> i32 {
  
      some_closure(1)
  }
  
  let answer = call_with_one(|x| x + 2);
  
  assert_eq!(3, answer);

We pass our closure, |x| x + 2, to call_with_one. It does what it suggests: it calls the closure, giving it 1 as an argument.

Let’s examine the signature of call_with_one in more depth:

fn call_with_one<F>(some_closure: F) -> i32

We take one parameter, and it has the type F. We also return a i32. This part isn’t interesting. The next part is:

    where F : Fn(i32) -> i32 {

Because Fn is a trait, we can bound our generic with it. In this case, our closure takes a i32 as an argument and returns an i32, and so the generic bound we use is Fn(i32) -> i32.

There’s one other key point here: because we’re bounding a generic with a trait, this will get monomorphized, and therefore, we’ll be doing static dispatch into the closure. That’s pretty neat. In many languages, closures are inherently heap allocated, and will always involve dynamic dispatch. In Rust, we can stack allocate our closure environment, and statically dispatch the call. This happens quite often with iterators and their adapters, which often take closures as arguments.

Of course, if we want dynamic dispatch, we can get that too. A trait object handles this case, as usual:

fn call_with_one(some_closure: &Fn(i32) -> i32) -> i32 {
      some_closure(1)
  }
  
  let answer = call_with_one(&|x| x + 2);
  
  assert_eq!(3, answer);

Now we take a trait object, a &Fn. And we have to make a reference to our closure when we pass it to call_with_one, so we use &||.

A quick note about closures that use explicit lifetimes. Sometimes you might have a closure that takes a reference like so:

fn call_with_ref<F>(some_closure:F) -> i32
      where F: Fn(&i32) -> i32 {
  
      let mut value = 0;
      some_closure(&value)
  }

Normally you can specify the lifetime of the parameter to our closure. We could annotate it on the function declaration:

fn call_with_ref<'a, F>(some_closure:F) -> i32 
      where F: Fn(&'a 32) -> i32 {

However this presents a problem with in our case. When you specify the explict lifetime on a function it binds that lifetime to the entire scope of the function instead of just the invocation scope of our closure. This means that the borrow checker will see a mutable reference in the same lifetime as our immutable reference and fail to compile.

In order to say that we only need the lifetime to be valid for the invocation scope of the closure we can use Higher-Ranked Trait Bounds with the for<...> syntax:

fn call_with_ref<F>(some_closure:F) -> i32
      where F: for<'a> Fn(&'a 32) -> i32 {

This lets the Rust compiler find the minimum lifetime to invoke our closure and satisfy the borrow checker’s rules. Our function then compiles and excutes as we expect.

fn call_with_ref<F>(some_closure:F) -> i32
      where F: for<'a> Fn(&'a i32) -> i32 {
  
      let mut value = 0;
      some_closure(&value)
  }

Function pointers and closures

A function pointer is kind of like a closure that has no environment. As such, you can pass a function pointer to any function expecting a closure argument, and it will work:

fn call_with_one(some_closure: &Fn(i32) -> i32) -> i32 {
      some_closure(1)
  }
  
  fn add_one(i: i32) -> i32 {
      i + 1
  }
  
  let f = add_one;
  
  let answer = call_with_one(&f);
  
  assert_eq!(2, answer);

In this example, we don’t strictly need the intermediate variable f, the name of the function works just fine too:

let answer = call_with_one(&add_one);

Returning closures

It’s very common for functional-style code to return closures in various situations. If you try to return a closure, you may run into an error. At first, it may seem strange, but we’ll figure it out. Here’s how you’d probably try to return a closure from a function:

fn factory() -> (Fn(i32) -> i32) {
      let num = 5;
  
      |x| x + num
  }
  
  let f = factory();
  
  let answer = f(1);
  assert_eq!(6, answer);

This gives us these long, related errors:

error: the trait bound `core::ops::Fn(i32) -> i32 : core::marker::Sized` is not satisf
  ↳ ied [E0277]
  fn factory() -> (Fn(i32) -> i32) {
                  ^~~~~~~~~~~~~~~~
  note: `core::ops::Fn(i32) -> i32` does not have a constant size known at compile-time
  fn factory() -> (Fn(i32) -> i32) {
                  ^~~~~~~~~~~~~~~~
  error: the trait bound `core::ops::Fn(i32) -> i32 : core::marker::Sized` is not satisf
  ↳ ied [E0277]
  let f = factory();
      ^
  note: `core::ops::Fn(i32) -> i32` does not have a constant size known at compile-time
  let f = factory();
      ^

In order to return something from a function, Rust needs to know what size the return type is. But since Fn is a trait, it could be various things of various sizes: many different types can implement Fn. An easy way to give something a size is to take a reference to it, as references have a known size. So we’d write this:

fn factory() -> &(Fn(i32) -> i32) {
      let num = 5;
  
      |x| x + num
  }
  
  let f = factory();
  
  let answer = f(1);
  assert_eq!(6, answer);

But we get another error:

error: missing lifetime specifier [E0106]
  fn factory() -> &(Fn(i32) -> i32) {
                  ^~~~~~~~~~~~~~~~~

Right. Because we have a reference, we need to give it a lifetime. But our factory() function takes no arguments, so elision doesn’t kick in here. Then what choices do we have? Try 'static:

fn factory() -> &'static (Fn(i32) -> i32) {
      let num = 5;
  
      |x| x + num
  }
  
  let f = factory();
  
  let answer = f(1);
  assert_eq!(6, answer);

But we get another error:

error: mismatched types:
   expected `&'static core::ops::Fn(i32) -> i32`,
      found `[closure@<anon>:7:9: 7:20]`
  (expected &-ptr,
      found closure) [E0308]
           |x| x + num
           ^~~~~~~~~~~
  

This error is letting us know that we don’t have a &'static Fn(i32) -> i32, we have a [closure@<anon>:7:9: 7:20]. Wait, what?

Because each closure generates its own environment struct and implementation of Fn and friends, these types are anonymous. They exist solely for this closure. So Rust shows them as closure@<anon>, rather than some autogenerated name.

The error also points out that the return type is expected to be a reference, but what we are trying to return is not. Further, we cannot directly assign a 'static lifetime to an object. So we’ll take a different approach and return a ‘trait object’ by Boxing up the Fn. This almost works:

fn factory() -> Box<Fn(i32) -> i32> {
      let num = 5;
  
      Box::new(|x| x + num)
  }
  let f = factory();
  
  let answer = f(1);
  assert_eq!(6, answer);

There’s just one last problem:

error: closure may outlive the current function, but it borrows `num`,
  which is owned by the current function [E0373]
  Box::new(|x| x + num)
           ^~~~~~~~~~~

Well, as we discussed before, closures borrow their environment. And in this case, our environment is based on a stack-allocated 5, the num variable binding. So the borrow has a lifetime of the stack frame. So if we returned this closure, the function call would be over, the stack frame would go away, and our closure is capturing an environment of garbage memory! With one last fix, we can make this work:

fn factory() -> Box<Fn(i32) -> i32> {
      let num = 5;
  
      Box::new(move |x| x + num)
  }
  fn main() {
  let f = factory();
  
  let answer = f(1);
  assert_eq!(6, answer);
  }

By making the inner closure a move Fn, we create a new stack frame for our closure. By Boxing it up, we’ve given it a known size, allowing it to escape our stack frame.

Angle-bracket Form

The form of UFCS we just talked about:

Trait::method(args);

Is a short-hand. There’s an expanded form of this that’s needed in some situations:

<Type as Trait>::method(args);

The <>:: syntax is a means of providing a type hint. The type goes inside the <>s. In this case, the type is Type as Trait, indicating that we want Trait’s version of method to be called here. The as Trait part is optional if it’s not ambiguous. Same with the angle brackets, hence the shorter form.

Here’s an example of using the longer form.

trait Foo {
      fn foo() -> i32;
  }
  
  struct Bar;
  
  impl Bar {
      fn foo() -> i32 {
          20
      }
  }
  
  impl Foo for Bar {
      fn foo() -> i32 {
          10
      }
  }
  
  fn main() {
      assert_eq!(10, <Bar as Foo>::foo());
      assert_eq!(20, Bar::foo());
  }

Using the angle bracket syntax lets you call the trait method instead of the inherent one.

Basic terminology: Crates and Modules

Rust has two distinct terms that relate to the module system: ‘crate’ and ‘module’. A crate is synonymous with a ‘library’ or ‘package’ in other languages. Hence “Cargo” as the name of Rust’s package management tool: you ship your crates to others with Cargo. Crates can produce an executable or a library, depending on the project.

Each crate has an implicit root module that contains the code for that crate. You can then define a tree of sub-modules under that root module. Modules allow you to partition your code within the crate itself.

As an example, let’s make a phrases crate, which will give us various phrases in different languages. To keep things simple, we’ll stick to ‘greetings’ and ‘farewells’ as two kinds of phrases, and use English and Japanese (日本語) as two languages for those phrases to be in. We’ll use this module layout:

                                    +-----------+
                                  +---| greetings |
                    +---------+   |   +-----------+
                +---| english |---+
                |   +---------+   |   +-----------+
                |                 +---| farewells |
  +---------+   |                     +-----------+
  | phrases |---+
  +---------+   |                     +-----------+
                |                 +---| greetings |
                |   +----------+  |   +-----------+
                +---| japanese |--+
                    +----------+  |   +-----------+
                                  +---| farewells |
                                      +-----------+

In this example, phrases is the name of our crate. All of the rest are modules. You can see that they form a tree, branching out from the crate root, which is the root of the tree: phrases itself.

Now that we have a plan, let’s define these modules in code. To start, generate a new crate with Cargo:

$ cargo new phrases
  $ cd phrases

If you remember, this generates a simple project for us:

$ tree .
  .
  ├── Cargo.toml
  └── src
      └── lib.rs
  
  1 directory, 2 files

src/lib.rs is our crate root, corresponding to the phrases in our diagram above.

Defining Modules

To define each of our modules, we use the mod keyword. Let’s make our src/lib.rs look like this:

mod english {
      mod greetings {
      }
  
      mod farewells {
      }
  }
  
  mod japanese {
      mod greetings {
      }
  
      mod farewells {
      }
  }

After the mod keyword, you give the name of the module. Module names follow the conventions for other Rust identifiers: lower_snake_case. The contents of each module are within curly braces ({}).

Within a given mod, you can declare sub-mods. We can refer to sub-modules with double-colon (::) notation: our four nested modules are english::greetings, english::farewells, japanese::greetings, and japanese::farewells. Because these sub-modules are namespaced under their parent module, the names don’t conflict: english::greetings and japanese::greetings are distinct, even though their names are both greetings.

Because this crate does not have a main() function, and is called lib.rs, Cargo will build this crate as a library:

$ cargo build
     Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
  $ ls target/debug
  build  deps  examples  libphrases-a7448e02a0468eaa.rlib  native

libphrases-<hash>.rlib is the compiled crate. Before we see how to use this crate from another crate, let’s break it up into multiple files.

Multiple File Crates

If each crate were just one file, these files would get very large. It’s often easier to split up crates into multiple files, and Rust supports this in two ways.

Instead of declaring a module like this:

mod english {
      // contents of our module go here
  }

We can instead declare our module like this:

mod english;

If we do that, Rust will expect to find either a english.rs file, or a english/mod.rs file with the contents of our module.

Note that in these files, you don’t need to re-declare the module: that’s already been done with the initial mod declaration.

Using these two techniques, we can break up our crate into two directories and seven files:

$ tree .
  .
  ├── Cargo.lock
  ├── Cargo.toml
  ├── src
  │   ├── english
  │   │   ├── farewells.rs
  │   │   ├── greetings.rs
  │   │   └── mod.rs
  │   ├── japanese
  │   │   ├── farewells.rs
  │   │   ├── greetings.rs
  │   │   └── mod.rs
  │   └── lib.rs
  └── target
      └── debug
          ├── build
          ├── deps
          ├── examples
          ├── libphrases-a7448e02a0468eaa.rlib
          └── native

src/lib.rs is our crate root, and looks like this:

mod english;
  mod japanese;

These two declarations tell Rust to look for either src/english.rs and src/japanese.rs, or src/english/mod.rs and src/japanese/mod.rs, depending on our preference. In this case, because our modules have sub-modules, we’ve chosen the second. Both src/english/mod.rs and src/japanese/mod.rs look like this:

mod greetings;
  mod farewells;

Again, these declarations tell Rust to look for either src/english/greetings.rs, src/english/farewells.rs, src/japanese/greetings.rs and src/japanese/farewells.rs or src/english/greetings/mod.rs, src/english/farewells/mod.rs, src/japanese/greetings/mod.rs and src/japanese/farewells/mod.rs. Because these sub-modules don’t have their own sub-modules, we’ve chosen to make them src/english/greetings.rs, src/english/farewells.rs, src/japanese/greetings.rs and src/japanese/farewells.rs. Whew!

The contents of src/english/greetings.rs, src/english/farewells.rs, src/japanese/greetings.rs and src/japanese/farewells.rs are all empty at the moment. Let’s add some functions.

Put this in src/english/greetings.rs:

fn hello() -> String {
      "Hello!".to_string()
  }

Put this in src/english/farewells.rs:

fn goodbye() -> String {
      "Goodbye.".to_string()
  }

Put this in src/japanese/greetings.rs:

fn hello() -> String {
      "こんにちは".to_string()
  }

Of course, you can copy and paste this from this web page, or type something else. It’s not important that you actually put ‘konnichiwa’ to learn about the module system.

Put this in src/japanese/farewells.rs:

fn goodbye() -> String {
      "さようなら".to_string()
  }

(This is ‘Sayōnara’, if you’re curious.)

Now that we have some functionality in our crate, let’s try to use it from another crate.

Importing External Crates

We have a library crate. Let’s make an executable crate that imports and uses our library.

Make a src/main.rs and put this in it (it won’t quite compile yet):

extern crate phrases;
  
  fn main() {
      println!("Hello in English: {}", phrases::english::greetings::hello());
      println!("Goodbye in English: {}", phrases::english::farewells::goodbye());
  
      println!("Hello in Japanese: {}", phrases::japanese::greetings::hello());
      println!("Goodbye in Japanese: {}", phrases::japanese::farewells::goodbye());
  }

The extern crate declaration tells Rust that we need to compile and link to the phrases crate. We can then use phrases’ modules in this one. As we mentioned earlier, you can use double colons to refer to sub-modules and the functions inside of them.

(Note: when importing a crate that has dashes in its name “like-this”, which is not a valid Rust identifier, it will be converted by changing the dashes to underscores, so you would write extern crate like_this;.)

Also, Cargo assumes that src/main.rs is the crate root of a binary crate, rather than a library crate. Our package now has two crates: src/lib.rs and src/main.rs. This pattern is quite common for executable crates: most functionality is in a library crate, and the executable crate uses that library. This way, other programs can also use the library crate, and it’s also a nice separation of concerns.

This doesn’t quite work yet, though. We get four errors that look similar to this:

$ cargo build
     Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
  src/main.rs:4:38: 4:72 error: function `hello` is private
  src/main.rs:4     println!("Hello in English: {}", phrases::english::greetings::hello(
  ↳ ));
                                                     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  note: in expansion of format_args!
  <std macros>:2:25: 2:58 note: expansion site
  <std macros>:1:1: 2:62 note: in expansion of print!
  <std macros>:3:1: 3:54 note: expansion site
  <std macros>:1:1: 3:58 note: in expansion of println!
  phrases/src/main.rs:4:5: 4:76 note: expansion site

By default, everything is private in Rust. Let’s talk about this in some more depth.

Exporting a Public Interface

Rust allows you to precisely control which aspects of your interface are public, and so private is the default. To make things public, you use the pub keyword. Let’s focus on the english module first, so let’s reduce our src/main.rs to only this:

extern crate phrases;
  
  fn main() {
      println!("Hello in English: {}", phrases::english::greetings::hello());
      println!("Goodbye in English: {}", phrases::english::farewells::goodbye());
  }

In our src/lib.rs, let’s add pub to the english module declaration:

pub mod english;
  mod japanese;

And in our src/english/mod.rs, let’s make both pub:

pub mod greetings;
  pub mod farewells;

In our src/english/greetings.rs, let’s add pub to our fn declaration:

pub fn hello() -> String {
      "Hello!".to_string()
  }

And also in src/english/farewells.rs:

pub fn goodbye() -> String {
      "Goodbye.".to_string()
  }

Now, our crate compiles, albeit with warnings about not using the japanese functions:

$ cargo run
     Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
  src/japanese/greetings.rs:1:1: 3:2 warning: function is never used: `hello`, #[warn(de
  ↳ ad_code)] on by default
  src/japanese/greetings.rs:1 fn hello() -> String {
  src/japanese/greetings.rs:2     "こんにちは".to_string()
  src/japanese/greetings.rs:3 }
  src/japanese/farewells.rs:1:1: 3:2 warning: function is never used: `goodbye`, #[warn(
  ↳ dead_code)] on by default
  src/japanese/farewells.rs:1 fn goodbye() -> String {
  src/japanese/farewells.rs:2     "さようなら".to_string()
  src/japanese/farewells.rs:3 }
       Running `target/debug/phrases`
  Hello in English: Hello!
  Goodbye in English: Goodbye.

pub also applies to structs and their member fields. In keeping with Rust’s tendency toward safety, simply making a struct public won’t automatically make its members public: you must mark the fields individually with pub.

Now that our functions are public, we can use them. Great! However, typing out phrases::english::greetings::hello() is very long and repetitive. Rust has another keyword for importing names into the current scope, so that you can refer to them with shorter names. Let’s talk about use.

Importing Modules with use

Rust has a use keyword, which allows us to import names into our local scope. Let’s change our src/main.rs to look like this:

extern crate phrases;
  
  use phrases::english::greetings;
  use phrases::english::farewells;
  
  fn main() {
      println!("Hello in English: {}", greetings::hello());
      println!("Goodbye in English: {}", farewells::goodbye());
  }

The two use lines import each module into the local scope, so we can refer to the functions by a much shorter name. By convention, when importing functions, it’s considered best practice to import the module, rather than the function directly. In other words, you can do this:

extern crate phrases;
  
  use phrases::english::greetings::hello;
  use phrases::english::farewells::goodbye;
  
  fn main() {
      println!("Hello in English: {}", hello());
      println!("Goodbye in English: {}", goodbye());
  }

But it is not idiomatic. This is significantly more likely to introduce a naming conflict. In our short program, it’s not a big deal, but as it grows, it becomes a problem. If we have conflicting names, Rust will give a compilation error. For example, if we made the japanese functions public, and tried to do this:

extern crate phrases;
  
  use phrases::english::greetings::hello;
  use phrases::japanese::greetings::hello;
  
  fn main() {
      println!("Hello in English: {}", hello());
      println!("Hello in Japanese: {}", hello());
  }

Rust will give us a compile-time error:

   Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
  src/main.rs:4:5: 4:40 error: a value named `hello` has already been imported in this m
  ↳ odule [E0252]
  src/main.rs:4 use phrases::japanese::greetings::hello;
                    ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  error: aborting due to previous error
  Could not compile `phrases`.

If we’re importing multiple names from the same module, we don’t have to type it out twice. Instead of this:

use phrases::english::greetings;
  use phrases::english::farewells;

We can use this shortcut:

use phrases::english::{greetings, farewells};

extern crate phrases;
  
  use phrases::english::{greetings,farewells};
  use phrases::japanese;
  
  fn main() {
      println!("Hello in English: {}", greetings::hello());
      println!("Goodbye in English: {}", farewells::goodbye());
  
      println!("Hello in Japanese: {}", japanese::hello());
      println!("Goodbye in Japanese: {}", japanese::goodbye());
  }

pub mod english;
  pub mod japanese;

pub fn hello() -> String {
      "こんにちは".to_string()
  }

pub fn goodbye() -> String {
      "さようなら".to_string()
  }

pub use self::greetings::hello;
  pub use self::farewells::goodbye;
  
  mod greetings;
  mod farewells;

$ cargo run
     Compiling phrases v0.0.1 (file:///home/you/projects/phrases)
       Running `target/debug/phrases`
  Hello in English: Hello!
  Goodbye in English: Goodbye.
  Hello in Japanese: こんにちは
  Goodbye in Japanese: さようなら

extern crate phrases as sayings;
  
  use sayings::japanese::greetings as ja_greetings;
  use sayings::japanese::farewells::*;
  use sayings::english::{self, greetings as en_greetings, farewells as en_farewells};
  
  fn main() {
      println!("Hello in English; {}", en_greetings::hello());
      println!("And in Japanese: {}", ja_greetings::hello());
      println!("Goodbye in English: {}", english::farewells::goodbye());
      println!("Again: {}", en_farewells::goodbye());
      println!("And in Japanese: {}", goodbye());
  }

use sayings::english;
  use sayings::english::greetings as en_greetings;
  use sayings::english::farewells as en_farewells;

static

Rust provides a ‘global variable’ sort of facility in static items. They’re similar to constants, but static items aren’t inlined upon use. This means that there is only one instance for each value, and it’s at a fixed location in memory.

Here’s an example:

static N: i32 = 5;

Unlike let bindings, you must annotate the type of a static.

Statics live for the entire lifetime of a program, and therefore any reference stored in a constant has a 'static lifetime:

static NAME: &'static str = "Steve";

static mut N: i32 = 5;

  unsafe {
      N += 1;
  
      println!("N: {}", N);
  }

Initializing

Both const and static have requirements for giving them a value. They must be given a value that’s a constant expression. In other words, you cannot use the result of a function call or anything similarly complex or at runtime.

Which construct should I use?

Almost always, if you can choose between the two, choose const. It’s pretty rare that you actually want a memory location associated with your constant, and using a const allows for optimizations like constant propagation not only in your crate but downstream crates.

Coercion

Coercion between types is implicit and has no syntax of its own, but can be spelled out with as.

Coercion occurs in let, const, and static statements; in function call arguments; in field values in struct initialization; and in a function result.

The most common case of coercion is removing mutability from a reference:

• &mut T to &T

An analogous conversion is to remove mutability from a raw pointer:

• *mut T to *const T

References can also be coerced to raw pointers:

• &T to *const T

• &mut T to *mut T

Custom coercions may be defined using Deref.

Coercion is transitive.

as

The as keyword does safe casting:

let x: i32 = 5;
  
  let y = x as i64;

There are three major categories of safe cast: explicit coercions, casts between numeric types, and pointer casts.

Casting is not transitive: even if e as U1 as U2 is a valid expression, e as U2 is not necessarily so (in fact it will only be valid if U1 coerces to U2).

let one = true as u8;
  let at_sign = 64 as char;
  let two_hundred = -56i8 as u8;