Uninstalling

If you decide you don’t want Rust anymore, we’ll be a bit sad, but that’s okay. Not every programming language is great for everyone. Just run the uninstall script:

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

If you used the Windows installer, just re-run the .msi and it will give you an uninstall option.

Some people, and somewhat rightfully so, get very upset when we tell you to curl | sh. Basically, when you do this, you are trusting that the good people who maintain Rust aren’t going to hack your computer and do bad things. That’s a good instinct! If you’re one of those people, please check out the documentation on building Rust from Source, or the official binary downloads.

Oh, we should also mention the officially supported platforms:

• Windows (7, 8, Server 2008 R2)
• Linux (2.6.18 or later, various distributions), x86 and x86-64
• OSX 10.7 (Lion) or greater, x86 and x86-64

We extensively test Rust on these platforms, and a few others, too, like Android. But these are the ones most likely to work, as they have the most testing.

Finally, a comment about Windows. Rust considers Windows to be a first-class platform upon release, but if we’re honest, the Windows experience isn’t as integrated as the Linux/OS X experience is. We’re working on it! If anything does not work, it is a bug. Please let us know if that happens. Each and every commit is tested against Windows just like any other platform.

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

$ rustc --version

You should see the version number, commit hash, commit date and build date:

rustc 1.0.0 (a59de37e9 2015-05-13) (built 2015-05-14)

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

This installer also installs a copy of the documentation locally, so you 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 wherever you installed Rust to.

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

Converting to Cargo

Let’s convert Hello World to Cargo.

To Cargo-ify our project, we need to do two things: Make a Cargo.toml configuration file, and put our source file in the right place. Let’s do that part first:

$ mkdir src
  $ mv main.rs src/main.rs

Note that since we’re creating an executable, we used main.rs. If we want to make a library instead, we should use lib.rs. Custom file locations for the entry point can be specified with a [[lib]] or [[bin]] key in the TOML file described below.

Cargo expects your source files to live inside a src directory. That leaves the top level for other things, like READMEs, license information, and anything not related to your code. Cargo helps us keep our projects nice and tidy. A place for everything, and everything in its place.

Next, our configuration file:

$ editor Cargo.toml

Make sure to get this name right: you need the capital C!

Put this inside:

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

This file is in the TOML format. Let’s let it explain itself to you:

TOML aims to be a minimal configuration file format that’s easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.

TOML is very similar to INI, but with some extra goodies.

Once you have this file in place, we should be ready to build! Try this:

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

Bam! We build our project with cargo build, and run it with ./target/debug/hello_world. We can do both in one step with cargo run:

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

Notice that we didn’t re-build the project this time. Cargo figured out that we hadn’t changed the source file, and so it just ran the binary. If we had made a modification, we would have seen it do both:

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

This hasn’t bought us a whole lot over our simple use of rustc, but think about the future: when our project gets more complex, we would need to do more things to get all of the parts to properly compile. With Cargo, as our project grows, we can just cargo build, and it’ll work the right way.

When your project is finally ready for release, you can use cargo build --release to compile your project with optimizations.

You’ll also notice that Cargo has created a new file: Cargo.lock.

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

This file is used by Cargo to keep track of dependencies in your application. Right now, we don’t have any, so it’s a bit sparse. You won’t ever need to touch this file yourself, just let Cargo handle it.

That’s it! We’ve successfully built hello_world with Cargo. Even though our program is simple, it’s using much of the real tooling that you’ll use for the rest of your Rust career. You can expect to do this to get started with virtually all Rust projects:

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

A New Project

You don’t have to go through this whole process every time you want to start a new project! Cargo has the ability to make a bare-bones project directory in which you can start developing right away.

To start a new project with Cargo, use cargo new:

$ cargo new hello_world --bin

We’re passing --bin because we’re making a binary program: if we were making a library, we’d leave it off.

Let’s check out what Cargo has generated for us:

$ cd hello_world
  $ tree .
  .
  ├── Cargo.toml
  └── src
      └── main.rs
  
  1 directory, 2 files

If you don’t have the tree command, you can probably get it from your distribution’s package manager. It’s not necessary, but it’s certainly useful.

This is all we need to get started. First, let’s check out Cargo.toml:

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

Cargo has populated this file with reasonable defaults based off 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’s in src/main.rs:

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

Cargo has generated a “Hello World!” for us, and you’re ready to start coding! Cargo has its own guide which covers Cargo’s features in much more depth.

Now that you’ve got the tools down, let’s actually learn more about the Rust language itself. These are the basics that will serve you well through the rest of your time with Rust.

You have two options: Dive into a project with ‘Learn Rust’, or start from the bottom and work your way up with ‘Syntax and Semantics’. More experienced systems programmers will probably prefer ‘Learn Rust’, while those from dynamic backgrounds may enjoy either. Different people learn differently! Choose whatever’s right for you.

Set up

Let’s set up a new project. Go to your projects directory. Remember how we had to create our directory structure and a Cargo.toml for hello_world? Cargo has a command that does that for us. Let’s give it a shot:

$ cd ~/projects
  $ cargo new guessing_game --bin
  $ cd guessing_game

We pass the name of our project to cargo new, and then the --bin flag, since we’re making a binary, rather than a library.

Check out the generated Cargo.toml:

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

Cargo gets this information from your environment. If it’s not correct, go ahead and fix that.

Finally, Cargo generated a ‘Hello, world!’ for us. Check out src/main.rs:

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

Let’s try compiling what Cargo gave us:

$ cargo build
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)

Excellent! Open up your src/main.rs again. We’ll be writing all of our code in this file.

Before we move on, let me show you one more Cargo command: run. cargo run is kind of like cargo build, but it also then runs the produced executable. Try it out:

$ cargo run
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
       Running `target/debug/guessing_game`
  Hello, world!

Great! The run command comes in handy when you need to rapidly iterate on a project. Our game is just such a project, we need to quickly test each iteration before moving on to the next one.

Processing a Guess

Let’s get to it! The first thing we need to do for our guessing game is allow our player to input a guess. Put this in your src/main.rs:

use std::io;
  
  fn main() {
      println!("Guess the number!");
  
      println!("Please input your guess.");
  
      let mut guess = String::new();
  
      io::stdin().read_line(&mut guess)
          .ok()
          .expect("Failed to read line");
  
      println!("You guessed: {}", guess);
  }

There’s a lot here! Let’s go over it, bit by bit.

use std::io;

We’ll need to take user input, and then print the result as output. As such, we need the io library from the standard library. Rust only imports a few things into every program, the ‘prelude’. If it’s not in the prelude, you’ll have to use it directly.

fn main() {

As you’ve seen before, the main() function is the entry point into your program. The fn syntax declares a new function, the ()s indicate that there are no arguments, and { starts the body of the function. Because we didn’t include a return type, it’s assumed to be (), an empty tuple.

    println!("Guess the number!");
  
      println!("Please input your guess.");

We previously learned that println!() is a macro that prints a string to the screen.

    let mut guess = String::new();

Now we’re getting interesting! There’s a lot going on in this little line. The first thing to notice is that this is a let statement, which is used to create ‘variable bindings’. They take this form:

let foo = bar;

This will create a new binding named foo, and bind it to the value bar. In many languages, this is called a ‘variable’, but Rust’s variable bindings have a few tricks up their sleeves.

For example, they’re immutable by default. That’s why our example uses mut: it makes a binding mutable, rather than immutable. let doesn’t take a name on the left hand side, it actually accepts a ‘pattern’. We’ll use patterns later. It’s easy enough to use for now:

let foo = 5; // immutable.
  let mut bar = 5; // mutable

Oh, and // will start a comment, until the end of the line. Rust ignores everything in comments.

So now we know that let mut guess will introduce a mutable binding named guess, but we have to look at the other side of the = for what it’s bound to: String::new().

String is a string type, provided by the standard library. A String is a growable, UTF-8 encoded bit of text.

The ::new() syntax uses :: because this is an ‘associated function’ of a particular type. That is to say, it’s associated with String itself, rather than a particular instance of a String. Some languages call this a ‘static method’.

This function is named new(), because it creates a new, empty String. You’ll find a new() function on many types, as it’s a common name for making a new value of some kind.

Let’s move forward:

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

That’s a lot more! Let’s go bit-by-bit. The first line has two parts. Here’s the first:

io::stdin()

Remember how we used std::io on the first line of the program? We’re now calling an associated function on it. If we didn’t use std::io, we could have written this line as std::io::stdin().

This particular function returns a handle to the standard input for your terminal. More specifically, a std::io::Stdin.

The next part will use this handle to get input from the user:

.read_line(&mut guess)

Here, we call the read_line() method on our handle. Methods are like associated functions, but are only available on a particular instance of a type, rather than the type itself. We’re also passing one argument to read_line(): &mut guess.

Remember how we bound guess above? We said it was mutable. However, read_line doesn’t take a String as an argument: it takes a &mut String. Rust has a feature called ‘references’, which allows you to have multiple references to one piece of data, which can reduce copying. References are a complex feature, as one of Rust’s major selling points is how safe and easy it is to use references. We don’t need to know a lot of those details to finish our program right now, though. For now, all we need to know is that like let bindings, references are immutable by default. Hence, we need to write &mut guess, rather than &guess.

Why does read_line() take a mutable reference to a string? Its job is to take what the user types into standard input, and place that into a string. So it takes that string as an argument, and in order to add the input, it needs to be mutable.

But we’re not quite done with this line of code, though. While it’s a single line of text, it’s only the first part of the single logical line of code:

        .ok()
          .expect("Failed to read line");

When you call a method with the .foo() syntax, you may introduce a newline and other whitespace. This helps you split up long lines. We could have done:

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

But that gets hard to read. So we’ve split it up, three lines for three method calls. We already talked about read_line(), but what about ok() and expect()? Well, we already mentioned that read_line() puts what the user types into the &mut String we pass it. But it also returns a value: in this case, an io::Result. Rust has a number of types named Result in its standard library: a generic Result, and then specific versions for sub-libraries, like io::Result.

The purpose of these Result types is to encode error handling information. Values of the Result type, like any type, have methods defined on them. In this case, io::Result has an ok() method, which says ‘we want to assume this value is a successful one. If not, just throw away the error information’. Why throw it away? Well, for a basic program, we just want to print a generic error, as basically any issue means we can’t continue. The ok() method returns a value which has another method defined on it: expect(). The expect() method takes a value it’s called on, and if it isn’t a successful one, panic!s with a message you passed it. A panic! like this will cause our program to crash, displaying the message.

If we leave off calling these two methods, our program will compile, but we’ll get a warning:

$ cargo build
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
  src/main.rs:10:5: 10:39 warning: unused result which must be used,
  #[warn(unused_must_use)] on by default
  src/main.rs:10     io::stdin().read_line(&mut guess);
                     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Rust warns us that we haven’t used the Result value. This warning comes from a special annotation that io::Result has. Rust is trying to tell you that you haven’t handled a possible error. The right way to suppress the error is to actually write error handling. Luckily, if we just want to crash if there’s a problem, we can use these two little methods. If we can recover from the error somehow, we’d do something else, but we’ll save that for a future project.

There’s just one line of this first example left:

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

This prints out the string we saved our input in. The {}s are a placeholder, and so we pass it guess as an argument. If we had multiple {}s, we would pass multiple arguments:

let x = 5;
  let y = 10;
  
  println!("x and y: {} and {}", x, y);

Easy.

Anyway, that’s the tour. We can run what we have with cargo run:

$ cargo run
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
       Running `target/debug/guessing_game`
  Guess the number!
  Please input your guess.
  6
  You guessed: 6

All right! Our first part is done: we can get input from the keyboard, and then print it back out.

Generating a secret number

Next, we need to generate a secret number. Rust does not yet include random number functionality in its standard library. The Rust team does, however, provide a rand crate. A ‘crate’ is a package of Rust code. We’ve been building a ‘binary crate’, which is an executable. rand is a ‘library crate’, which contains code that’s intended to be used with other programs.

Using external crates is where Cargo really shines. Before we can write the code using rand, we need to modify our Cargo.toml. Open it up, and add these few lines at the bottom:

[dependencies]
  
  rand="0.3.0"

The [dependencies] section of Cargo.toml is like the [package] section: everything that follows it is part of it, until the next section starts. Cargo uses the dependencies section to know what dependencies on external crates you have, and what versions you require. In this case, we’ve used version 0.3.0. Cargo understands Semantic Versioning, which is a standard for writing version numbers. If we wanted to use the latest version we could use * or we could use a range of versions. Cargo’s documentation contains more details.

Now, without changing any of our code, let’s build our project:

$ cargo build
      Updating registry `https://github.com/rust-lang/crates.io-index`
   Downloading rand v0.3.8
   Downloading libc v0.1.6
     Compiling libc v0.1.6
     Compiling rand v0.3.8
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)

(You may see different versions, of course.)

Lots of new output! Now that we have an external dependency, Cargo fetches the latest versions of everything from the registry, which is a copy of data from Crates.io. Crates.io is where people in the Rust ecosystem post their open source Rust projects for others to use.

After updating the registry, Cargo checks our [dependencies] and downloads any we don’t have yet. In this case, while we only said we wanted to depend on rand, we’ve also grabbed a copy of libc. This is because rand depends on libc to work. After downloading them, it compiles them, and then compiles our project.

If we run cargo build again, we’ll get different output:

$ cargo build

That’s right, no output! Cargo knows that our project has been built, and that all of its dependencies are built, and so there’s no reason to do all that stuff. With nothing to do, it simply exits. If we open up src/main.rs again, make a trivial change, and then save it again, we’ll just see one line:

$ cargo build
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)

So, we told Cargo we wanted any 0.3.x version of rand, and so it fetched the latest version at the time this was written, v0.3.8. But what happens when next week, version v0.3.9 comes out, with an important bugfix? While getting bugfixes is important, what if 0.3.9 contains a regression that breaks our code?

The answer to this problem is the Cargo.lock file you’ll now find in your project directory. When you build your project for the first time, Cargo figures out all of the versions that fit your criteria, and then writes them to the Cargo.lock file. When you build your project in the future, Cargo will see that the Cargo.lock file exists, and then use that specific version rather than do all the work of figuring out versions again. This lets you have a repeatable build automatically. In other words, we’ll stay at 0.3.8 until we explicitly upgrade, and so will anyone who we share our code with, thanks to the lock file.

What about when we do want to use v0.3.9? Cargo has another command, update, which says ‘ignore the lock, figure out all the latest versions that fit what we’ve specified. If that works, write those versions out to the lock file’. But, by default, Cargo will only look for versions larger than 0.3.0 and smaller than 0.4.0. If we want to move to 0.4.x, we’d have to update the Cargo.toml directly. When we do, the next time we cargo build, Cargo will update the index and re-evaluate our rand requirements.

There’s a lot more to say about Cargo and its ecosystem, but for now, that’s all we need to know. Cargo makes it really easy to re-use libraries, and so Rustaceans tend to write smaller projects which are assembled out of a number of sub-packages.

Let’s get on to actually using rand. Here’s our next step:

extern crate rand;
  
  use std::io;
  use rand::Rng;
  
  fn main() {
      println!("Guess the number!");
  
      let secret_number = rand::thread_rng().gen_range(1, 101);
  
      println!("The secret number is: {}", secret_number);
  
      println!("Please input your guess.");
  
      let mut guess = String::new();
  
      io::stdin().read_line(&mut guess)
          .ok()
          .expect("failed to read line");
  
      println!("You guessed: {}", guess);
  }

The first thing we’ve done is change the first line. It now says extern crate rand. Because we declared rand in our [dependencies], we can use extern crate to let Rust know we’ll be making use of it. This also does the equivalent of a use rand; as well, so we can make use of anything in the rand crate by prefixing it with rand::.

Next, we added another use line: use rand::Rng. We’re going to use a method in a moment, and it requires that Rng be in scope to work. The basic idea is this: methods are defined on something called ‘traits’, and for the method to work, it needs the trait to be in scope. For more about the details, read the traits section.

There are two other lines we added, in the middle:

    let secret_number = rand::thread_rng().gen_range(1, 101);
  
      println!("The secret number is: {}", secret_number);

We use the rand::thread_rng() function to get a copy of the random number generator, which is local to the particular thread of execution we’re in. Because we use rand::Rng’d above, it has a gen_range() method available. This method takes two arguments, and generates a number between them. It’s inclusive on the lower bound, but exclusive on the upper bound, so we need 1 and 101 to get a number between one and a hundred.

The second line just prints out the secret number. This is useful while we’re developing our program, so we can easily test it out. But we’ll be deleting it for the final version. It’s not much of a game if it prints out the answer when you start it up!

Try running our new program a few times:

$ cargo run
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
       Running `target/debug/guessing_game`
  Guess the number!
  The secret number is: 7
  Please input your guess.
  4
  You guessed: 4
  $ cargo run
       Running `target/debug/guessing_game`
  Guess the number!
  The secret number is: 83
  Please input your guess.
  5
  You guessed: 5

Great! Next up: let’s compare our guess to the secret guess.

Comparing guesses

Now that we’ve got user input, let’s compare our guess to the random guess. Here’s our next step, though it doesn’t quite work yet:

extern crate rand;
  
  use std::io;
  use std::cmp::Ordering;
  use rand::Rng;
  
  fn main() {
      println!("Guess the number!");
  
      let secret_number = rand::thread_rng().gen_range(1, 101);
  
      println!("The secret number is: {}", secret_number);
  
      println!("Please input your guess.");
  
      let mut guess = String::new();
  
      io::stdin().read_line(&mut guess)
          .ok()
          .expect("failed to read line");
  
      println!("You guessed: {}", guess);
  
      match guess.cmp(&secret_number) {
          Ordering::Less    => println!("Too small!"),
          Ordering::Greater => println!("Too big!"),
          Ordering::Equal   => println!("You win!"),
      }
  }

A few new bits here. The first is another use. We bring a type called std::cmp::Ordering into scope. Then, five new lines at the bottom that use it:

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

The cmp() method can be called on anything that can be compared, and it takes a reference to the thing you want to compare it to. It returns the Ordering type we used earlier. We use a match statement to determine exactly what kind of Ordering it is. Ordering is an enum, short for ‘enumeration’, which looks like this:

enum Foo {
      Bar,
      Baz,
  }

With this definition, anything of type Foo can be either a Foo::Bar or a Foo::Baz. We use the :: to indicate the namespace for a particular enum variant.

The Ordering enum has three possible variants: Less, Equal, and Greater. The match statement takes a value of a type, and lets you create an ‘arm’ for each possible value. Since we have three types of Ordering, we have three arms:

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

If it’s Less, we print Too small!, if it’s Greater, Too big!, and if Equal, You win!. match is really useful, and is used often in Rust.

I did mention that this won’t quite work yet, though. Let’s try it:

$ cargo build
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
  src/main.rs:28:21: 28:35 error: mismatched types:
   expected `&collections::string::String`,
      found `&_`
  (expected struct `collections::string::String`,
      found integral variable) [E0308]
  src/main.rs:28     match guess.cmp(&secret_number) {
                                     ^~~~~~~~~~~~~~
  error: aborting due to previous error
  Could not compile `guessing_game`.

Whew! This is a big error. The core of it is that we have ‘mismatched types’. Rust has a strong, static type system. However, it also has type inference. When we wrote let guess = String::new(), Rust was able to infer that guess should be a String, and so it doesn’t make us write out the type. And with our secret_number, there are a number of types which can have a value between one and a hundred: i32, a thirty-two-bit number, or u32, an unsigned thirty-two-bit number, or i64, a sixty-four-bit number or others. So far, that hasn’t mattered, and so Rust defaults to an i32. However, here, Rust doesn’t know how to compare the guess and the secret_number. They need to be the same type. Ultimately, we want to convert the String we read as input into a real number type, for comparison. We can do that with three more lines. Here’s our new program:

extern crate rand;
  
  use std::io;
  use std::cmp::Ordering;
  use rand::Rng;
  
  fn main() {
      println!("Guess the number!");
  
      let secret_number = rand::thread_rng().gen_range(1, 101);
  
      println!("The secret number is: {}", secret_number);
  
      println!("Please input your guess.");
  
      let mut guess = String::new();
  
      io::stdin().read_line(&mut guess)
          .ok()
          .expect("failed to read line");
  
      let guess: u32 = guess.trim().parse()
          .ok()
          .expect("Please type a number!");
  
      println!("You guessed: {}", guess);
  
      match guess.cmp(&secret_number) {
          Ordering::Less    => println!("Too small!"),
          Ordering::Greater => println!("Too big!"),
          Ordering::Equal   => println!("You win!"),
      }
  }

The new three lines:

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

Wait a minute, I thought we already had a guess? We do, but Rust allows us to ‘shadow’ the previous guess with a new one. This is often used in this exact situation, where guess starts as a String, but we want to convert it to an u32. Shadowing lets us re-use the guess name, rather than forcing us to come up with two unique names like guess_str and guess, or something else.

We bind guess to an expression that looks like something we wrote earlier:

guess.trim().parse()

Followed by an ok().expect() invocation. Here, guess refers to the old guess, the one that was a String with our input in it. The trim() method on Strings will eliminate any white space at the beginning and end of our string. This is important, as we had to press the ‘return’ key to satisfy read_line(). This means that if we type 5 and hit return, guess looks like this: 5\n. The \n represents ‘newline’, the enter key. trim() gets rid of this, leaving our string with just the 5. The parse() method on strings parses a string into some kind of number. Since it can parse a variety of numbers, we need to give Rust a hint as to the exact type of number we want. Hence, let guess: u32. The colon (:) after guess tells Rust we’re going to annotate its type. u32 is an unsigned, thirty-two bit integer. Rust has a number of built-in number types, but we’ve chosen u32. It’s a good default choice for a small positive number.

Just like read_line(), our call to parse() could cause an error. What if our string contained A👍%? There’d be no way to convert that to a number. As such, we’ll do the same thing we did with read_line(): use the ok() and expect() methods to crash if there’s an error.

Let’s try our program out!

$ cargo run
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
       Running `target/guessing_game`
  Guess the number!
  The secret number is: 58
  Please input your guess.
    76
  You guessed: 76
  Too big!

Nice! You can see I even added spaces before my guess, and it still figured out that I guessed 76. Run the program a few times, and verify that guessing the number works, as well as guessing a number too small.

Now we’ve got most of the game working, but we can only make one guess. Let’s change that by adding loops!

Looping

The loop keyword gives us an infinite loop. Let’s add that in:

extern crate rand;
  
  use std::io;
  use std::cmp::Ordering;
  use rand::Rng;
  
  fn main() {
      println!("Guess the number!");
  
      let secret_number = rand::thread_rng().gen_range(1, 101);
  
      println!("The secret number is: {}", secret_number);
  
      loop {
          println!("Please input your guess.");
  
          let mut guess = String::new();
  
          io::stdin().read_line(&mut guess)
              .ok()
              .expect("failed to read line");
  
          let guess: u32 = guess.trim().parse()
              .ok()
              .expect("Please type a number!");
  
          println!("You guessed: {}", guess);
  
          match guess.cmp(&secret_number) {
              Ordering::Less    => println!("Too small!"),
              Ordering::Greater => println!("Too big!"),
              Ordering::Equal   => println!("You win!"),
          }
      }
  }

And try it out. But wait, didn’t we just add an infinite loop? Yup. Remember our discussion about parse()? If we give a non-number answer, we’ll return and quit. Observe:

$ cargo run
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
       Running `target/guessing_game`
  Guess the number!
  The secret number is: 59
  Please input your guess.
  45
  You guessed: 45
  Too small!
  Please input your guess.
  60
  You guessed: 60
  Too big!
  Please input your guess.
  59
  You guessed: 59
  You win!
  Please input your guess.
  quit
  thread '<main>' panicked at 'Please type a number!'

Ha! quit actually quits. As does any other non-number input. Well, this is suboptimal to say the least. First, let’s actually quit when you win the game:

extern crate rand;
  
  use std::io;
  use std::cmp::Ordering;
  use rand::Rng;
  
  fn main() {
      println!("Guess the number!");
  
      let secret_number = rand::thread_rng().gen_range(1, 101);
  
      println!("The secret number is: {}", secret_number);
  
      loop {
          println!("Please input your guess.");
  
          let mut guess = String::new();
  
          io::stdin().read_line(&mut guess)
              .ok()
              .expect("failed to read line");
  
          let guess: u32 = guess.trim().parse()
              .ok()
              .expect("Please type a number!");
  
          println!("You guessed: {}", guess);
  
          match guess.cmp(&secret_number) {
              Ordering::Less    => println!("Too small!"),
              Ordering::Greater => println!("Too big!"),
              Ordering::Equal   => {
                  println!("You win!");
                  break;
              }
          }
      }
  }

By adding the break line after the You win!, we’ll exit the loop when we win. Exiting the loop also means exiting the program, since it’s the last thing in main(). We have just one more tweak to make: when someone inputs a non-number, we don’t want to quit, we just want to ignore it. We can do that like this:

extern crate rand;
  
  use std::io;
  use std::cmp::Ordering;
  use rand::Rng;
  
  fn main() {
      println!("Guess the number!");
  
      let secret_number = rand::thread_rng().gen_range(1, 101);
  
      println!("The secret number is: {}", secret_number);
  
      loop {
          println!("Please input your guess.");
  
          let mut guess = String::new();
  
          io::stdin().read_line(&mut guess)
              .ok()
              .expect("failed to read line");
  
          let guess: u32 = match guess.trim().parse() {
              Ok(num) => num,
              Err(_) => continue,
          };
  
          println!("You guessed: {}", guess);
  
          match guess.cmp(&secret_number) {
              Ordering::Less    => println!("Too small!"),
              Ordering::Greater => println!("Too big!"),
              Ordering::Equal   => {
                  println!("You win!");
                  break;
              }
          }
      }
  }

These are the lines that changed:

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

This is how you generally move from ‘crash on error’ to ‘actually handle the error’, by switching from ok().expect() to a match statement. The Result returned by parse() is an enum just like Ordering, but in this case, each variant has some data associated with it: Ok is a success, and Err is a failure. Each contains more information: the successful parsed integer, or an error type. In this case, we match on Ok(num), which sets the inner value of the Ok to the name num, and then we just return it on the right-hand side. In the Err case, we don’t care what kind of error it is, so we just use _ instead of a name. This ignores the error, and continue causes us to go to the next iteration of the loop.

Now we should be good! Let’s try:

$ cargo run
     Compiling guessing_game v0.1.0 (file:///home/you/projects/guessing_game)
       Running `target/guessing_game`
  Guess the number!
  The secret number is: 61
  Please input your guess.
  10
  You guessed: 10
  Too small!
  Please input your guess.
  99
  You guessed: 99
  Too big!
  Please input your guess.
  foo
  Please input your guess.
  61
  You guessed: 61
  You win!

Awesome! With one tiny last tweak, we have finished the guessing game. Can you think of what it is? That’s right, we don’t want to print out the secret number. It was good for testing, but it kind of ruins the game. Here’s our final source:

extern crate rand;
  
  use std::io;
  use std::cmp::Ordering;
  use rand::Rng;
  
  fn main() {
      println!("Guess the number!");
  
      let secret_number = rand::thread_rng().gen_range(1, 101);
  
      loop {
          println!("Please input your guess.");
  
          let mut guess = String::new();
  
          io::stdin().read_line(&mut guess)
              .ok()
              .expect("failed to read line");
  
          let guess: u32 = match guess.trim().parse() {
              Ok(num) => num,
              Err(_) => continue,
          };
  
          println!("You guessed: {}", guess);
  
          match guess.cmp(&secret_number) {
              Ordering::Less    => println!("Too small!"),
              Ordering::Greater => println!("Too big!"),
              Ordering::Equal   => {
                  println!("You win!");
                  break;
              }
          }
      }
  }

Complete!

At this point, you have successfully built the Guessing Game! Congratulations!

This first project showed you a lot: let, match, methods, associated functions, using external crates, and more. Our next project will show off even more.

The problem

There are many different projects we could choose here, but we’re going to pick an example where Rust has a clear advantage over many other languages: numeric computing and threading.

Many languages, for the sake of consistency, place numbers on the heap, rather than on the stack. Especially in languages that focus on object-oriented programming and use garbage collection, heap allocation is the default. Sometimes optimizations can stack allocate particular numbers, but rather than relying on an optimizer to do its job, we may want to ensure that we’re always using primitive number types rather than some sort of object type.

Second, many languages have a ‘global interpreter lock’ (GIL), which limits concurrency in many situations. This is done in the name of safety, which is a positive effect, but it limits the amount of work that can be done at the same time, which is a big negative.

To emphasize these two aspects, we’re going to create a little project that uses these two aspects heavily. Since the focus of the example is to embed Rust into other languages, rather than the problem itself, we’ll just use a toy example:

Start ten threads. Inside each thread, count from one to five million. After all ten threads are finished, print out ‘done!’.

I chose five million based on my particular computer. Here’s an example of this code in Ruby:

threads = []
  
  10.times do
    threads << Thread.new do
      count = 0
  
      5_000_000.times do
        count += 1
      end
    end
  end
  
  threads.each { |t| t.join }
  puts "done!"

Try running this example, and choose a number that runs for a few seconds. Depending on your computer’s hardware, you may have to increase or decrease the number.

On my system, running this program takes 2.156 seconds. And, if I use some sort of process monitoring tool, like top, I can see that it only uses one core on my machine. That’s the GIL kicking in.

While it’s true that this is a synthetic program, one can imagine many problems that are similar to this in the real world. For our purposes, spinning up a few busy threads represents some sort of parallel, expensive computation.

A Rust library

Let’s rewrite this problem in Rust. First, let’s make a new project with Cargo:

$ cargo new embed
  $ cd embed

This program is fairly easy to write in Rust:

use std::thread;
  
  fn process() {
      let handles: Vec<_> = (0..10).map(|_| {
          thread::spawn(|| {
              let mut _x = 0;
              for _ in (0..5_000_000) {
                  _x += 1
              }
          })
      }).collect();
  
      for h in handles {
          h.join().ok().expect("Could not join a thread!");
      }
  }

Some of this should look familiar from previous examples. We spin up ten threads, collecting them into a handles vector. Inside of each thread, we loop five million times, and add one to _x each time. Why the underscore? Well, if we remove it and compile:

$ cargo build
     Compiling embed v0.1.0 (file:///home/steve/src/embed)
  src/lib.rs:3:1: 16:2 warning: function is never used: `process`, #[warn(dead_code)] on
  ↳  by default
  src/lib.rs:3 fn process() {
  src/lib.rs:4     let handles: Vec<_> = (0..10).map(|_| {
  src/lib.rs:5         thread::spawn(|| {
  src/lib.rs:6             let mut x = 0;
  src/lib.rs:7             for _ in (0..5_000_000) {
  src/lib.rs:8                 x += 1
               ...
  src/lib.rs:6:17: 6:22 warning: variable `x` is assigned to, but never used, #[warn(unu
  ↳ sed_variables)] on by default
  src/lib.rs:6             let mut x = 0;
                               ^~~~~

That first warning is because we are building a library. If we had a test for this function, the warning would go away. But for now, it’s never called.

The second is related to x versus _x. Because we never actually do anything with x, we get a warning about it. In our case, that’s perfectly okay, as we’re just trying to waste CPU cycles. Prefixing x with the underscore removes the warning.

Finally, we join on each thread.

Right now, however, this is a Rust library, and it doesn’t expose anything that’s callable from C. If we tried to hook this up to another language right now, it wouldn’t work. We only need to make two small changes to fix this, though. The first is to modify the beginning of our code:

#[no_mangle]
  pub extern fn process() {

We have to add a new attribute, no_mangle. When you create a Rust library, it changes the name of the function in the compiled output. The reasons for this are outside the scope of this tutorial, but in order for other languages to know how to call the function, we can’t do that. This attribute turns that behavior off.

The other change is the pub extern. The pub means that this function should be callable from outside of this module, and the extern says that it should be able to be called from C. That’s it! Not a whole lot of change.

The second thing we need to do is to change a setting in our Cargo.toml. Add this at the bottom:

[lib]
  name = "embed"
  crate-type = ["dylib"]

This tells Rust that we want to compile our library into a standard dynamic library. By default, Rust compiles an ‘rlib’, a Rust-specific format.

Let’s build the project now:

$ cargo build --release
     Compiling embed v0.1.0 (file:///home/steve/src/embed)

We’ve chosen cargo build --release, which builds with optimizations on. We want this to be as fast as possible! You can find the output of the library in target/release:

$ ls target/release/
  build  deps  examples  libembed.so  native

That libembed.so is our ‘shared object’ library. We can use this file just like any shared object library written in C! As an aside, this may be embed.dll or libembed.dylib, depending on the platform.

Now that we’ve got our Rust library built, let’s use it from our Ruby.

Ruby

Open up an embed.rb file inside of our project, and do this:

require 'ffi'
  
  module Hello
    extend FFI::Library
    ffi_lib 'target/release/libembed.so'
    attach_function :process, [], :void
  end
  
  Hello.process
  
  puts 'done!'

Before we can run this, we need to install the ffi gem:

$ gem install ffi # this may need sudo
  Fetching: ffi-1.9.8.gem (100%)
  Building native extensions.  This could take a while...
  Successfully installed ffi-1.9.8
  Parsing documentation for ffi-1.9.8
  Installing ri documentation for ffi-1.9.8
  Done installing documentation for ffi after 0 seconds
  1 gem installed

And finally, we can try running it:

$ ruby embed.rb
  done!
  $

Whoa, that was fast! On my system, this took 0.086 seconds, rather than the two seconds the pure Ruby version took. Let’s break down this Ruby code:

require 'ffi'

We first need to require the ffi gem. This lets us interface with our Rust library like a C library.

module Hello
    extend FFI::Library
    ffi_lib 'target/release/libembed.so'

The Hello module is used to attach the native functions from the shared library. Inside, we extend the necessary FFI::Library module and then call ffi_lib to load up our shared object library. We just pass it the path that our library is stored, which, as we saw before, is target/release/libembed.so.

attach_function :process, [], :void

The attach_function method is provided by the FFI gem. It’s what connects our process() function in Rust to a Ruby function of the same name. Since process() takes no arguments, the second parameter is an empty array, and since it returns nothing, we pass :void as the final argument.

Hello.process

This is the actual call into Rust. The combination of our module and the call to attach_function sets this all up. It looks like a Ruby function but is actually Rust!

puts 'done!'

Finally, as per our project’s requirements, we print out done!.

That’s it! As we’ve seen, bridging between the two languages is really easy, and buys us a lot of performance.

Next, let’s try Python!

Python

Create an embed.py file in this directory, and put this in it:

from ctypes import cdll
  
  lib = cdll.LoadLibrary("target/release/libembed.so")
  
  lib.process()
  
  print("done!")

Even easier! We use cdll from the ctypes module. A quick call to LoadLibrary later, and we can call process().

On my system, this takes 0.017 seconds. Speedy!

Node.js

Node isn’t a language, but it’s currently the dominant implementation of server-side JavaScript.

In order to do FFI with Node, we first need to install the library:

$ npm install ffi

After that installs, we can use it:

var ffi = require('ffi');
  
  var lib = ffi.Library('target/release/libembed', {
    'process': ['void', []]
  });
  
  lib.process();
  
  console.log("done!");

It looks more like the Ruby example than the Python example. We use the ffi module to get access to ffi.Library(), which loads up our shared object. We need to annotate the return type and argument types of the function, which are void for return and an empty array to signify no arguments. From there, we just call it and print the result.

On my system, this takes a quick 0.092 seconds.

Conclusion

As you can see, the basics of doing this are very easy. Of course, there’s a lot more that we could do here. Check out the FFI chapter for more details.

Memory management

These two terms are about memory management. The stack and the heap are abstractions that help you determine when to allocate and deallocate memory.

Here’s a high-level comparison:

The stack is very fast, and is where memory is allocated in Rust by default. But the allocation is local to a function call, and is limited in size. The heap, on the other hand, is slower, and is explicitly allocated by your program. But it’s effectively unlimited in size, and is globally accessible.

The Stack

Let’s talk about this Rust program:

fn main() {
      let x = 42;
  }

This program has one variable binding, x. This memory needs to be allocated from somewhere. Rust ‘stack allocates’ by default, which means that basic values ‘go on the stack’. What does that mean?

Well, when a function gets called, some memory gets allocated for all of its local variables and some other information. This is called a ‘stack frame’, and for the purpose of this tutorial, we’re going to ignore the extra information and just consider the local variables we’re allocating. So in this case, when main() is run, we’ll allocate a single 32-bit integer for our stack frame. This is automatically handled for you, as you can see, we didn’t have to write any special Rust code or anything.

When the function is over, its stack frame gets deallocated. This happens automatically, we didn’t have to do anything special here.

That’s all there is for this simple program. The key thing to understand here is that stack allocation is very, very fast. Since we know all the local variables we have ahead of time, we can grab the memory all at once. And since we’ll throw them all away at the same time as well, we can get rid of it very fast too.

The downside is that we can’t keep values around if we need them for longer than a single function. We also haven’t talked about what that name, ‘stack’ means. To do that, we need a slightly more complicated example:

fn foo() {
      let y = 5;
      let z = 100;
  }
  
  fn main() {
      let x = 42;
  
      foo();
  }

This program has three variables total: two in foo(), one in main(). Just as before, when main() is called, a single integer is allocated for its stack frame. But before we can show what happens when foo() is called, we need to visualize what’s going on with memory. Your operating system presents a view of memory to your program that’s pretty simple: a huge list of addresses, from 0 to a large number, representing how much RAM your computer has. For example, if you have a gigabyte of RAM, your addresses go from 0 to 1,073,741,824. That number comes from 2³⁰, the number of bytes in a gigabyte.

This memory is kind of like a giant array: addresses start at zero and go up to the final number. So here’s a diagram of our first stack frame:

We’ve got x located at address 0, with the value 42.

When foo() is called, a new stack frame is allocated:

Because 0 was taken by the first frame, 1 and 2 are used for foo()’s stack frame. It grows upward, the more functions we call.

There’s some important things we have to take note of here. The numbers 0, 1, and 2 are all solely for illustrative purposes, and bear no relationship to the actual numbers the computer will actually use. In particular, the series of addresses are in reality going to be separated by some number of bytes that separate each address, and that separation may even exceed the size of the value being stored.

After foo() is over, its frame is deallocated:

And then, after main(), even this last value goes away. Easy!

It’s called a ‘stack’ because it works like a stack of dinner plates: the first plate you put down is the last plate to pick back up. Stacks are sometimes called ‘last in, first out queues’ for this reason, as the last value you put on the stack is the first one you retrieve from it.

Let’s try a three-deep example:

fn bar() {
      let i = 6;
  }
  
  fn foo() {
      let a = 5;
      let b = 100;
      let c = 1;
  
      bar();
  }
  
  fn main() {
      let x = 42;
  
      foo();
  }

Okay, first, we call main():

Next up, main() calls foo():

And then foo() calls bar():

Whew! Our stack is growing tall.

After bar() is over, its frame is deallocated, leaving just foo() and main():

And then foo() ends, leaving just main()

And then we’re done. Getting the hang of it? It’s like piling up dishes: you add to the top, you take away from the top.

The Heap

Now, this works pretty well, but not everything can work like this. Sometimes, you need to pass some memory between different functions, or keep it alive for longer than a single function’s execution. For this, we can use the heap.

In Rust, you can allocate memory on the heap with the Box<T> type. Here’s an example:

fn main() {
      let x = Box::new(5);
      let y = 42;
  }

Here’s what happens in memory when main() is called:

We allocate space for two variables on the stack. y is 42, as it always has been, but what about x? Well, x is a Box<i32>, and boxes allocate memory on the heap. The actual value of the box is a structure which has a pointer to ‘the heap’. When we start executing the function, and Box::new() is called, it allocates some memory for the heap, and puts 5 there. The memory now looks like this:

We have 2³⁰ in our hypothetical computer with 1GB of RAM. And since our stack grows from zero, the easiest place to allocate memory is from the other end. So our first value is at the highest place in memory. And the value of the struct at x has a raw pointer to the place we’ve allocated on the heap, so the value of x is 2³⁰, the memory location we’ve asked for.

We haven’t really talked too much about what it actually means to allocate and deallocate memory in these contexts. Getting into very deep detail is out of the scope of this tutorial, but what’s important to point out here is that the heap isn’t just a stack that grows from the opposite end. We’ll have an example of this later in the book, but because the heap can be allocated and freed in any order, it can end up with ‘holes’. Here’s a diagram of the memory layout of a program which has been running for a while now:

In this case, we’ve allocated four things on the heap, but deallocated two of them. There’s a gap between 2³⁰ and (2³⁰) - 3 which isn’t currently being used. The specific details of how and why this happens depends on what kind of strategy you use to manage the heap. Different programs can use different ‘memory allocators’, which are libraries that manage this for you. Rust programs use jemalloc for this purpose.

Anyway, back to our example. Since this memory is on the heap, it can stay alive longer than the function which allocates the box. In this case, however, it doesn’t.¹ When the function is over, we need to free the stack frame for main(). Box<T>, though, has a trick up its sleeve: Drop. The implementation of Drop for Box deallocates the memory that was allocated when it was created. Great! So when x goes away, it first frees the memory allocated on the heap:

And then the stack frame goes away, freeing all of our memory.

Arguments and borrowing

We’ve got some basic examples with the stack and the heap going, but what about function arguments and borrowing? Here’s a small Rust program:

fn foo(i: &i32) {
      let z = 42;
  }
  
  fn main() {
      let x = 5;
      let y = &x;
  
      foo(y);
  }

When we enter main(), memory looks like this:

x is a plain old 5, and y is a reference to x. So its value is the memory location that x lives at, which in this case is 0.

What about when we call foo(), passing y as an argument?

Stack frames aren’t just for local bindings, they’re for arguments too. So in this case, we need to have both i, our argument, and z, our local variable binding. i is a copy of the argument, y. Since y’s value is 0, so is i’s.

This is one reason why borrowing a variable doesn’t deallocate any memory: the value of a reference is just a pointer to a memory location. If we got rid of the underlying memory, things wouldn’t work very well.

A complex example

Okay, let’s go through this complex program step-by-step:

fn foo(x: &i32) {
      let y = 10;
      let z = &y;
  
      baz(z);
      bar(x, z);
  }
  
  fn bar(a: &i32, b: &i32) {
      let c = 5;
      let d = Box::new(5);
      let e = &d;
  
      baz(e);
  }
  
  fn baz(f: &i32) {
      let g = 100;
  }
  
  fn main() {
      let h = 3;
      let i = Box::new(20);
      let j = &h;
  
      foo(j);
  }

First, we call main():

We allocate memory for j, i, and h. i is on the heap, and so has a value pointing there.

Next, at the end of main(), foo() gets called:

Space gets allocated for x, y, and z. The argument x has the same value as j, since that’s what we passed it in. It’s a pointer to the 0 address, since j points at h.

Next, foo() calls baz(), passing z:

We’ve allocated memory for f and g. baz() is very short, so when it’s over, we get rid of its stack frame:

Next, foo() calls bar() with x and z:

We end up allocating another value on the heap, and so we have to subtract one from 2³⁰. It’s easier to just write that than 1,073,741,823. In any case, we set up the variables as usual.

At the end of bar(), it calls baz():

With this, we’re at our deepest point! Whew! Congrats for following along this far.

After baz() is over, we get rid of f and g:

Next, we return from bar(). d in this case is a Box<T>, so it also frees what it points to: (2³⁰) - 1.

And after that, foo() returns:

And then, finally, main(), which cleans the rest up. When i is Dropped, it will clean up the last of the heap too.

What do other languages do?

Most languages with a garbage collector heap-allocate by default. This means that every value is boxed. There are a number of reasons why this is done, but they’re out of scope for this tutorial. There are some possible optimizations that don’t make it true 100% of the time, too. Rather than relying on the stack and Drop to clean up memory, the garbage collector deals with the heap instead.

Which to use?

So if the stack is faster and easier to manage, why do we need the heap? A big reason is that Stack-allocation alone means you only have LIFO semantics for reclaiming storage. Heap-allocation is strictly more general, allowing storage to be taken from and returned to the pool in arbitrary order, but at a complexity cost.

Generally, you should prefer stack allocation, and so, Rust stack-allocates by default. The LIFO model of the stack is simpler, at a fundamental level. This has two big impacts: runtime efficiency and semantic impact.

The test attribute

At its simplest, a test in Rust is a function that’s annotated with the test attribute. Let’s make a new project with Cargo called adder:

$ cargo new adder
  $ cd adder

Cargo will automatically generate a simple test when you make a new project. Here’s the contents of src/lib.rs:

#[test]
  fn it_works() {
  }

Note the #[test]. This attribute indicates that this is a test function. It currently has no body. That’s good enough to pass! We can run the tests with cargo test:

$ cargo test
     Compiling adder v0.0.1 (file:///home/you/projects/adder)
       Running target/adder-91b3e234d4ed382a
  
  running 1 test
  test it_works ... ok
  
  test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
  
     Doc-tests adder
  
  running 0 tests
  
  test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured

Cargo compiled and ran our tests. There are two sets of output here: one for the test we wrote, and another for documentation tests. We’ll talk about those later. For now, see this line:

test it_works ... ok

Note the it_works. This comes from the name of our function:

fn it_works() {

We also get a summary line:

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

So why does our do-nothing test pass? Any test which doesn’t panic! passes, and any test that does panic! fails. Let’s make our test fail:

#[test]
  fn it_works() {
      assert!(false);
  }

assert! is a macro provided by Rust which takes one argument: if the argument is true, nothing happens. If the argument is false, it panic!s. Let’s run our tests again:

$ cargo test
     Compiling adder v0.0.1 (file:///home/you/projects/adder)
       Running target/adder-91b3e234d4ed382a
  
  running 1 test
  test it_works ... FAILED
  
  failures:
  
  ---- it_works stdout ----
          thread 'it_works' panicked at 'assertion failed: false', /home/steve/tmp/adder
  ↳ /src/lib.rs:3
  
  
  
  failures:
      it_works
  
  test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured
  
  thread '<main>' panicked at 'Some tests failed', /home/steve/src/rust/src/libtest/lib.
  ↳ rs:247

Rust indicates that our test failed:

test it_works ... FAILED

And that’s reflected in the summary line:

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured

We also get a non-zero status code:

$ echo $?
  101

This is useful if you want to integrate cargo test into other tooling.

We can invert our test’s failure with another attribute: should_panic:

#[test]
  #[should_panic]
  fn it_works() {
      assert!(false);
  }

This test will now succeed if we panic! and fail if we complete. Let’s try it:

$ cargo test
     Compiling adder v0.0.1 (file:///home/you/projects/adder)
       Running target/adder-91b3e234d4ed382a
  
  running 1 test
  test it_works ... ok
  
  test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
  
     Doc-tests adder
  
  running 0 tests
  
  test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured

Rust provides another macro, assert_eq!, that compares two arguments for equality:

#[test]
  #[should_panic]
  fn it_works() {
      assert_eq!("Hello", "world");
  }

Does this test pass or fail? Because of the should_panic attribute, it passes:

$ cargo test
     Compiling adder v0.0.1 (file:///home/you/projects/adder)
       Running target/adder-91b3e234d4ed382a
  
  running 1 test
  test it_works ... ok
  
  test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
  
     Doc-tests adder
  
  running 0 tests
  
  test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured

should_panic tests can be fragile, as it’s hard to guarantee that the test didn’t fail for an unexpected reason. To help with this, an optional expected parameter can be added to the should_panic attribute. The test harness will make sure that the failure message contains the provided text. A safer version of the example above would be:

#[test]
  #[should_panic(expected = "assertion failed")]
  fn it_works() {
      assert_eq!("Hello", "world");
  }

That’s all there is to the basics! Let’s write one ‘real’ test:

pub fn add_two(a: i32) -> i32 {
      a + 2
  }
  
  #[test]
  fn it_works() {
      assert_eq!(4, add_two(2));
  }

This is a very common use of assert_eq!: call some function with some known arguments and compare it to the expected output.

The tests module

There is one way in which our existing example is not idiomatic: it’s missing the tests module. The idiomatic way of writing our example looks like this:

pub fn add_two(a: i32) -> i32 {
      a + 2
  }
  
  #[cfg(test)]
  mod tests {
      use super::add_two;
  
      #[test]
      fn it_works() {
          assert_eq!(4, add_two(2));
      }
  }

There’s a few changes here. The first is the introduction of a mod tests with a cfg attribute. The module allows us to group all of our tests together, and to also define helper functions if needed, that don’t become a part of the rest of our crate. The cfg attribute only compiles our test code if we’re currently trying to run the tests. This can save compile time, and also ensures that our tests are entirely left out of a normal build.

The second change is the use declaration. Because we’re in an inner module, we need to bring our test function into scope. This can be annoying if you have a large module, and so this is a common use of the glob feature. Let’s change our src/lib.rs to make use of it:

  pub fn add_two(a: i32) -> i32 {
      a + 2
  }
  
  #[cfg(test)]
  mod tests {
      use super::*;
  
      #[test]
      fn it_works() {
          assert_eq!(4, add_two(2));
      }
  }

Note the different use line. Now we run our tests:

$ cargo test
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Compiling adder v0.0.1 (file:///home/you/projects/adder)
       Running target/adder-91b3e234d4ed382a
  
  running 1 test
  test tests::it_works ... ok
  
  test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
  
     Doc-tests adder
  
  running 0 tests
  
  test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured

It works!

The current convention is to use the tests module to hold your “unit-style” tests. Anything that just tests one small bit of functionality makes sense to go here. But what about “integration-style” tests instead? For that, we have the tests directory

The tests directory

To write an integration test, let’s make a tests directory, and put a tests/lib.rs file inside, with this as its contents:

extern crate adder;
  
  #[test]
  fn it_works() {
      assert_eq!(4, adder::add_two(2));
  }

This looks similar to our previous tests, but slightly different. We now have an extern crate adder at the top. This is because the tests in the tests directory are an entirely separate crate, and so we need to import our library. This is also why tests is a suitable place to write integration-style tests: they use the library like any other consumer of it would.

Let’s run them:

$ cargo test
     Compiling adder v0.0.1 (file:///home/you/projects/adder)
       Running target/adder-91b3e234d4ed382a
  
  running 1 test
  test tests::it_works ... ok
  
  test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
  
       Running target/lib-c18e7d3494509e74
  
  running 1 test
  test it_works ... ok
  
  test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
  
     Doc-tests adder
  
  running 0 tests
  
  test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured

Now we have three sections: our previous test is also run, as well as our new one.

That’s all there is to the tests directory. The tests module isn’t needed here, since the whole thing is focused on tests.

Let’s finally check out that third section: documentation tests.

Documentation tests

Nothing is better than documentation with examples. Nothing is worse than examples that don’t actually work, because the code has changed since the documentation has been written. To this end, Rust supports automatically running examples in your documentation. Here’s a fleshed-out src/lib.rs with examples:

//! The `adder` crate provides functions that add numbers to other numbers.
  //!
  //! # Examples
  //!
  //! ```
  //! assert_eq!(4, adder::add_two(2));
  //! ```
  
  /// This function adds two to its argument.
  ///
  /// # Examples
  ///
  /// ```
  /// use adder::add_two;
  ///
  /// assert_eq!(4, add_two(2));
  /// ```
  pub fn add_two(a: i32) -> i32 {
      a + 2
  }
  
  #[cfg(test)]
  mod tests {
      use super::*;
  
      #[test]
      fn it_works() {
          assert_eq!(4, add_two(2));
      }
  }

Note the module-level documentation with //! and the function-level documentation with ///. Rust’s documentation supports Markdown in comments, and so triple graves mark code blocks. It is conventional to include the # Examples section, exactly like that, with examples following.

Let’s run the tests again:

$ cargo test
     Compiling adder v0.0.1 (file:///home/steve/tmp/adder)
       Running target/adder-91b3e234d4ed382a
  
  running 1 test
  test tests::it_works ... ok
  
  test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
  
       Running target/lib-c18e7d3494509e74
  
  running 1 test
  test it_works ... ok
  
  test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
  
     Doc-tests adder
  
  running 2 tests
  test add_two_0 ... ok
  test _0 ... ok
  
  test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured

Now we have all three kinds of tests running! Note the names of the documentation tests: the _0 is generated for the module test, and add_two_0 for the function test. These will auto increment with names like add_two_1 as you add more examples.

cfg_attr

You can also set another attribute based on a cfg variable with cfg_attr:

#[cfg_attr(a, b)]

Will be the same as #[b] if a is set by cfg attribute, and nothing otherwise.

cfg!

The cfg! syntax extension lets you use these kinds of flags elsewhere in your code, too:

if cfg!(target_os = "macos") || cfg!(target_os = "ios") {
      println!("Think Different!");
  }

These will be replaced by a true or false at compile-time, depending on the configuration settings.

About rustdoc

The Rust distribution includes a tool, rustdoc, that generates documentation. rustdoc is also used by Cargo through cargo doc.

Documentation can be generated in two ways: from source code, and from standalone Markdown files.

Documenting source code

The primary way of documenting a Rust project is through annotating the source code. You can use documentation comments for this purpose:

/// Constructs a new `Rc<T>`.
  ///
  /// # Examples
  ///
  /// ```
  /// use std::rc::Rc;
  ///
  /// let five = Rc::new(5);
  /// ```
  pub fn new(value: T) -> Rc<T> {
      // implementation goes here
  }

This code generates documentation that looks like this. I’ve left the implementation out, with a regular comment in its place. That’s the first thing to notice about this annotation: it uses ///, instead of //. The triple slash indicates a documentation comment.

Documentation comments are written in Markdown.

Rust keeps track of these comments, and uses them when generating documentation. This is important when documenting things like enums:

/// The `Option` type. See [the module level documentation](../) for more.
  enum Option<T> {
      /// No value
      None,
      /// Some value `T`
      Some(T),
  }

The above works, but this does not:

/// The `Option` type. See [the module level documentation](../) for more.
  enum Option<T> {
      None, /// No value
      Some(T), /// Some value `T`
  }

You’ll get an error:

hello.rs:4:1: 4:2 error: expected ident, found `}`
  hello.rs:4 }
             ^

This unfortunate error is correct: documentation comments apply to the thing after them, and there’s no thing after that last comment.

/// Constructs a new `Rc<T>`.

///
  /// Other details about constructing `Rc<T>`s, maybe describing complicated
  /// semantics, maybe additional options, all kinds of stuff.
  ///

/// # Examples

/// # Panics

/// # Failures

/// # Safety

/// # Examples
  ///
  /// ```
  /// use std::rc::Rc;
  ///
  /// let five = Rc::new(5);
  /// ```

/// # Examples
  ///
  /// Simple `&str` patterns:
  ///
  /// ```
  /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
  /// assert_eq!(v, vec!["Mary", "had", "a", "little", "lamb"]);
  /// ```
  ///
  /// More complex patterns with a lambda:
  ///
  /// ```
  /// let v: Vec<&str> = "abc1def2ghi".split(|c: char| c.is_numeric()).collect();
  /// assert_eq!(v, vec!["abc", "def", "ghi"]);
  /// ```

/// ```
  /// println!("Hello, world");
  /// ```

/// ```c
  /// printf("Hello, world\n");
  /// ```

Documentation as tests

Let’s discuss our sample example documentation:

/// ```
  /// println!("Hello, world");
  /// ```

You’ll notice that you don’t need a fn main() or anything here. rustdoc will automatically add a main() wrapper around your code, and in the right place. For example:

/// ```
  /// use std::rc::Rc;
  ///
  /// let five = Rc::new(5);
  /// ```

This will end up testing:

fn main() {
      use std::rc::Rc;
      let five = Rc::new(5);
  }

Here’s the full algorithm rustdoc uses to postprocess examples:

1. Any leading #![foo] attributes are left intact as crate attributes.
2. Some common allow attributes are inserted, including unused_variables, unused_assignments, unused_mut, unused_attributes, and dead_code. Small examples often trigger these lints.
3. If the example does not contain extern crate, then extern crate <mycrate>; is inserted.
4. Finally, if the example does not contain fn main, the remainder of the text is wrapped in fn main() { your_code }

Sometimes, this isn’t enough, though. For example, all of these code samples with /// we’ve been talking about? The raw text:

/// Some documentation.
  # fn foo() {}

looks different than the output:

/// Some documentation.

Yes, that’s right: you can add lines that start with #, and they will be hidden from the output, but will be used when compiling your code. You can use this to your advantage. In this case, documentation comments need to apply to some kind of function, so if I want to show you just a documentation comment, I need to add a little function definition below it. At the same time, it’s just there to satisfy the compiler, so hiding it makes the example more clear. You can use this technique to explain longer examples in detail, while still preserving the testability of your documentation. For example, this code:

let x = 5;
  let y = 6;
  println!("{}", x + y);

Here’s an explanation, rendered:

First, we set x to five:

let x = 5;

Next, we set y to six:

let y = 6;

Finally, we print the sum of x and y:

println!("{}", x + y);

Here’s the same explanation, in raw text:

First, we set x to five:

let x = 5;
  # let y = 6;
  # println!("{}", x + y);

Next, we set y to six:

# let x = 5;
  let y = 6;
  # println!("{}", x + y);

Finally, we print the sum of x and y:

# let x = 5;
  # let y = 6;
  println!("{}", x + y);

By repeating all parts of the example, you can ensure that your example still compiles, while only showing the parts that are relevant to that part of your explanation.

/// Panic with a given message unless an expression evaluates to true.
  ///
  /// # Examples
  ///
  /// ```
  /// # #[macro_use] extern crate foo;
  /// # fn main() {
  /// panic_unless!(1 + 1 == 2, “Math is broken.”);
  /// # }
  /// ```
  ///
  /// ```should_panic
  /// # #[macro_use] extern crate foo;
  /// # fn main() {
  /// panic_unless!(true == false, “I’m broken.”);
  /// # }
  /// ```
  #[macro_export]
  macro_rules! panic_unless {
      ($condition:expr, $($rest:expr),+) => ({ if ! $condition { panic!($($rest),+); } }
  ↳ );
  }

$ rustdoc --test path/to/my/crate/root.rs
  # or
  $ cargo test

/// ```ignore
  /// fn foo() {
  /// ```

/// ```should_panic
  /// assert!(false);
  /// ```

/// ```no_run
  /// loop {
  ///     println!("Hello, world");
  /// }
  /// ```

mod foo {
      //! This is documentation for the `foo` module.
      //!
      //! # Examples
  
      // ...
  }

//! A module for using `foo`s.
  //!
  //! The `foo` module contains a lot of useful functionality blah blah blah

Other documentation

All of this behavior works in non-Rust source files too. Because comments are written in Markdown, they’re often .md files.

When you write documentation in Markdown files, you don’t need to prefix the documentation with comments. For example:

/// # Examples
  ///
  /// ```
  /// use std::rc::Rc;
  ///
  /// let five = Rc::new(5);
  /// ```

is just

### Examples
  
  ```
  use std::rc::Rc;
  
  let five = Rc::new(5);
  ```

when it’s in a Markdown file. There is one wrinkle though: Markdown files need to have a title like this:

% The title
  
  This is the example documentation.

This % line needs to be the very first line of the file.

doc attributes

At a deeper level, documentation comments are sugar for documentation attributes:

/// this
  
  #[doc="this"]

are the same, as are these:

//! this
  
  #![doc="/// this"]

You won’t often see this attribute used for writing documentation, but it can be useful when changing some options, or when writing a macro.

extern crate foo;
  
  pub use foo::bar;

extern crate foo;
  
  #[doc(no_inline)]
  pub use foo::bar;

#![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
         html_favicon_url = "http://www.rust-lang.org/favicon.ico",
         html_root_url = "http://doc.rust-lang.org/")]

Generation options

rustdoc also contains a few other options on the command line, for further customization:

• --html-in-header FILE: includes the contents of FILE at the end of the <head>...</head> section.
• --html-before-content FILE: includes the contents of FILE directly after <body>, before the rendered content (including the search bar).
• --html-after-content FILE: includes the contents of FILE after all the rendered content.

Security note

The Markdown in documentation comments is placed without processing into the final webpage. Be careful with literal HTML:

/// <script>alert(document.cookie)</script>

Consumers

A consumer operates on an iterator, returning some kind of value or values. The most common consumer is collect(). This code doesn’t quite compile, but it shows the intention:

let one_to_one_hundred = (1..101).collect();

As you can see, we call collect() on our iterator. collect() takes as many values as the iterator will give it, and returns a collection of the results. So why won’t this compile? Rust can’t determine what type of things you want to collect, and so you need to let it know. Here’s the version that does compile:

let one_to_one_hundred = (1..101).collect::<Vec<i32>>();

If you remember, the ::<> syntax allows us to give a type hint, and so we tell it that we want a vector of integers. You don’t always need to use the whole type, though. Using a _ will let you provide a partial hint:

let one_to_one_hundred = (1..101).collect::<Vec<_>>();

This says “Collect into a Vec<T>, please, but infer what the T is for me.” _ is sometimes called a “type placeholder” for this reason.

collect() is the most common consumer, but there are others too. find() is one:

let greater_than_forty_two = (0..100)
                               .find(|x| *x > 42);
  
  match greater_than_forty_two {
      Some(_) => println!("We got some numbers!"),
      None => println!("No numbers found :("),
  }

find takes a closure, and works on a reference to each element of an iterator. This closure returns true if the element is the element we’re looking for, and false otherwise. Because we might not find a matching element, find returns an Option rather than the element itself.

Another important consumer is fold. Here’s what it looks like:

let sum = (1..4).fold(0, |sum, x| sum + x);

fold() is a consumer that looks like this: fold(base, |accumulator, element| ...). It takes two arguments: the first is an element called the base. The second is a closure that itself takes two arguments: the first is called the accumulator, and the second is an element. Upon each iteration, the closure is called, and the result is the value of the accumulator on the next iteration. On the first iteration, the base is the value of the accumulator.

Okay, that’s a bit confusing. Let’s examine the values of all of these things in this iterator:

We called fold() with these arguments:

.fold(0, |sum, x| sum + x);

So, 0 is our base, sum is our accumulator, and x is our element. On the first iteration, we set sum to 0, and x is the first element of nums, 1. We then add sum and x, which gives us 0 + 1 = 1. On the second iteration, that value becomes our accumulator, sum, and the element is the second element of the array, 2. 1 + 2 = 3, and so that becomes the value of the accumulator for the last iteration. On that iteration, x is the last element, 3, and 3 + 3 = 6, which is our final result for our sum. 1 + 2 + 3 = 6, and that’s the result we got.

Whew. fold can be a bit strange the first few times you see it, but once it clicks, you can use it all over the place. Any time you have a list of things, and you want a single result, fold is appropriate.

Consumers are important due to one additional property of iterators we haven’t talked about yet: laziness. Let’s talk some more about iterators, and you’ll see why consumers matter.

Iterators

As we’ve said before, an iterator is something that we can call the .next() method on repeatedly, and it gives us a sequence of things. Because you need to call the method, this means that iterators can be lazy and not generate all of the values upfront. This code, for example, does not actually generate the numbers 1-100, instead creating a value that merely represents the sequence:

let nums = 1..100;

Since we didn’t do anything with the range, it didn’t generate the sequence. Let’s add the consumer:

let nums = (1..100).collect::<Vec<i32>>();

Now, collect() will require that the range gives it some numbers, and so it will do the work of generating the sequence.

Ranges are one of two basic iterators that you’ll see. The other is iter(). iter() can turn a vector into a simple iterator that gives you each element in turn:

let nums = vec![1, 2, 3];
  
  for num in nums.iter() {
     println!("{}", num);
  }

These two basic iterators should serve you well. There are some more advanced iterators, including ones that are infinite.

That’s enough about iterators. Iterator adapters are the last concept we need to talk about with regards to iterators. Let’s get to it!

Iterator adapters

Iterator adapters take an iterator and modify it somehow, producing a new iterator. The simplest one is called map:

(1..100).map(|x| x + 1);

map is called upon another iterator, and produces a new iterator where each element reference has the closure it’s been given as an argument called on it. So this would give us the numbers from 2-100. Well, almost! If you compile the example, you’ll get a warning:

warning: unused result which must be used: iterator adaptors are lazy and
           do nothing unless consumed, #[warn(unused_must_use)] on by default
  (1..100).map(|x| x + 1);
   ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Laziness strikes again! That closure will never execute. This example doesn’t print any numbers:

(1..100).map(|x| println!("{}", x));

If you are trying to execute a closure on an iterator for its side effects, just use for instead.

There are tons of interesting iterator adapters. take(n) will return an iterator over the next n elements of the original iterator. Note that this has no side effect on the original iterator. Let’s try it out with our infinite iterator from before:

for i in (1..).step_by(5).take(5) {
      println!("{}", i);
  }

This will print

1
  6
  11
  16
  21

filter() is an adapter that takes a closure as an argument. This closure returns true or false. The new iterator filter() produces only the elements that that closure returns true for:

for i in (1..100).filter(|&x| x % 2 == 0) {
      println!("{}", i);
  }

This will print all of the even numbers between one and a hundred. (Note that because filter doesn’t consume the elements that are being iterated over, it is passed a reference to each element, and thus the filter predicate uses the &x pattern to extract the integer itself.)

You can chain all three things together: start with an iterator, adapt it a few times, and then consume the result. Check it out:

(1..1000)
      .filter(|&x| x % 2 == 0)
      .filter(|&x| x % 3 == 0)
      .take(5)
      .collect::<Vec<i32>>();

This will give you a vector containing 6, 12, 18, 24, and 30.

This is just a small taste of what iterators, iterator adapters, and consumers can help you with. There are a number of really useful iterators, and you can write your own as well. Iterators provide a safe, efficient way to manipulate all kinds of lists. They’re a little unusual at first, but if you play with them, you’ll get hooked. For a full list of the different iterators and consumers, check out the iterator module documentation.

Background: Send and Sync

Concurrency is difficult to reason about. In Rust, we have a strong, static type system to help us reason about our code. As such, Rust gives us two traits to help us make sense of code that can possibly be concurrent.

Threads

Rust’s standard library provides a library for threads, which allow you to run Rust code in parallel. Here’s a basic example of using std::thread:

use std::thread;
  
  fn main() {
      thread::spawn(|| {
          println!("Hello from a thread!");
      });
  }

The thread::spawn() method accepts a closure, which is executed in a new thread. It returns a handle to the thread, that can be used to wait for the child thread to finish and extract its result:

use std::thread;
  
  fn main() {
      let handle = thread::spawn(|| {
          "Hello from a thread!"
      });
  
      println!("{}", handle.join().unwrap());
  }

Many languages have the ability to execute threads, but it’s wildly unsafe. There are entire books about how to prevent errors that occur from shared mutable state. Rust helps out with its type system here as well, by preventing data races at compile time. Let’s talk about how you actually share things between threads.

Safe Shared Mutable State

Due to Rust’s type system, we have a concept that sounds like a lie: “safe shared mutable state.” Many programmers agree that shared mutable state is very, very bad.

Someone once said this:

Shared mutable state is the root of all evil. Most languages attempt to deal with this problem through the ‘mutable’ part, but Rust deals with it by solving the ‘shared’ part.

The same ownership system that helps prevent using pointers incorrectly also helps rule out data races, one of the worst kinds of concurrency bugs.

As an example, here is a Rust program that would have a data race in many languages. It will not compile:

use std::thread;
  
  fn main() {
      let mut data = vec![1u32, 2, 3];
  
      for i in 0..3 {
          thread::spawn(move || {
              data[i] += 1;
          });
      }
  
      thread::sleep_ms(50);
  }

This gives us an error:

8:17 error: capture of moved value: `data`
          data[i] += 1;
          ^~~~

In this case, we know that our code should be safe, but Rust isn’t sure. And it’s actually not safe: if we had a reference to data in each thread, and the thread takes ownership of the reference, we have three owners! That’s bad. We can fix this by using the Arc<T> type, which is an atomic reference counted pointer. The ‘atomic’ part means that it’s safe to share across threads.

Arc<T> assumes one more property about its contents to ensure that it is safe to share across threads: it assumes its contents are Sync. But in our case, we want to be able to mutate the value. We need a type that can ensure only one person at a time can mutate what’s inside. For that, we can use the Mutex<T> type. Here’s the second version of our code. It still doesn’t work, but for a different reason:

use std::thread;
  use std::sync::Mutex;
  
  fn main() {
      let mut data = Mutex::new(vec![1u32, 2, 3]);
  
      for i in 0..3 {
          let data = data.lock().unwrap();
          thread::spawn(move || {
              data[i] += 1;
          });
      }
  
      thread::sleep_ms(50);
  }

Here’s the error:

<anon>:9:9: 9:22 error: the trait `core::marker::Send` is not implemented for the type
  ↳  `std::sync::mutex::MutexGuard<'_, collections::vec::Vec<u32>>` [E0277]
  <anon>:11         thread::spawn(move || {
                    ^~~~~~~~~~~~~
  <anon>:9:9: 9:22 note: `std::sync::mutex::MutexGuard<'_, collections::vec::Vec<u32>>` 
  ↳ cannot be sent between threads safely
  <anon>:11         thread::spawn(move || {
                    ^~~~~~~~~~~~~

You see, Mutex has a lock method which has this signature:

fn lock(&self) -> LockResult<MutexGuard<T>>

Because Send is not implemented for MutexGuard<T>, we can’t transfer the guard across thread boundaries, which gives us our error.

We can use Arc<T> to fix this. Here’s the working version:

use std::sync::{Arc, Mutex};
  use std::thread;
  
  fn main() {
      let data = Arc::new(Mutex::new(vec![1u32, 2, 3]));
  
      for i in 0..3 {
          let data = data.clone();
          thread::spawn(move || {
              let mut data = data.lock().unwrap();
              data[i] += 1;
          });
      }
  
      thread::sleep_ms(50);
  }

We now call clone() on our Arc, which increases the internal count. This handle is then moved into the new thread. Let’s examine the body of the thread more closely:

thread::spawn(move || {
      let mut data = data.lock().unwrap();
      data[i] += 1;
  });

First, we call lock(), which acquires the mutex’s lock. Because this may fail, it returns an Result<T, E>, and because this is just an example, we unwrap() it to get a reference to the data. Real code would have more robust error handling here. We’re then free to mutate it, since we have the lock.

Lastly, while the threads are running, we wait on a short timer. But this is not ideal: we may have picked a reasonable amount of time to wait but it’s more likely we’ll either be waiting longer than necessary or not long enough, depending on just how much time the threads actually take to finish computing when the program runs.

A more precise alternative to the timer would be to use one of the mechanisms provided by the Rust standard library for synchronizing threads with each other. Let’s talk about one of them: channels.

Channels

Here’s a version of our code that uses channels for synchronization, rather than waiting for a specific time:

use std::sync::{Arc, Mutex};
  use std::thread;
  use std::sync::mpsc;
  
  fn main() {
      let data = Arc::new(Mutex::new(0u32));
  
      let (tx, rx) = mpsc::channel();
  
      for _ in 0..10 {
          let (data, tx) = (data.clone(), tx.clone());
  
          thread::spawn(move || {
              let mut data = data.lock().unwrap();
              *data += 1;
  
              tx.send(());
          });
      }
  
      for _ in 0..10 {
          rx.recv();
      }
  }

We use the mpsc::channel() method to construct a new channel. We just send a simple () down the channel, and then wait for ten of them to come back.

While this channel is just sending a generic signal, we can send any data that is Send over the channel!

use std::thread;
  use std::sync::mpsc;
  
  fn main() {
      let (tx, rx) = mpsc::channel();
  
      for _ in 0..10 {
          let tx = tx.clone();
  
          thread::spawn(move || {
              let answer = 42u32;
  
              tx.send(answer);
          });
      }
  
     rx.recv().ok().expect("Could not receive answer");
  }

A u32 is Send because we can make a copy. So we create a thread, ask it to calculate the answer, and then it send()s us the answer over the channel.

Panics

A panic! will crash the currently executing thread. You can use Rust’s threads as a simple isolation mechanism:

use std::thread;
  
  let result = thread::spawn(move || {
      panic!("oops!");
  }).join();
  
  assert!(result.is_err());

Our Thread gives us a Result back, which allows us to check if the thread has panicked or not.

Failure vs. Panic

Rust uses two terms to differentiate between two forms of error: failure, and panic. A failure is an error that can be recovered from in some way. A panic is an error that cannot be recovered from.

What do we mean by “recover”? Well, in most cases, the possibility of an error is expected. For example, consider the parse function:

"5".parse();

This method converts a string into another type. But because it’s a string, you can’t be sure that the conversion actually works. For example, what should this convert to?

"hello5world".parse();

This won’t work. So we know that this function will only work properly for some inputs. It’s expected behavior. We call this kind of error a failure.

On the other hand, sometimes, there are errors that are unexpected, or which we cannot recover from. A classic example is an assert!:

assert!(x == 5);

We use assert! to declare that something is true. If it’s not true, something is very wrong. Wrong enough that we can’t continue with things in the current state. Another example is using the unreachable!() macro:

enum Event {
      NewRelease,
  }
  
  fn probability(_: &Event) -> f64 {
      // real implementation would be more complex, of course
      0.95
  }
  
  fn descriptive_probability(event: Event) -> &'static str {
      match probability(&event) {
          1.00 => "certain",
          0.00 => "impossible",
          0.00 ... 0.25 => "very unlikely",
          0.25 ... 0.50 => "unlikely",
          0.50 ... 0.75 => "likely",
          0.75 ... 1.00 => "very likely",
      }
  }
  
  fn main() {
      std::io::println(descriptive_probability(NewRelease));
  }

This will give us an error:

error: non-exhaustive patterns: `_` not covered [E0004]

While we know that we’ve covered all possible cases, Rust can’t tell. It doesn’t know that probability is between 0.0 and 1.0. So we add another case:

use Event::NewRelease;
  
  enum Event {
      NewRelease,
  }
  
  fn probability(_: &Event) -> f64 {
      // real implementation would be more complex, of course
      0.95
  }
  
  fn descriptive_probability(event: Event) -> &'static str {
      match probability(&event) {
          1.00 => "certain",
          0.00 => "impossible",
          0.00 ... 0.25 => "very unlikely",
          0.25 ... 0.50 => "unlikely",
          0.50 ... 0.75 => "likely",
          0.75 ... 1.00 => "very likely",
          _ => unreachable!()
      }
  }
  
  fn main() {
      println!("{}", descriptive_probability(NewRelease));
  }

We shouldn’t ever hit the _ case, so we use the unreachable!() macro to indicate this. unreachable!() gives a different kind of error than Result. Rust calls these sorts of errors panics.

Handling errors with Option and Result

The simplest way to indicate that a function may fail is to use the Option<T> type. For example, the find method on strings attempts to find a pattern in a string, and returns an Option:

let s = "foo";
  
  assert_eq!(s.find('f'), Some(0));
  assert_eq!(s.find('z'), None);

This is appropriate for the simplest of cases, but doesn’t give us a lot of information in the failure case. What if we wanted to know why the function failed? For this, we can use the Result<T, E> type. It looks like this:

enum Result<T, E> {
     Ok(T),
     Err(E)
  }

This enum is provided by Rust itself, so you don’t need to define it to use it in your code. The Ok(T) variant represents a success, and the Err(E) variant represents a failure. Returning a Result instead of an Option is recommended for all but the most trivial of situations.

Here’s an example of using Result:

#[derive(Debug)]
  enum Version { Version1, Version2 }
  
  #[derive(Debug)]
  enum ParseError { InvalidHeaderLength, InvalidVersion }
  
  fn parse_version(header: &[u8]) -> Result<Version, ParseError> {
      if header.len() < 1 {
          return Err(ParseError::InvalidHeaderLength);
      }
      match header[0] {
          1 => Ok(Version::Version1),
          2 => Ok(Version::Version2),
          _ => Err(ParseError::InvalidVersion)
      }
  }
  
  let version = parse_version(&[1, 2, 3, 4]);
  match version {
      Ok(v) => {
          println!("working with version: {:?}", v);
      }
      Err(e) => {
          println!("error parsing header: {:?}", e);
      }
  }

This function makes use of an enum, ParseError, to enumerate the various errors that can occur.

The Debug trait is what lets us print the enum value using the {:?} format operation.

Non-recoverable errors with panic!

In the case of an error that is unexpected and not recoverable, the panic! macro will induce a panic. This will crash the current thread, and give an error:

panic!("boom");

gives

thread '<main>' panicked at 'boom', hello.rs:2

when you run it.

Because these kinds of situations are relatively rare, use panics sparingly.

Upgrading failures to panics

In certain circumstances, even though a function may fail, we may want to treat it as a panic instead. For example, io::stdin().read_line(&mut buffer) returns a Result<usize>, when there is an error reading the line. This allows us to handle and possibly recover from error.

If we don’t want to handle this error, and would rather just abort the program, we can use the unwrap() method:

io::stdin().read_line(&mut buffer).unwrap();

unwrap() will panic! if the Result is Err. This basically says “Give me the value, and if something goes wrong, just crash.” This is less reliable than matching the error and attempting to recover, but is also significantly shorter. Sometimes, just crashing is appropriate.

There’s another way of doing this that’s a bit nicer than unwrap():

let mut buffer = String::new();
  let input = io::stdin().read_line(&mut buffer)
                         .ok()
                         .expect("Failed to read line");

ok() converts the Result into an Option, and expect() does the same thing as unwrap(), but takes a message. This message is passed along to the underlying panic!, providing a better error message if the code errors.

Using try!

When writing code that calls many functions that return the Result type, the error handling can be tedious. The try! macro hides some of the boilerplate of propagating errors up the call stack.

It replaces this:

use std::fs::File;
  use std::io;
  use std::io::prelude::*;
  
  struct Info {
      name: String,
      age: i32,
      rating: i32,
  }
  
  fn write_info(info: &Info) -> io::Result<()> {
      let mut file = File::create("my_best_friends.txt").unwrap();
  
      if let Err(e) = writeln!(&mut file, "name: {}", info.name) {
          return Err(e)
      }
      if let Err(e) = writeln!(&mut file, "age: {}", info.age) {
          return Err(e)
      }
      if let Err(e) = writeln!(&mut file, "rating: {}", info.rating) {
          return Err(e)
      }
  
      return Ok(());
  }

With this:

use std::fs::File;
  use std::io;
  use std::io::prelude::*;
  
  struct Info {
      name: String,
      age: i32,
      rating: i32,
  }
  
  fn write_info(info: &Info) -> io::Result<()> {
      let mut file = try!(File::create("my_best_friends.txt"));
  
      try!(writeln!(&mut file, "name: {}", info.name));
      try!(writeln!(&mut file, "age: {}", info.age));
      try!(writeln!(&mut file, "rating: {}", info.rating));
  
      return Ok(());
  }

Wrapping an expression in try! will result in the unwrapped success (Ok) value, unless the result is Err, in which case Err is returned early from the enclosing function.

It’s worth noting that you can only use try! from a function that returns a Result, which means that you cannot use try! inside of main(), because main() doesn’t return anything.

try! makes use of From<Error> to determine what to return in the error case.

Introduction

This guide will use the snappy compression/decompression library as an introduction to writing bindings for foreign code. Rust is currently unable to call directly into a C++ library, but snappy includes a C interface (documented in snappy-c.h).

The following is a minimal example of calling a foreign function which will compile if snappy is installed:

# #![feature(libc)]
  extern crate libc;
  use libc::size_t;
  
  #[link(name = "snappy")]
  extern {
      fn snappy_max_compressed_length(source_length: size_t) -> size_t;
  }
  
  fn main() {
      let x = unsafe { snappy_max_compressed_length(100) };
      println!("max compressed length of a 100 byte buffer: {}", x);
  }

The extern block is a list of function signatures in a foreign library, in this case with the platform’s C ABI. The #[link(...)] attribute is used to instruct the linker to link against the snappy library so the symbols are resolved.

Foreign functions are assumed to be unsafe so calls to them need to be wrapped with unsafe {} as a promise to the compiler that everything contained within truly is safe. C libraries often expose interfaces that aren’t thread-safe, and almost any function that takes a pointer argument isn’t valid for all possible inputs since the pointer could be dangling, and raw pointers fall outside of Rust’s safe memory model.

When declaring the argument types to a foreign function, the Rust compiler can not check if the declaration is correct, so specifying it correctly is part of keeping the binding correct at runtime.

The extern block can be extended to cover the entire snappy API:

# #![feature(libc)]
  extern crate libc;
  use libc::{c_int, size_t};
  
  #[link(name = "snappy")]
  extern {
      fn snappy_compress(input: *const u8,
                         input_length: size_t,
                         compressed: *mut u8,
                         compressed_length: *mut size_t) -> c_int;
      fn snappy_uncompress(compressed: *const u8,
                           compressed_length: size_t,
                           uncompressed: *mut u8,
                           uncompressed_length: *mut size_t) -> c_int;
      fn snappy_max_compressed_length(source_length: size_t) -> size_t;
      fn snappy_uncompressed_length(compressed: *const u8,
                                    compressed_length: size_t,
                                    result: *mut size_t) -> c_int;
      fn snappy_validate_compressed_buffer(compressed: *const u8,
                                           compressed_length: size_t) -> c_int;
  }
  # fn main() {}

Creating a safe interface

The raw C API needs to be wrapped to provide memory safety and make use of higher-level concepts like vectors. A library can choose to expose only the safe, high-level interface and hide the unsafe internal details.

Wrapping the functions which expect buffers involves using the slice::raw module to manipulate Rust vectors as pointers to memory. Rust’s vectors are guaranteed to be a contiguous block of memory. The length is number of elements currently contained, and the capacity is the total size in elements of the allocated memory. The length is less than or equal to the capacity.

pub fn validate_compressed_buffer(src: &[u8]) -> bool {
      unsafe {
          snappy_validate_compressed_buffer(src.as_ptr(), src.len() as size_t) == 0
      }
  }

The validate_compressed_buffer wrapper above makes use of an unsafe block, but it makes the guarantee that calling it is safe for all inputs by leaving off unsafe from the function signature.

The snappy_compress and snappy_uncompress functions are more complex, since a buffer has to be allocated to hold the output too.

The snappy_max_compressed_length function can be used to allocate a vector with the maximum required capacity to hold the compressed output. The vector can then be passed to the snappy_compress function as an output parameter. An output parameter is also passed to retrieve the true length after compression for setting the length.

pub fn compress(src: &[u8]) -> Vec<u8> {
      unsafe {
          let srclen = src.len() as size_t;
          let psrc = src.as_ptr();
  
          let mut dstlen = snappy_max_compressed_length(srclen);
          let mut dst = Vec::with_capacity(dstlen as usize);
          let pdst = dst.as_mut_ptr();
  
          snappy_compress(psrc, srclen, pdst, &mut dstlen);
          dst.set_len(dstlen as usize);
          dst
      }
  }

Decompression is similar, because snappy stores the uncompressed size as part of the compression format and snappy_uncompressed_length will retrieve the exact buffer size required.

pub fn uncompress(src: &[u8]) -> Option<Vec<u8>> {
      unsafe {
          let srclen = src.len() as size_t;
          let psrc = src.as_ptr();
  
          let mut dstlen: size_t = 0;
          snappy_uncompressed_length(psrc, srclen, &mut dstlen);
  
          let mut dst = Vec::with_capacity(dstlen as usize);
          let pdst = dst.as_mut_ptr();
  
          if snappy_uncompress(psrc, srclen, pdst, &mut dstlen) == 0 {
              dst.set_len(dstlen as usize);
              Some(dst)
          } else {
              None // SNAPPY_INVALID_INPUT
          }
      }
  }

For reference, the examples used here are also available as a library on GitHub.

Destructors

Foreign libraries often hand off ownership of resources to the calling code. When this occurs, we must use Rust’s destructors to provide safety and guarantee the release of these resources (especially in the case of panic).

For more about destructors, see the Drop trait.

Callbacks from C code to Rust functions

Some external libraries require the usage of callbacks to report back their current state or intermediate data to the caller. It is possible to pass functions defined in Rust to an external library. The requirement for this is that the callback function is marked as extern with the correct calling convention to make it callable from C code.

The callback function can then be sent through a registration call to the C library and afterwards be invoked from there.

A basic example is:

Rust code:

extern fn callback(a: i32) {
      println!("I'm called from C with value {0}", a);
  }
  
  #[link(name = "extlib")]
  extern {
     fn register_callback(cb: extern fn(i32)) -> i32;
     fn trigger_callback();
  }
  
  fn main() {
      unsafe {
          register_callback(callback);
          trigger_callback(); // Triggers the callback
      }
  }

C code:

typedef void (*rust_callback)(int32_t);
  rust_callback cb;
  
  int32_t register_callback(rust_callback callback) {
      cb = callback;
      return 1;
  }
  
  void trigger_callback() {
    cb(7); // Will call callback(7) in Rust
  }

In this example Rust’s main() will call trigger_callback() in C, which would, in turn, call back to callback() in Rust.

#[repr(C)]
  struct RustObject {
      a: i32,
      // other members
  }
  
  extern "C" fn callback(target: *mut RustObject, a: i32) {
      println!("I'm called from C with value {0}", a);
      unsafe {
          // Update the value in RustObject with the value received from the callback
          (*target).a = a;
      }
  }
  
  #[link(name = "extlib")]
  extern {
     fn register_callback(target: *mut RustObject,
                          cb: extern fn(*mut RustObject, i32)) -> i32;
     fn trigger_callback();
  }
  
  fn main() {
      // Create the object that will be referenced in the callback
      let mut rust_object = Box::new(RustObject { a: 5 });
  
      unsafe {
          register_callback(&mut *rust_object, callback);
          trigger_callback();
      }
  }

typedef void (*rust_callback)(void*, int32_t);
  void* cb_target;
  rust_callback cb;
  
  int32_t register_callback(void* callback_target, rust_callback callback) {
      cb_target = callback_target;
      cb = callback;
      return 1;
  }
  
  void trigger_callback() {
    cb(cb_target, 7); // Will call callback(&rustObject, 7) in Rust
  }

Linking

The link attribute on extern blocks provides the basic building block for instructing rustc how it will link to native libraries. There are two accepted forms of the link attribute today:

• #[link(name = "foo")]
• #[link(name = "foo", kind = "bar")]

In both of these cases, foo is the name of the native library that we’re linking to, and in the second case bar is the type of native library that the compiler is linking to. There are currently three known types of native libraries:

• Dynamic - #[link(name = "readline")]
• Static - #[link(name = "my_build_dependency", kind = "static")]
• Frameworks - #[link(name = "CoreFoundation", kind = "framework")]

Note that frameworks are only available on OSX targets.

The different kind values are meant to differentiate how the native library participates in linkage. From a linkage perspective, the rust compiler creates two flavors of artifacts: partial (rlib/staticlib) and final (dylib/binary). Native dynamic libraries and frameworks are propagated to the final artifact boundary, while static libraries are not propagated at all.

A few examples of how this model can be used are:

• A native build dependency. Sometimes some C/C++ glue is needed when writing some rust code, but distribution of the C/C++ code in a library format is just a burden. In this case, the code will be archived into libfoo.a and then the rust crate would declare a dependency via #[link(name = "foo", kind = "static")].

Regardless of the flavor of output for the crate, the native static library will be included in the output, meaning that distribution of the native static library is not necessary.

• A normal dynamic dependency. Common system libraries (like readline) are available on a large number of systems, and often a static copy of these libraries cannot be found. When this dependency is included in a rust crate, partial targets (like rlibs) will not link to the library, but when the rlib is included in a final target (like a binary), the native library will be linked in.

On OSX, frameworks behave with the same semantics as a dynamic library.

Unsafe blocks

Some operations, like dereferencing unsafe pointers or calling functions that have been marked unsafe are only allowed inside unsafe blocks. Unsafe blocks isolate unsafety and are a promise to the compiler that the unsafety does not leak out of the block.

Unsafe functions, on the other hand, advertise it to the world. An unsafe function is written like this:

unsafe fn kaboom(ptr: *const i32) -> i32 { *ptr }

This function can only be called from an unsafe block or another unsafe function.

Accessing foreign globals

Foreign APIs often export a global variable which could do something like track global state. In order to access these variables, you declare them in extern blocks with the static keyword:

# #![feature(libc)]
  extern crate libc;
  
  #[link(name = "readline")]
  extern {
      static rl_readline_version: libc::c_int;
  }
  
  fn main() {
      println!("You have readline version {} installed.",
               rl_readline_version as i32);
  }

Alternatively, you may need to alter global state provided by a foreign interface. To do this, statics can be declared with mut so we can mutate them.

# #![feature(libc)]
  extern crate libc;
  
  use std::ffi::CString;
  use std::ptr;
  
  #[link(name = "readline")]
  extern {
      static mut rl_prompt: *const libc::c_char;
  }
  
  fn main() {
      let prompt = CString::new("[my-awesome-shell] $").unwrap();
      unsafe {
          rl_prompt = prompt.as_ptr();
  
          println!("{:?}", rl_prompt);
  
          rl_prompt = ptr::null();
      }
  }

Note that all interaction with a static mut is unsafe, both reading and writing. Dealing with global mutable state requires a great deal of care.

Foreign calling conventions

Most foreign code exposes a C ABI, and Rust uses the platform’s C calling convention by default when calling foreign functions. Some foreign functions, most notably the Windows API, use other calling conventions. Rust provides a way to tell the compiler which convention to use:

extern crate libc;
  
  #[cfg(all(target_os = "win32", target_arch = "x86"))]
  #[link(name = "kernel32")]
  #[allow(non_snake_case)]
  extern "stdcall" {
      fn SetEnvironmentVariableA(n: *const u8, v: *const u8) -> libc::c_int;
  }

This applies to the entire extern block. The list of supported ABI constraints are:

• stdcall
• aapcs
• cdecl
• fastcall
• Rust
• rust-intrinsic
• system
• C
• win64

Most of the abis in this list are self-explanatory, but the system abi may seem a little odd. This constraint selects whatever the appropriate ABI is for interoperating with the target’s libraries. For example, on win32 with a x86 architecture, this means that the abi used would be stdcall. On x86_64, however, windows uses the C calling convention, so C would be used. This means that in our previous example, we could have used extern "system" { ... } to define a block for all windows systems, not just x86 ones.

Interoperability with foreign code

Rust guarantees that the layout of a struct is compatible with the platform’s representation in C only if the #[repr(C)] attribute is applied to it. #[repr(C, packed)] can be used to lay out struct members without padding. #[repr(C)] can also be applied to an enum.

Rust’s owned boxes (Box<T>) use non-nullable pointers as handles which point to the contained object. However, they should not be manually created because they are managed by internal allocators. References can safely be assumed to be non-nullable pointers directly to the type. However, breaking the borrow checking or mutability rules is not guaranteed to be safe, so prefer using raw pointers (*) if that’s needed because the compiler can’t make as many assumptions about them.

Vectors and strings share the same basic memory layout, and utilities are available in the vec and str modules for working with C APIs. However, strings are not terminated with \0. If you need a NUL-terminated string for interoperability with C, you should use the CString type in the std::ffi module.

The standard library includes type aliases and function definitions for the C standard library in the libc module, and Rust links against libc and libm by default.

The “nullable pointer optimization”

Certain types are defined to not be null. This includes references (&T, &mut T), boxes (Box<T>), and function pointers (extern "abi" fn()). When interfacing with C, pointers that might be null are often used. As a special case, a generic enum that contains exactly two variants, one of which contains no data and the other containing a single field, is eligible for the “nullable pointer optimization”. When such an enum is instantiated with one of the non-nullable types, it is represented as a single pointer, and the non-data variant is represented as the null pointer. So Option<extern "C" fn(c_int) -> c_int> is how one represents a nullable function pointer using the C ABI.

Calling Rust code from C

You may wish to compile Rust code in a way so that it can be called from C. This is fairly easy, but requires a few things:

#[no_mangle]
  pub extern fn hello_rust() -> *const u8 {
      "Hello, world!\0".as_ptr()
  }

The extern makes this function adhere to the C calling convention, as discussed above in “Foreign Calling Conventions”. The no_mangle attribute turns off Rust’s name mangling, so that it is easier to link to.

Borrow

The Borrow trait is used when you’re writing a datastructure, and you want to use either an owned or borrowed type as synonymous for some purpose.

For example, HashMap has a get method which uses Borrow:

fn get<Q: ?Sized>(&self, k: &Q) -> Option<&V>
      where K: Borrow<Q>,
            Q: Hash + Eq

This signature is pretty complicated. The K parameter is what we’re interested in here. It refers to a parameter of the HashMap itself:

struct HashMap<K, V, S = RandomState> {

The K parameter is the type of key the HashMap uses. So, looking at the signature of get() again, we can use get() when the key implements Borrow<Q>. That way, we can make a HashMap which uses String keys, but use &strs when we’re searching:

use std::collections::HashMap;
  
  let mut map = HashMap::new();
  map.insert("Foo".to_string(), 42);
  
  assert_eq!(map.get("Foo"), Some(&42));

This is because the standard library has impl Borrow<str> for String.

For most types, when you want to take an owned or borrowed type, a &T is enough. But one area where Borrow is effective is when there’s more than one kind of borrowed value. This is especially true of references and slices: you can have both an &T or a &mut T. If we wanted to accept both of these types, Borrow is up for it:

use std::borrow::Borrow;
  use std::fmt::Display;
  
  fn foo<T: Borrow<i32> + Display>(a: T) {
      println!("a is borrowed: {}", a);
  }
  
  let mut i = 5;
  
  foo(&i);
  foo(&mut i);

This will print out a is borrowed: 5 twice.

AsRef

The AsRef trait is a conversion trait. It’s used for converting some value to a reference in generic code. Like this:

let s = "Hello".to_string();
  
  fn foo<T: AsRef<str>>(s: T) {
      let slice = s.as_ref();
  }

Which should I use?

We can see how they’re kind of the same: they both deal with owned and borrowed versions of some type. However, they’re a bit different.

Choose Borrow when you want to abstract over different kinds of borrowing, or when you’re building a datastructure that treats owned and borrowed values in equivalent ways, such as hashing and comparison.

Choose AsRef when you want to convert something to a reference directly, and you’re writing generic code.

Overview

There are three channels for Rust releases:

• Nightly
• Beta
• Stable

New nightly releases are created once a day. Every six weeks, the latest nightly release is promoted to ‘Beta’. At that point, it will only receive patches to fix serious errors. Six weeks later, the beta is promoted to ‘Stable’, and becomes the next release of 1.x.

This process happens in parallel. So every six weeks, on the same day, nightly goes to beta, beta goes to stable. When 1.x is released, at the same time, 1.(x + 1)-beta is released, and the nightly becomes the first version of 1.(x + 2)-nightly.

Choosing a version

Generally speaking, unless you have a specific reason, you should be using the stable release channel. These releases are intended for a general audience.

However, depending on your interest in Rust, you may choose to use nightly instead. The basic tradeoff is this: in the nightly channel, you can use unstable, new Rust features. However, unstable features are subject to change, and so any new nightly release may break your code. If you use the stable release, you cannot use experimental features, but the next release of Rust will not cause significant issues through breaking changes.

Helping the ecosystem through CI

What about beta? We encourage all Rust users who use the stable release channel to also test against the beta channel in their continuous integration systems. This will help alert the team in case there’s an accidental regression.

Additionally, testing against nightly can catch regressions even sooner, and so if you don’t mind a third build, we’d appreciate testing against all channels.

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 just 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 ():

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’. A diverging function can be used as any type:

# fn diverges() -> ! {
  #    panic!("This function never returns!");
  # }
  let x: i32 = diverges();
  let x: String = diverges();

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 just one line of a file read into memory. By nature, a slice is not created directly, but from an existing variable. Slices have a length, can be mutable or not, and in many ways behave like arrays:

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

Slices have type &[T]. We’ll talk about that T when we cover generics.

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

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. As such, we’ll just leave it at that.

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 just 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, just 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 just 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.

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.

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);
  }

Both continue and break are valid in both while loops and for loops.

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, the resource that they’re bound to are freed. For example:

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

When v comes into scope, a new Vec<T> is created. In this case, the vector also allocates space on the heap, for the three 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.

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 v = vec![1, 2, 3];
  
  let v2 = v;

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

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!

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, just 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.

Otherwise, &mut references are just 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 smaller scope than the owner. Second, you may have one or the other of these two kinds of borrows, but not both at the same time:

• 0 to N references (&T) to a resource.
• exactly one mutable reference (&mut T)

You may notice that this is very similar, though not exactly the same as, to 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. If you are writing, you need two or more pointers to the same memory, and you can only have one &mut at a time. 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:

• I acquire a handle to some kind of resource.
• I lend you a reference to the resource.
• I decide I’m done with the resource, and deallocate it, while you still have your reference.
• 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 a reference by argument, 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 them in common cases. Before we get to that, though, let’s break the explicit example down:

fn bar<'a>(...)

This part declares 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 an &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 just 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’.

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

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.

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 uncle
  ↳ ar
  
  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 // expanded
  
  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:

struct Color(i32, i32, i32);
  struct Point(i32, i32, i32);

These two will not be equal, even if they have the same values:

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

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,
  }

Now, we have actual names, rather than positions. Good names are important, and with a struct, we have actual names.

There is one case when a tuple struct is very useful, though, and that’s a tuple struct with only one element. We call this the ‘newtype’ pattern, because it allows you to create a new type, distinct from that of its contained value and expressing 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, just 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;

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 just create a unit-like struct.

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 _.

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.

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 mut 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"),
  }

Ignoring variants

If you’re matching on an enum which has variants, you can use .. to ignore the value and type in the variant:

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

This prints Got an int!.

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!.

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),
  }

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: x, y: y } => println!("({},{})", x, y),
  }

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: x, .. } => println!("x is {}", x),
  }

This prints x is 0.

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

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

This prints y is 0.

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

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 just 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 just like any other parameter. Because we know it’s a Circle, we can access the radius just 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: