add second "capture" lifetime to SubCaptures and SubCapturesNamed

[defuz]

I think this code should work:

#[test]
fn test_iter_lifetimes() {
    fn get_first_subcapture<'t>(regex: &Regex, text: &'t str) -> Option<&'t str> {
        let captures = regex.captures(text).unwrap();
        captures.iter().next().unwrap()
    }

    let regex = Regex::new("(a+)(b+)").unwrap();
    let subcapture = get_first_subcapture(&regex, "aabbab");

    assert_eq!(subcapture, Some("aabb"));
}

But today it does not compile:

src/re.rs:956:9: 956:17 error: `captures` does not live long enough
src/re.rs:956         captures.iter().next().unwrap()
                      ^~~~~~~~
src/re.rs:954:82: 957:6 note: reference must be valid for the lifetime 't as defined on the block at 954:81...
src/re.rs:954     fn get_first_subcapture<'t>(regex: &Regex, text: &'t str) -> Option<&'t str> {
src/re.rs:955         let captures = regex.captures(text).unwrap();
src/re.rs:956         captures.iter().next().unwrap()
src/re.rs:957     }
src/re.rs:955:54: 957:6 note: ...but borrowed value is only valid for the block suffix following statement 0 at 955:53
src/re.rs:955         let captures = regex.captures(text).unwrap();
src/re.rs:956         captures.iter().next().unwrap()
src/re.rs:957     }

The problem is that subcaptures can not outlive Captures struct, which is wrong. To fix this, we need to add new lifetime:

pub fn iter<'c>(&'c self) -> SubCaptures<'c, 't>

And:

pub struct SubCaptures<'c, 't: 'c> {
    idx: usize,
    caps: &'c Captures<'t>,
}

There is a similar problem with iter_named and SubCapturesNamed. Possibly related to #158

[BurntSushi]

Man, what a bonehead move on my part. The current definition is trivially wrong:

pub struct SubCaptures<'t> {
    idx: usize,
    caps: &'t Captures<'t>,
}

How presumptuous of me to assume that the search text might not live as long as the capture value! In this case, I believe 't is inferred to be the shorter of the two lifetimes, which certainly can't be reconciled with the lifetime in your function declaration.

Nice find!

[BurntSushi]

This should also be bundled up into 1.0, since it will also be a breaking change. (But thankfully shouldn't actually result in a huge amount of breakage, since I doubt folks are actually uttering the SubCaptures type.)

[defuz]

About iter_pos and SubCapturesPos. I think it should be changed to this:

pub fn iter_pos<'c>(&'c self) -> SubCapturesPos<'c> { ... }

/// `'c` is the lifetime of `Captures` struct.
pub struct SubCapturesPos<'с> {
    idx: usize,
    locs: &'с [Option<usize>], // from Captures::locs
}

Also, I think we can correct documentation before 1.0: 't is not the lifetime of the matched text for SubCaptures, SubCapturesNamed and SubCapturesPos. It is lifetime of Captures borrow.

[BurntSushi]

Also, I think we can correct documentation before 1.0:

That'd be fine.

[BurntSushi]

Note that this is fixed in the bytes::Regex API.