[issue21510] fma documentation should provide better example.

[Raymond Hettinger]

Raymond Hettinger <raymond.hettinger at gmail.com> added the comment:

I suggest using the text and example from the spec:
http://speleotrove.com/decimal/daops.html#reffma

=====================================================

fused-multiply-add takes three operands; the first two are multiplied together, using multiply, with sufficient precision and exponent range that the result is exact and unrounded.[4]  No flags are set by the multiplication unless one of the first two operands is a signaling NaN or one is a zero and the other is an infinity.
Unless the multiplication failed, the third operand is then added to the result of that multiplication, using add, under the current context.

In other words, fused-multiply-add(x, y, z) delivers a result which is (x × y) + z with only the one, final, rounding.

Examples:

  fused-multiply-add(’3’, ’5’, ’7’)               ==>  ’22’
  fused-multiply-add(’3’, ’-5’, ’7’)              ==>  ’-8’
  fused-multiply-add(’888565290’, ’1557.96930’,
                                  ’-86087.7578’)  ==>  ’1.38435736E+12’
Note that the last example would have given the result ’1.38435735E+12’ if the operation had been carried out as a separate multiply followed by an add.

----------
nosy: +rhettinger

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue21510>
_______________________________________