rest25/library/math.rst => rest262/library/math.rst
16mathematics as required to understand complex numbers.  Receiving an exception
17instead of a complex result allows earlier detection of the unexpected complex
18number used as a parameter, so that the programmer can determine how and why it
19was generated in the first place.
20
21The following functions are provided by this module.  Except when explicitly
22noted otherwise, all return values are floats.
23
n24+ 
24-Number-theoretic and representation functions:
25+Number-theoretic and representation functions
25- 
26+---------------------------------------------
26
27.. function:: ceil(x)
28
29   Return the ceiling of *x* as a float, the smallest integer value greater than or
30   equal to *x*.
31
32
n34+.. function:: copysign(x, y)
35+ 
36+   Return *x* with the sign of *y*. ``copysign`` copies the sign bit of an IEEE
37+   754 float, ``copysign(1, -0.0)`` returns *-1.0*.
38+ 
39+   .. versionadded:: 2.6
40+ 
41+ 
33.. function:: fabs(x)
34
35   Return the absolute value of *x*.
n45+ 
46+ 
47+.. function:: factorial(x)
48+ 
49+   Return *x* factorial.  Raises :exc:`ValueError` if *x* is not integral or
50+   is negative.
51+ 
52+   .. versionadded:: 2.6
36
37
38.. function:: floor(x)
39
40   Return the floor of *x* as a float, the largest integer value less than or equal
41   to *x*.
n59+ 
60+   .. versionchanged:: 2.6
61+      Added :meth:`__floor__` delegation.
42
43
44.. function:: fmod(x, y)
45
46   Return ``fmod(x, y)``, as defined by the platform C library. Note that the
47   Python expression ``x % y`` may not return the same result.  The intent of the C
48   standard is that ``fmod(x, y)`` be exactly (mathematically; to infinite
49   precision) equal to ``x - n*y`` for some integer *n* such that the result has
59.. function:: frexp(x)
60
61   Return the mantissa and exponent of *x* as the pair ``(m, e)``.  *m* is a float
62   and *e* is an integer such that ``x == m * 2**e`` exactly. If *x* is zero,
63   returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``.  This is used to "pick
64   apart" the internal representation of a float in a portable way.
65
66
n87+.. function:: fsum(iterable)
88+ 
89+   Return an accurate floating point sum of values in the iterable.  Avoids
90+   loss of precision by tracking multiple intermediate partial sums::
91+ 
92+        >>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
93+        0.99999999999999989
94+        >>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
95+        1.0
96+ 
97+   The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
98+   typical case where the rounding mode is half-even.  On some non-Windows
99+   builds, the underlying C library uses extended precision addition and may
100+   occasionally double-round an intermediate sum causing it to be off in its
101+   least significant bit.
102+ 
103+   For further discussion and two alternative approaches, see the `ASPN cookbook
104+   recipes for accurate floating point summation
105+   <http://code.activestate.com/recipes/393090/>`_\.
106+ 
107+   .. versionadded:: 2.6
108+ 
109+ 
110+.. function:: isinf(x)
111+ 
112+   Checks if the float *x* is positive or negative infinite.
113+ 
114+   .. versionadded:: 2.6
115+ 
116+ 
117+.. function:: isnan(x)
118+ 
119+   Checks if the float *x* is a NaN (not a number). NaNs are part of the
120+   IEEE 754 standards. Operation like but not limited to ``inf * 0``,
121+   ``inf / inf`` or any operation involving a NaN, e.g. ``nan * 1``, return
122+   a NaN.
123+ 
124+   .. versionadded:: 2.6
125+ 
126+ 
67.. function:: ldexp(x, i)
68
69   Return ``x * (2**i)``.  This is essentially the inverse of function
70   :func:`frexp`.
71
72
73.. function:: modf(x)
74
n75-   Return the fractional and integer parts of *x*.  Both results carry the sign of
n135+   Return the fractional and integer parts of *x*.  Both results carry the sign
76-   *x*, and both are floats.
136+   of *x* and are floats.
137+ 
138+ 
139+.. function:: trunc(x)
140+ 
141+   Return the :class:`Real` value *x* truncated to an :class:`Integral` (usually
142+   a long integer). Delegates to ``x.__trunc__()``.
143+ 
144+   .. versionadded:: 2.6
145+ 
77
78Note that :func:`frexp` and :func:`modf` have a different call/return pattern
79than their C equivalents: they take a single argument and return a pair of
80values, rather than returning their second return value through an 'output
81parameter' (there is no such thing in Python).
82
83For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
84floating-point numbers of sufficiently large magnitude are exact integers.
85Python floats typically carry no more than 53 bits of precision (the same as the
86platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
87necessarily has no fractional bits.
88
n158+ 
89-Power and logarithmic functions:
159+Power and logarithmic functions
90- 
160+-------------------------------
91
92.. function:: exp(x)
93
94   Return ``e**x``.
95
96
97.. function:: log(x[, base])
98
99   Return the logarithm of *x* to the given *base*. If the *base* is not specified,
100   return the natural logarithm of *x* (that is, the logarithm to base *e*).
101
102   .. versionchanged:: 2.3
103      *base* argument added.
104
105
n176+.. function:: log1p(x)
177+ 
178+   Return the natural logarithm of *1+x* (base *e*). The
179+   result is calculated in a way which is accurate for *x* near zero.
180+ 
181+   .. versionadded:: 2.6
182+ 
183+ 
106.. function:: log10(x)
107
108   Return the base-10 logarithm of *x*.
109
110
111.. function:: pow(x, y)
112
n113-   Return ``x**y``.
n191+   Return ``x`` raised to the power ``y``.  Exceptional cases follow
192+   Annex 'F' of the C99 standard as far as possible.  In particular,
193+   ``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even
194+   when ``x`` is a zero or a NaN.  If both ``x`` and ``y`` are finite,
195+   ``x`` is negative, and ``y`` is not an integer then ``pow(x, y)``
196+   is undefined, and raises :exc:`ValueError`.
197+ 
198+   .. versionchanged:: 2.6
199+      The outcome of ``1**nan`` and ``nan**0`` was undefined.
114
115
116.. function:: sqrt(x)
117
118   Return the square root of *x*.
119
n206+ 
120-Trigonometric functions:
207+Trigonometric functions
121- 
208+-----------------------
122
123.. function:: acos(x)
124
125   Return the arc cosine of *x*, in radians.
126
127
128.. function:: asin(x)
129
160
161   Return the sine of *x* radians.
162
163
164.. function:: tan(x)
165
166   Return the tangent of *x* radians.
167
n255+ 
168-Angular conversion:
256+Angular conversion
169- 
257+------------------
170
171.. function:: degrees(x)
172
173   Converts angle *x* from radians to degrees.
174
175
176.. function:: radians(x)
177
178   Converts angle *x* from degrees to radians.
179
n268+ 
180-Hyperbolic functions:
269+Hyperbolic functions
270+--------------------
271+ 
272+.. function:: acosh(x)
273+ 
274+   Return the inverse hyperbolic cosine of *x*.
275+ 
276+   .. versionadded:: 2.6
277+ 
278+ 
279+.. function:: asinh(x)
280+ 
281+   Return the inverse hyperbolic sine of *x*.
282+ 
283+   .. versionadded:: 2.6
284+ 
285+ 
286+.. function:: atanh(x)
287+ 
288+   Return the inverse hyperbolic tangent of *x*.
289+ 
290+   .. versionadded:: 2.6
181
182
183.. function:: cosh(x)
184
185   Return the hyperbolic cosine of *x*.
186
187
188.. function:: sinh(x)
189
190   Return the hyperbolic sine of *x*.
191
192
193.. function:: tanh(x)
194
195   Return the hyperbolic tangent of *x*.
196
n197-The module also defines two mathematical constants:
198
n308+Constants
309+---------
199
200.. data:: pi
201
202   The mathematical constant *pi*.
203
204
205.. data:: e
206
207   The mathematical constant *e*.
208
n320+ 
209.. note::
210
211   The :mod:`math` module consists mostly of thin wrappers around the platform C
n212-   math library functions.  Behavior in exceptional cases is loosely specified by
n324+   math library functions.  Behavior in exceptional cases is loosely specified
213-   the C standards, and Python inherits much of its math-function error-reporting
325+   by the C standards, and Python inherits much of its math-function
214-   behavior from the platform C implementation.  As a result, the specific
326+   error-reporting behavior from the platform C implementation.  As a result,
215-   exceptions raised in error cases (and even whether some arguments are considered
327+   the specific exceptions raised in error cases (and even whether some
216-   to be exceptional at all) are not defined in any useful cross-platform or cross-
328+   arguments are considered to be exceptional at all) are not defined in any
217-   release way.  For example, whether ``math.log(0)`` returns ``-Inf`` or raises
329+   useful cross-platform or cross-release way.  For example, whether
218-   :exc:`ValueError` or :exc:`OverflowError` isn't defined, and in cases where
330+   ``math.log(0)`` returns ``-Inf`` or raises :exc:`ValueError` or
219-   ``math.log(0)`` raises :exc:`OverflowError`, ``math.log(0L)`` may raise
331+   :exc:`OverflowError` isn't defined, and in cases where ``math.log(0)`` raises
220-   :exc:`ValueError` instead.
332+   :exc:`OverflowError`, ``math.log(0L)`` may raise :exc:`ValueError` instead.
333+ 
334+   All functions return a quiet *NaN* if at least one of the args is *NaN*.
335+   Signaling *NaN*\s raise an exception. The exception type still depends on the
336+   platform and libm implementation. It's usually :exc:`ValueError` for *EDOM*
337+   and :exc:`OverflowError` for errno *ERANGE*.
338+ 
339+   .. versionchanged:: 2.6
340+      In earlier versions of Python the outcome of an operation with NaN as
341+      input depended on platform and libm implementation.
221
222
223.. seealso::
224
225   Module :mod:`cmath`
226      Complex number versions of many of these functions.
t227- 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op