[Python-checkins] r79860 - in python/branches/py3k: Doc/library/math.rst
python-checkins at python.org
Tue Apr 6 21:55:03 CEST 2010
Date: Tue Apr 6 21:55:03 2010
New Revision: 79860
Merged revisions 79858 via svnmerge from
r79858 | mark.dickinson | 2010-04-06 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.
python/branches/py3k/ (props changed)
--- python/branches/py3k/Doc/library/math.rst (original)
+++ python/branches/py3k/Doc/library/math.rst Tue Apr 6 21:55:03 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*.
.. function:: fabs(x)
@@ -99,15 +99,13 @@
.. function:: isinf(x)
- Checks if the float *x* is positive or negative infinite.
+ Check if the float *x* is positive or negative infinity.
.. 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.
.. function:: ldexp(x, i)
@@ -223,7 +221,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``.
@@ -331,28 +329,31 @@
.. 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.
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.
- 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 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'))``.
+ 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.
More information about the Python-checkins