Understanding lifetimes

Lifetime annotations

Before we go any further, just a short note on the notation of lifetimes, as it's a bit different from what you get in a lot of other languages.

Lifetimes are annotated by a leading apostrophe followed by a variable name. When talking about generic lifetimes, we often use single, lowercase letters, starting from ~'a~, ~'b~, etc. However, there is nothing stopping you from using longer, more explanatory names if that suits you better.

Why we need lifetimes

If they're such a weird feature, then why do we need lifetimes? The answer, my friend, lies in Rust's ownership model. The borrow checker takes care of allocating and freeing memory and also of making sure that no references point to memory that has been freed. Like borrows, lifetimes are checked at compile-time, which means that your program can't compile if the borrow checker deems the references invalid.

In particular, lifetimes are important to keep in mind when returning references from functions and when creating structs with references. These are both common situations, and it's easy to get lost if you don't understand what's going on.

The explanatory example

Ultimately, lifetimes are a matter of scope. Values get dropped when they go out of scope and any references to them after they have been dropped are invalid.

The simplest way to demonstrate lifetimes is something like the following example, shamelessly stolen/adapted from the Book's chapter on lifetimes.

// this code sample does *not* compile
{
    let x;
    {                           // create new scope
        let y = 42;
        x = &y;
    }                           // y is dropped

    println!("The value of 'x' is {}.", x);
}

This little piece of code has two distinct scopes. When the inner scope closes, y is dropped. At that point, even if x is still available in the outer scope, the reference is invalid because the value it pointed to is dropped: The value that x points to 'does not live long enough'.

In lifetime jargon, we can say that the outer scope has the lifetime ~'outer~ and the inner scope the lifetime ~'inner~. ~'outer~ clearly outlives ~'inner~ in this case. When ~'inner~ ends, all values with that lifetime are invalidated.

Lifetime elision

When writing functions that accept references as arguments, the compiler can infer the correct lifetimes in many cases, saving us the trouble of writing them out by hand. When lifetime annotations are implicit, we call this lifetime elision.

The compiler uses three rules to figure out whether lifetime annotations can be elided or not. The section on lifetime elision talks about these rules in detail, but the short form is that you can elide lifetime annotations in functions if one of the following is true:

• The function doesn't return a reference.
• There is exactly one reference input parameter.
• The function is a method, taking &self or &mut self as the

first parameter.

Returning references from functions

You can't return a reference from a function without also passing in a reference. If you try, you'll find that the reference is invalid as soon as the function returns and your program won't compile^[1].

If your function takes exactly one reference parameter, then you'll be fine without annotations. All output references will be given the same lifetime as the input parameter. As such, this simple function will compile just fine, even if there are no explicit lifetime annotations:

fn f(s: &str) -> &str {
    s
}

However, if we add another input string parameter (even if we don't use it), we'll suddenly not be able to compile this:

// this code sample does *not* compile
fn f(s: &str, t: &str) -> &str {
    if s.len() > 5 { s } else { t }
}

This is because of how the automatic lifetime annotation works. When a function accepts multiple references, they're each given their own lifetime. We know that the returned reference must be one of the references we received as an input argument, but we don't know which one. What goes in place of the ~'???~ below?

// this code sample does *not* compile
fn f<'a, 'b>(s: &'a str, t: &'b str) -> &'??? str {
    if s.len() > 5 { s } else { t }
}

Imagine that we want to use the returned value outside of this function. What lifetime would we assign to it? The only thing we can guarantee is that the reference we return is valid for at least as long as the shortest-lived reference we pass into the function. That tells the compiler that these two references are definitely valid for the shorter lifetime. We cannot give any guarantees outside of that.

The way we achieve this, is by giving both input parameters the same lifetime annotation. It's how we tell the compiler that 'as long as both of these input parameters are valid, so is the returned value'.

fn f<'a>(s: &'a str, t: &'a str) -> &'a str {
    if s.len() > 5 { s } else { t }
}

If you're returning a reference from a function that takes multiple input lifetime parameters, but you know exactly which one it is you're returning, you can annotate that specific lifetime. That way, the relationship between the lifetimes doesn't matter anymore.

fn f<'a, 'b>(s: &'a str, _t: &'b str) -> &'a str {
    s
}

Structs with references

References in structs can be a real hassle. You're often better off avoiding them and using owned values instead. That way, you don't need to worry about references being invalidated and lifetimes not lasting long enough. In my experience, it's usually also what you want.

However, there are certain cases where structs with references are exactly what you want. In particular: if you want to create a 'view' into something else. Using structs with references is a great way of organizing some data into a package that's easier to handle, without moving or copying data. This means that the original data source can still be referenced elsewhere and that we save on the extra work it would be to clone the data.

Here's an example. Imagine that we want to find the first and the last sentence of a paragraph and keep them in a struct S. Because we don't want to copy the data, we need to use references and give them lifetime annotations.

struct S<'a> {
    first: &'a str,
    last: &'a str,
}

We could use a function like this to populate the struct. For simplicity's sake, we'll assume that a full stop is the only sentence-ending punctuation mark in use. If the paragraph is empty, we'll return None, and if there is only a single sentence, we'll use that as both the first and the last sentence:

fn try_create(paragraph: &str) -> Option<S> {
    let mut sentences = paragraph.split('.').filter(|s| !s.is_empty());
    match (sentences.next(), sentences.next_back()) {
        (Some(first), Some(last)) => Some(S { first, last }),
        (Some(first), None) => Some(S { first, last: first }),
        _ => None,
    }
}

Notice how we don't need to annotate lifetimes in the function signature because the compiler can figure it out for us. In a case like this, there is really only one choice: the lifetime of the input string. Pretty neat, huh?