Michael Chermside wrote:
> Jim Jewett writes:
>> This change [in docs] looks wrong:
>>
>> PyDoc_STRVAR(rpartition__doc__,
>> -"S.rpartition(sep) -> (head, sep, tail)\n\
>> +"S.rpartition(sep) -> (tail, sep, head)\n\
>
> Raymond Hettinger replies:
>> It is correct. There may be some confusion in terminology. Head
>> and tail do not mean left-side or right-side. Instead, they refer to
>> the "small part chopped-off" and "the rest that is still choppable".
>> Think of head and tail in the sense of car and cdr.
>
>
> It is incorrect. The purpose of documentation is to explain
> things to users, and documentation which fails to achieve this
> is not "correct". The level of confusion generated by using "head"
> to refer to the last part of the string and "tail" to refer to
> the beginning, is quite significant.
>
> How about something like this:
>
> S.partition(sep) -> (head, sep, tail)
> S.rpartition(sep) -> (tail, sep, rest)
This isn't immediately clear to me what I will get.
s.partition(sep) -> (left, sep, right)
s.rpartition(sep) -> (left, sep, right)
Would be clearer, along with an explanation of what left, and right are.
I hope this discussion is only about the words used and the
documentation and not about the actual order of what is received. I
would expect both the following should be true, and it is the current
behavior.
''.join(s.partition(sep)) -> s
''.join(s.rpartition(sep)) -> s
> Perhaps someone else can find something clearer than my suggestion,
> but in my own head, the terms "head" and "tail" are tighly bound
> with the idea of beginning and end (respectively) rather than with
> the idea of "small part chopped off" and "big part that is still
> choppable".
Maybe this?
partition(...)
S.partition(sep) -> (left, sep, right)
Partition a string at the first occurrence of sep from the
left into a tuple of left, sep, and right parts.
Returns (S, '', '') if sep is not found in S.
rpartition(...)
S.rpartition(sep) -> (left, sep, right)
Partition a string at the first occurrence of sep from the right
into a tuple of left, sep, and right parts.
Returns ('', '', S) if sep is not found in S.
I feel the terms head and tail, rest etc... should be used in examples
where their meaning will be clear by the context they are used in. But
not in the definition where their meanings are not obvious.
Cheers,
Ron
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
