Issue #7947: Clarify math module behaviour for IEEE 754 special cases, along

with a number of additional minor edits and typo corrections.
This commit is contained in:
Mark Dickinson 2010-04-06 19:50:03 +00:00
parent ea7e5510aa
commit 99e73f9145
1 changed files with 23 additions and 25 deletions

View File

@ -33,8 +33,8 @@ Number-theoretic and representation functions
.. 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 @@ Number-theoretic and representation functions
.. 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
@ -247,7 +245,7 @@ Trigonometric functions
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``.
@ -361,35 +359,35 @@ Constants
.. 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.
.. impl-detail::
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 math-function
error-reporting 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 cross-platform or cross-release 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.
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 divide-by-zero),
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'))``.
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*.
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::