[3.12] gh-99880: document rounding mode for new-style formatting (GH-121481) (#126335)

The CPython uses _Py_dg_dtoa(), which does rounding to nearest with half
to even tie-breaking rule.

If that functions is unavailable, PyOS_double_to_string() fallbacks to
system snprintf().  Since CPython 3.12, build requirements include C11
compiler *and* support for IEEE 754 floating point numbers (Annex F).
This means that FE_TONEAREST macro is available and, per default,
printf-like functions should use same rounding mode as _Py_dg_dtoa().

(cherry picked from commit 7d7d56d8b1147a6b85e1c09d01b164df7c5c4942)

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 9e8e44a8abe770c46354e4f8519f6dce44c7e993..a000bb49f148006bee24a296da70d41a5bb10e1f 100644 (file)
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -589,6 +589,11 @@ The available presentation types for :class:`float` and
    |         | as altered by the other format modifiers.                |
    +---------+----------------------------------------------------------+
 
+The result should be correctly rounded to a given precision ``p`` of digits
+after the decimal point.  The rounding mode for :class:`float` matches that
+of the :func:`round` builtin.  For :class:`~decimal.Decimal`, the rounding
+mode of the current :ref:`context <decimal-context>` will be used.
+
 The available presentation types for :class:`complex` are the same as those for
 :class:`float` (``'%'`` is not allowed).  Both the real and imaginary components
 of a complex number are formatted as floating-point numbers, according to the