Chapter 10.3. Third elision rule.

[smccrossin]

• I have checked the latest main branch to see if this has already been fixed
• I have searched existing issues and pull requests for duplicates

URL to the section(s) of the book with this problem:
https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html

Description of the problem:
This has to do with the example provided of the 3rd elision rule in action:

impl<'a> ImportantExcerpt<'a> {
    fn announce_and_return_part(&self, announcement: &str) -> &str {
        println!("Attention please: {}", announcement);
        self.part
    }
}

I'm new to Rust. My immediate thought in reading this example was "Oh no, what if the function returns 'announcement'? Assigning self's lifetime to the output reference seems very dangerous here. What if 'announcement' is returned instead?" I was so concerned, I tried it. And was very relieved that the compiler reported an error.

Suggested fix:
I would suggest stating that the 3rd elision is making the assumption that self (or some component thereof) will be returned. And although the compiler will in all cases apply the 3rd elision rule to a method signature like the above, the code will not compile if that assumption is violated. This is an important difference from the first two elision rules. I believe they can safely be applied without any particular assumptions about the body of the function. Otherwise put, I don't think either of them could cause code to fail to compile.

[GDYendell]

I agree with this. I also did some testing to check my understanding of what the book was saying. It seems to me that the statements

The third rule is that, if there are multiple input lifetime parameters, but one of them is &self or &mut self because this is a method, the lifetime of self is assigned to all output lifetime parameters.

and

There are two input lifetimes, so Rust applies the first lifetime elision rule and gives both &self and announcement their own lifetimes. Then, because one of the parameters is &self, the return type gets the lifetime of &self, and all lifetimes have been accounted for.

are wrong. The compiler only assigns the lifetime of self to an output parameter if it is a reference to self. As @smccrossin says, if the example is updated to return announcement, it fails to compile with error: lifetime may not live long enough.

I think what this section is trying to explain is the distinction between a function that takes two references and returns one of them and a method that takes one reference (or any number) and returns a reference to its own member. Only in the latter case does lifetime elision happen.

Expanding on the example in the book:

struct ImportantExcerpt<'a> {
    part: &'a str
}

impl<'a> ImportantExcerpt<'a> {
    fn m_announce_and_return_part(&self, announcement: &str) -> &str {
        println!("Attention please: {}", announcement);
        self.part
    }
}

// fn f_announce_and_return_part(part: &str, announcement: &str) -> &str {
//     println!("Attention please: {}", announcement);
//     part
// }

fn main() {}

m_announce_and_return_part compiles OK, but f_announce_and_return_part does not:

error[E0106]: missing lifetime specifier
  --> /tmp/Anpa02arYR/main.rs:19:66
   |
19 | fn f_announce_and_return_part(part: &str, announcement: &str) -> &str {
   |                                     ----                ----     ^ expected named lifetime parameter
   |
   = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `part` or `announcement`
help: consider introducing a named lifetime parameter
   |
19 | fn f_announce_and_return_part<'a>(part: &'a str, announcement: &'a str) -> &'a str {
   |                              ++++        ++                     ++          ++

It would make more sense to me if it was made clear that lifetime elision happens for a method specifically in the case that the output parameter is a reference to a member of self.

[yatian-liu]

Was just reading Chapter 10 and had the same thought with @smccrossin . I also tried to return announcement in fn announce_and_return_part(), and the compiler successfully detects the potential problem, but I would like to propose a different explanation of how the compiler handles the situation and detects the problem than what @GDYendell had proposed.

First, the example given by @GDYendell is not correct. It should be in the following form:

impl<'a> ImportantExcerpt<'a> {
    fn announce_and_return_part(&self, announcement: &str) -> &str {
        println!("Attention please: {}", announcement);
        announcement
    }
}

For the third elision rule to apply, one of the function's parameters must be &self, so the function signature fn f_announce_and_return_part(part: &str, announcement: &str) -> &str will not trigger the third elision rule.

Second, I would argue that the two statements referenced by @GDYendell , i.e.,

The third rule is that, if there are multiple input lifetime parameters, but one of them is &self or &mut self because this is a method, the lifetime of self is assigned to all output lifetime parameters.

and

There are two input lifetimes, so Rust applies the first lifetime elision rule and gives both &self and announcement their own lifetimes. Then, because one of the parameters is &self, the return type gets the lifetime of &self, and all lifetimes have been accounted for.

are actually not wrong. The third elision rule does apply, but then the borrow checker discovers that the method using &self does not return a reference that has the same lifetime as &self, and refuses to compile the code.

To see the full compilation error message after announce_and_return_part() is returning announcement instead of self.part:

error: lifetime may not live long enough
 --> src/main.rs:8:9
  |
6 |     fn announce_and_return_part(&self, announcement: &str) -> &str {
  |                                 -                    - let's call the lifetime of this reference `'1`
  |                                 |
  |                                 let's call the lifetime of this reference `'2`
7 |         println!("Attention please: {}", announcement);
8 |         announcement
  |         ^^^^^^^^^^^^ method was supposed to return data with lifetime `'2` but it is returning data with lifetime `'1`
  |
help: consider introducing a named lifetime parameter and update trait if needed
  |
6 |     fn announce_and_return_part<'b>(&self, announcement: &'b str) -> &'b str {
  |                                ++++                       ++          ++

The main clue to notice is the message "method was supposed to return data with lifetime '2 but it is returning data with lifetime '1". By saying that method was supposed to return data with lifetime '2, it means that the compiler has annotated the output value &str with lifetime '2, which is the lifetime of &self! This means that the compiler still use the third elision rule to implicitly assign the lifetime of &self to the output value.

However, from my understanding, which may need correction, the compiler would not blindly trust the lifetime annotation given by the third elision rule. It will still track the lifetime relationship of variables inside the function, compute the lifetime of the return value, and verify that the lifetime of the return value indeed match the lifetime annotation. If the return value's lifetime is different from the lifetime annotation, the compiler will still refuse to compile the code, which is where the error originated from.

To verify this new explanation of how the compiler detects the potential lifetime problem, we can manually add the implicit lifetime annotation given by the third elision rule to &str:

impl<'a> ImportantExcerpt<'a> {
    fn announce_and_return_part<'b>(&'a self, announcement: &'b str) -> &'a str {
        println!("Attention please: {}", announcement);
        announcement
    }
}

The compiler still refuses to compile this code, and the updated error message is:

error: lifetime may not live long enough
 --> src/main.rs:8:9
  |
5 | impl<'a> ImportantExcerpt<'a> {
  |      -- lifetime `'a` defined here
6 |     fn announce_and_return_part<'b>(&'a self, announcement: &'b str) -> &'a str {
  |                                 -- lifetime `'b` defined here
7 |         println!("Attention please: {}", announcement);
8 |         announcement
  |         ^^^^^^^^^^^^ method was supposed to return data with lifetime `'a` but it is returning data with lifetime `'b`
  |
  = help: consider adding the following bound: `'b: 'a`

This means that no matter the lifetime annotation of the output &str is given by the third elision rule or given explicitly, the compiler will compare the return value's computed lifetime with the annotated lifetime, and gives an error when the two does not match.

For updating the book, I agree with @smccrossin that it should be mentioned that the third elision rule is making the assumption that self (or some component thereof) will be returned, but the compiler will still verify the assumption. I also think it should be noted that the compiler verification of lifetime annotation applies regardless of the elision rules, as shown in the above example that explicit lifetime annotations that are problematic will also be detected.