Document additional use case for Iterator::inspect

[nickbabcock]

If you'd like to fix this bug, here's how.

---

Currently iterator::inspect contains the following documentation:

It's much more common for inspect() to be used as a debugging tool than to exist in your final code, but never say never.

Though I like the never say never wording, I think it might be helpful to document a use case where it's not used for debugging. I use inspect in daemon applications for that slurp in stdin lines and discard and log the lines that can't be parsed. Like so:

lines
.iter()
.map(|line| parse_line(line))
.inspect(|line| {
    // If we can't parse a line, yeah that sucks but it's bound to happen so discard
    // the line after it's logged for the attentive sysadmin
    if let Err(ref e) = *line {
        error!("Parsing error: {}", e);
    }
})
.flat_map(|x| x)
// etc

Maybe the documentation of inspect can be updated to something like:

It's more common for inspect() to be used as a debugging tool than to exist in your final code, but applications may find it useful in certain situations as well. Say an application is reading stdin lines, it may be it helpful to log lines with errors before discarding them.

What do you think? Suggestions certainly wanted 😄

[scottmcm]

Well, another possibility (YMMV) would be to combine the inspect+flat_map into a filter_map:

lines
.iter()
.map(|line| parse_line(line))
.filter_map(|line| match line {
    Ok(x) => Some(x),
    Err(e) => { error!("Parsing error: {}", e); None },
})
// etc

FWIW it took me a second to remember that flat_map over a result does what it does, so I think I prefer the explicitness of the filter_map overall.

[nickbabcock]

Yeah, you can use filter_map(Result::ok) as well

lines
.iter()
.map(|line| parse_line(line))
.inspect(|line| {
    if let Err(ref e) = *line {
        error!("Parsing error: {}", e);
    }
})
.filter_map(Result::ok)

Sorry, I wasn't trying to draw attention to flat_map 😅

[steveklabnik]

I'm happy to mentor anyone who'd like to fix this bug! Here's how:

The documentation for this method lives here:

rust/src/libcore/iter/iterator.rs

Lines 1174 to 1211 in 5092c6b

	/// # Examples
	///
	/// Basic usage:
	///
	/// ```
	/// let a = [1, 4, 2, 3];
	///
	/// // this iterator sequence is complex.
	/// let sum = a.iter()
	/// .cloned()
	/// .filter(|x| x % 2 == 0)
	/// .fold(0, |sum, i| sum + i);
	///
	/// println!("{}", sum);
	///
	/// // let's add some inspect() calls to investigate what's happening
	/// let sum = a.iter()
	/// .cloned()
	/// .inspect(|x| println!("about to filter: {}", x))
	/// .filter(|x| x % 2 == 0)
	/// .inspect(|x| println!("made it through filter: {}", x))
	/// .fold(0, |sum, i| sum + i);
	///
	/// println!("{}", sum);
	/// ```
	///
	/// This will print:
	///
	/// ```text
	/// 6
	/// about to filter: 1
	/// about to filter: 4
	/// made it through filter: 4
	/// about to filter: 2
	/// made it through filter: 2
	/// about to filter: 3
	/// 6
	/// ```

Add the final example by @nickbabcock above below all of the other ones.

I'm happy to answer any more questions!

[nickbabcock]

I'll take it. I didn't know if there needed to be more discussion about the proposed use case.

If I don't figure things out, I'll come back here with question 😉