rsdoc search engine

On Firefox, you can add this as a keyword bookmark.

Why Rustup?

It’s common to want to use different versions of the compiler.

Rustup also helps you install new targets (to cross-compile).

Different versions?

New features start off in Unstable Rust and “cook” for a while.

It is only possible to use unstable features using the Nightly build.

Also, you may need to test your project on older versions at times.

Cross-compilation

Rust is based on LLVM, and so cross-compilation is supported out-of-the-box.

But to target a target, you need to have the standard library for that target. Rustup helps you install those additional things.

Cargo.toml

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

[dependencies]

Compiling with Cargo

Edit your program: src/main.rs

fn main() {
  println!("Hello Cargo!");
}

Compile and run

$ cargo build
$ target/debug/hello_cargo
# Or...
$ cargo run

Moving forward

Until we start using Cargo features, you can either call rustc directly, or use Cargo.

Block expression

All blocks are expressions.

println!("{:?}", {
  let mut y = 0;
  while y < 10 { y += 1; }
  y
});

Blocks evaluate to the last expression evaluated.

The semicolon

; converts an expression to a statement (which is of type ()), discarding the value.

println!("{:?}", {
  let mut y = 0;
  while y < 10 { y += 1; }
  y;
});

if expression [B]

if is an expression.

let x = true;
println!("{}", if x { 1 } else { 0 });

Note that both branches must evaluate to the same type (which could be ()).

while loop [B]

The while loop is an expression evaluating to ().

let mut x = 0;
println!("{:?}", while x < 10 { x += 1; });

for loop [B]

The for loop is an expression evaluating to ().

let x = [1, 2, 3];
for y in &x {
  println!("{}", y);
}

Infinite loop [B]

let mut x = 0;
println!("{}", loop {
  x += 1;
  if x > 10 { break x; }
});

loop expressions can evaluate to a non-() value!

Formatting macros

Macros operate on the AST level at compile-time.

println!("Hello! {0} in hex is {0:02X}", 15);

This means that format strings are actually parsed and type-checked at compile-time,

println!("Hello! {0} in hex is {0:02X}", "Hello");
// error[E0277]: the trait bound `str: std::fmt::UpperHex`
// is not satisfied

…and are expanded out into function calls to produce the string you need.

Exercise 1

fn main() {
  for i in 1..=100 {
    let m3 = i % 3 == 0; let m5 = i % 5 == 0;
    if m3 || m5 {
      println!("{}{}",
        if m3 { "Fizz" } else { "" },
        if m5 { "Buzz" } else { "" });
    } else {
      println!("{}", i);
    }
  }
}

(Note: this isn’t the most idiomatic Rust.
We’ll get there.)

String

To exemplify ownership, let’s look at the String type: a resizable string buffer.

It is akin to StringBuilder in Java/C#, or std::string in C++.

let mut s = String::from("hello");
s.push_str(", world!");
println!("{}", s);

This prints “hello, world!”.

String

String is internally a pointer to a heap buffer and a string length (plus the length of the buffer).

When we create a new String, the function we call allocates this buffer for us.

But how do we then deallocate (free) this buffer?

Dropping

{
  let mut s = String::from("hello");
  // do things with s
} // the String owned by s is dropped

s owns the String. When s goes out of scope, the value it points to is dropped.

When a value is dropped, a destructor can be called. In the case of String, it frees the heap allocation.

This is essentially RAII in C++.

Moving

{
  let s1 = String::from("hello");
  let s2 = s1;
}

When s1 and s2 go out of scope, what happens?

Moving

When we do s2 = s1, the String is moved into s2. s1 is now invalid.

{
  let s1 = String::from("hello");
  let s2 = s1;
  println!("{}", s1);
  // error[E0382]: borrow of moved value: `s1`
}

This is what is unique about Rust: values have unique ownership; this eliminates use-after-frees and double-frees.

cloneing

let s1 = String::from("hello");
let s2 = s1.clone();
println!("{}", s1);

clone is a method implemented by String that makes a deep copy.

What about primitives?

let a = 1;
let b = a;
println!("{}", a);

Scalar primitives (integers, floats, characters) implement the Copy trait.

(We’ll talk about traits later.)

drop

It is possible to manually drop a value:

let s1 = String::from("hello");
drop(s1);

Quick question: How is drop implemented?

References

fn calc_len(x: String) -> (String, usize) {
  let len = x.len();
  (x, len)
}

fn main() {
  let x = String::from("hello");
  let y = calc_len(x);
  let x = y.0;
  let len = y.1;
  println!("{}", x);
  println!("{}", len);
}

Not very convenient.

References

Let’s pass in a reference instead.

fn calc_len(x: &String) -> usize {
  x.len()
}

fn main() {
  let x = String::from("hello");
  println!("{}", calc_len(&x));
  println!("{}", x);
}

Mutable references

fn change(some_string: &String) {
  some_string.push_str(", world");
  // error[E0596]: cannot borrow `*some_string` as mutable,
  // as it is behind a `&` reference
}

fn main() {
  let s = String::from("hello");
  change(&s);
}

Normal references are immutable.

Mutable references

fn change(some_string: &mut String) {
  some_string.push_str(", world");
}

fn main() {
  let mut s = String::from("hello");
  change(&mut s);
}

We need to make a mutable reference.

Aside: Docs

String docs

You can tell whether a method takes:

Mutable refs are exclusive

fn main() {
  let mut s = String::from("hello");
  let mutref1 = &mut s;
  let mutref2 = &mut s;
  // error[E0499]: cannot borrow `s` as mutable
  // more than once at a time
  println!("{}", mutref1);
}

Mutable refs are exclusive

fn main() {
  let mut s = String::from("hello");
  let mutref1 = &mut s;
  let mut t = s;
  // error[E0505]: cannot move out of `s`
  // because it is borrowed
  println!("{}", mutref1);
}

Mutable refs are exclusive

fn main() {
  let mut s = String::from("hello");
  let mutref1 = &mut s;
  let ref1 = &s;
  // error[E0502]: cannot borrow `s` as immutable
  // because it is also borrowed as mutable
  println!("{}", mutref1);
}

Mutable refs are exclusive

This solves data races.

It is possible to have aliasing and mutability using Cell/RefCell, or Mutex/RwLock for multithreaded scenarios.

These types do checks at runtime instead, in line with Rust’s philosophy: you opt-in to only what you need.

String literals

The type of a string literal is &str *.

let s: &str = "Hello!";
println!("{} {}", s.len(), s);

We can slice them too.

let s: &str = "Hello world!";
println!("{}", &s[..5]);

* Almost.

Array slices

You can slice arrays:

let arr: [u32; 5] = [1, 2, 3, 4, 5];
let slice: &[u32] = &arr[..3];
println!("{:?}", slice);

The type of a slice is just &[T].

Specifying lifetimes

Lifetimes are part of references’ types.

It is possible to name lifetimes, but we’ll only see how this is important later.

There is a special lifetime name static.

With that, we can give the full type of a string literal:

let x: &'static str = "Hello!";

impling methods

Continuing from the previous example.

impl Bus {
  fn arrive(&self) {
    println!("{} has arrived", self.number);
  }
}

fn main() {
  let route = get_route("A1");
  route.arrive();
}

Update syntax

impl Bus {
  fn with_number(self, new_num: &str) -> Bus {
    Bus {
      number: String::from(new_num),
      ..self
    }
  }
}

fn main() {
  let route = get_route("A1").with_number("A2");
  route.arrive();
}

Associated methods

i.e. “static” methods

impl Bus {
  fn of_number(num: &str) -> Self {
    Bus {
      number: String::from(num), interval: 5
    }
  }
}

fn main() {
  let route = Bus::of_number("A1").with_number("A2");
  route.arrive();
}

Using enums

fn handle(x: Message) {
  // ... ???
}

fn main() {
  let x = Message::ChangeColor(0, 0, 0);
  handle(x);
}

How do we know which variant we have?

match is exhaustive

fn handle(x: Message) {
  match x {
    Message::Quit => println!("Quitting."),
    Message::Move { x, y } => println!("Moving to {}, {}", x, y),
    Message::Write(str) => println!("Write {}", str),
    // Message::ChangeColor(r, g, b) => println!("Changing colour to {}, {}, {}", r, g, b)
  };
}

Comment out that line. We get:

error[E0004]: non-exhaustive patterns:
  `ChangeColor(_, _, _)` not covered

Patterns

You can do the same with enums and structs.

struct Bus {
  number: String, interval: u32
}

impl Bus {
  fn of_number(num: &str) -> Self {
    Bus {
      number: String::from(num), interval: 5
    }
  }
}

fn main() {
  let route = Bus::of_number("A1");
  let Bus { interval: int, .. } = route;
  println!("Got interval {}", int);
}

Patterns

_ acts as a wildcard, since matches need to be exhaustive.

fn main() {
  let x = 7;
  match x {
    1 => println!("one"),
    3 => println!("three"),
    5 => println!("five"),
    7 => println!("seven"),
    _ => (),
  };
}

Exercise 2

fn main() {
  for i in 1..=100 {
    match (i % 3, i % 5) {
      (0, 0) => println!("FizzBuzz"),
      (0, _) => println!("Fizz"),
      (_, 0) => println!("Buzz"),
      (_, _) => println!("{}", i)
    }
  }
}

Option methods

Option has many methods. Let’s rewrite Person::greet.

struct Person {
  name: Option<String>
}

impl Person {
  fn greet(&self) {
    println!("Hello, {}",
      self.name.as_ref().map(String::as_str)
        .unwrap_or("MISSINGNO."));
  }
}

fn main() {
  Person { name: None }.greet();
}

Generics

In impls:

struct Point<T> {
  x: T,
  y: T,
}

impl<T> Point<T> {
  fn x(&self) -> &T {
    &self.x
  }
}

Generics

You can impl a specific concrete type:

impl Point<f32> {
  fn distance_from_origin(&self) -> f32 {
    (self.x.powi(2) + self.y.powi(2)).sqrt()
  }
}

Generics over lifetimes

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

impling traits [B]

struct NewsArticle {
  headline: String,
  author: String,
  content: String,
}

impl Summary for NewsArticle {
  fn summarize(&self) -> String {
    format!("{}, by {}", self.headline, self.author)
  }
}

fn main() {
  let art = NewsArticle {
    headline: "Rust is great!".to_owned(),
    author: "Graydon Hoare".to_owned(),
    content: "Rust is really really good!".to_owned()
  };
  println!("{}", art.summarize());
}

impling traits

You can impl a trait you define on other types:

impl Summary for String {
  fn summarize(&self) -> String {
    (&self[..self.len().min(10)]).to_owned()
  }
}

fn main() {
  let x = String::from("Hellohello hello");
  println!("{}", x.summarize());
}

Trait bounds [B]

fn print_summary<T>(x: &T) where T: Summary {
  println!("{}", x.summarize());
}

fn main() {
  let x = String::from("Hellohello hello");
  print_summary(&x);
}

Trait bounds

fn print_summary<T: Summary>(x: &T) {
  println!("{}", x.summarize());
}

fn main() {
  let x = String::from("Hellohello hello");
  print_summary(&x);
}

Blanket impls [B]

use std::fmt::Display;

impl<T: Display> Summary for T {
  fn summarize(&self) -> String {
    let s = self.to_string();
    (&s[..s.len().min(5)]).to_owned()
  }
}

fn main() {
  print_summary(&1234567890);
}

#[derive]

Some traits can be auto-derived:

#[derive(Debug, Clone)]
struct Bus {
  number: String, interval: u32
}

fn main() {
  let a2 = Bus {
    number: "A2".to_owned(),
    interval: 5
  };
  let a2_2 = a2.clone();
  println!("{:?}", a2);
  println!("{:?}", a2_2);
}

Lambdas and closures

Closures implement (one of)

• Fn: those that only take immutable references to captured variables
• FnMut: those that take mutable references
• FnOnce: those that might only be callable once

Lambdas and closures

fn apply_fn<F, T>(f: F, arg: T) -> T
  where F: Fn(T) -> T {
  f(arg)
}

fn main() {
  println!("{}", apply_fn(|x| x * 2, 5));
}

Lambdas and closures

fn apply_fn<F, T>(mut f: F, arg: T) -> T
  where F: FnMut(T) -> T {
  f(arg)
}

fn main() {
  let mut y = 10;
  println!("{}", apply_fn(|x| { y += x; y }, 5));
}

Iterators

But their power comes from their composability:

let x = [1, 2, 3, 4, 5];
for i in x.iter().map(|x| x * x) {
  println!("{}", i);
}

Iterators

On ranges:

for i in (1..=5).map(|x| x * x) {
  println!("{}", i);
}

Iterators

for i in (1..=5).chain(21..=25).map(|x| x * x) {
  println!("{}", i);
}

Iterators

let x = ["Hello", "World", "3", "4", "5"];
for (i, s) in x.iter().enumerate() {
  println!("{} = {}", i, s);
}

Adding dependencies

In Cargo.toml:

[dependencies]
rand = "0.7"

Using dependencies

Docs at docs.rs/rand

src/main.rs:

fn main() {
  for i in (1..100).map(|_| rand::random::<i32>()) {
    println!("{}", i);
  }
}

Common crates

• rand: Random generators
• log: Logging
• serde: Serialisation
• tokio: Async I/O
• crossbeam: Tools for concurrent programming
• hyper: Low-level HTTP
• reqwest: Higher-level HTTP
• …

Documentation

You can render the documentation:

$ cargo doc

Architecting Rust programs

• Decide on & vs &mut from the caller’s perspective
  • Expect to have many threads calling it? Use & and handle mutability internally
  • Expect to have only one thread? Use &mut to enforce that guarantee

Architecting Rust programs

• If you’re fighting the borrow checker, something is not right