From 2cede399ec01cba5f6998401c24cd6c0c9042cac Mon Sep 17 00:00:00 2001 From: "Andrew M. Kuchling" Date: Sun, 20 Apr 2008 16:54:02 +0000 Subject: [PATCH] Move description of math module changes; various edits to description of cmath changes --- Doc/whatsnew/2.6.rst | 110 ++++++++++++++++++++++++------------------- 1 file changed, 62 insertions(+), 48 deletions(-) diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index 144d058cfda..c4d040e3761 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -1292,11 +1292,42 @@ Here are all of the changes that Python 2.6 makes to the core Python language. :func:`isnan`, return true if their floating-point argument is infinite or Not A Number. (:issue:`1640`) - The ``math.copysign(x, y)`` function - copies the sign bit of an IEEE 754 number, returning the absolute - value of *x* combined with the sign bit of *y*. For example, - ``math.copysign(1, -0.0)`` returns -1.0. (Contributed by Christian - Heimes.) +* The :mod:`math` module has seven new functions, and the existing + functions have been improved to give more consistent behaviour + across platforms, especially with respect to handling of + floating-point exceptions and IEEE 754 special values. + The new functions are: + + * :func:`isinf` and :func:`isnan` determine whether a given float is + a (positive or negative) infinity or a NaN (Not a Number), + respectively. + + * ``copysign(x, y)`` copies the sign bit of an IEEE 754 number, + returning the absolute value of *x* combined with the sign bit of + *y*. For example, ``math.copysign(1, -0.0)`` returns -1.0. + (Contributed by Christian Heimes.) + + * The inverse hyperbolic functions :func:`acosh`, :func:`asinh` and + :func:`atanh`. + + * The function :func:`log1p`, returning the natural logarithm of + *1+x* (base *e*). + + There's also a new :func:`trunc` function as a result of the + backport of `PEP 3141's type hierarchy for numbers <#pep-3141>`__. + + The existing math functions have been modified to follow the + recommendations of the C99 standard with respect to special values + whenever possible. For example, ``sqrt(-1.)`` should now give a + :exc:`ValueError` across (nearly) all platforms, while + ``sqrt(float('NaN'))`` should return a NaN on all IEEE 754 + platforms. Where Annex 'F' of the C99 standard recommends signaling + 'divide-by-zero' or 'invalid', Python will raise :exc:`ValueError`. + Where Annex 'F' of the C99 standard recommends signaling 'overflow', + Python will raise :exc:`OverflowError`. (See :issue:`711019`, + :issue:`1640`.) + + (Contributed by Christian Heimes and Mark Dickinson.) * Changes to the :class:`Exception` interface as dictated by :pep:`352` continue to be made. For 2.6, @@ -1415,33 +1446,40 @@ complete list of changes, or look through the CVS logs for all the details. available, instead of restricting itself to protocol 1. (Contributed by W. Barnes; :issue:`1551443`.) -* The :mod:`cmath` module has gained five new functions: :func:`polar` - converts a complex number to polar form, returning the modulus and - argument of that complex number. :func:`rect` does the opposite, - turning a (modulus, argument) pair back into the corresponding - complex number. :func:`phase` returns the phase or argument of a - complex number. :func:`isnan` returns True if either the real or - imaginary part of its argument is a NaN. :func:`isinf` returns True - if either the real or imaginary part of its argument is infinite. +* The :mod:`cmath` module underwent an extensive set of revisions, + thanks to Mark Dickinson and Christian Heimes, that added some new + features and greatly improved the accuracy of the computations. - The :mod:`cmath` module is no longer numerically unsound. (See - :issue:`1381`): for all functions, the real and imaginary parts of - the results are accurate to within a few ulps, whenever possible. + Five new functions were added: - The branch cuts for :func:`asinh`, :func:`atanh`: and :func:`atan` - have been corrected. + * :func:`polar` converts a complex number to polar form, returning + the modulus and argument of that complex number. - The tests for the :mod:`cmath` module have been greatly expanded. A - set of nearly 2000 new testcases provides tests for the algebraic - functions. + * :func:`rect` does the opposite, turning a (modulus, argument) pair + back into the corresponding complex number. + + * :func:`phase` returns the phase or argument of a complex number. + + * :func:`isnan` returns True if either + the real or imaginary part of its argument is a NaN. + + * :func:`isinf` returns True if either the real or imaginary part of + its argument is infinite. + + The revisions also improved the numerical soundness of the + :mod:`cmath` module. For all functions, the real and imaginary + parts of the results are accurate to within a few units of least + precision (ulps) whenever possible. See :issue:`1381` for the + details. The branch cuts for :func:`asinh`, :func:`atanh`: and + :func:`atan` have also been corrected. + + The tests for the module have been greatly expanded; nearly 2000 new + test cases exercise the algebraic functions. On IEEE 754 platforms, the :mod:`cmath` module now handles IEEE 754 special values and floating-point exceptions in a manner consistent with Annex 'G' of the C99 standard. - (Updates to :mod:`cmath` contributed by Mark Dickinson and Christian - Heimes.) - * A new data type in the :mod:`collections` module: :class:`namedtuple(typename, fieldnames)` is a factory function that creates subclasses of the standard tuple whose fields are accessible by name as well as index. For example:: @@ -1678,30 +1716,6 @@ complete list of changes, or look through the CVS logs for all the details. :func:`macostools.touched` function to be removed because it depended on the :mod:`macfs` module. (:issue:`1490190`) -* The :mod:`math` module has seven new functions, and the existing - functions have been improved to give more consistent behaviour - across platforms, especially with respect to handling of - floating-point exceptions and IEEE 754 special values. - - The new functions are: :func:`isinf` and :func:`isnan`, which - determine whether a given float is a (positive or negative) infinity - or a NaN (Not a Number), respectively; :func:`copysign`; the inverse - hyperbolic functions :func:`acosh`, :func:`asinh` and :func:`atanh`; - and the function :func:`log1p`. (There's also a new function - :func:`trunc` as a result of the backport of PEP 3141; see above.) - - The existing math functions have been modified to follow the - recommendations of the C99 standard with respect to special values - whenever possible. For example, sqrt(-1.) should now give a - ValueError across (nearly) all platforms, while sqrt(float('NaN')) - should return a NaN on all IEEE 754 platforms. Where Annex 'F' of - the C99 standard recommends signaling 'divide-by-zero' or 'invalid', - Python will raise ValueError. Where Annex 'F' of the C99 standard - recommends signaling 'overflow', Python will raise OverflowError. - (See :issue:`711019`, :issue:`1640`.) - - (Contributed by Christian Heimes and Mark Dickinson.) - * :class:`mmap` objects now have a :meth:`rfind` method that finds a substring, beginning at the end of the string and searching backwards. The :meth:`find` method