Rust lifetimes and relationships.

Rust borrowing and references showed that a function with two reference inputs needs a lifetime annotation to return a reference, as in fn longer<'a>(a: &'a str, b: &'a str) -> &'a str. This lesson looks at what that annotation says, and what it does not say.

A function cannot lend out a value it made itself, because that value is dropped when the function returns. So a reference that a function returns must point into one of its inputs. The annotation says which one. In bird below, <'a> after the name declares a lifetime name. Writing 'a on entry and on the result says: the result points into entry. place has no 'a, so the result does not point into place.

&entry[6..] is a string slice: a &str that points into entry’s text, from byte 6 to the end. &entry[..5] is the first five bytes. Nothing is copied.

The compiler uses the signature in two places. In the body, it checks that the result really points into entry; returning place would be rejected. At each call, it checks that the result is used only while entry’s owner is alive. It does not compare the result with place, so the caller may drop place first.

'a is not a length of time, and it makes no value live longer or shorter. The stepper shows the same addresses and lengths with or without it.

A lifetime annotation says which input a returned reference points into; it changes no lifetime.

Most functions that return a reference need no annotation, because the compiler fills it in. This is called lifetime elision, and it follows rules you can apply yourself.

Each reference parameter gets its own lifetime. If there is exactly one reference input, the result gets that lifetime: fn year(date: &str) -> &str returns a reference into date. In a method, &self means the method borrows the value it is called on. If a method takes &self, the result gets the lifetime of self, even when there are other reference parameters.

Elision chooses a relationship from the signature alone; it does not look at the body. If a method returns a parameter instead of something inside self, the filled-in relationship is wrong. For example, fn bird_or(&self, fallback: &str) -> &str with the body fallback gives:

error: lifetime may not live long enough

with “associated function was supposed to return data with lifetime `'2` but it is returning data with lifetime `'1`”. An associated function is any function declared inside an impl block; a method is one that takes self. '1 and '2 are names the compiler makes up for the lifetimes it filled in: '2 is the lifetime of self, and '1 is the lifetime of fallback. So the message says: the signature promised a result from self, and the body returns fallback. Write the relationship out instead, as bird_or does below.

When no rule applies, for example with two reference inputs and no &self, the compiler reports E0106, as in Rust borrowing and references.

With one reference input, or &self, the compiler fills in the relationship; write it out when the result can point somewhere else.

A struct can hold a reference too. Its type then needs a lifetime parameter, because a value of the struct is only valid while the value its field points into is alive. Leaving it out, as in struct Sighting { bird: &str }, gives:

error[E0106]: missing lifetime specifier

with “expected named lifetime parameter” under &str, and help that adds <'a> to the struct and 'a to the field.

struct Sighting<'a> says that a Sighting points into whatever bird points into. The Sighting and the text it points into are two separate values, and the borrow links them. The Sighting may be dropped first. While the Sighting is still used, the text cannot be changed, moved, or dropped.

A reference to such a struct holds two borrows. In &'b Sighting<'a>, 'b is how long the borrow of the Sighting lasts, and 'a is how long the borrow of the text lasts. bird_of below names only 'a, so its result stays usable after the Sighting is dropped. With s: &'a Sighting<'a>, the two borrows get one name, and the result may be used only while the Sighting is alive too.

So a struct with a reference suits a short-lived view of data that something else owns, such as the parts of one line while you work with that line. A struct that must be kept, returned, or stored after its source changes should own its data: bird: String.

A struct that holds a reference is a borrow: its source must stay unchanged while the struct is used.

Some functions make new data: a label built from a name, or a name in lower case. A reference to that data could point only into a local of the function, which is dropped when the function returns. No annotation can describe that, because there is no input to name. The compiler reports error[E0515]: cannot return reference to local variable `text`, with “returns a reference to data owned by the current function”, as in Rust borrowing and references.

The compiler’s help can mislead here. For a function with no reference inputs, the help for E0106 suggests the 'static lifetime. 'static is the lifetime of values that last for the whole run of the program, such as a string literal written in the code. -> &'static str promises to return such a value. Writing it does not make text live longer; the same &text is rejected with E0515.

'static on a parameter does not help either. The function then accepts only references that last the whole run, so a call with &entry, where entry is a local String, gives error[E0597]: `entry` does not live long enough, with “argument requires that `entry` is borrowed for `'static`”.

The fix is to change the relationship, not the annotation. Return the String itself: ownership moves to the caller, and the text is not copied.

When the result is new data, return it owned; 'static never keeps a local alive.

Four mistakes with lifetimes are common in larger programs. If the compiler says E0502, E0515, or E0597, look here.

Adding 'static to silence an error. The help for E0106 suggests it, and the code compiles while every caller passes a string literal. The first caller with a String gets E0597. Return an owned value instead.

Keeping slices of a buffer you reuse. A loop reads each line into one String and pushes line.trim() into a Vec<&str>. The next line.clear() gives E0502, because the Vec still borrows line. Push line.trim().to_string(), as below.

Returning a struct that borrows a local. A function that reads text into a local String cannot return Sighting { bird: &text[6..], count: 1 }: that gives E0515. Give the struct owned fields, or let the caller own the text.

Keeping a position instead of a reference. An index into a Vec compiles, because the compiler cannot check a number. After insert, remove, or sort, the index names a different element, and nothing reports it. Keep an owned copy, or an id that never changes.

Never add 'static only to silence an error, own what must outlive its source, and do not trade a reference for a position the compiler cannot check.

Find what pick points into, then decide whether the program compiles and what it prints.