Clojure

range function has missing documentation

Details

  • Type: Enhancement Enhancement
  • Status: Open Open
  • Priority: Trivial Trivial
  • Resolution: Unresolved
  • Affects Version/s: Release 1.2
  • Fix Version/s: None
  • Component/s: None
  • Labels:
  • Environment:
    All
  • Approval:
    Triaged

Description

The range function's documentation does indicate the following usage:

(range 10 0 -1) -> (10, 9, 8, 7, 6, 5, 4, 3, 2, 1)

Current doc:

Returns a lazy seq of nums from start (inclusive) to end
(exclusive), by step, where start defaults to 0, step to 1, and end
to infinity.

Suggestion:

Returns a lazy seq of nums from start (inclusive) to end
(exclusive), by step, where start defaults to 0, step to 1, and end
to infinity.

Its also possible to step down rather than up, for example counting
backwards from 10 by -1: (range 10 0 -1).

Activity

Hide
Rasmus Svensson added a comment -

The current doc actually mentions the 'step' parameter briefly:

"[...] to end (exclusive), by step, where start [...]"

But as this might be easy to miss, an addition to the doc is still a good idea, I think.

My suggestion:

Returns a lazy seq of nums from start (inclusive) to end
(exclusive), by step, where start defaults to 0, step to 1, and end
to infinity. Step may be negative to count backwards.

Show
Rasmus Svensson added a comment - The current doc actually mentions the 'step' parameter briefly: "[...] to end (exclusive), by step, where start [...]" But as this might be easy to miss, an addition to the doc is still a good idea, I think. My suggestion: Returns a lazy seq of nums from start (inclusive) to end (exclusive), by step, where start defaults to 0, step to 1, and end to infinity. Step may be negative to count backwards.
Hide
Plínio Balduino added a comment - - edited

There was any news about it?

Could I assign it to me?

Show
Plínio Balduino added a comment - - edited There was any news about it? Could I assign it to me?
Hide
Andy Fingerhut added a comment -

No, no news about this one. It is in the 'open' state, meaning that there is currently no judgement as to whether Clojure screeners or Rich Hickey are interested in such a change. http://dev.clojure.org/display/community/JIRA+workflow

That said, it seems like it should not take a lot of time to create a patch. Detailed instructions are given here: http://dev.clojure.org/display/community/Developing+Patches

Show
Andy Fingerhut added a comment - No, no news about this one. It is in the 'open' state, meaning that there is currently no judgement as to whether Clojure screeners or Rich Hickey are interested in such a change. http://dev.clojure.org/display/community/JIRA+workflow That said, it seems like it should not take a lot of time to create a patch. Detailed instructions are given here: http://dev.clojure.org/display/community/Developing+Patches
Hide
Alex Miller added a comment -

Go for it!

Show
Alex Miller added a comment - Go for it!
Hide
Plínio Balduino added a comment -

I cannot reproduce this: "When step is equal to 0, returns an infinite sequence of start."

https://github.com/clojure/clojure/blob/master/src/clj/clojure/core.clj#L2726-L2729

Is this correct?

Show
Plínio Balduino added a comment - I cannot reproduce this: "When step is equal to 0, returns an infinite sequence of start." https://github.com/clojure/clojure/blob/master/src/clj/clojure/core.clj#L2726-L2729 Is this correct?
Hide
Andy Fingerhut added a comment -

The last time range was modified was due to ticket CLJ-1018. See the attached patch there, which I believe is the one that was applied after Clojure 1.5 but before Clojure 1.6.

Perhaps that change does not do what it claimed to do in the doc string. I haven't looked at it in detail yet.

Show
Andy Fingerhut added a comment - The last time range was modified was due to ticket CLJ-1018. See the attached patch there, which I believe is the one that was applied after Clojure 1.5 but before Clojure 1.6. Perhaps that change does not do what it claimed to do in the doc string. I haven't looked at it in detail yet.
Hide
Andy Fingerhut added a comment - - edited

In Clojure 1.6, it appears that it may be more accurate if the last two sentences in the doc string were modified. range's doc string is currently:

Returns a lazy seq of nums from start (inclusive) to end
(exclusive), by step, where start defaults to 0, step to 1, and end to
infinity. When step is equal to 0, returns an infinite sequence of
start. When start is equal to end, returns empty list.

It might be more accurate to say:

Returns a lazy seq of nums from start (inclusive) to end
(exclusive), by step, where start defaults to 0, step to 1, and end to
infinity. When start is equal to end, returns empty list. When step
is equal to 0 and start and end differ, returns an infinite sequence of
start.

Show
Andy Fingerhut added a comment - - edited In Clojure 1.6, it appears that it may be more accurate if the last two sentences in the doc string were modified. range's doc string is currently: Returns a lazy seq of nums from start (inclusive) to end (exclusive), by step, where start defaults to 0, step to 1, and end to infinity. When step is equal to 0, returns an infinite sequence of start. When start is equal to end, returns empty list. It might be more accurate to say: Returns a lazy seq of nums from start (inclusive) to end (exclusive), by step, where start defaults to 0, step to 1, and end to infinity. When start is equal to end, returns empty list. When step is equal to 0 and start and end differ, returns an infinite sequence of start.

People

Vote (0)
Watch (3)

Dates

  • Created:
    Updated: