[ python-Bugs-1265100 ] sequence slicing documentation incomplete

[SourceForge.net]

Bugs item #1265100, was opened at 2005-08-20 15:30
Message generated for change (Tracker Item Submitted) made by Item Submitter
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1265100&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Steven Bethard (bediviere)
Assigned to: Nobody/Anonymous (nobody)
Summary: sequence slicing documentation incomplete

Initial Comment:
Here's what points (3) and (5) of the Sequence Types[1]
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), which uses the vague word "end'' in its
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.
"""

One of the motivations for this patch is to be able to
explain the difference in behavior between sequence
slicing and slice.indices(), e.g.

    >>> seq[::-2]
    'eca'
    >>> slice(None, None, -2).indices(5)
    (4, -1, -2)
    >>> seq[4:-1:-2]
    ''

Right now, I think the documentation is too vague to be
able to make it clear why slices behave differently. 
If this patch is accepted, I'll work on a patch for
slice objects that explains the differences.

[1] http://docs.python.org/lib/typesseq.html 

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

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