Changeset 391 for python/trunk/Doc/library/math.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/math.rst (modified) (13 diffs)

python/trunk/Doc/library/math.rst

@@ -6 +6 @@
    :synopsis: Mathematical functions (sin() etc.).
 
+.. testsetup::
+
+   from math import fsum
 
 This module is always available.  It provides access to the mathematical
@@ -34 +37 @@
 .. 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
@@ -57 +60 @@
    Return the floor of *x* as a float, the largest integer value less than or equal
    to *x*.
-
-   .. versionchanged:: 2.6
-      Added :meth:`__floor__` delegation.
 
 
@@ -91 +91 @@
 
         >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
-        0.99999999999999989
+        0.9999999999999999
         >>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
         1.0
@@ -110 +110 @@
 .. 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
@@ -117 +117 @@
 .. 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
@@ -139 +137 @@
 .. function:: trunc(x)
 
-   Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
-   a long integer). Delegates to ``x.__trunc__()``.
+   Return the :class:`~numbers.Real` value *x* truncated to an
+   :class:`~numbers.Integral` (usually a long integer).  Uses the
+   ``__trunc__`` method.
 
    .. versionadded:: 2.6
@@ -163 +162 @@
 
    Return ``e**x``.
+
+
+.. function:: expm1(x)
+
+   Return ``e**x - 1``.  For small floats *x*, the subtraction in
+   ``exp(x) - 1`` can result in a significant loss of precision; the
+   :func:`expm1` function provides a way to compute this quantity to
+   full precision::
+
+      >>> from math import exp, expm1
+      >>> exp(1e-5) - 1  # gives result accurate to 11 places
+      1.0000050000069649e-05
+      >>> expm1(1e-5)    # result accurate to full precision
+      1.0000050000166668e-05
+
+   .. versionadded:: 2.7
 
 
@@ -199 +214 @@
    is undefined, and raises :exc:`ValueError`.
 
+   Unlike the built-in ``**`` operator, :func:`math.pow` converts both
+   its arguments to type :class:`float`.  Use ``**`` or the built-in
+   :func:`pow` function for computing exact integer powers.
+
    .. versionchanged:: 2.6
       The outcome of ``1**nan`` and ``nan**0`` was undefined.
@@ -232 +251 @@
    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``.
 
@@ -309 +328 @@
 
 
+Special functions
+-----------------
+
+.. function:: erf(x)
+
+   Return the error function at *x*.
+
+   .. versionadded:: 2.7
+
+
+.. function:: erfc(x)
+
+   Return the complementary error function at *x*.
+
+   .. versionadded:: 2.7
+
+
+.. function:: gamma(x)
+
+   Return the Gamma function at *x*.
+
+   .. versionadded:: 2.7
+
+
+.. function:: lgamma(x)
+
+   Return the natural logarithm of the absolute value of the Gamma
+   function at *x*.
+
+   .. versionadded:: 2.7
+
+
 Constants
 ---------
@@ -314 +365 @@
 .. 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.
 
 
@@ -325 +376 @@
 
    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.