diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/math.rst | 21 | ||||
| -rw-r--r-- | Doc/whatsnew/3.7.rst | 6 |
2 files changed, 27 insertions, 0 deletions
diff --git a/Doc/library/math.rst b/Doc/library/math.rst index b1f5692..0c53b29 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -175,6 +175,27 @@ Number-theoretic and representation functions of *x* and are floats. +.. 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:: trunc(x) Return the :class:`~numbers.Real` value *x* truncated to an diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst index 12f65ff..b5107ea 100644 --- a/Doc/whatsnew/3.7.rst +++ b/Doc/whatsnew/3.7.rst @@ -110,6 +110,12 @@ Added another argument *monetary* in :meth:`format_string` of :mod:`locale`. If *monetary* is true, the conversion uses monetary thousands separator and grouping strings. (Contributed by Garvit in :issue:`10379`.) +math +---- + +New :func:`~math.remainder` function, implementing the IEEE 754-style remainder +operation. (Contributed by Mark Dickinson in :issue:`29962`.) + os -- |