Make Iterators.peel return nothing when itr empty

[cmcaine]

Fixes #39569.

Old behaviour: peel throws BoundsError when itr is empty.

try
    h, t = Iterators.peel(itr)
    # do something with h and t
catch e
    if e isa BoundsError
        # itr was probably empty
    else
        rethrow()
    end
end

New behaviour: peel returns nothing when itr is empty.

x = Iterators.peel(itr)
if isnothing(x)
    # itr was empty
end
h, t = x

Motivation: head, tail... = itr is a fundamental operation for lots of recursive code, and it would be nice if the lazy version of that (peel) were more ergonomic to use. This PR makes it about as easy to use as iterate.

Impact: this is a bit backwards incompatible, but I did a code search on GitHub, and none of the 140 matches for Iterators.peel would be broken by this change because they all try to iterate the object returned by peel immediately, so they will still get a BoundsError if itr is empty.

Argument against: if isempty(itr) works well then this pattern is fine and works right now:

if isempty(itr)
    # itr was empty
else
    h, t = Iterators.peel(itr)
end

The issue is that isempty is not safe for all stateful iterators (see discussion at #27412).

[cmcaine]

Grep didn't find any existing tests of Iterators.peel, so I added a few simple ones. I'm using the arrow syntax so the characters line up better, making it clearer when I'm calling with the same arguments.

[sostock]

You don’t need to use try block in the first version, you can simply check whether the iterator isempty before calling Iterators.peel. I don’t see an improvement in calling Iterators.peel and then isnothing (instead of isempty and then Iterators.peel).

[cmcaine]

That's a good point. My initial motivation for this PR was that isempty is unsafe for stateful iterators: the fallback implementation consumes a value from the iterator while testing if it is empty.

I have some other PRs that fix eachline and readeach, but there will be more around.

Anyway, I'd forgotten that those things were related by the time I wrote the commit message for this.

If we could fix the isempty fallback method in a backwards compatible way (we'd probably need to add a trait), then that would make this PR redundant, I think, but I'm not sure it can be fixed before V2.

[cmcaine]

Can triage give an opinion on this, please?

I've updated the first post to reflect all discussion on the original issue and this PR up to this point, so that's all that needs to be read.

[aviatesk]

This change could lead to type inference inaccuracy for certain iterators that inference can't understand its length, e.g. peel(::<:AbstractString), and could possibly cause some invalidation risks.
Some of them will be addressed by #41094.