bpo-29962: add math.remainder (#950)
* Implement math.remainder.
* Fix markup for arguments; use double spaces after period.
* Mark up function reference in what's new entry.
* Add comment explaining the calculation in the final branch.
* Fix out-of-order entry in whatsnew.
* Add comment explaining why it's good enough to compare m with c, in spite of possible rounding error.
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 @@
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