Lifetimes

Why lifetimes exist

Rule 2 of borrowing says a reference must never outlive the value it points to. The compiler checks this by tracking a lifetime for every reference: the region of code where it is valid. Most of the time this is invisible. You only write lifetimes when the compiler cannot work out, from a function's signature alone, how long a returned reference is valid.

let r;                 // ---------+-- 'a (r)
{                      //          |
    let x = 5;         // -+-- 'b  |
    r = &x;            //  |       |
}                      // -+       |   x dropped here
println!("{r}");       //          |   r used here: x is gone!
                       // ---------+

A function that needs an annotation

fn longest(x: &str, y: &str) -> &str {
    if x.len() > y.len() { x } else { y }
}
// error[E0106]: missing lifetime specifier
// help: this function's return type contains a borrowed value, but the
//       signature does not say whether it is borrowed from `x` or `y`

The fix is a lifetime parameter. It is written with an apostrophe and a short name, usually 'a, declared in angle brackets after the function name, like a generic.

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

In practice, 'a becomes the shorter of the two input lifetimes. The caller may use the result only while BOTH inputs are still alive.

fn main() {
    let a = String::from("Thiruvananthapuram");
    let result;
    {
        let b = String::from("Goa");
        result = longest(&a, &b);
        println!("{result}");      // OK: a and b are both alive
    }
    // println!("{result}");       // error[E0597]: `b` does not live long enough
}

Lifetime elision: why you rarely write them

Elision means "leaving out". The compiler applies three rules to fill in lifetimes for you:

1. Each reference parameter gets its own lifetime.
2. If there is exactly one input lifetime, it is given to all output references. That is why fn first_word(s: &str) -> &str needs no annotation.
3. If there is a &self or &mut self parameter (a method), its lifetime is given to the outputs.

If the rules still leave an output lifetime unknown, as with longest (two inputs, no self), you must write it.

Structs that hold references

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

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

'static

'static is a special lifetime meaning "valid for the whole program". String literals are &'static str because they are stored inside the program file. When the compiler suggests adding 'static, it is usually a sign to return an owned String instead, not to make your data static.

Common mistakes

• Adding 'static to silence an error. It rarely fixes the real problem.
• Thinking 'a makes a value live longer. It does not; it only describes.
• Putting references in structs everywhere. Start with owned data.
• Annotating every function. Let elision work; add lifetimes only when the compiler asks.