hg: Move static stream construction methods from Streams to Stream, {Int, Long, Double}Stream

[Brian Goetz]

> Also, I can't remember the last time I wrote a loop where it would
> have been correct to step backwards if and only if end < start. When
> I write a loop I expect it to run forward (usually) or backwards
> (sometimes) but never either-or. I think these are typical
> experiences for coding loops over integer ranges.
>
> So I think the implicit 'step' parameter should always be 1, not 1 or
> -1.  Allowing an automagic -1 will just hide bugs.

+1.

> In the same theme, I am uncomfortable with a data parameter
> determining the loop shape.  Having two potential loop shapes makes
> it twice as hard to reason statically about the code, which in turn
> impedes optimization and debugging.  Having two potential loop shapes
> also makes a mess of your javadoc:  Note that it is incorrect,
> because it only displays one of the two loop shapes.  (The 'i < end'
> is incorrect if you really want a downward loop, and the javadoc
> leaves it up to the user's imagination how to amend the loop.)
>
> So I suggest a separate 'rangeDown' method, which (alone) accepts a
> negative step value.
>
> (Additionally, consider having rangeDown take (int startExclusive,
> int endInclusive, int step), since Java like C usually works on
> left-closed, right-open iteration ranges.  Compare a[0 to length by
> 1] with a[length-1 to -1 by -1] vs. a[length to 0 by -1].  I know
> this is a fuzzy area of design endlessly discussed; the pure maths
> folks will want to reflect the range formally while the coders will
> recognize the tricky need to count down to zero inclusive.  Sorry to
> bring it up, but if you are going to have downward iteration it has
> to be deal with clearly.)

Or, just don't support negative increments for the first round.