Rust Lifetime Annotations

Also Known As

TL;DR

Explanation

A lifetime is a region of code over which a reference is valid. Rust's borrow checker tracks these regions to guarantee that no reference outlives the data it points to, eliminating dangling pointers and use-after-free without a garbage collector. Most of the time you never write lifetimes explicitly because the compiler infers them, but when a function returns a reference, or a struct holds one, the compiler sometimes cannot work out the relationship on its own and asks you to spell it out.

Lifetime annotations use a leading apostrophe, like `'a`, and read as 'a generic lifetime parameter'. In `fn longest<'a>(x: &'a str, y: &'a str) -> &'a str`, the annotation says the returned reference lives at least as long as both inputs, so the caller knows the result cannot outlive either argument. The annotation does not change how long anything lives; it only describes constraints the borrow checker then verifies. If your code does not actually satisfy the constraint, it fails to compile.

Lifetime elision rules let the compiler fill in the obvious cases. Each elided input reference gets its own lifetime; if there is exactly one input lifetime it is assigned to all outputs; and in methods the lifetime of `&self` is assigned to outputs. These three rules cover the vast majority of signatures, which is why beginners rarely see explicit lifetimes until they return references from multi-argument functions or store references in structs.

The special lifetime `'static` means a reference can live for the entire program, as with string literals. It is frequently misused as a way to silence borrow errors, which usually just moves the problem or forces unnecessary cloning. The right fix is almost always to express the genuine relationship between inputs and outputs, or to restructure ownership so a borrow is not needed at all. Lifetimes are not runtime constructs; they are erased before code generation and exist purely to let the compiler prove memory safety.

Common Misconception

Why It Matters

Common Mistakes

• Assuming two arguments sharing the lifetime 'a must live exactly as long, when the compiler instead picks a single region that fits within both borrows.

Avoid When

• Functions that take or return owned values, where no reference crosses the boundary and lifetimes never appear.
• Cases the elision rules already handle, such as a single input reference, where explicit annotations only add noise.
• Situations where cloning a small value is genuinely cheaper in complexity than threading a lifetime through many types.

When To Use

• Returning a reference from a function that takes more than one reference argument, so the compiler knows which input the output borrows from.
• Storing references inside a struct or enum, which requires declaring a lifetime parameter on the type.
• Writing zero-copy APIs that hand back borrowed slices instead of allocating new owned data.
• Bounding generic types with lifetimes when a trait object or generic must not outlive borrowed data.

Code Examples

// This does not compile: the returned reference would dangle.
fn first_word(s: String) -> &str {
    // s is owned by this function and dropped when it returns,
    // so any reference into it would be invalid afterward.
    s.split_whitespace().next().unwrap()
}

// A common 'fix' people reach for: force 'static and clone everywhere.
fn longest(x: &str, y: &str) -> &'static str {
    // 'static is wrong here; these inputs do not live forever.
    // This will not compile, and leaking or cloning to satisfy it is wasteful.
    if x.len() > y.len() { x } else { y }
}

fn main() {
    let a = String::from("hello world");
    println!("{}", first_word(a));
}

// Borrow the input so the caller keeps ownership; elision infers the lifetime.
fn first_word(s: &str) -> &str {
    s.split_whitespace().next().unwrap_or("")
}

// Spell out that the result lives at least as long as both inputs.
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}

// Structs holding references need a lifetime parameter.
struct Excerpt<'a> {
    part: &'a str,
}

fn main() {
    let a = String::from("hello world");
    println!("{}", first_word(&a));

    let one = String::from("short");
    let two = String::from("a longer string");
    println!("{}", longest(&one, &two));

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

References

• https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html
• https://doc.rust-lang.org/reference/lifetime-elision.html
• https://doc.rust-lang.org/nomicon/lifetimes.html
• https://doc.rust-lang.org/reference/trait-bounds.html#lifetime-bounds

Tags

Related Terms