Elision rule 3 and the &self trap

Rule 3 of lifetime elision is the friendliest of the three: if a method takes &self or &mut self, every elided output lifetime silently becomes the receiver’s.

It is also the only elision rule that can quietly give you the wrong answer.

Two methods that look identical

pub struct Owner { text: String }

impl Owner {
    pub fn text(&self) -> &str { &self.text }
}

pub struct Viewer<'a> { rest: &'a str }

impl<'a> Viewer<'a> {
    pub fn peek(&self) -> Option<&str> { self.rest.split_whitespace().next() }
}

Both compile. Both are one line. Rule 3 filled in both return lifetimes from &self. One of them is right and one of them is a bug, and no test you can write will tell you which.

The diagnostic question

Does this returned reference point into self, or through self into something self merely borrows?

In Owner::text, the String is a field the struct owns. The returned &str points into memory that dies exactly when the Owner dies. Tying the result to &self‘s lifetime is not a compromise — it is the literal truth. Rule 3 is correct here, and naming a lifetime yourself would be noise.

In Viewer::peek, rest is a &'a str — a reference the viewer is holding, not data it owns. The bytes belong to whatever created the viewer, and they will still be there long after the viewer is gone. Rule 3’s answer — “the result lives as long as the borrow of self“ — is sound but under-promising. It throws away the fact that made the type worth writing.

Always look at the call site

This is the part that makes the bug invisible in unit tests, so it is worth demonstrating rather than asserting. The failure never appears in the method. It appears the first time something tries to drop the receiver:

fn main() {
    let s = String::from("a b");
    let first;
    {
        let v = Viewer { rest: &s };
        first = v.peek();
    }                                  // `v` dropped here
    println!("{first:?}");
    // error[E0597]: `v` does not live long enough
}

Read that error carefully. The data — s — is alive and well; it outlives the whole block. The thing that “does not live long enough” is the viewer, which has nothing to do with the bytes being printed. That is the smell of an under-promising rule-3 signature: the compiler complains about the wrong object.

The fix is to name the struct’s lifetime:

impl<'a> Viewer<'a> {
    pub fn peek(&self) -> Option<&'a str> { self.rest.split_whitespace().next() }
}

Now &self‘s borrow ends when the call returns, and the result carries 'a — the lifetime of the text, which outlives everything. The block above compiles.

const _: () = {
    fn _pin<'a>(v: &Viewer<'a>) -> Option<&'a str> { v.peek() }
};

“If it compiles, my annotations are correct”

This deserves to be stated as the misconception it is:

The compiler verifies soundness. It never verifies intent.

A signature that compiles has passed exactly one check — that no reference can outlive its referent. It has not been checked for being the signature you meant, the signature your callers need, or the signature that makes your type useful. Elision rule 3 will happily hand you a sound, useless one.

This generalises well past lifetimes, and it is the reason API review is a thing in Rust codebases. “It compiles” is the floor, not the ceiling.

Do not overcorrect

Having been burned once, the temptation is to name lifetimes everywhere. Don’t — that is its own smell, and it is a graded one:

impl Owner {
    pub fn text<'a>(&'a self) -> &'a str { &self.text }
}

error: the following explicit lifetimes could be elided: 'a
  = note: `-D clippy::needless-lifetimes` implied by `-D warnings`

Since the returned reference genuinely points into self, elision produces exactly this signature, so writing it out adds nothing but noise. clippy::needless_lifetimes fails your submission for it — and it is careful enough to stay silent on Viewer::peek‘s Option<&'a str>, because there elision would produce something different.

Most methods genuinely should use rule 3. Getters on owning structs, accessors, iterators over owned collections — all correct as elided. The trap is specific: it fires when your struct is a view rather than a container.

struct Buffer { data: Vec<u8> }
impl Buffer {
    fn head(&self) -> &[u8];              // A
}

struct Cursor<'a> { data: &'a [u8], pos: usize }
impl<'a> Cursor<'a> {
    fn remaining(&self) -> &[u8];         // B
    fn position(&self) -> usize;          // C
    fn take(&mut self, n: usize) -> &[u8]; // D
}

The rule of thumb

When you write a method on a struct that holds references, stop at the return type and ask the diagnostic question. If the answer is “through self“, name the struct’s lifetime. If it is “into self“, let elision do it and move on.

And write the const _: pin. It is three lines, it costs nothing, and it is the only test that can tell you which one you built.