Borrowing & ownership

fn main() {
    let s = String::from("hello");   // s owns the String
    println!("{s}");
}                                     // s goes out of scope: the memory is freed

fn main() {
    let a = String::from("a");
    {
        let b = String::from("b");
        println!("{a} {b}");
    }                              // b is freed here
    // println!("{b}");            // ERROR: b no longer exists
}                                  // a is freed here

struct Noisy(&'static str);

impl Drop for Noisy {
    fn drop(&mut self) {
        println!("dropping {}", self.0);
    }
}

fn main() {
    let _a = Noisy("a");
    let _b = Noisy("b");
    println!("end of main");
}
// end of main
// dropping b
// dropping a

Variables are freed in the reverse order of their declaration: a value declared later can borrow a value declared earlier, so the earlier one is always freed last. The fields of a struct are freed in declaration order.

let big = vec![0u8; 100_000_000];
process(&big);
drop(big);                // frees now instead of waiting for the end of the block
// long code that no longer needs big

fn process(_: &[u8]) {}

drop(x) is not magic: it is a function that takes the value and does nothing, so the value is freed when the function returns. It is also used to release a lock before the end of a block.

let s1 = String::from("hello");
let s2 = s1;                       // the String is MOVED from s1 to s2
// println!("{s1}");               // ERROR E0382: borrow of moved value
println!("{s2}");

Only the header (pointer, length, capacity) is copied; the bytes on the heap do not move. If s1 stayed valid, two variables would own the same block and free it twice. Rust therefore invalidates s1.

fn take(s: String) {
    println!("{s}");
}                                   // s is freed here

fn main() {
    let text = String::from("hello");
    take(text);                     // moved into the function
    // println!("{text}");          // ERROR
}

fn make() -> String {
    let s = String::from("new");
    s                               // moved to the caller: not freed here
}

fn add_dot(mut s: String) -> String {
    s.push('.');
    s                               // taken then given back
}

fn main() {
    let a = make();
    let a = add_dot(a);
}

Taking then giving back works, but it is heavy: a reference does the same thing more simply (section 6).

let name = String::from("Ada");
let v = vec![name];                 // moved into the Vec
// println!("{name}");              // ERROR

let title = String::from("x");
let show = move || println!("{title}");   // move: the closure owns title
show();
// println!("{title}");             // ERROR

let s = String::from("a");
for _ in 0..3 {
    // take(s);                     // ERROR: moved on the first turn, missing on the second
    take(s.clone());                // one copy per turn
}

fn take(_: String) {}

struct Person { name: String, age: u32 }

let p = Person { name: String::from("Ada"), age: 36 };
let name = p.name;                  // only the name field is moved
println!("{}", p.age);              // OK: age is still there
// println!("{}", p.name);          // ERROR: moved
// let q = p;                       // ERROR: p is incomplete

let s = String::from("a");
let condition = true;
if condition {
    drop(s);
}
// println!("{s}");                 // ERROR: maybe moved

The compiler reasons about all possible paths: if a single path moves the value, it is considered unavailable afterwards.

let x = 5;
let y = x;            // copy: x stays usable
println!("{x} {y}");

A Copy type is copied bit by bit instead of being moved. These are Copy:

• integers, floats, bool, char;
• shared references &T;
• tuples and arrays whose elements are all Copy;
• your own types with #[derive(Clone, Copy)], if all their fields are Copy.

These are not Copy: String, Vec, Box, HashMap, &mut T, and any type that implements Drop.

let s1 = String::from("hello");
let s2 = s1.clone();              // new allocation, bytes copied
println!("{s1} {s2}");            // both are valid

.clone() is visible in the code: this is intended, because copying heap data has a cost.

fn length(s: &String) -> usize {
    s.len()
}                                 // s is a reference: nothing is freed

fn main() {
    let text = String::from("hello");
    let n = length(&text);        // we lend text
    println!("{text}: {n}");      // text is still there
}

A reference &T is a pointer to a value owned by someone else. It never frees it.

let s = String::from("hello");
let r1 = &s;
let r2 = &s;
let r3 = &s;
println!("{r1} {r2} {r3}");       // as many readers as you want

fn modify(s: &String) {
    // s.push('!');               // ERROR: cannot borrow `*s` as mutable
}

let x = 5;
let r = &x;
assert_eq!(*r, 5);                // * to read the pointed value
assert_eq!(r.pow(2), 25);         // methods dereference automatically
let total = r + 1;                // operators too, for numbers

fn add_world(s: &mut String) {
    s.push_str(", world");
}

fn main() {
    let mut text = String::from("hello");   // the variable must be mut
    add_world(&mut text);                    // we lend for writing
    println!("{text}");                      // hello, world
}

You need mut in two places: on the variable (let mut) and on the borrow (&mut).

fn double(n: &mut i32) {
    *n *= 2;                    // * is required to assign the pointed value
}

let mut x = 5;
double(&mut x);
assert_eq!(x, 10);

let mut s = String::from("a");
let r1 = &mut s;
// let r2 = &mut s;             // ERROR E0499: two mutable borrows
r1.push('b');

What it is for: if two references could modify the same value, one could reallocate the content while the other reads it. This is the cause of "data races" between threads; Rust makes them impossible at compile time.

let mut s = String::from("hello");

let r1 = &s;
let r2 = &s;
println!("{r1} {r2}");           // last use of r1 and r2

let r3 = &mut s;                 // OK: r1 and r2 are no longer used
r3.push('!');

A borrow does not last until the end of the block but until its last use (a rule called NLL, Non-Lexical Lifetimes). Reordering the lines is often enough to fix an error.

let mut v = vec![1, 2, 3];
let first = &v[0];               // v is lent for reading
// v.push(4);                    // ERROR E0502: v cannot be modified
println!("{first}");
v.push(4);                       // OK: first is no longer used

push may reallocate the array: first would then point to freed memory.

// fn make() -> &String {
//     let s = String::from("hello");
//     &s                        // ERROR: s is freed at the end of the function
// }

fn make() -> String {            // fix: return the value itself
    String::from("hello")
}

fn add(v: &mut Vec<i32>) {
    v.push(1);
}

let mut v = vec![];
let r = &mut v;
add(r);                           // temporary reborrow of *r
add(r);                           // r is still usable
r.push(2);

Passing a &mut to a function does not move it: Rust creates a reborrow (&mut *r) that lasts for the duration of the call.

let mut v: Vec<usize> = vec![1, 2, 3];
v.push(v.len());                  // OK: v.len() is evaluated before the mutable borrow of push

struct Game { players: Vec<String>, scores: Vec<u32> }

let mut g = Game { players: vec!["a".into()], scores: vec![0] };
let players = &g.players;         // borrows g.players only
g.scores.push(10);                // OK: different field
println!("{players:?}");

The compiler tracks borrows field by field.

impl Game {
    fn players(&self) -> &Vec<String> { &self.players }
    fn add_score(&mut self, s: u32) { self.scores.push(s); }
}

let players = g.players();        // borrows ALL of g
// g.add_score(10);               // ERROR: g is already borrowed
println!("{players:?}");

A &self method borrows the whole struct: the compiler does not look at what the method really reads. Three fixes:

// 1. Access the fields directly (in the module that sees them)
let players = &g.players;
g.scores.push(10);

// 2. Copy what you need beforehand
let count = g.players().len();
g.add_score(10);

// 3. A method that returns both parts at the same time
impl Game {
    fn parts(&mut self) -> (&Vec<String>, &mut Vec<u32>) {
        (&self.players, &mut self.scores)
    }
}
let (players, scores) = g.parts();
scores.push(10);

let s = String::from("hello world");
let hello: &str = &s[0..5];
let world: &str = &s[6..];
let all: &str = &s[..];
let literal: &str = "text";       // a literal is already a &str

Indexes are in bytes: cutting in the middle of an accented character panics.

let word = "café";
// let x = &word[0..4];           // panics: 'é' takes bytes 3 and 4
let x = word.get(0..4);           // None, no panic
let first: String = word.chars().take(3).collect();   // "caf", in characters

let v = vec![1, 2, 3, 4, 5];
let middle: &[i32] = &v[1..4];    // [2, 3, 4]
let t = [10, 20, 30];
let start = &t[..2];

let (a, b) = v.split_at(2);       // two slices: [1, 2] and [3, 4, 5]

fn first_word(s: &str) -> &str {
    s.split(' ').next().unwrap_or("")
}

let mut s = String::from("hello world");
let word = first_word(&s);
// s.clear();                     // ERROR: word still borrows s
println!("{word}");

If the function returned an index (usize), nothing would prevent clearing s and then using the index, which is now wrong. The slice ties the result to the data.

// 1. Takes the String: the caller loses it
fn uppercase_v1(s: String) -> String { s.to_uppercase() }

// 2. Borrows a &String: only accepts String
fn uppercase_v2(s: &String) -> String { s.to_uppercase() }

// 3. Borrows a &str: accepts String, &str, literals, slices
fn uppercase_v3(s: &str) -> String { s.to_uppercase() }

// 4. Modifies in place: no new allocation
fn uppercase_v4(s: &mut String) { s.make_ascii_uppercase(); }

fn main() {
    let mut a = String::from("abc");
    uppercase_v3(&a);
    uppercase_v3("literal");
    uppercase_v4(&mut a);
    let b = uppercase_v1(a);       // a is no longer usable
}

let s = String::from("a");
let t = s;
// println!("{s}");

Fixes:

let t = s.clone();      // 1. copy
let t = &s;             // 2. borrow
// 3. use s before moving it
println!("{s}");
let t = s;

let mut v = vec![1, 2];
let a = &mut v[0];
// let b = &mut v[1];
// *a += *b;

Fixes:

// 1. split_at_mut: two mutable slices that do not overlap
let (left, right) = v.split_at_mut(1);
left[0] += right[0];

// 2. Go through the indexes
let b = v[1];
v[0] += b;

// 3. swap to exchange
v.swap(0, 1);

let mut v = vec![1, 2, 3];
// for x in &v {
//     if *x == 2 { v.push(4); }
// }

Fixes:

// 1. Decide first, modify afterwards
let contains = v.contains(&2);
if contains { v.push(4); }

// 2. Collect the additions then apply them
let additions: Vec<i32> = v.iter().filter(|&&x| x == 2).map(|_| 4).collect();
v.extend(additions);

// 3. Loop over the indexes when the change depends on the current element
for i in 0..v.len() {
    if v[i] == 2 { v[i] = 20; }
}

let s = String::from("a");
let r = &s;
// drop(s);
println!("{r}");

Fix: finish using the borrow before moving (println! before drop), or clone.

struct Container { content: String }

fn empty(b: &mut Container) -> String {
    // b.content                  // ERROR: cannot move out of `b.content` which is behind a mutable reference
    std::mem::take(&mut b.content)    // takes the value, leaves String::new()
}

fn read(b: &Container) -> String {
    b.content.clone()             // or return &str: &b.content
}

With an Option: opt.take() takes the value and leaves None.

let r;
{
    let x = 5;
    r = &x;
}                                 // x freed
// println!("{r}");               // ERROR: `x` does not live long enough

Fix: declare x in the same scope as r (or before), or store the value itself rather than a reference.

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

When a function returns a reference that can come from several parameters, you must say which parameter it depends on. Details are in the lifetimes course.

use std::mem;

let mut a = String::from("old");
let old = mem::replace(&mut a, String::from("new"));
let empty = mem::take(&mut a);          // a becomes ""
let mut x = 1;
let mut y = 2;
mem::swap(&mut x, &mut y);

fn main() {
    let mut list = vec![1, 2, 3];
    let first = &list[0];
    list.push(4);
    println!("{first}");
}

// Solution 1: copy the integer (Copy, free)
let first = list[0];
list.push(4);
println!("{first}");

// Solution 2: reorder
let first = &list[0];
println!("{first}");
list.push(4);

struct Session { token: Option<String> }

// Write `fn log_out(s: &mut Session) -> Option<String>` that returns the token and removes it.

// Solution:
fn log_out(s: &mut Session) -> Option<String> {
    s.token.take()
}

let t = s;              // move (non-Copy type)
let t = s.clone();      // explicit copy
let r = &s;             // read borrow (several possible)
let r = &mut s;         // write borrow (only one, nothing else at the same time)
*r = value;             // write through &mut
drop(s);                // free now
std::mem::take(&mut x)  // take, leaving Default
opt.take()              // take, leaving None
v.split_at_mut(i)       // two disjoint &mut