Issue 821701: reduce docs neglect a very important piece of information. (original) (raw)

I was writing a platform-independent hash function for pathnames, and the documentation was useless for determining in which order the arguments to the reducing function are given. In the one example given, the arguments are of the same type, and the reducing function uses a commutative operator, so it doesn't matter. In my case, however, I was doing this:

reduce(lambda h, s: h ^ hash(s), s.split(os.path.sep), 0) -740391245

where the arguments aren't the same type, so order does matter. I actually tried this first (since it's the order of arguments of foldl in Haskell/SML):

reduce(lambda s, h: h ^ hash(s), s.split(os.path.sep), 0) Traceback (most recent call last): File "", line 1, in ? File "", line 1, in TypeError: unsupported operand type(s) for ^: 'str' and 'int'

Especially considering that the order of arguments here is counter to the traditional order of arguments for such functions in functional languages, I think there should be a note in the documentation about the order of arguments.

Logged In: YES user_id=593130

A draft of clarification text:

The rule is that the first (left) arg is the current cumulation and the second (right) is the update value from the sequence. The initial cumulation is either the optional initializer or the first item of the sequence, at least one of which most exist to avoid a TypeError.

I inferred the left/right arg rule from ''' reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calculates ((((1+2) +3)+4)+5). ''' but an explicit statement would be helpful.

Logged In: YES user_id=593130

Revised clarification text to possibly add after current first sentence.

The first (left) argument is the accumulator; the second (right) is the update value from the sequence. The accumulator starts as the initializer, if given, or as seq[0].
An empty sequence with no initializer is a TypeError.

Follow this with the example. I think the current wordier sentence about initialization could be deleted (or greatly reduced if above does not encompass all of current content).