Lifetimes

A reference (&T) is a pointer that does not own what it points at. Something else owns the value, and when that owner goes out of scope the value is dropped. If a reference is still around after that, it points at freed memory: a dangling reference. In C and C++ this compiles and then crashes, or worse, silently reads garbage. Rust refuses to compile it.

A lifetime is the stretch of code during which a reference is valid. The compiler part that checks lifetimes is the borrow checker (you met it in Module 03). Its one rule: a reference must never outlive the value it borrows from. Most of the time it works out every lifetime on its own and you never write one. You only annotate when the compiler cannot tell which input a returned reference came from.

fn main() {
    let owner = String::from("borrowed text");
    let r = &owner;          // r borrows from owner
    println!("{}", r);       // fine: owner is still alive
    println!("{} bytes", r.len());
}   // r stops being used, then owner is dropped here

borrowed text
13 bytes

fn main() {
    let r;
    {
        let x = 5;
        r = &x;
    }
    println!("r = {}", r);
}

error[E0597]: `x` does not live long enough
 --> main.rs:5:13
  |
4 |         let x = 5;
  |             - binding `x` declared here
5 |         r = &x;
  |             ^^ borrowed value does not live long enough
6 |     }
  |     - `x` dropped here while still borrowed
7 |     println!("r = {}", r);
  |                        - borrow later used here

fn main() {
    let x = 5;
    let r = &x;
    println!("r = {}", r);
}

When a function takes two references and returns one, the compiler cannot see from the signature which input the result borrows from. Callers need to know that, because it decides how long they must keep each argument alive. So Rust asks you to say it.

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

fn main() {
    println!("{}", longest("apple", "fig"));
}

error[E0106]: missing lifetime specifier
 --> main.rs:1:33
  |
1 | fn longest(x: &str, y: &str) -> &str {
  |               ----     ----     ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `x` or `y`
help: consider introducing a named lifetime parameter
  |
1 | fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
  |           ++++     ++          ++          ++

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

<'a> declares a lifetime parameter, just like <T> declares a type parameter. &'a str reads "a string slice that is valid for at least 'a". The signature below promises: the returned reference is valid for as long as both inputs are valid. In practice 'a becomes the shorter of the two lifetimes. Annotations never change how long anything lives; they only describe relationships so the checker can verify them.

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

fn main() {
    let a = String::from("a long string");
    let b = String::from("xyz");
    let result = longest(a.as_str(), b.as_str());
    println!("longest: {}", result);

    let c = String::from("inner");
    {
        let d = String::from("tiny");
        println!("longest: {}", longest(c.as_str(), d.as_str()));
    }
}

longest: a long string
longest: inner

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

fn main() {
    let a = String::from("a long string");
    let result;
    {
        let b = String::from("xyz");
        result = longest(a.as_str(), b.as_str());
    }
    println!("{}", result);
}

error[E0597]: `b` does not live long enough
  --> main.rs:10:38
   |
 9 |         let b = String::from("xyz");
   |             - binding `b` declared here
10 |         result = longest(a.as_str(), b.as_str());
   |                                      ^ borrowed value does not live long enough
11 |     }
   |     - `b` dropped here while still borrowed
12 |     println!("{}", result);
   |                    ------ borrow later used here

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

fn main() {
    let a = String::from("a long string");
    let b = String::from("xyz");
    let result = longest(a.as_str(), b.as_str());
    println!("{}", result);
}

A returned reference must borrow from one of the inputs (or from something 'static). It can never borrow from a local variable, because every local is dropped when the function returns. No annotation can fix that; the answer is to return an owned value instead.

fn make_greeting(name: &str) -> &str {
    let s = format!("Hello, {}!", name);
    &s
}

fn main() {
    println!("{}", make_greeting("Ada"));
}

error[E0515]: cannot return reference to local variable `s`
 --> main.rs:3:5
  |
3 |     &s
  |     ^^ returns a reference to data owned by the current function

fn make_greeting(name: &str) -> String {
    format!("Hello, {}!", name)
}

fn main() {
    println!("{}", make_greeting("Ada"));
}

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

fn shout(s: &str) -> String {
    s.to_uppercase()
}

fn main() {
    let line = String::from("borrow checker rules");
    let w = first_word(&line);   // borrows from line
    let loud = shout(w);         // brand new owned String
    println!("{} -> {}", w, loud);
}

borrow -> BORROW

Early Rust made you annotate every reference in every signature. The patterns were so repetitive that the compiler now fills them in using three elision rules. If the rules produce an answer, you write nothing. If they do not, you get E0106.

1. 1
   Rule 1: every input reference gets its own lifetime

   fn f(x: &str, y: &str) is read as fn f<'a, 'b>(x: &'a str, y: &'b str).

2. 2
   Rule 2: one input lifetime flows to every output

   If there is exactly one input lifetime, the output gets it. fn first_word(s: &str) -> &str becomes fn first_word<'a>(s: &'a str) -> &'a str.

3. 3
   Rule 3: methods borrow from self

   If one of the inputs is &self or &mut self, the output gets the lifetime of self, however many other reference parameters there are.

// Written with elision...
fn trim_dots(s: &str) -> &str {
    s.trim_matches('.')
}

// ...and exactly what the compiler reads it as.
fn trim_dots_explicit<'a>(s: &'a str) -> &'a str {
    s.trim_matches('.')
}

fn main() {
    let raw = String::from("...ready...");
    println!("{}", trim_dots(&raw));
    println!("{}", trim_dots_explicit(&raw));
}

ready
ready

A struct field can be a reference, but then the struct itself must not outlive what that field points at. You express this with a lifetime parameter on the struct: struct Excerpt<'a> { part: &'a str } reads "an Excerpt cannot outlive the text its part borrows from".

struct Excerpt {
    part: &str,
}

fn main() {
    let text = String::from("Call me Ishmael. Some years ago...");
    let e = Excerpt { part: &text[..16] };
    println!("{}", e.part);
}

error[E0106]: missing lifetime specifier
 --> main.rs:2:11
  |
2 |     part: &str,
  |           ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct Excerpt<'a> {
2 ~     part: &'a str,
  |

struct Excerpt<'a> {
    part: &'a str,
}

struct Excerpt<'a> {
    part: &'a str,
}

impl<'a> Excerpt<'a> {
    fn word_count(&self) -> usize {
        self.part.split_whitespace().count()
    }

    // Rule 3: the returned &str borrows from self
    fn first(&self) -> &str {
        self.part.split(' ').next().unwrap_or("")
    }
}

fn main() {
    let novel = String::from("Call me Ishmael. Some years ago...");
    let first_sentence = novel.split('.').next().unwrap();
    let e = Excerpt { part: first_sentence };
    println!("{}", e.part);
    println!("{} words, starts with {}", e.word_count(), e.first());
}

Call me Ishmael
3 words, starts with Call

'static means "valid for the whole run of the program". Every string literal is a &'static str, because its bytes are baked into the compiled binary and never freed. Constants and static items are 'static too.

static APP_NAME: &str = "inventory";

fn level_name(level: u8) -> &'static str {
    match level {
        0 => "debug",
        1 => "info",
        2 => "warn",
        _ => "error",
    }
}

fn main() {
    let name: &'static str = level_name(2);
    println!("[{}] {}", APP_NAME, name);
    println!("[{}] {}", APP_NAME, level_name(9));
}

[inventory] warn
[inventory] error

You will also see T: 'static as a bound, for example on std::thread::spawn. That means "T contains no borrowed data that could expire", so an owned String or Vec satisfies it. It does not mean the value lives forever. Module 10 shows why threads need this.

Lifetime

The region of code during which a reference is valid. Checked at compile time, costs nothing at runtime.

Dangling reference

A reference to memory that has already been freed. Rust rejects any program that could create one.

Lifetime parameter ('a)

A generic name for a lifetime, declared like <'a>, used to relate the lifetimes of inputs, outputs and struct fields.

Lifetime elision

Three rules the compiler uses to fill in lifetimes in function signatures so you do not have to.

'static

The lifetime of the whole program. String literals have it. As a bound (T: 'static) it means the type holds no short-lived borrows.

Borrow checker

The part of rustc that proves every reference is used only while its owner is alive and that mutable borrows are exclusive.