[ python-Bugs-1265100 ] sequence slicing documentation incomplete

[SourceForge.net]

Bugs item #1265100, was opened at 2005-08-20 16:30
Message generated for change (Comment added) made by rhettinger
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: Documentation
Group: Python 2.4
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 

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

>Comment By: Raymond Hettinger (rhettinger)
Date: 2005-08-21 04:29

Message:
Logged In: YES 
user_id=80475

-0

The docs read better with "vague" words like "end".  Making
the description more mathematical may make it more precise
but will also make it harder to just read and understand. 
The wording suggested above is fathomable only after you
already understand how slicing works.  It is the "vague"
words that help achieve the understanding in the first place.

Also, I do not want to clutter this section with examples
intended to compare and contrast slices versus
slice.indices.  It would be okay to add a brief comparative
example to the docs for slice.indices().  Understanding the
latter is aided by a comparison.  In contrast, you can get
pretty good with slices and know nothing about
slice.indices() which is a somewhat challenging method.

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

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