[Python-checkins] python/nondist/peps pep-0303.txt,NONE,1.1

2002年12月31日 07:57:20 -0800

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1:/tmp/cvs-serv27416/python/nondist/peps
Added Files:
	pep-0303.txt 
Log Message:
Extend divmod() for Multiple Divisors, by Thomas Bellman
--- NEW FILE: pep-0303.txt ---
PEP: 303
Title: Extend divmod() for Multiple Divisors
Version: $Revision: 1.1 $
Last-Modified: $Date: 2002年12月31日 15:57:18 $
Author: Thomas Bellman <bellman+pep-divmod@lysator.liu.se>
Status: Draft
Type: Standards Track
Content-Type: text/plain
Created: 31-Dec-2002
Python-Version: 2.3
Post-History:
Abstract
 This PEP describes an extension to the builtin divmod() function,
 allowing it to take multiple divisors, chaining several calls to
 divmod() into one.
Specification
 The builtin 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() builtin 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
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: