Merged revisions 65258,65292,65299,65308-65309,65315,65326 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r65258 | mark.dickinson | 2008-07-27 08:15:29 +0100 (Sun, 27 Jul 2008) | 4 lines

  Remove math.sum tests related to overflow, special values, and behaviour
  near the extremes of the floating-point range.  (The behaviour of math.sum
  should be regarded as undefined in these cases.)
........
  r65292 | mark.dickinson | 2008-07-29 19:45:38 +0100 (Tue, 29 Jul 2008) | 4 lines

  More modifications to tests for math.sum:  replace the Python
  version of msum by a version using a different algorithm, and
  use the new float.fromhex method to specify test results exactly.
........
  r65299 | mark.dickinson | 2008-07-30 13:01:41 +0100 (Wed, 30 Jul 2008) | 5 lines

  Fix special-value handling for math.sum.
  Also minor cleanups to the code: fix tabbing, remove
  trailing whitespace, and reformat to fit into 80
  columns.
........
  r65308 | mark.dickinson | 2008-07-30 17:20:10 +0100 (Wed, 30 Jul 2008) | 2 lines

  Rename math.sum to math.fsum
........
  r65309 | mark.dickinson | 2008-07-30 17:25:16 +0100 (Wed, 30 Jul 2008) | 3 lines

  Replace math.sum with math.fsum in a couple of comments
  that were missed by r65308
........
  r65315 | mark.dickinson | 2008-07-30 21:23:15 +0100 (Wed, 30 Jul 2008) | 2 lines

  Add note about problems with math.fsum on x86 hardware.
........
  r65326 | mark.dickinson | 2008-07-31 15:48:32 +0100 (Thu, 31 Jul 2008) | 2 lines

  Rename testSum to testFsum and move it to proper place in test_math.py
........

2 files changed, 37 insertions, 7 deletions

diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index c8090b5..df4ec1b 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -76,6 +76,42 @@ Number-theoretic and representation functions:
    apart" the internal representation of a float in a portable way.
 
 
+.. function:: fsum(iterable)
+
+   Return an accurate floating point sum of values in the iterable.  Avoids
+   loss of precision by tracking multiple intermediate partial sums.  The
+   algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
+   typical case where the rounding mode is half-even.
+
+   .. note::
+
+      On platforms where arithmetic results are not correctly rounded,
+      :func:`fsum` may occasionally produce incorrect results; these
+      results should be no less accurate than those from the builtin
+      :func:`sum` function, but nevertheless may have arbitrarily
+      large relative error.
+
+      In particular, this affects some older Intel hardware (for
+      example Pentium and earlier x86 processors) that makes use of
+      'extended precision' floating-point registers with 64 bits of
+      precision instead of the 53 bits of precision provided by a C
+      double.  Arithmetic operations using these registers may be
+      doubly rounded (rounded first to 64 bits, and then rerounded to
+      53 bits), leading to incorrectly rounded results.  To test
+      whether your machine is one of those affected, try the following
+      at a Python prompt::
+
+         >>> 1e16 + 2.9999
+         10000000000000002.0
+
+      Machines subject to the double-rounding problem described above
+      are likely to print ``10000000000000004.0`` instead of
+      ``10000000000000002.0``.
+
+
+   .. versionadded:: 2.6
+
+
 .. function:: isinf(x)
 
    Checks if the float *x* is positive or negative infinite.
@@ -100,12 +136,6 @@ Number-theoretic and representation functions:
    Return the fractional and integer parts of *x*.  Both results carry the sign of
    *x*, and both are floats.
 
-.. function:: sum(iterable)
-
-   Return an accurate floating point sum of values in the iterable.  Avoids
-   loss of precision by tracking multiple intermediate partial sums.  The
-   algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
-   typical case where the rounding mode is half-even.
 
 .. function:: trunc(x)
 
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index a8d89cb..9959ecd 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -1537,7 +1537,7 @@ Here are all of the changes that Python 2.6 makes to the core Python language.
   * :func:`~math.factorial` computes the factorial of a number.
     (Contributed by Raymond Hettinger; :issue:`2138`.)
 
-  * :func:`~math.sum` adds up the stream of numbers from an iterable,
+  * :func:`~math.fsum` adds up the stream of numbers from an iterable,
     and is careful to avoid loss of precision by calculating partial sums.
     (Contributed by Jean Brouwers, Raymond Hettinger, and Mark Dickinson;
     :issue:`2819`.)