Document what happens if `std::iter::Take`'s `n` is greater than the amount of elements

[KizzyCode]

The documentation of std::iter::Take gives no information about what happens if the underlying iterator yields less elements than Take should take.
Does it return less than n elements, does it panic, ...

Maybe we should change

An iterator that only iterates over the first n iterations of iter.

to something like

An iterator that only iterates over the first n iterations of iter. If iter yields less elements than n, only the amount of elements produced by iter will be returned.

However english is not my mother tongue and I'm pretty sure there is a much better formulation than this (even to my ears this sounds clumsy)^^

[czipperz]

Well I believe it is correct right now. It just returns the result of self.iter.next(). It doesn't really care what it returns. Some iterators restart iteration after one None, for example Fuse

for example Fuse

unless I'm missing something, that Fuse example is flawed ie. panics when overflow. (in playground, switch from Debug to Release for a possible fix)

[Mark-Simulacrum]

There's not really a notion I think of the amount of elements an iterator returns -- i.e., take will limit the amount of times Some could be returned but other than that it'll simply call next on the underlying iterator. We could perhaps provide an example that None is still returned, e.g., something like the following, but I'm not sure it's super helpful since None is the only thing that could really be returned.

let v = vec![1, 2];
let mut iter = v.into_iter().take(5);
assert_eq!(iter.next(), Some(1));
assert_eq!(iter.next(), Some(2));
assert_eq!(iter.next(), None);
...

[KizzyCode]

Well, my problem (as a foreign speaker) is that the function is not called take_up_to, but take, which (at least to me) implies some sort of "guarantee" that it would take exactly n elements.

While within the iterator-logic the behavior is completely logical, for me in the first minutes it was not.

[czipperz]

Yep. I agree it is kinda weird

[poliorcetics]

@KizzyCode I made a PR for that, is the added explanation clear from you point of view ?

[poliorcetics]

The PR fixing this has been merged, this could be closed.