explain why the side effects of `peek` matter

[tshepang]

Why does one have to be aware of the side effects? See #33016 for the change.

[GuillaumeGomez]

It is said:

Note that the underlying iterator is still advanced when peek is
called for the first time: In order to retrieve the next element,
next is called on the underlying iterator, hence any side effects of
the next method will occur.

Doesn't that sound explicit enough?

[tshepang]

Why do the side effects matter to the user of the API? What is it that they must watch out for that could affect them negatively?

[TyOverby]

@tshepang If your iterator does things that have side-effects when next is called, then peek can trigger those side-effects. Similarly, after a peek, calling next won't trigger side-effects because the next value has already been cached.

This isn't an issue for most iterators, but if you are using iterators as an abstraction over a state machine, then the behavior could be confusing.

[tshepang]

So this is about custom iterators, not iterators in the stdlib?

[TyOverby]

I don't think that there are any really weird iterators in the stdlib, but you can make them using the stdlib very easily.

let new_iter = my_vector.iter().map(|a| { println!("hi"); a });

Now you have an iterator with a side-effect that will behave weirdly when peeked at.

[tshepang]

Oh, so side effect means doing stuff other than fetch the next value, that being writing to stdout in your example?

[arielb1]

That's what "side effect" means in this context - the effects of calling a function other than its value being returned.

[abonander]

Unexpected side-effects in the stdlib might include blocking and early consumption of values from channel and I/O iterators.

[steveklabnik]

It sounds like there might be confusion about the term "side effect" here, which I don't think is fixable in our docs. But maybe being more explicit could help.

@tshepang how are you feeling about this issue? Do you have any suggestions as to how this could be improved, now that you see what's going on?

[tshepang]

We can add a bit to the text, e.g.:

Note that the underlying iterator is still advanced when peek is
called for the first time: In order to retrieve the next element,
next is called on the underlying iterator, hence any side effects (i.e.
anything other than just fetching the next value) of
the next method will occur.

If that's not satisfactory, I would not mind if this issue was closed.

[steveklabnik]

Sounds good to me!