[Python-bugs-list] [ python-Bugs-528748 ] range() description: rewording suggested

noreply@sourceforge.net noreply@sourceforge.net
Fri, 12 Apr 2002 13:52:04 -0700


Bugs item #528748, was opened at 2002-03-12 00:49
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=528748&group_id=5470

Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Colin J. Williams (cjwhrh)
Assigned to: Nobody/Anonymous (nobody)
Summary: range() description: rewording suggested

Initial Comment:
The help now has: 
     range([start,] stop[, step]) 
     This is a versatile function to create lists containing arithmetic
     progressions. It is most often used in for loops. The arguments
     must be plain integers. If the step argument is omitted, it
     defaults to 1. If the start argument is omitted, it defaults to
     0. The full form returns a list of plain integers [start, start +
     step, start + 2 * step, ...].  If step is positive, the last
     element is the largest start + i * step less than stop; if step is
     negative, the last element is the largest start + i * step greater
     than stop. step must not be zero (or else ValueError is raised). 

It might say:   

     range([start= 0,] stop[, step= 1]) 
     This function creates a list containing an arithmetic progression.
     The arguments must be integers.   If only one argument is passed it 
     is the 'stop' value, if two values are passed then the first is the
     'start' value and the second the 'stop' value.
     The function returns a list of integers [start, start + step, start
     + 2 * step, ...]. The 'step' must not be zero; if 'step' is positive, 
     the last element is the largest; if  'step' is negative, the last
     element is the smallest.
-----------------------------------------------------------
Using Python 2.2

The main intent is to clarify the usage of the optional arguments.


----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2002-04-12 20:52

Message:
Logged In: YES 
user_id=80475

IMO, the current version is clearer than the re-write.  
Also, the docs add further clarity by showing 7 examples.  
The proposed documentation style, range([start=0,] stop
[,step=1 ]) is inconsistent with the style used in the rest 
of the docs.

A side note, the docstring for range() is shorter and 
clearer than both of the above:

range(...)
    range([start,] stop[, step]) -> list of integers
    
    Return a list containing an arithmetic progression of 
integers.  range(i, j) returns [i, i+1, i+2, ..., j-1]; 
start (!) defaults to 0.  When step is given, it specifies 
the increment (or decrement).  For example, range(4) 
returns [0, 1, 2, 3].  The end point is omitted!  These are 
exactly the valid indices for a list of 4 elements.

----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=105470&aid=528748&group_id=5470