215 lines
7.3 KiB
ReStructuredText
215 lines
7.3 KiB
ReStructuredText
PEP: 303
|
|
Title: Extend divmod() for Multiple Divisors
|
|
Version: $Revision$
|
|
Last-Modified: $Date$
|
|
Author: Thomas Bellman <bellman+pep-divmod@lysator.liu.se>
|
|
Status: Rejected
|
|
Type: Standards Track
|
|
Content-Type: text/x-rst
|
|
Created: 31-Dec-2002
|
|
Python-Version: 2.3
|
|
Post-History:
|
|
|
|
|
|
Abstract
|
|
========
|
|
|
|
This PEP describes an extension to the built-in ``divmod()`` function,
|
|
allowing it to take multiple divisors, chaining several calls to
|
|
``divmod()`` into one.
|
|
|
|
|
|
Pronouncement
|
|
=============
|
|
|
|
This PEP is rejected. Most uses for chained ``divmod()`` involve a
|
|
constant modulus (in radix conversions for example) and are more
|
|
properly coded as a loop. The example of splitting seconds
|
|
into days/hours/minutes/seconds does not generalize to months
|
|
and years; rather, the whole use case is handled more flexibly and
|
|
robustly by date and time modules. The other use cases mentioned
|
|
in the PEP are somewhat rare in real code. The proposal is also
|
|
problematic in terms of clarity and obviousness. In the examples,
|
|
it is not immediately clear that the argument order is correct or
|
|
that the target tuple is of the right length. Users from other
|
|
languages are more likely to understand the standard two argument
|
|
form without having to re-read the documentation. See python-dev
|
|
discussion on 17 June 2005 [1]_.
|
|
|
|
|
|
Specification
|
|
=============
|
|
|
|
The built-in ``divmod()`` function would be changed to accept multiple
|
|
divisors, changing its signature from ``divmod(dividend, divisor)`` to
|
|
``divmod(dividend, *divisors)``. The dividend is divided by the last
|
|
divisor, giving a quotient and a remainder. The quotient is then
|
|
divided by the second to last divisor, giving a new quotient and
|
|
remainder. This is repeated until all divisors have been used,
|
|
and ``divmod()`` then returns a tuple consisting of the quotient from
|
|
the last step, and the remainders from all the steps.
|
|
|
|
A Python implementation of the new ``divmod()`` behaviour could look
|
|
like::
|
|
|
|
def divmod(dividend, *divisors):
|
|
modulos = ()
|
|
q = dividend
|
|
while divisors:
|
|
q, r = q.__divmod__(divisors[-1])
|
|
modulos = (r,) + modulos
|
|
divisors = divisors[:-1]
|
|
return (q,) + modulos
|
|
|
|
|
|
Motivation
|
|
==========
|
|
|
|
Occasionally one wants to perform a chain of ``divmod()`` operations,
|
|
calling ``divmod()`` on the quotient from the previous step, with
|
|
varying divisors. The most common case is probably converting a
|
|
number of seconds into weeks, days, hours, minutes and seconds.
|
|
This would today be written as::
|
|
|
|
def secs_to_wdhms(seconds):
|
|
m, s = divmod(seconds, 60)
|
|
h, m = divmod(m, 60)
|
|
d, h = divmod(h, 24)
|
|
w, d = divmod(d, 7)
|
|
return (w, d, h, m, s)
|
|
|
|
This is tedious and easy to get wrong each time you need it.
|
|
|
|
If instead the ``divmod()`` built-in is changed according the proposal,
|
|
the code for converting seconds to weeks, days, hours, minutes and
|
|
seconds then become ::
|
|
|
|
def secs_to_wdhms(seconds):
|
|
w, d, h, m, s = divmod(seconds, 7, 24, 60, 60)
|
|
return (w, d, h, m, s)
|
|
|
|
which is easier to type, easier to type correctly, and easier to
|
|
read.
|
|
|
|
Other applications are:
|
|
|
|
- Astronomical angles (declination is measured in degrees, minutes
|
|
and seconds, right ascension is measured in hours, minutes and
|
|
seconds).
|
|
- Old British currency (1 pound = 20 shilling, 1 shilling = 12 pence).
|
|
- Anglo-Saxon length units: 1 mile = 1760 yards, 1 yard = 3 feet,
|
|
1 foot = 12 inches.
|
|
- Anglo-Saxon weight units: 1 long ton = 160 stone, 1 stone = 14
|
|
pounds, 1 pound = 16 ounce, 1 ounce = 16 dram.
|
|
- British volumes: 1 gallon = 4 quart, 1 quart = 2 pint, 1 pint
|
|
= 20 fluid ounces.
|
|
|
|
|
|
Rationale
|
|
=========
|
|
|
|
The idea comes from APL, which has an operator that does this. (I
|
|
don't remember what the operator looks like, and it would probably
|
|
be impossible to render in ASCII anyway.)
|
|
|
|
The APL operator takes a list as its second operand, while this
|
|
PEP proposes that each divisor should be a separate argument to
|
|
the ``divmod()`` function. This is mainly because it is expected that
|
|
the most common uses will have the divisors as constants right in
|
|
the call (as the 7, 24, 60, 60 above), and adding a set of
|
|
parentheses or brackets would just clutter the call.
|
|
|
|
Requiring an explicit sequence as the second argument to ``divmod()``
|
|
would seriously break backwards compatibility. Making ``divmod()``
|
|
check its second argument for being a sequence is deemed to be too
|
|
ugly to contemplate. And in the case where one *does* have a
|
|
sequence that is computed other-where, it is easy enough to write
|
|
``divmod(x, *divs)`` instead.
|
|
|
|
Requiring at least one divisor, i.e rejecting ``divmod(x)``, has been
|
|
considered, but no good reason to do so has come to mind, and is
|
|
thus allowed in the name of generality.
|
|
|
|
Calling ``divmod()`` with no divisors should still return a tuple (of
|
|
one element). Code that calls ``divmod()`` with a varying number of
|
|
divisors, and thus gets a return value with an "unknown" number of
|
|
elements, would otherwise have to special case that case. Code
|
|
that *knows* it is calling ``divmod()`` with no divisors is considered
|
|
to be too silly to warrant a special case.
|
|
|
|
Processing the divisors in the other direction, i.e dividing with
|
|
the first divisor first, instead of dividing with the last divisor
|
|
first, has been considered. However, the result comes with the
|
|
most significant part first and the least significant part last
|
|
(think of the chained divmod as a way of splitting a number into
|
|
"digits", with varying weights), and it is reasonable to specify
|
|
the divisors (weights) in the same order as the result.
|
|
|
|
The inverse operation::
|
|
|
|
def inverse_divmod(seq, *factors):
|
|
product = seq[0]
|
|
for x, y in zip(factors, seq[1:]):
|
|
product = product * x + y
|
|
return product
|
|
|
|
could also be useful. However, writing ::
|
|
|
|
seconds = (((((w * 7) + d) * 24 + h) * 60 + m) * 60 + s)
|
|
|
|
is less cumbersome both to write and to read than the chained
|
|
divmods. It is therefore deemed to be less important, and its
|
|
introduction can be deferred to its own PEP. Also, such a
|
|
function needs a good name, and the PEP author has not managed to
|
|
come up with one yet.
|
|
|
|
Calling ``divmod("spam")`` does not raise an error, despite strings
|
|
supporting neither division nor modulo. However, unless we know
|
|
the other object too, we can't determine whether ``divmod()`` would
|
|
work or not, and thus it seems silly to forbid it.
|
|
|
|
|
|
Backwards Compatibility
|
|
=======================
|
|
|
|
Any module that replaces the ``divmod()`` function in the ``__builtin__``
|
|
module, may cause other modules using the new syntax to break. It
|
|
is expected that this is very uncommon.
|
|
|
|
Code that expects a ``TypeError`` exception when calling ``divmod()`` with
|
|
anything but two arguments will break. This is also expected to
|
|
be very uncommon.
|
|
|
|
No other issues regarding backwards compatibility are known.
|
|
|
|
|
|
Reference Implementation
|
|
========================
|
|
|
|
Not finished yet, but it seems a rather straightforward
|
|
new implementation of the function ``builtin_divmod()`` in
|
|
``Python/bltinmodule.c``.
|
|
|
|
|
|
References
|
|
==========
|
|
|
|
.. [1] Raymond Hettinger, "Propose rejection of PEP 303 -- Extend divmod() for
|
|
Multiple Divisors" https://mail.python.org/pipermail/python-dev/2005-June/054283.html
|
|
|
|
|
|
Copyright
|
|
=========
|
|
|
|
This document has been placed in the public domain.
|
|
|
|
|
|
|
|
..
|
|
Local Variables:
|
|
mode: indented-text
|
|
indent-tabs-mode: nil
|
|
sentence-end-double-space: t
|
|
fill-column: 70
|
|
End:
|