[Pythoncheckins] r79859  in python/branches/release26maint: Doc/library/math.rst
mark.dickinson
pythoncheckins at python.org
Tue Apr 6 21:52:05 CEST 2010
Author: mark.dickinson
Date: Tue Apr 6 21:52:05 2010
New Revision: 79859
Log:
Merged revisions 79858 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r79858  mark.dickinson  20100406 20:50:03 +0100 (Tue, 06 Apr 2010)  3 lines
Issue #7947: Clarify math module behaviour for IEEE 754 special cases, along
with a number of additional minor edits and typo corrections.
........
Modified:
python/branches/release26maint/ (props changed)
python/branches/release26maint/Doc/library/math.rst
Modified: python/branches/release26maint/Doc/library/math.rst
==============================================================================
 python/branches/release26maint/Doc/library/math.rst (original)
+++ python/branches/release26maint/Doc/library/math.rst Tue Apr 6 21:52:05 2010
@@ 33,8 +33,8 @@
.. function:: copysign(x, y)
 Return *x* with the sign of *y*. ``copysign`` copies the sign bit of an IEEE
 754 float, ``copysign(1, 0.0)`` returns *1.0*.
+ Return *x* with the sign of *y*. On a platform that supports
+ signed zeros, ``copysign(1.0, 0.0)`` returns *1.0*.
.. versionadded:: 2.6
@@ 109,17 +109,15 @@
.. function:: isinf(x)
 Checks if the float *x* is positive or negative infinite.
+ Check if the float *x* is positive or negative infinity.
.. versionadded:: 2.6
.. function:: isnan(x)
 Checks if the float *x* is a NaN (not a number). NaNs are part of the
 IEEE 754 standards. Operation like but not limited to ``inf * 0``,
 ``inf / inf`` or any operation involving a NaN, e.g. ``nan * 1``, return
 a NaN.
+ Check if the float *x* is a NaN (not a number). For more information
+ on NaNs, see the IEEE 754 standards.
.. versionadded:: 2.6
@@ 231,7 +229,7 @@
The vector in the plane from the origin to point ``(x, y)`` makes this angle
with the positive X axis. The point of :func:`atan2` is that the signs of both
inputs are known to it, so it can compute the correct quadrant for the angle.
 For example, ``atan(1``) and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(1,
+ For example, ``atan(1)`` and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(1,
1)`` is ``3*pi/4``.
@@ 313,35 +311,35 @@
.. data:: pi
 The mathematical constant *pi*.
+ The mathematical constant π = 3.141592..., to available precision.
.. data:: e
 The mathematical constant *e*.
+ The mathematical constant e = 2.718281..., to available precision.
.. impldetail::
The :mod:`math` module consists mostly of thin wrappers around the platform C
 math library functions. Behavior in exceptional cases is loosely specified
 by the C standards, and Python inherits much of its mathfunction
 errorreporting behavior from the platform C implementation. As a result,
 the specific exceptions raised in error cases (and even whether some
 arguments are considered to be exceptional at all) are not defined in any
 useful crossplatform or crossrelease way. For example, whether
 ``math.log(0)`` returns ``Inf`` or raises :exc:`ValueError` or
 :exc:`OverflowError` isn't defined, and in cases where ``math.log(0)`` raises
 :exc:`OverflowError`, ``math.log(0L)`` may raise :exc:`ValueError` instead.

 All functions return a quiet *NaN* if at least one of the args is *NaN*.
 Signaling *NaN*\s raise an exception. The exception type still depends on the
 platform and libm implementation. It's usually :exc:`ValueError` for *EDOM*
 and :exc:`OverflowError` for errno *ERANGE*.
+ math library functions. Behavior in exceptional cases follows Annex F of
+ the C99 standard where appropriate. The current implementation will raise
+ :exc:`ValueError` for invalid operations like ``sqrt(1.0)`` or ``log(0.0)``
+ (where C99 Annex F recommends signaling invalid operation or dividebyzero),
+ and :exc:`OverflowError` for results that overflow (for example,
+ ``exp(1000.0)``). A *NaN* will not be returned from any of the functions
+ above unless one or more of the input arguments was a *NaN*; in that case,
+ most functions will return a *NaN*, but (again following C99 Annex F) there
+ are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or
+ ``hypot(float('nan'), float('inf'))``.
+
+ Note that Python makes no effort to distinguish signaling nans from
+ quiet nans, and behavior for signaling nans remains unspecified.
+ Typical behavior is to treat all nans as though they were quiet.
.. versionchanged:: 2.6
 In earlier versions of Python the outcome of an operation with NaN as
 input depended on platform and libm implementation.
+ Behavior in special cases now aims to follow C99 Annex F. In earlier
+ versions of Python the behavior in special cases was loosely specified.
.. seealso::
More information about the Pythoncheckins
mailing list