Lifetimes
A lifetime means "how long the variable lives". You only need to think about lifetimes with references. This is because references can't live longer than the object they come from. For example, this function does not work:
fn returns_reference() -> &str { let my_string = String::from("I am a string"); &my_string // ⚠️ } fn main() {}
The problem is that my_string only lives inside returns_reference. We try to return &my_string, but &my_string can't exist without my_string. So the compiler says no.
This code also doesn't work:
fn returns_str() -> &str { let my_string = String::from("I am a string"); "I am a str" // ⚠️ } fn main() { let my_str = returns_str(); println!("{}", my_str); }
But it almost works. The compiler says:
error[E0106]: missing lifetime specifier
--> src\main.rs:6:21
|
6 | fn returns_str() -> &str {
| ^ expected named lifetime parameter
|
= help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from
help: consider using the `'static` lifetime
|
6 | fn returns_str() -> &'static str {
| ^^^^^^^^
missing lifetime specifier means that we need to add a ' with the lifetime. Then it says that it contains a borrowed value, but there is no value for it to be borrowed from. That means that I am a str isn't borrowed from anything. It says consider using the 'static lifetime by writing &'static str. So it thinks we should try saying that this is a string literal.
Now it works:
fn returns_str() -> &'static str { let my_string = String::from("I am a string"); "I am a str" } fn main() { let my_str = returns_str(); println!("{}", my_str); }
That's because we returned a &str with a lifetime of static. Meanwhile, my_string can only be returned as a String: we can't return a reference to it because it is going to die in the next line.
So now fn returns_str() -> &'static str tells Rust: "don't worry, we will only return a string literal". String literals live for the whole program, so Rust is happy. You'll notice that this is similar to generics. When we tell the compiler something like <T: Display>, we promise that we will only use inputs with Display. Lifetimes are similar: we are not changing any variable lifetimes. We are just telling the compiler what the lifetimes of the inputs will be.
But 'static is not the only lifetime. Actually, every variable has a lifetime, but usually we don't have to write it. The compiler is pretty smart and can usually figure out for itself. We only have to write the lifetime when the compiler doesn't know.
Here is an example of another lifetime. Imagine we want to create a City struct and give it a &str for the name. We might want to do that because it gives faster performance than with String. So we write it like this, but it won't work yet:
#[derive(Debug)] struct City { name: &str, // ⚠️ date_founded: u32, } fn main() { let my_city = City { name: "Ichinomiya", date_founded: 1921, }; }
The compiler says:
error[E0106]: missing lifetime specifier
--> src\main.rs:3:11
|
3 | name: &str,
| ^ expected named lifetime parameter
|
help: consider introducing a named lifetime parameter
|
2 | struct City<'a> {
3 | name: &'a str,
|
Rust needs a lifetime for &str because &str is a reference. What happens when the value that name points to is dropped? That would be unsafe.
What about 'static, will that work? We used it before. Let's try:
#[derive(Debug)] struct City { name: &'static str, // change &str to &'static str date_founded: u32, } fn main() { let my_city = City { name: "Ichinomiya", date_founded: 1921, }; println!("{} was founded in {}", my_city.name, my_city.date_founded); }
Okay, that works. And maybe this is what you wanted for the struct. However, note that we can only take "string literals", so not references to something else. So this will not work:
#[derive(Debug)] struct City { name: &'static str, // must live for the whole program date_founded: u32, } fn main() { let city_names = vec!["Ichinomiya".to_string(), "Kurume".to_string()]; // city_names does not live for the whole program let my_city = City { name: &city_names[0], // ⚠️ This is a &str, but not a &'static str. It is a reference to a value inside city_names date_founded: 1921, }; println!("{} was founded in {}", my_city.name, my_city.date_founded); }
The compiler says:
error[E0597]: `city_names` does not live long enough
--> src\main.rs:12:16
|
12 | name: &city_names[0],
| ^^^^^^^^^^
| |
| borrowed value does not live long enough
| requires that `city_names` is borrowed for `'static`
...
18 | }
| - `city_names` dropped here while still borrowed
This is important to understand, because the reference we gave it actually lives long enough. But we promised that we would only give it a &'static str, and that is the problem.
So now we will try what the compiler suggested before. It said to try writing struct City<'a> and name: &'a str. This means that it will only take a reference for name if it lives as long as City.
#[derive(Debug)] struct City<'a> { // City has lifetime 'a name: &'a str, // and name also has lifetime 'a. date_founded: u32, } fn main() { let city_names = vec!["Ichinomiya".to_string(), "Kurume".to_string()]; let my_city = City { name: &city_names[0], date_founded: 1921, }; println!("{} was founded in {}", my_city.name, my_city.date_founded); }
Also remember that you can write anything instead of 'a if you want. This is also similar to generics where we write T and U but can actually write anything.
#[derive(Debug)] struct City<'city> { // The lifetime is now called 'city name: &'city str, // and name has the 'city lifetime date_founded: u32, } fn main() {}
So usually you will write 'a, 'b, 'c etc. because it is quick and the usual way to write. But you can always change it if you want. One good tip is that changing the lifetime to a "human-readable" name can help you read code if it is very complicated.
Let's look at the comparison to traits for generics again. For example:
use std::fmt::Display; fn prints<T: Display>(input: T) { println!("T is {}", input); } fn main() {}
When you write T: Display, it means "please only take T if it has Display".
It does not mean: "I am giving Display to T".
The same is true for lifetimes. When you write 'a here:
#[derive(Debug)] struct City<'a> { name: &'a str, date_founded: u32, } fn main() {}
It means "please only take an input for name if it lives at least as long as City".
It does not mean: "I will make the input for name live as long as City".
Now we can learn about <'_> that we saw before. This is called the "anonymous lifetime" and is an indicator that references are being used. Rust will suggest it to you when you are implementing structs, for example. Here is one struct that almost works, but not yet:
// ⚠️ struct Adventurer<'a> { name: &'a str, hit_points: u32, } impl Adventurer { fn take_damage(&mut self) { self.hit_points -= 20; println!("{} has {} hit points left!", self.name, self.hit_points); } } fn main() {}
So we did what we needed to do for the struct: first we said that name comes from a &str. That means we need a lifetime, so we gave it <'a>. Then we had to do the same for the struct to show that they are at least as long as this lifetime. But then Rust tells us to do this:
error[E0726]: implicit elided lifetime not allowed here
--> src\main.rs:6:6
|
6 | impl Adventurer {
| ^^^^^^^^^^- help: indicate the anonymous lifetime: `<'_>`
It wants us to add that anonymous lifetime to show that there is a reference being used. So if we write that, it will be happy:
struct Adventurer<'a> { name: &'a str, hit_points: u32, } impl Adventurer<'_> { fn take_damage(&mut self) { self.hit_points -= 20; println!("{} has {} hit points left!", self.name, self.hit_points); } } fn main() {}
This lifetime was made so that you don't always have to write things like impl<'a> Adventurer<'a>, because the struct already shows the lifetime.
Lifetimes can be difficult in Rust, but here are some tips to avoid getting too stressed about them:
- You can stay with owned types, use clones etc. if you want to avoid them for the time being.
- Much of the time, when the compiler wants a lifetime you will just end up writing <'a> here and there and then it will work. It's just a way of saying "don't worry, I won't give you anything that doesn't live long enough".
- You can explore lifetimes just a bit at a time. Write some code with owned values, then make one a reference. The compiler will start to complain, but also give some suggestions. And if it gets too complicated, you can undo it and try again next time.
Let's do this with our code and see what the compiler says. First we'll go back and take the lifetimes out, and also implement Display. Display will just print the Adventurer's name.
// ⚠️ struct Adventurer { name: &str, hit_points: u32, } impl Adventurer { fn take_damage(&mut self) { self.hit_points -= 20; println!("{} has {} hit points left!", self.name, self.hit_points); } } impl std::fmt::Display for Adventurer { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "{} has {} hit points.", self.name, self.hit_points) } } fn main() {}
First complaint is this:
error[E0106]: missing lifetime specifier
--> src\main.rs:2:11
|
2 | name: &str,
| ^ expected named lifetime parameter
|
help: consider introducing a named lifetime parameter
|
1 | struct Adventurer<'a> {
2 | name: &'a str,
|
It suggests what to do: <'a> after Adventurer, and &'a str. So we do that:
// ⚠️ struct Adventurer<'a> { name: &'a str, hit_points: u32, } impl Adventurer { fn take_damage(&mut self) { self.hit_points -= 20; println!("{} has {} hit points left!", self.name, self.hit_points); } } impl std::fmt::Display for Adventurer { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "{} has {} hit points.", self.name, self.hit_points) } } fn main() {}
Now it's happy with those parts, but is wondering about the impl blocks. It wants us to mention that it's using references:
error[E0726]: implicit elided lifetime not allowed here
--> src\main.rs:6:6
|
6 | impl Adventurer {
| ^^^^^^^^^^- help: indicate the anonymous lifetime: `<'_>`
error[E0726]: implicit elided lifetime not allowed here
--> src\main.rs:12:28
|
12 | impl std::fmt::Display for Adventurer {
| ^^^^^^^^^^- help: indicate the anonymous lifetime: `<'_>`
Okay, so we will write those in...and now it works! Now we can make an Adventurer and do some things with it.
struct Adventurer<'a> { name: &'a str, hit_points: u32, } impl Adventurer<'_> { fn take_damage(&mut self) { self.hit_points -= 20; println!("{} has {} hit points left!", self.name, self.hit_points); } } impl std::fmt::Display for Adventurer<'_> { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(f, "{} has {} hit points.", self.name, self.hit_points) } } fn main() { let mut billy = Adventurer { name: "Billy", hit_points: 100_000, }; println!("{}", billy); billy.take_damage(); }
This prints:
Billy has 100000 hit points.
Billy has 99980 hit points left!
So you can see that lifetimes are often just the compiler wanting to make sure. And it is usually smart enough to almost guess at what lifetimes you want, and just needs you to tell it so it can be certain.