gh-99880: document rounding mode for new-style formatting

[skirpichev]

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. C17 says here (p 230, "Recommended practice"): "For e, E, f, F, g, and G conversions, if the number of significant decimal digits is at most DECIMAL_DIG, then the result should be correctly rounded."

• Issue: Document (undefined) rounding behaviour of new-style formatting #99880

---

📚 Documentation preview 📚: https://cpython-previews--121481.org.readthedocs.build/

[jowagner]

My opinion (not a core developer):

• The word "correctly" doesn't add anything useful here as correctness is subjective, i.e. what is the correct way of rounding to one person may be wrong to another. Suggest removing this word.
• Not clear what kind of vagueness is expressed with "it should round" here. Suggestion: "it will, on common platforms, round".
• Many readers may not understand what least significant bits have to do with decimals. Suggestion: "[...] toward the value with an even last digit (0, 2, 4, 6 or 8) in its representation." (For midway values, there are always two nearest values and one is always odd and the other even, so there is exactly one even value. Note also that "even" and "odd" are not properties of numbers alone but only of numbers with a selected format, e.g. 3 is odd for .0f but even for .1f.)

[skirpichev]

@jowagner, thanks for review.

The word "correctly" doesn't add anything useful here as correctness is subjective

The meaning in this context actually is not subjective at all. From § 3.9 of the C11 standard: correctly rounded result - representation in the result format that is nearest in value, subject to the current rounding mode, to what the result would be given unlimited range and precision.

Maybe it worth to add something like above definition to the glossary? It's used a lot e.g. in the decimal module.

Suggestion: "it will, on common platforms, round".

+1

Many readers may not understand what least significant bits have to do with decimals.

Well, it's a bit not a digit;) Hardly we should everywhere emphasize that floats are binary floating point numbers. I would prefer if more detailed description (in depth, with examples and with a warning!) will be consolidated in round() docs. There is a link.

Suggestion: "[...] toward the value with an even last digit (0, 2, 4, 6 or 8) in its representation."

I doubt it's a correct description. Consider this example:

>>> round(2.675, 2)
2.67
>>> from decimal import Decimal, getcontext
>>> getcontext().rounding
'ROUND_HALF_EVEN'
>>> round(Decimal('2.675'), 2)
Decimal('2.68')

[willingc]

This looks good to me @skirpichev. There is a merge conflict that needs resolution. Thanks.

[skirpichev]

Thanks, fixed.

[willingc]

Thanks @skirpichev.

[miss-islington-app]

Thanks @skirpichev for the PR, and @willingc for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

[bedevere-app]

GH-126334 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-126335 is a backport of this pull request to the 3.12 branch.