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

[John Rose]

On Apr 21, 2013, at 3:49 AM, Stephen Colebourne <scolebourne at joda.org> wrote:

> IntStream range(int startInclusive, int endExclusive) {...}

+1

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.

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.)

— John