bpo-39310: Add math.ulp(x) (GH-17965)
Add math.ulp(): return the value of the least significant bit
of a float.
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index c9f2a38..c4c1800 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -226,6 +226,8 @@
* ``math.nextafter(x, 0.0)`` goes towards zero.
* ``math.nextafter(x, math.copysign(math.inf, x))`` goes away from zero.
+ See also :func:`math.ulp`.
+
.. versionadded:: 3.9
.. function:: perm(n, k=None)
@@ -284,6 +286,30 @@
:class:`~numbers.Integral` (usually an integer). Delegates to
:meth:`x.__trunc__() <object.__trunc__>`.
+.. function:: ulp(x)
+
+ Return the value of the least significant bit of the float *x*:
+
+ * If *x* is a NaN (not a number), return *x*.
+ * If *x* is negative, return ``ulp(-x)``.
+ * If *x* is a positive infinity, return *x*.
+ * If *x* is equal to zero, return the smallest positive
+ *denormalized* representable float (smaller than the minimum positive
+ *normalized* float, :data:`sys.float_info.min <sys.float_info>`).
+ * If *x* is equal to the largest positive representable float,
+ return the value of the least significant bit of *x*, such that the first
+ float smaller than *x* is ``x - ulp(x)``.
+ * Otherwise (*x* is a positive finite number), return the value of the least
+ significant bit of *x*, such that the first float bigger than *x*
+ is ``x + ulp(x)``.
+
+ ULP stands for "Unit in the Last Place".
+
+ See also :func:`math.nextafter` and :data:`sys.float_info.epsilon
+ <sys.float_info>`.
+
+ .. 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
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 0aae263..351a8e4 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -479,8 +479,10 @@
+---------------------+----------------+--------------------------------------------------+
| attribute | float.h macro | explanation |
+=====================+================+==================================================+
- | :const:`epsilon` | DBL_EPSILON | difference between 1 and the least value greater |
- | | | than 1 that is representable as a float |
+ | :const:`epsilon` | DBL_EPSILON | difference between 1.0 and the least value |
+ | | | greater than 1.0 that is representable as a float|
+ | | | |
+ | | | See also :func:`math.ulp`. |
+---------------------+----------------+--------------------------------------------------+
| :const:`dig` | DBL_DIG | maximum number of decimal digits that can be |
| | | faithfully represented in a float; see below |
@@ -488,20 +490,24 @@
| :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` |
| | | digits in the significand of a float |
+---------------------+----------------+--------------------------------------------------+
- | :const:`max` | DBL_MAX | maximum representable finite float |
+ | :const:`max` | DBL_MAX | maximum representable positive finite float |
+---------------------+----------------+--------------------------------------------------+
- | :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is |
+ | :const:`max_exp` | DBL_MAX_EXP | maximum integer *e* such that ``radix**(e-1)`` is|
| | | a representable finite float |
+---------------------+----------------+--------------------------------------------------+
- | :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the |
+ | :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer *e* such that ``10**e`` is in the|
| | | range of representable finite floats |
+---------------------+----------------+--------------------------------------------------+
- | :const:`min` | DBL_MIN | minimum positive normalized float |
+ | :const:`min` | DBL_MIN | minimum representable positive *normalized* float|
+ | | | |
+ | | | Use :func:`math.ulp(0.0) <math.ulp>` to get the |
+ | | | smallest positive *denormalized* representable |
+ | | | float. |
+---------------------+----------------+--------------------------------------------------+
- | :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is |
+ | :const:`min_exp` | DBL_MIN_EXP | minimum integer *e* such that ``radix**(e-1)`` is|
| | | a normalized float |
+---------------------+----------------+--------------------------------------------------+
- | :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a |
+ | :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer *e* such that ``10**e`` is a |
| | | normalized float |
+---------------------+----------------+--------------------------------------------------+
| :const:`radix` | FLT_RADIX | radix of exponent representation |