Title: Document the meaning of values for sys.float_info.rounds
Type: Stage:
Components: Documentation Versions: Python 3.10
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eamanu, mark.dickinson, rahul-kumi, rhettinger, serhiy.storchaka, tim.peters
Priority: normal Keywords: newcomer friendly

Created on 2020-09-21 00:38 by rhettinger, last changed 2020-10-18 09:13 by rhettinger.

Messages (5)
msg377236 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-09-21 00:38
The current docs unnecessarily refer readers to the C99 standard. "integer constant representing the rounding mode used for arithmetic operations. This reflects the value of the system FLT_ROUNDS macro at interpreter startup time. See section of the C99 standard for an explanation of the possible values and their meanings."

The docs should quote the standard, "The rounding mode for floating-point addition is characterized by the implementation defined value of FLT_ROUNDS: -1 indeterminable, 0 toward zero, 1 to nearest, 2 toward positive infinity, 3 toward negative infinity.  All other values for FLT_ROUNDS characterize implementation-defined rounding."
msg378852 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-10-18 08:20
Also, we should document the meaning of the other fields.  Several of them are not self explanatory:

min_10_exp = -307

   does not mean that 2.3e-308 isn't normalized

   does mean that 10**-307 is normalized and 10**-308 isn't

min_exp = -1021

   does not mean that 2**-1021 is the lowest normalized value

   does mean ldexp(0.5, -1021) == float_info.min

decimal_dig = 15

   does not mean digits required to specify every unique float

   does mean, "number of decimal digits, q, such that any 
   floating-point number with q decimal digits can be rounded
   into a floating-point number with p radix b digits and back
   again without change to the q decimal digits"
msg378853 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-10-18 08:48
Python does not set the meaning and the value of these fields itself. It exposes C constants. Should we just copy definitions from corresponding C or floating-point standards?
msg378854 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-10-18 08:50
Oh, seems it was what Raymond proposed initially.
msg378856 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-10-18 09:13
Here's a link:
Date User Action Args
2020-10-18 09:13:18rhettingersetmessages: + msg378856
2020-10-18 08:50:54serhiy.storchakasetmessages: + msg378854
2020-10-18 08:48:55serhiy.storchakasetmessages: + msg378853
2020-10-18 08:20:26rhettingersetmessages: + msg378852
2020-10-13 00:58:07eamanusetnosy: + eamanu
2020-09-26 14:13:24rahul-kumisetnosy: + rahul-kumi
2020-09-25 23:13:38terry.reedysettitle: Document the mean of values for sys.float_info.rounds -> Document the meaning of values for sys.float_info.rounds
versions: + Python 3.10
2020-09-21 00:46:43rhettingersetnosy: + tim.peters, mark.dickinson, serhiy.storchaka
2020-09-21 00:38:26rhettingercreate