Fix length of Iterators.Stateful with underlying mutable iterator

[jakobnissen]

Previously, Iterators.Stateful kept track of how many elements have been taken,
and reported its length as the length of the underlying iterator minus the
number of taken elements.
However, this assumes the underlying iterator is immutable. If it is mutable,
then the reported length is the same as the number of remaining elements,
meaning the wrapper Stateful should not subtract the number of taken elements.

After this PR, Stateful instead stores the length of the underlying iterator,
if that can be known, and subtracts one every time an element is taken. Hence,
the number of remaining elements is being kept track of directly.

Fixes #43245

[vtjnash]

Thanks! I think it might remain useful to keep the prior behavior also, by using the signbit instead of a Union. Commented my suggestions on how to do that.

[vtjnash]

Suggested change

	rem = s.remaining
	if rem !== nothing
	s.remaining = rem - 1
	end
	rem = s.remaining
	@assert !iszero(rem)
	s.remaining = rem - 1

[jakobnissen]

I can make these changes, no problem. But I don't quite understand:

• What is the advantage of having remaining be a type param instead of just an Int? Given that it will only be used to store an integer? Is it to prevent overflow for iterators who return their length as e.g. BigInt?
• What is the purpose of keeping the old behaviour? As far as I can tell, all it does it to defer the call to length when the wrapper iterator has no length from instatiation of Stateful until length(::Stateful) is called. It will error either way.
  Edit: Ah, I guess it's to not require that the underlying iterator actually implements length, like the CharStr in the tests I had to modify to make it work. For backwards compatibility?

[vtjnash]

• What is the advantage of having remaining be a type param instead of just an Int? Given that it will only be used to store an integer? Is it to prevent overflow for iterators who return their length as e.g. BigInt?

Mostly just to avoid any possible regression here. Though length is typically expected to be an Int, it isn't strictly required. Someone might theoretically pair it with a truncating iterator (such as via zip), making the length the shorter of this and the other.

• What is the purpose of keeping the old behaviour? As far as I can tell, all it does it to defer the call to length when the wrapper iterator has no length from instatiation of Stateful until length(::Stateful) is called. It will error either way.
  Edit: Ah, I guess it's to not require that the underlying iterator actually implements length, like the CharStr in the tests I had to modify to make it work. For backwards compatibility?

Yeah, that was my hope

[jakobnissen]

@vtjnash I think this should be good to go, and would be nice to get in v1.9 :)

[vtjnash]

Thanks for the bump

[aviatesk]

Bisected that this introduced a regression reported at #46719.