Learning Rust the Hands-On Way

Performant Software Systems with Rust — Lecture 2

Baochun Li, Professor
Department of Electrical and Computer Engineering
University of Toronto

• Rust is one of the most exciting languages in the recent years

• Yet, it is known to be a complex language with a steep learning curve

I wish I can tell you that it’s not true.

And that it is simple.

It’s not, it’s more complex than other high-level languages you probably are familiar with, Python, Javascript, C, etc.

And that complexity does require more syntax.

But you don’t have to use it all at once.

But I’ve got some good news for you.

It can be simple if you learn it the hands-on way.

Advanced, yet friendly, compiler

The rust compiler is the most advanced, friendly compiler you will have ever used.

It only requires that you read its clear, colourful output.

This is surprisingly challenging: We developers have been trained over our careers, to not read very much into errors.

Stack traces often have single-line errors.

Unhelpful, cryptic errors abound

JSONDecodingError On Line 1

NullPointerException

IndexError In File <in>

Unhelpful, cryptic errors that force you to playback the whole application state using your mind’s compiler.

A glance at the first line of the error is often as good as reading the whole useless stack trace.

So we stop reading. And start hacking.

I want you to unlearn this bad habit.

Read the errors carefully

and the compiler will teach you itself

This is because the errors are so helpful that you don’t actually need me to teach you.

You just need to read the error carefully, and the compiler will teach you itself.

Let’s start with a preposterous example:

Let’s Write Some Rust Javascript

function hello(name) {
    return "hello " + name
}

This first example assumes you know no Rust, and have instead typed Javascript into your editor.

Don’t laugh, we all have to start somewhere.

As you can see, we are trying to write a function with a single parameter that returns that parameter concatenated with a string.

A typical hello world function.

Obviously this does not compile. There is an error.

But something magical has happened:

The Rust compiler, written by the kind and thoughtful core developers, is offering us help, even though we’ve given it some outrageous input.

The error tells us to “write fn instead of function to declare a function”

def hello():
    return "Hello World"

print(hello())

fn hello(name) {
    return "hello " + name
}

OK back to our javascript, but we’ve done as we were told, and replaced the word function with fn.

We are then treated to:

This error.

Do not be afraid of this wall of text.

Do not google the first line “expected one of : @ or |”.

Do not continue hacking your source code to make the error go away.

The answers are all here if you only read them.

Let’s do so together.

error: expected one of `:`, `@`, or `|`, found `)`
 --> main.rs:1:14
1 | fn hello(name) {
  |              ^ expected one of `:`, `@`, or `|`
  |
help: if this is a `self` type, give it a parameter name
  |
1 | fn hello(self: name) {
  |          +++++
help: if this is a parameter name, give it a type
  |
1 | fn hello(name: TypeName) {
  |              ++++++++++
help: if this is a type, explicitly ignore the parameter
  |
1 | fn hello(_: name) {
  |          ++

[1-5]

The top of the output gives us the syntax error.

We have closed the paren at the end of the function definition without doing something Rust wants.

It was expecting us to type : @ or | before the end of the closing paren.

It might be tempting to guess how to fix the error at this point, but read on.

[6-9]

We now have some help text, the first of which is trying to solve our problem with an example.

If this is a self type, like you might have on a method, give it a parameter name, it says.

It doesn’t seem likely that we ARE writing a method, so let us read on.

[10-13]

Now we’re getting somewhere.

The help text says “if this is a parameter name, give it a type”

This is exactly what we were trying to do, make a function with a parameter!

So we must give it a type, and the compiler provided an example of what that looks like. We put the type name after a colon.

Terrific!

[14-17]

For completeness, we’ll just check the final help example.

I don’t think we want to explicitly ignore the param as it suggests.

OK onward.

help: if this is a parameter name, give it a type
  |
1 | fn hello(name: TypeName) {
  |              ++++++++++

So! We’re back to this addition.

We must tell the compiler what kind of data the ‘name’ parameter is.

The reason we do this, and the reason Rust has much more syntax than javascript, is that the more you tell the compiler, the more it can help you, to the point of giving you superpowers.

fn hello(name: string) {
    return "hello " + name
}

[1]

So, adding a type to our parameter.

Let’s put a string in there, seems reasonable.

But woops! again, we have guessed wrong, but AGAIN the compiler tells us exactly what to do.

error[E0412]: cannot find type `string` in this scope
 --> main.rs:1:16
  |
1 | fn hello(name: string) {
  |                ^^^^^^ help: a struct with a similar
    name exists (notice the capitalization): `String`

AH, so structs in Rust are capitalised, like Classes in other languages, ok, fair enough.

Let’s fix that:

fn hello(name: String) {
    return "hello " + name
}

now we’ve got a valid parameter type.

The rust error moves on to focus on the body of the function.

error[E0369]: cannot add `String` to `&str`
 --> main.rs:2:21
  |
2 |    return "hello " + name
  |           -------- ^ ---- String
  |           |        |
  |           |       `+` cannot be used to concatenate
              |       a `&str` with a `String`
  |           &str
  |
help: create an owned `String` on the left
      and add a borrow on the right
  |
2 |     return "hello ".to_owned() + &name
  |                   +++++++++++   +

Another wall of text, but it’s so good.

Let’s read this error together with all it’s retro asci graphics.

error[E0369]: cannot add `String` to `&str`
 --> main.rs:2:21
  |
2 |    return "hello " + name
  |           -------- ^ ---- String
  |           |        |
  |           |       `+` cannot be used to concatenate
              |       a `&str` with a `String`
  |           &str
  |
help: create an owned `String` on the left
      and add a borrow on the right
  |
2 |     return "hello ".to_owned() + &name
  |                   +++++++++++   +

The error is “cannot add String to a string slice” that’s how &str is pronounced.

You will very often come across this problem with two strings in Rust, but it’s so easily worked around when you start out.

You don’t need to know the difference to continue working on your function, I’m not even going to tell you it, because, as we’ll see, Rust gives you the exact answer in the help text.

But let’s dutifully walk through the error, as you would do if you were looking at this with fresh eyes, trying to grok it.

error[E0369]: cannot add `String` to `&str`
 --> main.rs:2:21
  |
2 |    return "hello " + name
  |           -------- ^ ---- String
  |           |        |
  |           |       `+` cannot be used to concatenate
              |       a `&str` with a `String`
  |           &str
  |
help: create an owned `String` on the left
      and add a borrow on the right
  |
2 |     return "hello ".to_owned() + &name
  |                   +++++++++++   +

Rust produces ascii diagrams to help point out what it’s talking about, which in heavily-nested code can be a life saver!

Here, it’s drawn a line between “hello” and it’s label, which is a &str.

It’s telling us that this “hello” string is of type string slice, which is perhaps not quite what we expected.

We will fix it in a moment. Let’s continue walking the error.

error[E0369]: cannot add `String` to `&str`
 --> main.rs:2:21
  |
2 |    return "hello " + name
  |           -------- ^ ---- String
  |           |        |
  |           |       `+` cannot be used to concatenate
              |       a `&str` with a `String`
  |           &str
  |
help: create an owned `String` on the left
      and add a borrow on the right
  |
2 |     return "hello ".to_owned() + &name
  |                   +++++++++++   +

We are warned here, on lines 7 and 8 that the + symbol can’t be used to concatenate a string slice and a string.

Fair enough, they are different types, different types often can’t be simply concatenated by using plus.

error[E0369]: cannot add `String` to `&str`
 --> main.rs:2:21
  |
2 |    return "hello " + name
  |           -------- ^ ---- String
  |           |        |
  |           |       `+` cannot be used to concatenate
              |       a `&str` with a `String`
  |           &str
  |
help: create an owned `String` on the left
      and add a borrow on the right
  |
2 |     return "hello ".to_owned() + &name
  |                   +++++++++++   +

At the end of line 5, the compiler is telling us that name is of type String, capital S String, as we set in the function signature.

Now that we’ve decomposed this ascii diagram explaining the pieces of the puzzle and what the problem is, let’s focus on the compiler’s proposed solution:

error[E0369]: cannot add `String` to `&str`
 --> main.rs:2:21
  |
2 |    return "hello " + name
  |           -------- ^ ---- String
  |           |        |
  |           |       `+` cannot be used to concatenate
              |       a `&str` with a `String`
  |           &str
  |
help: create an owned `String` on the left
      and add a borrow on the right
  |
2 |     return "hello ".to_owned() + &name
  |                   +++++++++++   +

We are told the exact code to solve this common beginner problem.

Turn that literal string slice into a proper String, with to_owned(), and borrow the name variable with &.

You do not yet need to know exactly what the explanation means to keep using Rust, and to use Rust’s superpowers, you merely need to do what the compiler tells you to do.

We will do just that.

fn hello(name: String) {
    return "hello ".to_owned() + &name
}

here We have dutifully added the to_owned() call, converting the string slice into a proper String, and borrowed the name variable.

We are on the home stretch, there is just one more correction, and if you have used a statically-typed language before, you may have guessed it already:

error[E0308]: mismatched types
 --> main.rs:2:12
  |
1 | fn hello(name: String) {
  |            - help: try adding a return type: `-> String`
2 |     return "hello ".to_owned() + &name
  |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected `()`,
                found `String`
For more information about an error, try `rustc
--explain E0308`.

the problem is that Rust expected an empty return value, which in rust is the empty tuple, pronounced “unit”, but it found a String.

The language of the compiler is that it expects the return type of the function signature. And what you actually return is what it finds.

Expects and finds.

in this case, we have not specified any return type, so it expects nothing, but it found a String.

The solution, as in every example today, is told to you by the help text of the compiler.

Try adding a return type, String, it says.

Before we do that, it’s worth noting the last two lines of the error.

Most rust errors have this link to longer explanations and examples and counterexamples of errors.

Let’s try running rustc --explain E0308

Expected Type Did Not Match the Received Type

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

plus_one("Not a number");
//       ^^^^^^^^^^^^^^ expected `i32`, found `&str`

if "Not a bool" {
// ^^^^^^^^^^^^ expected `bool`, found `&str`
}

let x: f32 = "Not a float";
//     ---   ^^^^^^^^^^^^^ expected `f32`, found `&str`
//     |
//     expected due to this

This is the output, small toy examples of other mistakes that can lead to this error, along with a longer explanation of the problem, which I will read to you now.

This error (the output states) occurs when an expression was used in a place where the compiler expected an expression of a different type. It can occur in several cases, the most common being when calling a function and passing an argument which has a different type than the matching type in the function declaration.

Exactly what we did.

Let’s fix our function by adding the missing String return type.

fn hello(name: String) -> String {
    return "hello ".to_owned() + &name
}

$ cargo build
Finished dev [unoptimized + debuginfo] target(s) in 0.01s

The compiler is now happy, and if the compiler is happy, I am happy.

We have satisfied the compiler, which means many things are guaranteed about this simple function that are not guaranteed in other languages: - This code has no memory leaks, is thread-safe, and has no scaling surprises. - Memory is automatically freed when it goes out of scope, you don’t have to stop execution to do garbage collection - There are no execution paths that cause errors in the function, you can tell this by the signature. If a Rust function can error, it returns a Result type. Our function always returns a pure string, which means it is infallible, it will always work because the compiler guarantees that the calling code is providing a valid UTF-8 string. (panics are still possible, though rare)

Not only that but these guarantees hold through concurrent code, through threads, locks, channels, high-performance web APIs, and bare-metal coding.

The Compiler Teaches You

But how do we compile the code in Rust?

https://rustup.rs

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Beautiful one-liner install

• except if you are running Windows

The installer is a one-liner on linux, WSL, and macos, and an graphical installer is available for windows.

Updating Rust

rustup update

Local Offline Docs

rustup doc

Or directly open the Rust Book

rustup doc --book

Hello World

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

Compiling Your Code

rustc main.rs

Creating a Project with Cargo

$ cargo new hello
$ cd hello

Three items have been created for you

• Cargo.toml
• src/main.rs
• local git repo

Cargo.toml

[package]
name = "hello"
version = "0.1.0"
edition = "2021"

[dependencies]

TOML (Tom’s Obvious, Minimal Language) format

Building Your Project

$ cargo clean           # remove all previous builds
$ cargo build           # build the project incrementally
$ cargo build --release # build release binaries

Running Your Project

$ cargo run # run your code in debug mode

Checking Your Project

$ cargo check # check for errors

Cargo: Swiss Army Knife

cargo doc                 # local package documentation
cargo bench               # built-in benchmarking
cargo test                # built-in parallel testing
cargo add aws-sdk         # easily add dependencies
cargo install             # install exes into .cargo/bin
cargo clippy              # run the code linter
cargo publish             # publish packages to crates.io

Rust is the easiest language I have ever used because everything is right at hand.

You don’t need a teacher, the compiler is right on your machine

The tooling is almost as incredible as the language.

Not just incredible compared with C or C++, but compared with ANY language.

Modern Tooling

• cargo - packaging, building
• cargo fmt - standard formatting
• cargo test - doc and unit tests
• cargo bench - benchmarking
• cargo clippy - code linting
• rustup - rust version switching

Rust has a best-in-class package manager, solving all the dependency nightmares we face day-to-day.

This is what you get when you have a community focussed on correctness.

https://github.com/rust-lang/rustlings

To take this iterative approach to learning the whole of the Rust language, try Rustlings, a simple code system where the compiler and unit tests teach you.

Additional Resources

• Everything related to Rust on fasterthanli.me

• Rust By Example https://doc.rust-lang.org/rust-by-example/

  • follows the same chapter ordering to the Rust Book

Rust

Your code can be perfect

Because, finally, our code can be perfect.

Our First Rust Project

The Guessing Game

use std::io;

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

    let mut guess = String::new();

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

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

use std::io;

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

    let mut guess = String::new();

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

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

Generating a Secret Number

Cargo.toml

[dependencies]
rand = "0.8.5"

Updating a Crate

$ cargo update
    Updating crates.io index
    Updating rand v0.8.5 -> v0.8.6

Generating a Random Number

use std::io;
use rand::Rng;

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

    let secret_number =
        rand::thread_rng().gen_range(1..=100);

Consulting local docs

cargo doc --open

Comparing the Guess to the Secret Number

use std::cmp::Ordering;

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

Resolving the Compile-Time Error

let mut guess = String::new();

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

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

Adding a Loop

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

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

        // --snip--
    }

Quitting after a Correct Guess

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

Handling Invalid Input

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

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

You have just built your first Rust project!

Required Additional Reading

The Rust Programming Language, Chapter 1-2