`size_hint`, correctness, reproducibility and documentation

[scottmcm]

@dhardy

Is it allowable to incorrectly return None when randomly choosing an element from an iterator whose length is less than the claimed lower bound?

Yes. Garbage in, garbage out: of someone gives you an iterator that doesn't implement Iterator correctly, you're also allowed to not behave correctly. The only thing you're not allowed to do is be memory-unsafe.

Some examples:

• if the size_hint says there will be N elements, you can OOM for the N even if it was actually empty

• if it claims to be ExactSizeIterator, you can loop to the len calling .next().unwrap(), which might panic or skip some (but you cannot call .next().unwrap_or_else(unreachable_unchecked))