==================================================== ============================================
-**Number-theoretic and representation functions**
+**Number-theoretic functions**
--------------------------------------------------------------------------------------------------
-:func:`ceil(x) <ceil>` Ceiling of *x*, the smallest integer greater than or equal to *x*
:func:`comb(n, k) <comb>` Number of ways to choose *k* items from *n* items without repetition and without order
-:func:`copysign(x, y) <copysign>` Magnitude (absolute value) of *x* with the sign of *y*
-:func:`fabs(x) <fabs>` Absolute value of *x*
:func:`factorial(n) <factorial>` *n* factorial
-:func:`floor (x) <floor>` Floor of *x*, the largest integer less than or equal to *x*
+:func:`gcd(*integers) <gcd>` Greatest common divisor of the integer arguments
+:func:`isqrt(n) <isqrt>` Integer square root of a nonnegative integer *n*
+:func:`lcm(*integers) <lcm>` Least common multiple of the integer arguments
+:func:`perm(n, k) <perm>` Number of ways to choose *k* items from *n* items without repetition and with order
+
+**Floating point arithmetic**
+--------------------------------------------------------------------------------------------------
+:func:`ceil(x) <ceil>` Ceiling of *x*, the smallest integer greater than or equal to *x*
+:func:`fabs(x) <fabs>` Absolute value of *x*
+:func:`floor(x) <floor>` Floor of *x*, the largest integer less than or equal to *x*
:func:`fma(x, y, z) <fma>` Fused multiply-add operation: ``(x * y) + z``
:func:`fmod(x, y) <fmod>` Remainder of division ``x / y``
+:func:`modf(x) <modf>` Fractional and integer parts of *x*
+:func:`remainder(x, y) <remainder>` Remainder of *x* with respect to *y*
+:func:`trunc(x) <trunc>` Integer part of *x*
+
+**Floating point manipulation functions**
+--------------------------------------------------------------------------------------------------
+:func:`copysign(x, y) <copysign>` Magnitude (absolute value) of *x* with the sign of *y*
:func:`frexp(x) <frexp>` Mantissa and exponent of *x*
-:func:`fsum(iterable) <fsum>` Sum of values in the input *iterable*
-:func:`gcd(*integers) <gcd>` Greatest common divisor of the integer arguments
:func:`isclose(a, b, rel_tol, abs_tol) <isclose>` Check if the values *a* and *b* are close to each other
:func:`isfinite(x) <isfinite>` Check if *x* is neither an infinity nor a NaN
:func:`isinf(x) <isinf>` Check if *x* is a positive or negative infinity
:func:`isnan(x) <isnan>` Check if *x* is a NaN (not a number)
-:func:`isqrt(n) <isqrt>` Integer square root of a nonnegative integer *n*
-:func:`lcm(*integers) <lcm>` Least common multiple of the integer arguments
:func:`ldexp(x, i) <ldexp>` ``x * (2**i)``, inverse of function :func:`frexp`
-:func:`modf(x) <modf>` Fractional and integer parts of *x*
:func:`nextafter(x, y, steps) <nextafter>` Floating-point value *steps* steps after *x* towards *y*
-:func:`perm(n, k) <perm>` Number of ways to choose *k* items from *n* items without repetition and with order
-:func:`prod(iterable, start) <prod>` Product of elements in the input *iterable* with a *start* value
-:func:`remainder(x, y) <remainder>` Remainder of *x* with respect to *y*
-:func:`sumprod(p, q) <sumprod>` Sum of products from two iterables *p* and *q*
-:func:`trunc(x) <trunc>` Integer part of *x*
:func:`ulp(x) <ulp>` Value of the least significant bit of *x*
-**Power and logarithmic functions**
+**Power, exponential and logarithmic functions**
--------------------------------------------------------------------------------------------------
:func:`cbrt(x) <cbrt>` Cube root of *x*
:func:`exp(x) <exp>` *e* raised to the power *x*
:func:`pow(x, y) <math.pow>` *x* raised to the power *y*
:func:`sqrt(x) <sqrt>` Square root of *x*
+**Summation and product functions**
+--------------------------------------------------------------------------------------------------
+:func:`dist(p, q) <dist>` Euclidean distance between two points *p* and *q* given as an iterable of coordinates
+:func:`fsum(iterable) <fsum>` Sum of values in the input *iterable*
+:func:`hypot(*coordinates) <hypot>` Euclidean norm of an iterable of coordinates
+:func:`prod(iterable, start) <prod>` Product of elements in the input *iterable* with a *start* value
+:func:`sumprod(p, q) <sumprod>` Sum of products from two iterables *p* and *q*
+
+**Angular conversion**
+--------------------------------------------------------------------------------------------------
+:func:`degrees(x) <degrees>` Convert angle *x* from radians to degrees
+:func:`radians(x) <radians>` Convert angle *x* from degrees to radians
+
**Trigonometric functions**
--------------------------------------------------------------------------------------------------
:func:`acos(x) <acos>` Arc cosine of *x*
:func:`atan(x) <atan>` Arc tangent of *x*
:func:`atan2(y, x) <atan2>` ``atan(y / x)``
:func:`cos(x) <cos>` Cosine of *x*
-:func:`dist(p, q) <dist>` Euclidean distance between two points *p* and *q* given as an iterable of coordinates
-:func:`hypot(*coordinates) <hypot>` Euclidean norm of an iterable of coordinates
:func:`sin(x) <sin>` Sine of *x*
:func:`tan(x) <tan>` Tangent of *x*
-**Angular conversion**
---------------------------------------------------------------------------------------------------
-:func:`degrees(x) <degrees>` Convert angle *x* from radians to degrees
-:func:`radians(x) <radians>` Convert angle *x* from degrees to radians
-
**Hyperbolic functions**
--------------------------------------------------------------------------------------------------
:func:`acosh(x) <acosh>` Inverse hyperbolic cosine of *x*
==================================================== ============================================
-Number-theoretic and representation functions
----------------------------------------------
-
-.. function:: ceil(x)
-
- Return the ceiling of *x*, the smallest integer greater than or equal to *x*.
- If *x* is not a float, delegates to :meth:`x.__ceil__ <object.__ceil__>`,
- which should return an :class:`~numbers.Integral` value.
-
+Number-theoretic functions
+--------------------------
.. function:: comb(n, k)
.. versionadded:: 3.8
-.. function:: copysign(x, y)
+.. function:: factorial(n)
- Return a float with the magnitude (absolute value) of *x* but the sign of
- *y*. On platforms that support signed zeros, ``copysign(1.0, -0.0)``
- returns *-1.0*.
+ Return *n* factorial as an integer. Raises :exc:`ValueError` if *n* is not integral or
+ is negative.
+ .. versionchanged:: 3.10
+ Floats with integral values (like ``5.0``) are no longer accepted.
-.. function:: fabs(x)
- Return the absolute value of *x*.
+.. function:: gcd(*integers)
+
+ Return the greatest common divisor of the specified integer arguments.
+ If any of the arguments is nonzero, then the returned value is the largest
+ positive integer that is a divisor of all arguments. If all arguments
+ are zero, then the returned value is ``0``. ``gcd()`` without arguments
+ returns ``0``.
+ .. versionadded:: 3.5
-.. function:: factorial(n)
+ .. versionchanged:: 3.9
+ Added support for an arbitrary number of arguments. Formerly, only two
+ arguments were supported.
- Return *n* factorial as an integer. Raises :exc:`ValueError` if *n* is not integral or
- is negative.
- .. versionchanged:: 3.10
- Floats with integral values (like ``5.0``) are no longer accepted.
+.. function:: isqrt(n)
+
+ Return the integer square root of the nonnegative integer *n*. This is the
+ floor of the exact square root of *n*, or equivalently the greatest integer
+ *a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
+
+ For some applications, it may be more convenient to have the least integer
+ *a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
+ the exact square root of *n*. For positive *n*, this can be computed using
+ ``a = 1 + isqrt(n - 1)``.
+
+ .. versionadded:: 3.8
+
+
+.. function:: lcm(*integers)
+
+ Return the least common multiple of the specified integer arguments.
+ If all arguments are nonzero, then the returned value is the smallest
+ positive integer that is a multiple of all arguments. If any of the arguments
+ is zero, then the returned value is ``0``. ``lcm()`` without arguments
+ returns ``1``.
+
+ .. versionadded:: 3.9
+
+
+.. function:: perm(n, k=None)
+
+ Return the number of ways to choose *k* items from *n* items
+ without repetition and with order.
+
+ Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
+ to zero when ``k > n``.
+
+ If *k* is not specified or is ``None``, then *k* defaults to *n*
+ and the function returns ``n!``.
+
+ Raises :exc:`TypeError` if either of the arguments are not integers.
+ Raises :exc:`ValueError` if either of the arguments are negative.
+
+ .. versionadded:: 3.8
+
+
+Floating point arithmetic
+-------------------------
+
+.. function:: ceil(x)
+
+ Return the ceiling of *x*, the smallest integer greater than or equal to *x*.
+ If *x* is not a float, delegates to :meth:`x.__ceil__ <object.__ceil__>`,
+ which should return an :class:`~numbers.Integral` value.
+
+
+.. function:: fabs(x)
+
+ Return the absolute value of *x*.
.. function:: floor(x)
floats, while Python's ``x % y`` is preferred when working with integers.
-.. function:: frexp(x)
+.. function:: modf(x)
- Return the mantissa and exponent of *x* as the pair ``(m, e)``. *m* is a float
- and *e* is an integer such that ``x == m * 2**e`` exactly. If *x* is zero,
- returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``. This is used to "pick
- apart" the internal representation of a float in a portable way.
+ Return the fractional and integer parts of *x*. Both results carry the sign
+ of *x* and are floats.
+ Note that :func:`modf` has a different call/return pattern
+ than its C equivalents: it takes a single argument and return a pair of
+ values, rather than returning its second return value through an 'output
+ parameter' (there is no such thing in Python).
-.. function:: fsum(iterable)
- Return an accurate floating-point sum of values in the iterable. Avoids
- loss of precision by tracking multiple intermediate partial sums.
+.. function:: remainder(x, y)
- The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
- typical case where the rounding mode is half-even. On some non-Windows
- builds, the underlying C library uses extended precision addition and may
- occasionally double-round an intermediate sum causing it to be off in its
- least significant bit.
+ Return the IEEE 754-style remainder of *x* with respect to *y*. For
+ finite *x* and finite nonzero *y*, this is the difference ``x - n*y``,
+ where ``n`` is the closest integer to the exact value of the quotient ``x /
+ y``. If ``x / y`` is exactly halfway between two consecutive integers, the
+ nearest *even* integer is used for ``n``. The remainder ``r = remainder(x,
+ y)`` thus always satisfies ``abs(r) <= 0.5 * abs(y)``.
- For further discussion and two alternative approaches, see the `ASPN cookbook
- recipes for accurate floating-point summation
- <https://code.activestate.com/recipes/393090-binary-floating-point-summation-accurate-to-full-p/>`_\.
+ Special cases follow IEEE 754: in particular, ``remainder(x, math.inf)`` is
+ *x* for any finite *x*, and ``remainder(x, 0)`` and
+ ``remainder(math.inf, x)`` raise :exc:`ValueError` for any non-NaN *x*.
+ If the result of the remainder operation is zero, that zero will have
+ the same sign as *x*.
+ On platforms using IEEE 754 binary floating point, the result of this
+ operation is always exactly representable: no rounding error is introduced.
-.. function:: gcd(*integers)
+ .. versionadded:: 3.7
- Return the greatest common divisor of the specified integer arguments.
- If any of the arguments is nonzero, then the returned value is the largest
- positive integer that is a divisor of all arguments. If all arguments
- are zero, then the returned value is ``0``. ``gcd()`` without arguments
- returns ``0``.
- .. versionadded:: 3.5
+.. function:: trunc(x)
- .. versionchanged:: 3.9
- Added support for an arbitrary number of arguments. Formerly, only two
- arguments were supported.
+ Return *x* with the fractional part
+ removed, leaving the integer part. This rounds toward 0: ``trunc()`` is
+ equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil`
+ for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__
+ <object.__trunc__>`, which should return an :class:`~numbers.Integral` value.
+
+
+For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
+floating-point numbers of sufficiently large magnitude are exact integers.
+Python floats typically carry no more than 53 bits of precision (the same as the
+platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
+necessarily has no fractional bits.
+Floating point manipulation functions
+-------------------------------------
+
+.. function:: copysign(x, y)
+
+ Return a float with the magnitude (absolute value) of *x* but the sign of
+ *y*. On platforms that support signed zeros, ``copysign(1.0, -0.0)``
+ returns *-1.0*.
+
+
+.. function:: frexp(x)
+
+ Return the mantissa and exponent of *x* as the pair ``(m, e)``. *m* is a float
+ and *e* is an integer such that ``x == m * 2**e`` exactly. If *x* is zero,
+ returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``. This is used to "pick
+ apart" the internal representation of a float in a portable way.
+
+ Note that :func:`frexp` has a different call/return pattern
+ than its C equivalents: it takes a single argument and return a pair of
+ values, rather than returning its second return value through an 'output
+ parameter' (there is no such thing in Python).
+
.. function:: isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0)
Return ``True`` if the values *a* and *b* are close to each other and
Return ``True`` if *x* is a NaN (not a number), and ``False`` otherwise.
-.. function:: isqrt(n)
-
- Return the integer square root of the nonnegative integer *n*. This is the
- floor of the exact square root of *n*, or equivalently the greatest integer
- *a* such that *a*\ ² |nbsp| ≤ |nbsp| *n*.
-
- For some applications, it may be more convenient to have the least integer
- *a* such that *n* |nbsp| ≤ |nbsp| *a*\ ², or in other words the ceiling of
- the exact square root of *n*. For positive *n*, this can be computed using
- ``a = 1 + isqrt(n - 1)``.
-
- .. versionadded:: 3.8
-
-
-.. function:: lcm(*integers)
-
- Return the least common multiple of the specified integer arguments.
- If all arguments are nonzero, then the returned value is the smallest
- positive integer that is a multiple of all arguments. If any of the arguments
- is zero, then the returned value is ``0``. ``lcm()`` without arguments
- returns ``1``.
-
- .. versionadded:: 3.9
-
-
.. function:: ldexp(x, i)
Return ``x * (2**i)``. This is essentially the inverse of function
:func:`frexp`.
-.. function:: modf(x)
-
- Return the fractional and integer parts of *x*. Both results carry the sign
- of *x* and are floats.
-
-
.. function:: nextafter(x, y, steps=1)
Return the floating-point value *steps* steps after *x* towards *y*.
.. versionchanged:: 3.12
Added the *steps* argument.
-.. function:: perm(n, k=None)
-
- Return the number of ways to choose *k* items from *n* items
- without repetition and with order.
-
- Evaluates to ``n! / (n - k)!`` when ``k <= n`` and evaluates
- to zero when ``k > n``.
-
- If *k* is not specified or is ``None``, then *k* defaults to *n*
- and the function returns ``n!``.
-
- Raises :exc:`TypeError` if either of the arguments are not integers.
- Raises :exc:`ValueError` if either of the arguments are negative.
-
- .. versionadded:: 3.8
-
-
-.. function:: prod(iterable, *, start=1)
-
- Calculate the product of all the elements in the input *iterable*.
- The default *start* value for the product is ``1``.
-
- When the iterable is empty, return the start value. This function is
- intended specifically for use with numeric values and may reject
- non-numeric types.
-
- .. versionadded:: 3.8
-
-
-.. function:: remainder(x, y)
-
- Return the IEEE 754-style remainder of *x* with respect to *y*. For
- finite *x* and finite nonzero *y*, this is the difference ``x - n*y``,
- where ``n`` is the closest integer to the exact value of the quotient ``x /
- y``. If ``x / y`` is exactly halfway between two consecutive integers, the
- nearest *even* integer is used for ``n``. The remainder ``r = remainder(x,
- y)`` thus always satisfies ``abs(r) <= 0.5 * abs(y)``.
-
- Special cases follow IEEE 754: in particular, ``remainder(x, math.inf)`` is
- *x* for any finite *x*, and ``remainder(x, 0)`` and
- ``remainder(math.inf, x)`` raise :exc:`ValueError` for any non-NaN *x*.
- If the result of the remainder operation is zero, that zero will have
- the same sign as *x*.
-
- On platforms using IEEE 754 binary floating point, the result of this
- operation is always exactly representable: no rounding error is introduced.
-
- .. versionadded:: 3.7
-
-
-.. function:: sumprod(p, q)
-
- Return the sum of products of values from two iterables *p* and *q*.
-
- Raises :exc:`ValueError` if the inputs do not have the same length.
-
- Roughly equivalent to::
-
- sum(map(operator.mul, p, q, strict=True))
-
- For float and mixed int/float inputs, the intermediate products
- and sums are computed with extended precision.
-
- .. versionadded:: 3.12
-
-
-.. function:: trunc(x)
-
- Return *x* with the fractional part
- removed, leaving the integer part. This rounds toward 0: ``trunc()`` is
- equivalent to :func:`floor` for positive *x*, and equivalent to :func:`ceil`
- for negative *x*. If *x* is not a float, delegates to :meth:`x.__trunc__
- <object.__trunc__>`, which should return an :class:`~numbers.Integral` value.
.. function:: ulp(x)
.. versionadded:: 3.9
-Note that :func:`frexp` and :func:`modf` have a different call/return pattern
-than their C equivalents: they take a single argument and return a pair of
-values, rather than returning their second return value through an 'output
-parameter' (there is no such thing in Python).
-
-For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
-floating-point numbers of sufficiently large magnitude are exact integers.
-Python floats typically carry no more than 53 bits of precision (the same as the
-platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
-necessarily has no fractional bits.
-
-
-Power and logarithmic functions
--------------------------------
+Power, exponential and logarithmic functions
+--------------------------------------------
.. function:: cbrt(x)
Return the square root of *x*.
-Trigonometric functions
------------------------
-
-.. function:: acos(x)
-
- Return the arc cosine of *x*, in radians. The result is between ``0`` and
- ``pi``.
-
-
-.. function:: asin(x)
-
- Return the arc sine of *x*, in radians. The result is between ``-pi/2`` and
- ``pi/2``.
-
-
-.. function:: atan(x)
-
- Return the arc tangent of *x*, in radians. The result is between ``-pi/2`` and
- ``pi/2``.
-
-
-.. function:: atan2(y, x)
-
- Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.
- 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,
- -1)`` is ``-3*pi/4``.
-
-
-.. function:: cos(x)
-
- Return the cosine of *x* radians.
-
+Summation and product functions
+-------------------------------
.. function:: dist(p, q)
.. versionadded:: 3.8
+.. function:: fsum(iterable)
+
+ Return an accurate floating-point sum of values in the iterable. Avoids
+ loss of precision by tracking multiple intermediate partial sums.
+
+ The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
+ typical case where the rounding mode is half-even. On some non-Windows
+ builds, the underlying C library uses extended precision addition and may
+ occasionally double-round an intermediate sum causing it to be off in its
+ least significant bit.
+
+ For further discussion and two alternative approaches, see the `ASPN cookbook
+ recipes for accurate floating-point summation
+ <https://code.activestate.com/recipes/393090-binary-floating-point-summation-accurate-to-full-p/>`_\.
+
+
.. function:: hypot(*coordinates)
Return the Euclidean norm, ``sqrt(sum(x**2 for x in coordinates))``.
is almost always correctly rounded to within 1/2 ulp.
-.. function:: sin(x)
+.. function:: prod(iterable, *, start=1)
- Return the sine of *x* radians.
+ Calculate the product of all the elements in the input *iterable*.
+ The default *start* value for the product is ``1``.
+ When the iterable is empty, return the start value. This function is
+ intended specifically for use with numeric values and may reject
+ non-numeric types.
-.. function:: tan(x)
+ .. versionadded:: 3.8
- Return the tangent of *x* radians.
+
+.. function:: sumprod(p, q)
+
+ Return the sum of products of values from two iterables *p* and *q*.
+
+ Raises :exc:`ValueError` if the inputs do not have the same length.
+
+ Roughly equivalent to::
+
+ sum(map(operator.mul, p, q, strict=True))
+
+ For float and mixed int/float inputs, the intermediate products
+ and sums are computed with extended precision.
+
+ .. versionadded:: 3.12
Angular conversion
Convert angle *x* from degrees to radians.
+Trigonometric functions
+-----------------------
+
+.. function:: acos(x)
+
+ Return the arc cosine of *x*, in radians. The result is between ``0`` and
+ ``pi``.
+
+
+.. function:: asin(x)
+
+ Return the arc sine of *x*, in radians. The result is between ``-pi/2`` and
+ ``pi/2``.
+
+
+.. function:: atan(x)
+
+ Return the arc tangent of *x*, in radians. The result is between ``-pi/2`` and
+ ``pi/2``.
+
+
+.. function:: atan2(y, x)
+
+ Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.
+ 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,
+ -1)`` is ``-3*pi/4``.
+
+
+.. function:: cos(x)
+
+ Return the cosine of *x* radians.
+
+
+.. function:: sin(x)
+
+ Return the sine of *x* radians.
+
+
+.. function:: tan(x)
+
+ Return the tangent of *x* radians.
+
+
Hyperbolic functions
--------------------
projects / thirdparty / Python / cpython.git / commitdiff
