diff options
Diffstat (limited to 'Doc/library/math.rst')
| -rw-r--r-- | Doc/library/math.rst | 50 |
1 files changed, 24 insertions, 26 deletions
diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 0857b7a..13b85bf 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -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. - - 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. .. 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:: |