document and justify temporary lifetime rules in the documentation

[nikomatsakis]

The new syntax-based rules for temporary lifetimes that landed with #3511 have not yet been thoroughly documented outside the source. This should be fixed!

[pnkfelix]

1.0 blocker, P-low.

[brson]

Nominating for removal from milestone. We'll live if this isn't documented.

[pnkfelix]

Removing from 1.0 milestone.

[steveklabnik]

Traige: I'm not sure what these are exactly, maybe we can have a chat about them, @nikomatsakis ?

[pnkfelix]

@steveklabnik I would say

• niko's blog posts are a great start for understanding the background here:
  • http://smallcultfollowing.com/babysteps/blog/2012/09/15/rvalue-lifetimes/
  • http://smallcultfollowing.com/babysteps/blog/2014/01/09/rvalue-lifetimes-in-rust/
• Many of the rules are illustrated via example in run-pass/cleanup-value-scopes.rs, as noted in RFC: Rvalue lifetimes #3511

---

My go-to example of a gotcha here: Consider the following hypothetical desugaring of for-loop into more primitive constructs:

macro_rules! for_bad {
    (($pat:pat) in $head:expr { $($body:stmt)* }) => { {
        let mut iter = IntoIterator::into_iter($head);
        loop {
            match Iterator::next(&mut iter) {
                Some($pat) => { $($body)* }
                None => break,
            }
        }
    } }
}

The above is remarkably easy to read, at least for someone versed in macro_rules!: evaluate the input $head expression, convert it to an iterator, bind that result to iter, and then loop over the method calls to next.

Unfortunately, it does not work, and (according to my understanding), it is due to the R-value lifetime rules for temporaries.

In particular, consider: for_bad!( (k) in &[7,8,9] { println!("{}", k) } );; here, the temporaries created during the evaluation of:

        let mut iter = IntoIterator::into_iter($head);

only live to the end of that statement, not beyond. Thus the [7,8,9] in the head expression &[7,8,9] does not survive long enough for us to iterate over it!

So, what's the go-to fix for this? Its this: Bind via match instead of let, because match keeps its input alive for the entirety of the evaluation of the matched arm. (The main surprise to me here is that we need to use match to bind a non enum value.)

Here's that desugaring:

macro_rules! for_gud {
    (($pat:pat) in $head:expr { $($body:stmt)* }) => { {
        match IntoIterator::into_iter($head) {
            mut iter => loop {
                match Iterator::next(&mut iter) {
                    Some($pat) => { $($body)* }
                    None => break,
                }
            }
        }
    } }
}

And here's a playpen link to save you the trouble of transcribing the above into code if you want to play with it: http://is.gd/NmptIx

[sanxiyn]

Any update? I wrote down some rules here: https://internals.rust-lang.org/t/borrow-scopes/1732