In trying to work out what's different between the start, stop and step
of slice.indices() and the start, stop and step of sequence slicing[1] I
found that some of the list slicing documentation[2] is vague. I'd like
to submit a documentation fix, but I want to make sure I have it right.
Here's what points (3) and (5) of the Sequence Types documentation say
now:
"""
(3) If i or j is negative, the index is relative to the end of the
string: len(s) + i or len(s) + j is substituted. But note that -0 is
still 0.
...
(5) The slice of s from i to j with step k is defined as the sequence of
items with index x = i + n*k such that $0 \leq n < \frac{j-i}{k}$. In
other words, the indices are i, i+k, i+2*k, i+3*k and so on, stopping
when j is reached (but never including j). If i or j is greater than
len(s), use len(s). If i or j are omitted then they become ``end''
values (which end depends on the sign of k). Note, k cannot be zero.
"""
I'd like to replace that second-to-last sentence in point (5) with the
vague ``end'' description with something more explicit. I'd like it to
read something like:
"""
If k is positive and i or j is omitted, they will be replaced with 0 and
len(s) respectively. If k is negative and i or j is omitted, they will
be replaced with -1 and -len(s)-1 respectively. Note that these
replacements happen before the rule from point (3) is applied.
"""
I'd also like to put an example with point (5) to show this behavior in
action. Something like:
"""
So for example::
>>> seq = 'abcde'
>>> len(seq)
5
>>> 'edc' == seq[:1:-1] == seq[-1:1:-1]
True
>>> 'ca' == seq[2::-2] == seq[2:-5-1:-2]
True
Note however that manually applying the rule from point (3) (adding
len(s) to any i or j that is negative) works for i, but does not work
for j::
>>> seq[5-1:1:-1]
'edc'
>>> seq[2:-1:-2]
''
This is because Python sees the -1 in the j position and applies the
rule from point (3) again.
"""
If a few people could check over my logic here and make sure I'm not
completely misguided, I'll post a documentation fix.
Thanks,
STeVe
[1] http://mail.python.org/pipermail/python-list/2005-August/293963.html
[2] http://docs.python.org/lib/typesseq.html
--
http://mail.python.org/mailman/listinfo/python-list
